cloudcruise 0.0.2 → 0.0.4

package/dist/events/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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;
+}
+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

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

@@ -10,7 +10,9 @@ 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 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

@@ -7,5 +7,7 @@ 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.js

@@ -1,3 +1,4 @@
+import { EventType } from '../events/types.js';
 import { AsyncEventQueue } from '../utils/asyncQueue.js';
 import { SimpleEventEmitter } from '../utils/events.js';
 export class RunsClient {
@@ -37,7 +38,9 @@ export class RunsClient {
             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 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
@@ -69,6 +72,11 @@ export class RunsClient {
                     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);
@@ -107,7 +115,7 @@ export class RunsClient {
                 }
                 else {
                     // End without explicit type; still clean up
-                    endAndCleanup('execution.stopped');
+                    endAndCleanup(EventType.ExecutionStopped);
                 }
             });
         };

package/dist/runs/types.d.ts

@@ -1,7 +1,9 @@
 /**
  * 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';
+import type { EventType, RunEventMessage, EventPayloadMap, ExecutionQueuedPayload, ExecutionStartPayload, ExecutionStepPayload, InteractionWaitingPayload, InteractionFinishedPayload, AgentErrorAnalysisPayload, ExecutionRequeuedPayload, EndRunPayload, EndRunError, ExecutionStoppedEarlyPayload, FileUploadedPayload, ScreenshotUploadedPayload } from '../events/types.js';
+export type { EventType };
+export type { ExecutionQueuedPayload, ExecutionStartPayload, ExecutionStepPayload, InteractionWaitingPayload, InteractionFinishedPayload, AgentErrorAnalysisPayload, ExecutionRequeuedPayload, EndRunPayload, EndRunError, ExecutionStoppedEarlyPayload, FileUploadedPayload, ScreenshotUploadedPayload, EventPayloadMap, };
 export interface DryRun {
     enabled: boolean;
     add_to_output?: Record<string, any>;
@@ -109,27 +111,14 @@ export interface WebhookReplayResponse {
  * 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 type RunEventEnvelope<E extends EventType = EventType> = RunEventMessage<E>;
 export interface PingEnvelope {
     event: 'ping';
     data: {
         ts: number;
     } | Record<string, any>;
 }
-export type SseMessage = RunEventEnvelope | PingEnvelope;
+export type SseMessage<E extends EventType = EventType> = RunEventEnvelope<E> | PingEnvelope;
 export interface RunStreamOptions {
     signal?: AbortSignal;
     withCredentials?: boolean;
@@ -140,9 +129,26 @@ export interface RunStreamOptions {
         jitter?: number;
     };
 }
+export type RunEventMap = {
+    [K in EventType]: RunEventEnvelope<K>;
+};
+export type RunHandleEventMap = {
+    'open': undefined;
+    'close': undefined;
+    'reconnect': {
+        attemptDelayMs: number;
+    };
+    'error': unknown;
+    'end': {
+        type: EventType;
+    };
+    'run.event': SseMessage;
+    'ping': PingEnvelope;
+    'message': SseMessage | PingEnvelope;
+} & RunEventMap;
 export interface RunHandle {
     sessionId: string;
-    on(event: 'open' | 'reconnect' | 'error' | 'end' | SseEventName | 'message', handler: (e: unknown) => void): () => void;
+    on<K extends keyof RunHandleEventMap>(event: K, handler: (e: RunHandleEventMap[K]) => void): () => void;
     wait(): Promise<GetRunResult>;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<SseMessage>;

package/dist/utils/connectionManager.js

@@ -1,8 +1,11 @@
 import { openSSE } from './sse.js';
 import { SimpleEventEmitter } from './events.js';
 import { AsyncEventQueue } from './asyncQueue.js';
+import { EventType } from '../events/types.js';
 function isFinalEvent(eventType) {
-    return eventType === 'execution.success' || eventType === 'execution.failed' || eventType === 'execution.stopped';
+    return (eventType === EventType.ExecutionSuccess ||
+        eventType === EventType.ExecutionFailed ||
+        eventType === EventType.ExecutionStopped);
 }
 export class ConnectionManager {
     baseUrl;
@@ -144,7 +147,9 @@ export class ConnectionManager {
                         if (!data) {
                             return;
                         }
-                        const sessionId = data.payload?.session_id;
+                        // Extract session_id - it's always present in payload
+                        const payload = data.payload;
+                        const sessionId = payload?.session_id;
                         if (!sessionId) {
                             return;
                         }
@@ -152,7 +157,12 @@ export class ConnectionManager {
                         if (!channel) {
                             return;
                         }
-                        const msg = { event: 'run.event', data };
+                        const msg = {
+                            event: 'run.event',
+                            data: data,
+                            timestamp: raw.timestamp || new Date().toISOString(),
+                            expires_at: raw.expires_at || new Date(Date.now() + 3600000).toISOString()
+                        };
                         // fan-out to all subscribers
                         for (const q of channel.subscribers)
                             q.push(msg);

package/dist/utils/events.d.ts

@@ -1,7 +1,24 @@
 export type EventHandler<T = unknown> = (event: T) => void;
-export declare class SimpleEventEmitter {
+/**
+ * Event emitter that supports both typed and untyped usage.
+ *
+ * - Use without type parameter for untyped events (backward compatible)
+ * - Use with EventMap type parameter for type-safe events
+ *
+ * @example
+ * // Untyped usage
+ * const emitter = new SimpleEventEmitter();
+ * emitter.on('foo', (data) => console.log(data));
+ *
+ * @example
+ * // Typed usage
+ * type Events = { foo: string; bar: number };
+ * const emitter = new SimpleEventEmitter<Events>();
+ * emitter.on('foo', (data) => console.log(data)); // data is string
+ */
+export declare class SimpleEventEmitter<EventMap extends Record<string, any> = Record<string, unknown>> {
     private listeners;
-    on(event: string, handler: EventHandler<unknown>): () => void;
-    emit(event: string, payload?: unknown): void;
+    on<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): () => void;
+    emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
     clear(): void;
 }

