cloudcruise 0.0.3 → 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,8 +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 { WebhookEventType } from './webhook/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,6 +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 { WebhookEventType } from './webhook/types.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,4 +1,5 @@
-import type { WebhookEventType, WebhookPayload, WebhookVerificationOptions } from './types.js';
+import type { WebhookVerificationOptions } from './types.js';
+import type { EventType, WebhookMessage } from '../events/types.js';
 export declare class WebhookClient {
     constructor();
     /**
@@ -10,5 +11,5 @@ export declare class WebhookClient {
      * @param options - Optional overrides controlling signature verification behavior.
      * @returns Verified webhook payload when the signature matches.
      */
-    verifySignature<E extends WebhookEventType = WebhookEventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookPayload<E>;
+    verifySignature<E extends EventType = EventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookMessage<E>;
 }

package/dist/webhook/types.d.ts

@@ -5,111 +5,3 @@ export declare class VerificationError extends Error {
 export interface WebhookVerificationOptions {
     allowExpired?: boolean;
 }
-export declare enum WebhookEventType {
-    ExecutionQueued = "execution.queued",
-    ExecutionStart = "execution.start",
-    ExecutionStep = "execution.step",
-    InteractionWaiting = "interaction.waiting",
-    InteractionFinished = "interaction.finished",
-    AgentErrorAnalysis = "agent.error_analysis",
-    ExecutionRequeued = "execution.requeued",
-    ExecutionSuccess = "execution.success",
-    ExecutionFailed = "execution.failed",
-    ExecutionStopped = "execution.stopped"
-}
-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: "execution.success" | "execution.failed" | "execution.stopped";
-    encrypted_variables: string[] | null;
-    file_urls: any[] | null;
-}
-export interface ExecutionStoppedEarlyPayload {
-    message: string;
-    error_code: string;
-    session_id: string;
-}
-export interface WebhookEnvelope<E extends WebhookEventType, P> {
-    event: E;
-    timestamp: number;
-    expires_at: number;
-    payload: P;
-    metadata?: Record<string, any>;
-}
-export type WebhookPayloadMap = {
-    [WebhookEventType.ExecutionQueued]: ExecutionQueuedPayload;
-    [WebhookEventType.ExecutionStart]: ExecutionStartPayload;
-    [WebhookEventType.ExecutionStep]: ExecutionStepPayload;
-    [WebhookEventType.InteractionWaiting]: InteractionWaitingPayload;
-    [WebhookEventType.InteractionFinished]: InteractionFinishedPayload;
-    [WebhookEventType.AgentErrorAnalysis]: AgentErrorAnalysisPayload;
-    [WebhookEventType.ExecutionRequeued]: ExecutionRequeuedPayload;
-    [WebhookEventType.ExecutionSuccess]: EndRunPayload;
-    [WebhookEventType.ExecutionFailed]: EndRunPayload;
-    [WebhookEventType.ExecutionStopped]: EndRunPayload | ExecutionStoppedEarlyPayload;
-};
-export type WebhookPayload<E extends WebhookEventType = WebhookEventType> = E extends WebhookEventType ? WebhookEnvelope<E, WebhookPayloadMap[E]> : never;

package/dist/webhook/types.js

@@ -6,16 +6,3 @@ export class VerificationError extends Error {
         this.name = "VerificationError";
     }
 }
-export var WebhookEventType;
-(function (WebhookEventType) {
-    WebhookEventType["ExecutionQueued"] = "execution.queued";
-    WebhookEventType["ExecutionStart"] = "execution.start";
-    WebhookEventType["ExecutionStep"] = "execution.step";
-    WebhookEventType["InteractionWaiting"] = "interaction.waiting";
-    WebhookEventType["InteractionFinished"] = "interaction.finished";
-    WebhookEventType["AgentErrorAnalysis"] = "agent.error_analysis";
-    WebhookEventType["ExecutionRequeued"] = "execution.requeued";
-    WebhookEventType["ExecutionSuccess"] = "execution.success";
-    WebhookEventType["ExecutionFailed"] = "execution.failed";
-    WebhookEventType["ExecutionStopped"] = "execution.stopped";
-})(WebhookEventType || (WebhookEventType = {}));

package/dist/webhook/utils.d.ts

@@ -1,2 +1,3 @@
-import { WebhookEventType, type WebhookPayload, type WebhookVerificationOptions } from './types.js';
-export declare function verifyMessage<E extends WebhookEventType = WebhookEventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookPayload<E>;
+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.3",
+  "version": "0.0.4",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {