cloudcruise 0.0.6 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudcruise",
-  "version": "0.0.6",
+  "version": "1.0.0",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {
@@ -18,16 +18,16 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "pnpm build && node --test test/*.test.js"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "pnpm build && node --test test/*.test.js"
   }
-}
+}

package/dist/CloudCruise.d.ts

@@ -1,29 +0,0 @@
-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;
-    /**
-     * CloudCruise API base URL. Authenticated requests are restricted to the
-     * production CloudCruise API origin.
-     */
-    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

@@ -1,111 +0,0 @@
-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';
-const DEFAULT_BASE_URL = 'https://api.cloudcruise.com';
-const DEFAULT_API_HOST = new URL(DEFAULT_BASE_URL).host.toLowerCase();
-function normalizeBaseUrl(baseUrl) {
-    let url;
-    try {
-        url = new URL(baseUrl);
-    }
-    catch {
-        throw new Error(`Invalid baseUrl: ${baseUrl}`);
-    }
-    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
-        throw new Error(`Invalid baseUrl protocol: ${url.protocol}. Use https: or http:.`);
-    }
-    url.search = '';
-    url.hash = '';
-    return url.toString().replace(/\/+$/, '');
-}
-function assertBaseUrlAllowed(baseUrl) {
-    const url = new URL(baseUrl);
-    const host = url.host.toLowerCase();
-    if (host === DEFAULT_API_HOST && url.protocol !== 'https:') {
-        throw new Error(`Refusing to send CloudCruise API key to "${baseUrl}". The default CloudCruise API host requires https:.`);
-    }
-    if (baseUrl !== DEFAULT_BASE_URL) {
-        throw new Error(`Refusing to send CloudCruise API key to unapproved baseUrl "${baseUrl}". ` +
-            `Authenticated requests are restricted to ${DEFAULT_BASE_URL}.`);
-    }
-}
-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') ?? DEFAULT_BASE_URL;
-        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.');
-        }
-        const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
-        assertBaseUrlAllowed(normalizedBaseUrl);
-        this.apiKey = apiKey;
-        this.baseUrl = normalizedBaseUrl;
-        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/events/types.d.ts

@@ -1,153 +0,0 @@
-/**
- * Shared Event Type Definitions
- * Used by both Webhook and SSE Run event handlers
- */
-export declare enum EventType {
-    ExecutionQueued = "execution.queued",
-    ExecutionStart = "execution.start",
-    ExecutionStep = "execution.step",
-    ExecutionPause = "execution.pause",
-    ExecutionStopped = "execution.stopped",
-    ExecutionFailed = "execution.failed",
-    ExecutionSuccess = "execution.success",
-    ExecutionRequeued = "execution.requeued",
-    FileUploaded = "file.uploaded",
-    ScreenshotUploaded = "screenshot.uploaded",
-    VideoUploaded = "video.uploaded",
-    InteractionWaiting = "interaction.waiting",
-    InteractionFinished = "interaction.finished",
-    InteractionFailed = "interaction.failed",
-    AgentErrorAnalysis = "agent.error_analysis"
-}
-export interface ExecutionQueuedPayload {
-    session_id: string;
-    workflow_id: string;
-}
-export interface ExecutionStartPayload {
-    session_id: string;
-    workflow_id: string;
-    live_view_url?: string;
-}
-export interface ExecutionStepPayload {
-    session_id: string;
-    workflow_id: string;
-    current_step: string;
-    next_step: string;
-}
-export interface InteractionWaitingPayload {
-    session_id: string;
-    workflow_id: string;
-    current_step: string;
-    missing_properties: string[];
-    expected_json_schema_datamodel: Record<string, any>;
-    message: string;
-}
-export type InteractionFinishedPayload = {
-    session_id: string;
-    workflow_id: string;
-    current_step: string;
-    missing_properties: [];
-    expected_json_schema_datamodel: Record<string, any>;
-    message: string;
-} | {
-    session_id: string;
-    workflow_id: string;
-    provided_input: any;
-    message?: string;
-    expected_json_schema_datamodel: Record<string, any>;
-};
-export interface AgentErrorAnalysisPayload {
-    analysis_step_name: string;
-    ai_analysis?: string;
-    root_cause_analysis?: string;
-    error_category?: string;
-}
-export interface ExecutionRequeuedPayload {
-    session_id: string;
-    workflow_id: string;
-    retry_attempt: number;
-    max_retries?: number;
-    next_execution_time: string;
-    delay_ms: number;
-}
-export interface EndRunError {
-    message: string;
-    error_id: string;
-    full_url?: string;
-    created_at: string;
-    error_code?: string;
-    action_type?: string;
-    action_display_name?: string;
-    llm_error_category?: string;
-}
-export interface EndRunPayload {
-    session_id: string;
-    workflow_id: string;
-    data: any;
-    input_variables: Record<string, any>;
-    errors: EndRunError[];
-    status: EventType.ExecutionSuccess | EventType.ExecutionFailed | EventType.ExecutionStopped;
-    encrypted_variables: string[] | null;
-    file_urls: any[] | null;
-    vault_entries: Record<string, any> | null;
-}
-export interface ExecutionStoppedEarlyPayload {
-    message: string;
-    error_code: string;
-    session_id: string;
-}
-export interface FileUploadedPayload {
-    signed_file_url: string;
-    file_name: string;
-    timestamp: string;
-    signed_file_url_expires: string;
-    metadata: Record<string, any>;
-    session_id: string;
-}
-export interface ScreenshotUploadedPayload {
-    screenshot_id: string;
-    signed_screenshot_url: string;
-    node_display_name: string;
-    node_id: string;
-    timestamp: string;
-    signed_screenshot_url_expires: string;
-    error_screenshot: boolean;
-    retry_index: number;
-    full_length_screenshot: boolean;
-    session_id: string;
-}
-export type EventPayloadMap = {
-    [EventType.ExecutionQueued]: ExecutionQueuedPayload;
-    [EventType.ExecutionStart]: ExecutionStartPayload;
-    [EventType.ExecutionStep]: ExecutionStepPayload;
-    [EventType.InteractionWaiting]: InteractionWaitingPayload;
-    [EventType.InteractionFinished]: InteractionFinishedPayload;
-    [EventType.AgentErrorAnalysis]: AgentErrorAnalysisPayload;
-    [EventType.ExecutionRequeued]: ExecutionRequeuedPayload;
-    [EventType.ExecutionSuccess]: EndRunPayload;
-    [EventType.ExecutionFailed]: EndRunPayload;
-    [EventType.ExecutionStopped]: EndRunPayload | ExecutionStoppedEarlyPayload;
-    [EventType.FileUploaded]: FileUploadedPayload;
-    [EventType.ScreenshotUploaded]: ScreenshotUploadedPayload;
-    [EventType.VideoUploaded]: never;
-    [EventType.ExecutionPause]: never;
-    [EventType.InteractionFailed]: never;
-};
-export type WebhookMessage<E extends EventType = EventType> = {
-    event: E;
-    timestamp: number;
-    expires_at: number;
-    payload: EventPayloadMap[E];
-    metadata?: Record<string, any>;
-};
-export type RunEventMessage<E extends EventType = EventType> = {
-    event: "run.event";
-    data: {
-        event: E;
-        payload: EventPayloadMap[E];
-        timestamp: number;
-        expires_at: number;
-    };
-    timestamp: string;
-    expires_at: string;
-};

package/dist/events/types.js

@@ -1,22 +0,0 @@
-/**
- * Shared Event Type Definitions
- * Used by both Webhook and SSE Run event handlers
- */
-export var EventType;
-(function (EventType) {
-    EventType["ExecutionQueued"] = "execution.queued";
-    EventType["ExecutionStart"] = "execution.start";
-    EventType["ExecutionStep"] = "execution.step";
-    EventType["ExecutionPause"] = "execution.pause";
-    EventType["ExecutionStopped"] = "execution.stopped";
-    EventType["ExecutionFailed"] = "execution.failed";
-    EventType["ExecutionSuccess"] = "execution.success";
-    EventType["ExecutionRequeued"] = "execution.requeued";
-    EventType["FileUploaded"] = "file.uploaded";
-    EventType["ScreenshotUploaded"] = "screenshot.uploaded";
-    EventType["VideoUploaded"] = "video.uploaded";
-    EventType["InteractionWaiting"] = "interaction.waiting";
-    EventType["InteractionFinished"] = "interaction.finished";
-    EventType["InteractionFailed"] = "interaction.failed";
-    EventType["AgentErrorAnalysis"] = "agent.error_analysis";
-})(EventType || (EventType = {}));

package/dist/index.d.ts

@@ -1,18 +0,0 @@
-/**
- * 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 { DryRun, Metadata, RunSpecificWebhook, PayloadWebhook, StartRunRequest, StartRunResponse, UserInteractionData, VideoUrl, SignedFileUrl, SignedScreenshotUrl, RunError, WorkflowError, RunResult, GetRunResult, WebhookEvent, WebhookReplayResponse, RunHandle, RunStreamOptions, SseEventName, SseMessage, RunEventEnvelope, RunHandleEventMap } from './runs/types.js';
-export { EventType } from './events/types.js';
-export type { WebhookMessage, RunEventMessage } from './events/types.js';
-export type { WebhookVerificationOptions } from './webhook/types.js';
-export { VerificationError } from './webhook/types.js';
-export { InputValidationError } from './workflows/types.js';

package/dist/index.js

@@ -1,13 +0,0 @@
-/**
- * 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 shared event types
-export { EventType } from './events/types.js';
-export { VerificationError } from './webhook/types.js';
-export { InputValidationError } from './workflows/types.js';

package/dist/runs/RunsClient.d.ts

@@ -1,42 +0,0 @@
-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

@@ -1,200 +0,0 @@
-import { EventType } from '../events/types.js';
-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 === EventType.ExecutionSuccess ||
-            status === EventType.ExecutionFailed ||
-            status === EventType.ExecutionStopped;
-        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);
-                // Emit typed per-event key for better DX
-                try {
-                    emitter.emit(sseMsg.data.event, sseMsg);
-                }
-                catch { }
-                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(EventType.ExecutionStopped);
-                }
-            });
-        };
-        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);
-    }
-}