package/dist/utils/events.js

@@ -1,3 +1,20 @@
+/**
+ * Event emitter that supports both typed and untyped usage.
+ *
+ * - Use without type parameter for untyped events (backward compatible)
+ * - Use with EventMap type parameter for type-safe events
+ *
+ * @example
+ * // Untyped usage
+ * const emitter = new SimpleEventEmitter();
+ * emitter.on('foo', (data) => console.log(data));
+ *
+ * @example
+ * // Typed usage
+ * type Events = { foo: string; bar: number };
+ * const emitter = new SimpleEventEmitter<Events>();
+ * emitter.on('foo', (data) => console.log(data)); // data is string
+ */
 export class SimpleEventEmitter {
     listeners = new Map();
     on(event, handler) {

package/dist/webhook/WebhookClient.d.ts

@@ -1,5 +1,15 @@
-import type { WebhookPayload, WebhookVerificationOptions } from './types.js';
+import type { WebhookVerificationOptions } from './types.js';
+import type { EventType, WebhookMessage } from '../events/types.js';
 export declare class WebhookClient {
     constructor();
-    verifySignature(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookPayload;
+    /**
+     * Verifies the signature of an incoming webhook payload.
+     *
+     * @param receivedData - Raw request body supplied by the webhook sender.
+     * @param receivedSignature - Value from the `x-hmac-signature` request header. e.g req.headers["x-hmac-signature"]
+     * @param secretKey - Webhook secret configured in the CloudCruise portal.
+     * @param options - Optional overrides controlling signature verification behavior.
+     * @returns Verified webhook payload when the signature matches.
+     */
+    verifySignature<E extends EventType = EventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookMessage<E>;
 }

package/dist/webhook/WebhookClient.js

@@ -3,11 +3,15 @@ export class WebhookClient {
     constructor() {
         // No makeRequest needed for webhook verification
     }
-    /*
-    1. receivedSignature will be in the request header: "x-hmac-signature"
-    2. receivedData will be the request body.
-    3. secretKey is the key you set when creating this webhook in the CloudCruise portal.
-    */
+    /**
+     * Verifies the signature of an incoming webhook payload.
+     *
+     * @param receivedData - Raw request body supplied by the webhook sender.
+     * @param receivedSignature - Value from the `x-hmac-signature` request header. e.g req.headers["x-hmac-signature"]
+     * @param secretKey - Webhook secret configured in the CloudCruise portal.
+     * @param options - Optional overrides controlling signature verification behavior.
+     * @returns Verified webhook payload when the signature matches.
+     */
     verifySignature(receivedData, receivedSignature, secretKey, options) {
         return verifyMessage(receivedData, receivedSignature, secretKey, options);
     }

package/dist/webhook/types.d.ts

@@ -1,13 +1,7 @@
-import { EventType } from "../runs/types";
 export declare class VerificationError extends Error {
     readonly statusCode: number;
     constructor(message?: string, statusCode?: number);
 }
-export interface WebhookPayload {
-    event: EventType;
-    expires_at: number;
-    [key: string]: any;
-}
 export interface WebhookVerificationOptions {
     allowExpired?: boolean;
 }

package/dist/webhook/utils.d.ts

@@ -1,2 +1,3 @@
-import { type WebhookPayload, type WebhookVerificationOptions } from './types.js';
-export declare function verifyMessage(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookPayload;
+import type { EventType, WebhookMessage } from '../events/types.js';
+import { type WebhookVerificationOptions } from './types.js';
+export declare function verifyMessage<E extends EventType = EventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookMessage<E>;

package/package.json

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