cloudcruise 0.0.1 → 0.0.2-alpha.1

package/README.md

@@ -1 +1,45 @@
-# cloudcruise-js
+# cloudcruise-js
+
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+![NPM Downloads](https://img.shields.io/npm/dw/cloudcruise)
+[![GitHub Repo stars](https://img.shields.io/github/stars/CloudCruise/cloudcruise-js?style=flat-square&logo=GitHub&label=cloudcruise-js)](https://github.com/CloudCruise/cloudcruise-js)
+[![Discord](https://img.shields.io/discord/1227480834945318933?style=flat-square&logo=Discord&logoColor=white&label=Discord&color=%23434EE4)](https://discord.com/invite/MHjbUqedZF)
+[![YC W24](https://img.shields.io/badge/Y%20Combinator-W24-orange?style=flat-square)](https://www.ycombinator.com/companies/cloudcruise)
+
+The official CloudCruise JavaScript/TypeScript client library for automated browser workflows, credential management, and real-time monitoring.
+
+## Installation
+
+```bash
+npm install cloudcruise
+```
+
+## Clients
+
+| Client                           | Description                                              | Documentation                                  |
+| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
+| [**Vault**](./src/vault)         | Encrypted credential storage with AES-256-GCM encryption | [📖 Vault Docs](./src/vault/README.md)         |
+| [**Workflows**](./src/workflows) | Workflow definitions, metadata, and input validation     | [📖 Workflows Docs](./src/workflows/README.md) |
+| [**Runs**](./src/runs)           | Workflow execution with real-time SSE streaming          | [📖 Runs Docs](./src/runs/README.md)           |
+| [**Webhook**](./src/webhook)     | Secure webhook payload verification with HMAC            | [📖 Webhook Docs](./src/webhook/README.md)     |
+
+## Documentation
+
+- [**API Documentation**](https://docs.cloudcruise.com) - Complete API reference and guides
+- [**CloudCruise Platform**](https://cloudcruise.com) - Learn more about CloudCruise
+
+## Development
+
+This project uses TypeScript and supports Node.js 18+. See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed development instructions.
+
+Quick start:
+
+```bash
+npm install     # Install dependencies
+npm run build   # Build TypeScript to JavaScript
+npm run dev     # Run in watch mode
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/CloudCruise.d.ts

@@ -0,0 +1,25 @@
+import { VaultClient } from './vault/VaultClient.js';
+import { WorkflowsClient } from './workflows/WorkflowsClient.js';
+import { RunsClient } from './runs/RunsClient.js';
+import { WebhookClient } from './webhook/WebhookClient.js';
+export interface CloudCruiseParams {
+    apiKey?: string;
+    baseUrl?: string;
+    encryptionKey?: string;
+}
+export declare class CloudCruise {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly encryptionKey;
+    readonly vault: VaultClient;
+    readonly workflows: WorkflowsClient;
+    readonly runs: RunsClient;
+    readonly webhook: WebhookClient;
+    private readonly connectionManager;
+    constructor(params?: CloudCruiseParams);
+    /**
+     * Makes an HTTP request to the CloudCruise API
+     * Automatically adds the cc-key header for authentication
+     */
+    private makeRequest;
+}

package/dist/CloudCruise.js

@@ -0,0 +1,81 @@
+import { getEnv } from './utils/env.js';
+import { VaultClient } from './vault/VaultClient.js';
+import { WorkflowsClient } from './workflows/WorkflowsClient.js';
+import { RunsClient } from './runs/RunsClient.js';
+import { WebhookClient } from './webhook/WebhookClient.js';
+import { ConnectionManager } from './utils/connectionManager.js';
+export class CloudCruise {
+    apiKey;
+    baseUrl;
+    encryptionKey;
+    vault;
+    workflows;
+    runs;
+    webhook;
+    connectionManager;
+    constructor(params) {
+        const apiKey = params?.apiKey ?? getEnv('CLOUDCRUISE_API_KEY');
+        const baseUrl = params?.baseUrl ?? getEnv('CLOUDCRUISE_BASE_URL') ?? 'https://api.cloudcruise.com';
+        const encryptionKey = params?.encryptionKey ?? getEnv('CLOUDCRUISE_ENCRYPTION_KEY');
+        if (!apiKey) {
+            throw new Error('Missing apiKey. Provide via params.apiKey or CLOUDCRUISE_API_KEY env var.');
+        }
+        if (!encryptionKey) {
+            throw new Error('Missing encryptionKey. Provide via params.encryptionKey or CLOUDCRUISE_ENCRYPTION_KEY env var.');
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.encryptionKey = encryptionKey;
+        // Initialize namespace clients
+        this.connectionManager = new ConnectionManager(this.baseUrl, this.apiKey);
+        this.vault = new VaultClient(this.makeRequest.bind(this), this.encryptionKey);
+        this.workflows = new WorkflowsClient(this.makeRequest.bind(this));
+        this.runs = new RunsClient(this.connectionManager, this.makeRequest.bind(this), this.workflows);
+        this.webhook = new WebhookClient();
+    }
+    /**
+     * Makes an HTTP request to the CloudCruise API
+     * Automatically adds the cc-key header for authentication
+     */
+    async makeRequest(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            'cc-key': this.apiKey
+        };
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+                try {
+                    const errorJson = JSON.parse(errorText);
+                    errorMessage = errorJson.message || errorJson.error || errorMessage;
+                }
+                catch {
+                    // Use HTTP status if we can't parse error response
+                }
+                throw new Error(errorMessage);
+            }
+            const contentType = response.headers.get('content-type');
+            if (contentType && contentType.includes('application/json')) {
+                return await response.json();
+            }
+            else {
+                return await response.text();
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw error;
+            }
+            else {
+                throw new Error(`Request failed: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CloudCruise JavaScript/TypeScript SDK
+ * Official client library for the CloudCruise Platform
+ */
+export { CloudCruise } from './CloudCruise.js';
+export type { CloudCruiseParams } from './CloudCruise.js';
+export { VaultClient } from './vault/VaultClient.js';
+export { WorkflowsClient } from './workflows/WorkflowsClient.js';
+export { RunsClient } from './runs/RunsClient.js';
+export { WebhookClient } from './webhook/WebhookClient.js';
+export type { VaultEntry, GetVaultEntriesFilters, ProxyConfig, VaultPostPutHeadersInBody } from './vault/types.js';
+export type { Workflow, WorkflowInputSchema, WorkflowMetadata } from './workflows/types.js';
+export type { EventType, DryRun, Metadata, RunSpecificWebhook, PayloadWebhook, StartRunRequest, StartRunResponse, UserInteractionData, VideoUrl, SignedFileUrl, SignedScreenshotUrl, RunError, WorkflowError, RunResult, GetRunResult, WebhookEvent, WebhookReplayResponse, RunHandle, RunStreamOptions, SseEventName, SseMessage, RunEventEnvelope } from './runs/types.js';
+export type { WebhookPayload, WebhookVerificationOptions } from './webhook/types.js';
+export { VerificationError } from './webhook/types.js';
+export { InputValidationError } from './workflows/types.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * CloudCruise JavaScript/TypeScript SDK
+ * Official client library for the CloudCruise Platform
+ */
+export { CloudCruise } from './CloudCruise.js';
+export { VaultClient } from './vault/VaultClient.js';
+export { WorkflowsClient } from './workflows/WorkflowsClient.js';
+export { RunsClient } from './runs/RunsClient.js';
+export { WebhookClient } from './webhook/WebhookClient.js';
+export { VerificationError } from './webhook/types.js';
+export { InputValidationError } from './workflows/types.js';

package/dist/runs/RunsClient.d.ts

@@ -0,0 +1,42 @@
+import type { StartRunRequest, UserInteractionData, GetRunResult, WebhookReplayResponse, RunHandle, RunStreamOptions } from './types.js';
+import { ConnectionManager } from '../utils/connectionManager.js';
+export declare class RunsClient {
+    private readonly makeRequest;
+    private readonly workflows?;
+    private readonly connectionManager;
+    constructor(connectionManager: ConnectionManager, makeRequest: <T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: any) => Promise<T>, workflows?: {
+        validateWorkflowInput: (workflowId: string, payload: Record<string, any>) => Promise<void>;
+    });
+    /**
+     * Queues a new run and returns a RunHandle.
+     * The handle exposes sessionId immediately and subscribes to SSE under the hood.
+     */
+    start(request: StartRunRequest, options?: RunStreamOptions): Promise<RunHandle>;
+    /**
+     * Subscribes to SSE events for a given session. Returns a handle with helpers.
+     */
+    subscribeToSession(sessionId: string, options?: RunStreamOptions): RunHandle;
+    /**
+     * Submits user interaction data during an active run
+     * @param sessionId - The unique identifier for the workflow execution session
+     * @param data - User input data as key-value pairs
+     */
+    submitUserInteraction(sessionId: string, data: UserInteractionData): Promise<void>;
+    /**
+     * Retrieves comprehensive results and execution details for a specific run
+     * @param sessionId - The unique identifier for the workflow execution session
+     * @returns Promise resolving to complete run results
+     */
+    getResults(sessionId: string): Promise<GetRunResult>;
+    /**
+     * Interrupts a running browser agent run
+     * @param sessionId - The unique identifier for the workflow execution session
+     */
+    interrupt(sessionId: string): Promise<void>;
+    /**
+     * Replays all webhooks that were sent during a session
+     * @param sessionId - The ID of the session to replay webhooks for
+     * @returns Promise resolving to webhook replay results
+     */
+    replayWebhooks(sessionId: string): Promise<WebhookReplayResponse>;
+}

package/dist/runs/RunsClient.js

@@ -0,0 +1,192 @@
+import { AsyncEventQueue } from '../utils/asyncQueue.js';
+import { SimpleEventEmitter } from '../utils/events.js';
+export class RunsClient {
+    makeRequest;
+    workflows;
+    connectionManager;
+    constructor(connectionManager, makeRequest, workflows) {
+        this.makeRequest = makeRequest;
+        this.workflows = workflows;
+        this.connectionManager = connectionManager;
+    }
+    /**
+     * Queues a new run and returns a RunHandle.
+     * The handle exposes sessionId immediately and subscribes to SSE under the hood.
+     */
+    async start(request, options) {
+        if (this.workflows) {
+            await this.workflows.validateWorkflowInput(request.workflow_id, request.run_input_variables);
+        }
+        // Ensure client_id and connection are ready to avoid missing early events
+        const clientId = await this.connectionManager.ensureClientId();
+        await this.connectionManager.connectIfNeeded();
+        request.client_id = clientId;
+        const { session_id } = await this.makeRequest('POST', '/run', request);
+        return this.subscribeToSession(session_id, options);
+    }
+    /**
+     * Subscribes to SSE events for a given session. Returns a handle with helpers.
+     */
+    subscribeToSession(sessionId, options) {
+        const emitter = new SimpleEventEmitter();
+        const stream = new AsyncEventQueue();
+        let ended = false;
+        let closed = false;
+        let sub = null;
+        const reconnectCfg = {
+            enabled: options?.reconnect?.enabled ?? true,
+            delays: options?.reconnect?.delays ?? [1000, 3000, 10000],
+        };
+        const isTerminalEvent = (status) => status === 'execution.success' || status === 'execution.failed' || status === 'execution.stopped';
+        const emit = (event, payload) => {
+            emitter.emit(event, payload);
+            // Mirror only SSE messages to 'message' for catch-all consumers
+            if (event === 'run.event' || event === 'ping') {
+                emitter.emit('message', payload);
+            }
+        };
+        const endAndCleanup = (status) => {
+            if (ended)
+                return;
+            ended = true;
+            closed = true;
+            try {
+                sub?.close();
+            }
+            catch { }
+            emit('end', { type: status });
+            stream.close();
+            emitter.clear();
+        };
+        const connect = () => {
+            sub = this.connectionManager.subscribe(sessionId, { signal: options?.signal });
+            const s = sub;
+            s.on('open', () => emit('open', undefined));
+            s.on('ping', (evt) => emit('ping', evt));
+            s.on('run.event', (msg) => {
+                const sseMsg = msg;
+                if (sseMsg.event !== 'run.event')
+                    return;
+                stream.push(sseMsg);
+                emit('run.event', sseMsg);
+                const eventType = sseMsg.data.event;
+                if (typeof eventType === 'string' && isTerminalEvent(eventType)) {
+                    endAndCleanup(eventType);
+                }
+            });
+            s.on('error', (err) => {
+                emit('error', err);
+                if (!reconnectCfg.enabled || ended || closed)
+                    return;
+                (async () => {
+                    for (const base of reconnectCfg.delays) {
+                        if (ended || closed)
+                            return;
+                        await new Promise(r => setTimeout(r, base));
+                        if (ended || closed)
+                            return;
+                        try {
+                            const snapshot = await this.getResults(sessionId);
+                            const status = snapshot?.status;
+                            if (isTerminalEvent(status)) {
+                                endAndCleanup(status);
+                                return;
+                            }
+                        }
+                        catch { }
+                        emit('reconnect', { attemptDelayMs: base });
+                        return; // manager handles reconnect of mux
+                    }
+                })();
+            });
+            s.on('reconnect', (e) => emit('reconnect', e));
+            s.on('end', (e) => {
+                const t = e?.type;
+                if (t && typeof t === 'string' && isTerminalEvent(t)) {
+                    endAndCleanup(t);
+                }
+                else {
+                    // End without explicit type; still clean up
+                    endAndCleanup('execution.stopped');
+                }
+            });
+        };
+        connect();
+        const client = this;
+        const handle = {
+            sessionId,
+            on: (event, handler) => emitter.on(event, handler),
+            async wait() {
+                if (ended) {
+                    return await client.getResults(sessionId);
+                }
+                return await new Promise((resolve, reject) => {
+                    const offEnd = handle.on('end', async () => {
+                        offErr();
+                        try {
+                            const result = await client.getResults(sessionId);
+                            resolve(result);
+                        }
+                        catch (e) {
+                            reject(e);
+                        }
+                    });
+                    const offErr = handle.on('error', (e) => {
+                        offEnd();
+                        reject(e instanceof Error ? e : new Error('SSE error'));
+                    });
+                });
+            },
+            close() {
+                closed = true;
+                try {
+                    sub?.close();
+                }
+                catch { }
+                stream.close();
+                emitter.clear();
+            },
+            async *[Symbol.asyncIterator]() {
+                for await (const msg of stream) {
+                    yield msg;
+                }
+            },
+        };
+        return handle;
+    }
+    /**
+     * Submits user interaction data during an active run
+     * @param sessionId - The unique identifier for the workflow execution session
+     * @param data - User input data as key-value pairs
+     */
+    async submitUserInteraction(sessionId, data) {
+        const path = `/run/${sessionId}/user_interaction`;
+        await this.makeRequest('POST', path, data);
+    }
+    /**
+     * Retrieves comprehensive results and execution details for a specific run
+     * @param sessionId - The unique identifier for the workflow execution session
+     * @returns Promise resolving to complete run results
+     */
+    async getResults(sessionId) {
+        const path = `/run/${sessionId}`;
+        return await this.makeRequest('GET', path);
+    }
+    /**
+     * Interrupts a running browser agent run
+     * @param sessionId - The unique identifier for the workflow execution session
+     */
+    async interrupt(sessionId) {
+        const path = `/run/${sessionId}/interrupt`;
+        await this.makeRequest('POST', path);
+    }
+    /**
+     * Replays all webhooks that were sent during a session
+     * @param sessionId - The ID of the session to replay webhooks for
+     * @returns Promise resolving to webhook replay results
+     */
+    async replayWebhooks(sessionId) {
+        const path = `/webhooks/${sessionId}/replay`;
+        return await this.makeRequest('POST', path);
+    }
+}

package/dist/runs/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * CloudCruise Runs API Type Definitions
+ */
+export type EventType = 'execution.queued' | 'execution.start' | 'execution.step' | 'execution.pause' | 'execution.stopped' | 'execution.failed' | 'execution.success' | 'execution.requeued' | 'file.uploaded' | 'screenshot.uploaded' | 'video.uploaded' | 'interaction.waiting' | 'interaction.finished' | 'interaction.failed';
+export interface DryRun {
+    enabled: boolean;
+    add_to_output?: Record<string, any>;
+}
+export interface Metadata {
+    metadata: Record<string, any>;
+}
+export interface RunSpecificWebhook {
+    url: string;
+    event_types_subscribed: EventType[];
+    secret: string;
+    validity: number;
+}
+export type PayloadWebhook = Metadata | RunSpecificWebhook;
+export interface StartRunRequest {
+    workflow_id: string;
+    run_input_variables: Record<string, any>;
+    dry_run?: DryRun;
+    webhook?: PayloadWebhook;
+    additional_context?: Record<string, any>;
+    client_id?: string;
+}
+export interface StartRunResponse {
+    session_id: string;
+}
+export type UserInteractionData = Record<string, any>;
+export interface VideoUrl {
+    timestamp: string;
+    session_id: string;
+    signed_screen_recording_url: string;
+    signed_screen_recording_url_expires: string;
+}
+export interface RunError {
+    prompt?: string | null;
+    message?: string | null;
+    error_id?: string | null;
+    full_url?: string | null;
+    llm_model?: string | null;
+    created_at?: string | null;
+    error_code?: string | null;
+    action_type?: string | null;
+    action_display_name?: string | null;
+}
+export interface SignedFileUrl {
+    signed_file_url: string;
+    file_name: string;
+    timestamp: string;
+    signed_file_url_expires: string;
+    metadata: Record<string, any>;
+}
+export interface SignedScreenshotUrl {
+    signed_screenshot_url: string;
+    node_display_name: string;
+    timestamp: string;
+    signed_screenshot_url_expires: string;
+    error_screenshot: boolean;
+    full_length_screenshot?: boolean;
+    retry_index?: number;
+}
+export interface WorkflowError {
+    message: string;
+    error_id: string;
+    full_url?: string | null;
+    created_at?: string | null;
+    error_code?: string | null;
+    action_type?: string | null;
+    action_display_name?: string | null;
+}
+export interface RunResult {
+    session_id: string;
+    status: EventType;
+    input_variables: Record<string, any>;
+    data: Record<string, any>;
+    video_urls: VideoUrl[];
+    file_urls: SignedFileUrl[];
+    screenshot_urls: SignedScreenshotUrl[];
+    errors: RunError[] | null;
+}
+export interface GetRunResult {
+    data: Record<string, any> | null;
+    session_id: string;
+    errors: WorkflowError[];
+    status: EventType;
+    input_variables: Record<string, any>;
+    workflow_id: string | null;
+    session_retries: number | null;
+    encrypted_variables: string[] | null;
+    video_urls: VideoUrl[] | null;
+    screenshot_urls?: SignedScreenshotUrl[] | null;
+    file_urls: SignedFileUrl[] | null;
+}
+export interface WebhookEvent {
+    success: boolean;
+    response: string;
+    error: string;
+}
+export interface WebhookReplayResponse {
+    status: string;
+    info: string;
+    nr_success: number;
+    nr_failed: number;
+    webhook_events: WebhookEvent[];
+}
+/**
+ * Streaming (SSE) types
+ */
+export type SseEventName = 'run.event' | 'ping';
+export interface RunEventEnvelope {
+    event: 'run.event';
+    data: {
+        event: EventType | string;
+        payload: {
+            session_id: string;
+            [key: string]: any;
+        };
+        expires_at: number;
+        timestamp: number;
+    };
+    timestamp?: string;
+    expires_at?: string;
+}
+export interface PingEnvelope {
+    event: 'ping';
+    data: {
+        ts: number;
+    } | Record<string, any>;
+}
+export type SseMessage = RunEventEnvelope | PingEnvelope;
+export interface RunStreamOptions {
+    signal?: AbortSignal;
+    withCredentials?: boolean;
+    headers?: Record<string, string>;
+    reconnect?: {
+        enabled?: boolean;
+        delays?: number[];
+        jitter?: number;
+    };
+}
+export interface RunHandle {
+    sessionId: string;
+    on(event: 'open' | 'reconnect' | 'error' | 'end' | SseEventName | 'message', handler: (e: unknown) => void): () => void;
+    wait(): Promise<GetRunResult>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SseMessage>;
+}

package/dist/runs/types.js

@@ -0,0 +1,4 @@
+/**
+ * CloudCruise Runs API Type Definitions
+ */
+export {};

package/dist/utils/asyncQueue.d.ts

@@ -0,0 +1,9 @@
+export declare class AsyncEventQueue<T> implements AsyncIterable<T> {
+    private items;
+    private pending;
+    private done;
+    push(item: T): void;
+    close(): void;
+    next(): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/utils/asyncQueue.js

@@ -0,0 +1,43 @@
+export class AsyncEventQueue {
+    items = [];
+    pending = null;
+    done = false;
+    push(item) {
+        if (this.done)
+            return;
+        if (this.pending) {
+            const resolve = this.pending;
+            this.pending = null;
+            resolve({ value: item, done: false });
+        }
+        else {
+            this.items.push(item);
+        }
+    }
+    close() {
+        if (this.done)
+            return;
+        this.done = true;
+        if (this.pending) {
+            const resolve = this.pending;
+            this.pending = null;
+            resolve({ value: undefined, done: true });
+        }
+    }
+    async next() {
+        if (this.items.length) {
+            return { value: this.items.shift(), done: false };
+        }
+        if (this.done) {
+            return { value: undefined, done: true };
+        }
+        return await new Promise(resolve => {
+            this.pending = resolve;
+        });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+        };
+    }
+}

package/dist/utils/connectionManager.d.ts

@@ -0,0 +1,29 @@
+import type { SseMessage } from '../runs/types.js';
+type Listener = (e: unknown) => void;
+interface SubscribeOptions {
+    signal?: AbortSignal;
+}
+export interface SessionSubscription {
+    on(event: string, handler: Listener): () => void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SseMessage>;
+}
+export declare class ConnectionManager {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private clientId;
+    private conn;
+    private connecting;
+    private connected;
+    private reconnecting;
+    private readonly reconnectDelays;
+    private readonly sessions;
+    constructor(baseUrl: string, apiKey: string);
+    ensureClientId(): Promise<string>;
+    private generateClientId;
+    connectIfNeeded(): Promise<void>;
+    subscribe(sessionId: string, opts?: SubscribeOptions): SessionSubscription;
+    private openMuxConnection;
+    private scheduleReconnect;
+}
+export {};