cloudcruise 1.0.1 → 1.1.0

package/dist/CloudCruise.d.ts

@@ -6,7 +6,7 @@ export interface CloudCruiseParams {
     apiKey?: string;
     /**
      * CloudCruise API base URL. Authenticated requests are restricted to the
-     * production CloudCruise API origin.
+     * production CloudCruise API origin or the staging API origin.
      */
     baseUrl?: string;
     encryptionKey?: string;

package/dist/CloudCruise.js

@@ -5,6 +5,8 @@ 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;
@@ -27,9 +29,9 @@ function assertBaseUrlAllowed(baseUrl) {
     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) {
+    if (!ALLOWED_BASE_URLS.has(baseUrl)) {
         throw new Error(`Refusing to send CloudCruise API key to unapproved baseUrl "${baseUrl}". ` +
-            `Authenticated requests are restricted to ${DEFAULT_BASE_URL}.`);
+            `Authenticated requests are restricted to: ${Array.from(ALLOWED_BASE_URLS).join(", ")}.`);
     }
 }
 export class CloudCruise {

package/dist/events/types.d.ts

@@ -17,7 +17,8 @@ export declare enum EventType {
     InteractionWaiting = "interaction.waiting",
     InteractionFinished = "interaction.finished",
     InteractionFailed = "interaction.failed",
-    AgentErrorAnalysis = "agent.error_analysis"
+    AgentErrorAnalysis = "agent.error_analysis",
+    ExecutionInputRequired = "execution.input_required"
 }
 export interface ExecutionQueuedPayload {
     session_id: string;
@@ -61,6 +62,37 @@ export interface AgentErrorAnalysisPayload {
     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;
@@ -132,6 +164,7 @@ export type EventPayloadMap = {
     [EventType.VideoUploaded]: never;
     [EventType.ExecutionPause]: never;
     [EventType.InteractionFailed]: never;
+    [EventType.ExecutionInputRequired]: ExecutionInputRequiredPayload;
 };
 export type WebhookMessage<E extends EventType = EventType> = {
     event: E;

package/dist/events/types.js

@@ -19,4 +19,5 @@ export var EventType;
     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

@@ -12,7 +12,7 @@ export type { VaultEntry, GetVaultEntriesFilters, ProxyConfig, VaultPostPutHeade
 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 { 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/runs/RunsClient.d.ts

@@ -1,4 +1,5 @@
 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;
@@ -22,6 +23,64 @@ export declare class RunsClient {
      * @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

package/dist/runs/RunsClient.js

@@ -1,6 +1,37 @@
 import { EventType } from '../events/types.js';
 import { AsyncEventQueue } from '../utils/asyncQueue.js';
 import { SimpleEventEmitter } from '../utils/events.js';
+/**
+ * Default error reporter for the recovery helpers. Writes to console.error
+ * so submission failures surface in customer logs even if no onError
+ * callback is provided. The runtime SimpleEventEmitter ignores async-handler
+ * returns, so without this default a rejection from /new_input_variables
+ * would become a silent unhandled rejection.
+ */
+function defaultRecoverySubmitErrorLog(operation) {
+    return (err) => {
+        try {
+            const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+            console.error(`[CloudCruise SDK] ${operation} failed during recovery: ${msg}`);
+        }
+        catch {
+            // never throw from the error reporter
+        }
+    };
+}
+/**
+ * Helper for `verbose: true` mode on the recovery helpers. Writes a single
+ * line to console.error so customers can watch the recovery loop without
+ * instrumenting their own decider.
+ */
+function verboseLog(operation, message) {
+    try {
+        console.error(`[CloudCruise SDK verbose] ${operation}: ${message}`);
+    }
+    catch {
+        // never throw
+    }
+}
 export class RunsClient {
     makeRequest;
     workflows;
@@ -171,6 +202,175 @@ export class RunsClient {
         const path = `/run/${sessionId}/user_interaction`;
         await this.makeRequest('POST', path, data);
     }
+    /**
+     * 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.
+     */
+    async submitModalAction(sessionId, actionId) {
+        const path = `/run/${sessionId}/new_input_variables`;
+        await this.makeRequest('POST', path, { modal_action: actionId });
+    }
+    /**
+     * 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.
+     */
+    async submitInputVariables(sessionId, inputVariables) {
+        const path = `/run/${sessionId}/new_input_variables`;
+        await this.makeRequest('POST', path, { input_variables: inputVariables });
+    }
+    /**
+     * 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, decider, onError, options) {
+        const verbose = options?.verbose === true;
+        const reportError = (err) => {
+            const reporter = onError ?? defaultRecoverySubmitErrorLog('submitModalAction');
+            try {
+                reporter(err);
+            }
+            catch {
+                // defense: a buggy onError must not crash the event loop
+            }
+        };
+        if (verbose)
+            verboseLog('onPopupDecisionRequired', 'listener registered');
+        const listener = async (event) => {
+            const payload = (event?.data?.payload ?? event?.payload);
+            if (!payload || payload.reason !== 'non_dismissible_popup' || !payload.popup_context) {
+                if (verbose) {
+                    verboseLog('onPopupDecisionRequired', `skipping reason=${payload?.reason ?? 'undefined'}`);
+                }
+                return;
+            }
+            if (verbose) {
+                const attempt = payload.popup_context.retry?.attempt;
+                const actions = payload.popup_context.available_actions?.map((a) => a.id) ?? [];
+                verboseLog('onPopupDecisionRequired', `event received attempt=${attempt} actions=${JSON.stringify(actions)}`);
+            }
+            let actionId;
+            try {
+                actionId = await decider(payload.popup_context);
+            }
+            catch (e) {
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `decider raised: ${e}`);
+                return;
+            }
+            if (typeof actionId !== 'string' || actionId.length === 0) {
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `decider returned non-string/empty (${JSON.stringify(actionId)}); skipping`);
+                return;
+            }
+            const sid = payload.session_id || handle.sessionId;
+            if (verbose)
+                verboseLog('onPopupDecisionRequired', `submitting modal_action=${JSON.stringify(actionId)} for session=${sid}`);
+            try {
+                await this.submitModalAction(sid, actionId);
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `submit ok for action=${JSON.stringify(actionId)}`);
+            }
+            catch (err) {
+                reportError(err);
+            }
+        };
+        const unsubscribe = handle.on(EventType.ExecutionInputRequired, listener);
+        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
+    }
+    /**
+     * 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, decider, onError, options) {
+        const verbose = options?.verbose === true;
+        const VARIABLE_REASONS = new Set([
+            'input_required',
+            'incorrect_form_input',
+            'multiple_matching_results',
+        ]);
+        const reportError = (err) => {
+            const reporter = onError ?? defaultRecoverySubmitErrorLog('submitInputVariables');
+            try {
+                reporter(err);
+            }
+            catch {
+                // defense
+            }
+        };
+        if (verbose)
+            verboseLog('onInputVariablesRequired', 'listener registered');
+        const listener = async (event) => {
+            const payload = (event?.data?.payload ?? event?.payload);
+            if (!payload || !payload.reason || !VARIABLE_REASONS.has(payload.reason)) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `skipping reason=${payload?.reason ?? 'undefined'}`);
+                return;
+            }
+            if (verbose)
+                verboseLog('onInputVariablesRequired', `event received reason=${payload.reason}`);
+            let inputVars;
+            try {
+                inputVars = await decider(payload);
+            }
+            catch (e) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `decider raised: ${e}`);
+                return;
+            }
+            if (!inputVars || typeof inputVars !== 'object' || Array.isArray(inputVars)) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `decider returned non-object (${Array.isArray(inputVars) ? 'array' : typeof inputVars}); skipping`);
+                return;
+            }
+            const sid = payload.session_id || handle.sessionId;
+            if (verbose)
+                verboseLog('onInputVariablesRequired', `submitting input_variables keys=${JSON.stringify(Object.keys(inputVars))} for session=${sid}`);
+            try {
+                await this.submitInputVariables(sid, inputVars);
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', 'submit ok');
+            }
+            catch (err) {
+                reportError(err);
+            }
+        };
+        const unsubscribe = handle.on(EventType.ExecutionInputRequired, listener);
+        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
+    }
     /**
      * Retrieves comprehensive results and execution details for a specific run
      * @param sessionId - The unique identifier for the workflow execution session

package/dist/vault/types.d.ts

@@ -38,6 +38,8 @@ export interface VaultEntry {
     cookie_domain_to_store?: string | null;
     proxy?: ProxyConfig;
     proxy_string?: string | null;
+    proxy_setting?: 'random' | 'static' | 'country' | 'custom' | null;
+    proxy_value?: string | null;
     headers?: VaultPostPutHeadersInBody[];
     created_at?: string | null;
     session_data_set_at?: string | null;

package/dist/vault/utils.d.ts

@@ -18,7 +18,8 @@ export declare function encryptData(data: any, keyHex: string): Promise<string>;
 export declare function decryptData(encryptedHex: string, keyHex: string): Promise<any>;
 /**
  * Encrypts sensitive fields in a vault entry
- * Fields encrypted: user_name, password, tfa_secret (if present)
+ * Fields encrypted: user_name, password, tfa_secret (if present), and
+ * proxy_value when proxy_setting is "custom" (the bring-your-own proxy URL).
  * @param entry - Vault entry with potentially sensitive data
  * @param encryptionKey - Hex-encoded encryption key
  * @returns Entry with encrypted sensitive fields

package/dist/vault/utils.js

@@ -51,7 +51,8 @@ export async function decryptData(encryptedHex, keyHex) {
 }
 /**
  * Encrypts sensitive fields in a vault entry
- * Fields encrypted: user_name, password, tfa_secret (if present)
+ * Fields encrypted: user_name, password, tfa_secret (if present), and
+ * proxy_value when proxy_setting is "custom" (the bring-your-own proxy URL).
  * @param entry - Vault entry with potentially sensitive data
  * @param encryptionKey - Hex-encoded encryption key
  * @returns Entry with encrypted sensitive fields
@@ -67,6 +68,22 @@ export async function encryptSensitiveFields(entry, encryptionKey) {
     if (entry.tfa_secret !== undefined) {
         encryptedEntry.tfa_secret = await encryptData(entry.tfa_secret, encryptionKey);
     }
+    // proxy_value is meaningless to the backend without proxy_setting, which is
+    // also the discriminator that tells us whether to encrypt. Fail closed: a
+    // custom proxy URL (often with embedded credentials) must never be sent in
+    // plaintext because the caller forgot the mode on a partial update.
+    if (entry.proxy_value !== undefined &&
+        entry.proxy_value !== null &&
+        (entry.proxy_setting === undefined || entry.proxy_setting === null)) {
+        throw new Error("proxy_value requires proxy_setting. Pass proxy_setting: 'custom' for a " +
+            "bring-your-own proxy URL (so it is encrypted before sending), or " +
+            "'static'/'country' for a managed proxy.");
+    }
+    if (entry.proxy_setting === 'custom' &&
+        entry.proxy_value !== undefined &&
+        entry.proxy_value !== null) {
+        encryptedEntry.proxy_value = await encryptData(entry.proxy_value, encryptionKey);
+    }
     return encryptedEntry;
 }
 /**
@@ -95,5 +112,11 @@ export async function decryptSensitiveFields(entry, encryptionKey) {
         }
         catch { }
     }
+    if (entry.proxy_setting === 'custom' && typeof entry.proxy_value === 'string') {
+        try {
+            decryptedEntry.proxy_value = await decryptData(entry.proxy_value, encryptionKey);
+        }
+        catch { }
+    }
     return decryptedEntry;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudcruise",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {