cloudcruise 1.0.0 → 1.1.0

package/dist/CloudCruise.d.ts

@@ -0,0 +1,29 @@
+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 or the staging 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

@@ -0,0 +1,113 @@
+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 STAGING_BASE_URL = 'https://staging-api.cloudcruise.app';
+const ALLOWED_BASE_URLS = new Set([DEFAULT_BASE_URL, STAGING_BASE_URL]);
+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 (!ALLOWED_BASE_URLS.has(baseUrl)) {
+        throw new Error(`Refusing to send CloudCruise API key to unapproved baseUrl "${baseUrl}". ` +
+            `Authenticated requests are restricted to: ${Array.from(ALLOWED_BASE_URLS).join(", ")}.`);
+    }
+}
+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

@@ -0,0 +1,186 @@
+/**
+ * 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",
+    ExecutionInputRequired = "execution.input_required"
+}
+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;
+    phase?: "modal_decision_dispatched" | "popup_dismiss_verified" | string;
+    session_id?: string;
+    modal_action?: string;
+    modal_action_label?: string;
+    response_time_ms?: number;
+    outcome?: "success" | "failure";
+    host?: string;
+    popup_signature?: string;
+}
+export interface AvailableAction {
+    id: string;
+    label: string;
+}
+export interface PopupRetry {
+    attempt: number;
+    max_attempts: number;
+}
+export interface PopupContext {
+    error_description: string;
+    error_sub_type?: string;
+    full_url?: string;
+    available_actions: AvailableAction[];
+    retry: PopupRetry;
+}
+export type InputRequiredReason = "input_required" | "incorrect_form_input" | "multiple_matching_results" | "non_dismissible_popup";
+export interface ExecutionInputRequiredPayload {
+    session_id: string;
+    input_variables: Record<string, any>;
+    screenshot_url: string | null;
+    reason?: InputRequiredReason;
+    popup_context?: PopupContext;
+}
+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;
+    [EventType.ExecutionInputRequired]: ExecutionInputRequiredPayload;
+};
+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

@@ -0,0 +1,23 @@
+/**
+ * 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["ExecutionInputRequired"] = "execution.input_required";
+})(EventType || (EventType = {}));

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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, AvailableAction, PopupRetry, PopupContext, InputRequiredReason, ExecutionInputRequiredPayload, AgentErrorAnalysisPayload } 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

@@ -0,0 +1,13 @@
+/**
+ * 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

@@ -0,0 +1,101 @@
+import type { StartRunRequest, UserInteractionData, GetRunResult, WebhookReplayResponse, RunHandle, RunStreamOptions } from './types.js';
+import type { PopupContext, ExecutionInputRequiredPayload } from '../events/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>;
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "non_dismissible_popup" by picking one of the CTA buttons surfaced in
+     * popup_context.available_actions. The backend dispatches a synthetic
+     * click on the chosen button and resumes the workflow.
+     *
+     * Only valid while the session is waiting for input. The backing endpoint
+     * returns 400 if the wait already expired (the workspace setting
+     * input_required_timeout_seconds, default 15s, max 300s).
+     *
+     * @param sessionId - The session waiting for input.
+     * @param actionId - One of the ids in popup_context.available_actions.
+     */
+    submitModalAction(sessionId: string, actionId: string): Promise<void>;
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "input_required", "incorrect_form_input", or "multiple_matching_results"
+     * by supplying the corrected/required input variables. Backend resumes from
+     * the appropriate recovery node with the new values substituted in.
+     *
+     * Mutually exclusive with submitModalAction at the endpoint level.
+     *
+     * @param sessionId - The session waiting for input.
+     * @param inputVariables - Mapping of variable name to new value.
+     */
+    submitInputVariables(sessionId: string, inputVariables: Record<string, any>): Promise<void>;
+    /**
+     * Registers a listener that auto-responds ONLY to non-dismissible modal
+     * input_required events (reason === "non_dismissible_popup"). The decider
+     * receives the popup_context and must return one of the action ids in
+     * popup_context.available_actions.
+     *
+     * The SDK never picks an action on its own. The customer's decider IS the
+     * decision point. If decider throws, the listener swallows it and skips
+     * submission; the backend's input wait will time out naturally.
+     *
+     * Other input_required reasons (incorrect_form_input, etc.) are ignored
+     * here and should be routed to onInputVariablesRequired.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onPopupDecisionRequired(handle: RunHandle, decider: (ctx: PopupContext) => string | Promise<string>, onError?: (err: unknown) => void, options?: {
+        verbose?: boolean;
+    }): () => void;
+    /**
+     * Registers a listener that auto-responds ONLY to workflow-variable
+     * input_required events (reason in {"input_required",
+     * "incorrect_form_input", "multiple_matching_results"}). The decider
+     * receives the full payload and must return the input_variables dict.
+     *
+     * Counterpart to onPopupDecisionRequired. Modal events
+     * (reason === "non_dismissible_popup") are routed there and ignored here.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onInputVariablesRequired(handle: RunHandle, decider: (payload: ExecutionInputRequiredPayload) => Record<string, any> | Promise<Record<string, any>>, onError?: (err: unknown) => void, options?: {
+        verbose?: boolean;
+    }): () => 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>;
+}