​
TS/JS SDK Overview

Alpha Release - This SDK is in alpha and actively under development. Method signatures may change.Contributions are welcome at https://github.com/CloudCruise/cloudcruise-js.Report bugs via GitHub issues or Discord.
The CloudCruise TypeScript/JavaScript SDK provides a simple way to integrate browser automation workflows into your applications. Execute workflows, manage credentials, and monitor runs programmatically.

​
Installation

npm install cloudcruise
Get your keys at CloudCruise Settings. 
import { CloudCruise } from 'cloudcruise';

const client = new CloudCruise({
  apiKey: "your-api-key",
  encryptionKey: "your-encryption-key",
});

​
1. Creating a Run

const run = await client.runs.start({
  workflow_id: "workflow-123",
  run_input_variables: {
    variable_1: "https://example.com",
    variable_2: "john_doe",
  },
});

console.log("Session ID:", run.sessionId);

​
2. Processing Events via Webhook (Most Reliable)

Webhooks are the most reliable way to receive updates. 
// In your webhook endpoint
app.post("/webhook", (req, res) => {
  try {
    const signature = req.headers["x-hmac-signature"];
    const payload = req.body;
    
    const verifiedPayload = client.webhook.verifySignature(
      payload,
      signature,
      "your-webhook-secret"
    );

    switch (payload.event) {
      case "execution.success":
        console.log("Workflow completed successfully");
        break;
      case "execution.failed":
        console.log("Workflow failed");
        break;
    }

    res.status(200).json({ status: "received" });
  } catch (error) {
    res.status(400).json({ error: "Invalid webhook" });
  }
});

​
3. Event Handler Alternative

If you don’t want to use webhooks, you can use the built-in event handlers: 
const run = await client.runs.start({
  workflow_id: "workflow-123",
  run_input_variables: { target: "https://example.com" },
});

// Listen to events
run.on("run.event", (event) => {
  console.log("Event:", event.data.event);
  console.log("Payload:", event.data.payload);
});

// Or use async iteration
for await (const event of run) {
  console.log("Received event:", event.data.event);
  
  if (event.data.event === "execution.success") {
    break;
  }
}

​
4. Wait for Completion

You can wait for the run to finish, but keep in mind if your run is long, this can be a very long time: 
const run = await client.runs.start({
  workflow_id: "workflow-123",
  run_input_variables: { target: "https://example.com" },
});

// This will block until completion - use with caution for long workflows
const result = await run.wait();
console.log("Run completed:", result.status);
console.log("Output data:", result.data);

​
Next Steps

  • Explore the Run API for detailed workflow execution options
  • Learn about Vault API for secure credential management
  • Check out Workflow API to manage your workflows
  • Set up Webhooks for event notifications