cloudcruise 1.0.0 → 1.1.0

package/dist/utils/connectionManager.js

@@ -0,0 +1,234 @@
+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 === EventType.ExecutionSuccess ||
+        eventType === EventType.ExecutionFailed ||
+        eventType === EventType.ExecutionStopped);
+}
+export class ConnectionManager {
+    baseUrl;
+    apiKey;
+    clientId;
+    conn = null;
+    connecting = false;
+    connected = false;
+    reconnecting = false;
+    reconnectDelays = [1000, 3000, 10000];
+    sessions = new Map();
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.apiKey = apiKey;
+    }
+    async ensureClientId() {
+        if (this.clientId)
+            return this.clientId;
+        this.clientId = this.generateClientId();
+        return this.clientId;
+    }
+    /*
+    try to use crypto.randomUUID if the platform is supported. otherwise fallback to other methods: https://stackoverflow.com/questions/105034/how-do-i-create-a-guid-uuid/2117523#2117523
+    */
+    generateClientId() {
+        const cryptoObj = globalThis.crypto;
+        // Preferred: native CSPRNG-backed UUID
+        if (cryptoObj?.randomUUID) {
+            return cryptoObj.randomUUID();
+        }
+        // Fallback: RFC4122 v4 built from CSPRNG bytes
+        if (cryptoObj?.getRandomValues) {
+            const bytes = new Uint8Array(16);
+            cryptoObj.getRandomValues(bytes);
+            bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+            bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 10xx
+            const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0'));
+            return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex.slice(6, 8).join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10).join('')}`;
+        }
+        // Last resort: non-CSPRNG timestamp + Math.random
+        let d = Date.now();
+        let d2 = typeof performance !== 'undefined' && typeof performance.now === 'function'
+            ? Math.floor(performance.now() * 1000)
+            : 0;
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            let r = Math.random() * 16;
+            if (d > 0) {
+                r = ((d + r) % 16) | 0;
+                d = Math.floor(d / 16);
+            }
+            else {
+                r = ((d2 + r) % 16) | 0;
+                d2 = Math.floor(d2 / 16);
+            }
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+    async connectIfNeeded() {
+        if (this.connected || this.connecting)
+            return;
+        if (!this.clientId)
+            await this.ensureClientId();
+        await this.openMuxConnection();
+    }
+    subscribe(sessionId, opts) {
+        // Kick off connection if not already connected
+        try {
+            void this.connectIfNeeded();
+        }
+        catch { }
+        // Ensure channel exists
+        let channel = this.sessions.get(sessionId);
+        if (!channel) {
+            channel = {
+                sessionId,
+                emitter: new SimpleEventEmitter(),
+                subscribers: new Set(),
+                ended: false
+            };
+            this.sessions.set(sessionId, channel);
+        }
+        // Create per-handle queue
+        const queue = new AsyncEventQueue();
+        channel.subscribers.add(queue);
+        // Propagate abort to handle close
+        if (opts?.signal) {
+            const onAbort = () => sub.close();
+            opts.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        const sub = {
+            on: (event, handler) => channel.emitter.on(event, handler),
+            close: () => {
+                if (!channel)
+                    return;
+                queue.close();
+                channel.subscribers.delete(queue);
+                // If no more subscribers and channel is ended, remove it
+                if (channel.subscribers.size === 0 && channel.ended) {
+                    this.sessions.delete(sessionId);
+                }
+            },
+            [Symbol.asyncIterator]() {
+                return queue[Symbol.asyncIterator]();
+            }
+        };
+        return sub;
+    }
+    async openMuxConnection() {
+        if (this.connecting || this.connected)
+            return;
+        if (!this.clientId)
+            await this.ensureClientId();
+        this.connecting = true;
+        const headers = {
+            'cc-key': this.apiKey
+        };
+        const url = `${this.baseUrl}/run/clients/${this.clientId}/events`;
+        const emitAll = (event, payload) => {
+            for (const ch of this.sessions.values()) {
+                ch.emitter.emit(event, payload);
+            }
+        };
+        try {
+            this.conn = openSSE(url, {
+                onOpen: () => {
+                    this.connected = true;
+                    this.connecting = false;
+                    emitAll('open');
+                },
+                onEvent: (evt) => {
+                    if (evt.event === 'ping') {
+                        emitAll('ping', evt);
+                        return;
+                    }
+                    if (evt.event === 'run.event') {
+                        const raw = evt;
+                        const data = raw.data?.data;
+                        if (!data) {
+                            return;
+                        }
+                        // Extract session_id - it's always present in payload
+                        const payload = data.payload;
+                        const sessionId = payload?.session_id;
+                        if (!sessionId) {
+                            return;
+                        }
+                        const channel = this.sessions.get(sessionId);
+                        if (!channel) {
+                            return;
+                        }
+                        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);
+                        channel.emitter.emit('run.event', msg);
+                        const eventType = data.event;
+                        if (isFinalEvent(eventType)) {
+                            channel.ended = true;
+                            channel.emitter.emit('end', { type: eventType });
+                            for (const q of channel.subscribers)
+                                q.close();
+                            channel.subscribers.clear();
+                            // Remove the channel after notifying
+                            this.sessions.delete(sessionId);
+                        }
+                        return;
+                    }
+                    const u = evt;
+                },
+                onError: (err) => {
+                    // Surface error to all channels and attempt reconnect
+                    emitAll('error', err);
+                    if (!this.reconnecting)
+                        this.scheduleReconnect();
+                },
+                onClose: () => {
+                    this.connected = false;
+                    this.connecting = false;
+                    emitAll('close');
+                    if (!this.reconnecting)
+                        this.scheduleReconnect();
+                }
+            }, {
+                headers,
+                withCredentials: false
+            });
+        }
+        catch (e) {
+            this.connected = false;
+            this.connecting = false;
+            if (!this.reconnecting)
+                this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnecting)
+            return;
+        this.reconnecting = true;
+        (async () => {
+            for (const delay of this.reconnectDelays) {
+                // Notify listeners about reconnect attempt
+                for (const ch of this.sessions.values())
+                    ch.emitter.emit('reconnect', { attemptDelayMs: delay });
+                await new Promise(r => setTimeout(r, delay));
+                try {
+                    await this.openMuxConnection();
+                    if (this.connected) {
+                        this.reconnecting = false;
+                        return;
+                    }
+                }
+                catch {
+                    // continue to next delay
+                }
+            }
+            // Give up after exhausting delays; next event/subscribe will try again
+            this.reconnecting = false;
+        })();
+    }
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,2 @@
+export type CloudCruiseEnvVar = 'CLOUDCRUISE_API_KEY' | 'CLOUDCRUISE_BASE_URL' | 'CLOUDCRUISE_ENCRYPTION_KEY';
+export declare function getEnv(key: CloudCruiseEnvVar): string | undefined;

package/dist/utils/env.js

@@ -0,0 +1,9 @@
+export function getEnv(key) {
+    if (typeof process !== 'undefined' && process.env && process.env[key]) {
+        return process.env[key];
+    }
+    else if (typeof globalThis !== 'undefined' && globalThis[key]) {
+        return globalThis[key];
+    }
+    return undefined;
+}

package/dist/utils/events.d.ts

@@ -0,0 +1,24 @@
+export type EventHandler<T = unknown> = (event: T) => void;
+/**
+ * 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<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

@@ -0,0 +1,40 @@
+/**
+ * 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) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        this.listeners.get(event).add(handler);
+        return () => {
+            const set = this.listeners.get(event);
+            if (set)
+                set.delete(handler);
+        };
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const handler of set)
+            handler(payload);
+    }
+    clear() {
+        this.listeners.clear();
+    }
+}

package/dist/utils/sse.d.ts

@@ -0,0 +1,24 @@
+export interface SSEHandlers {
+    onOpen?: () => void;
+    onEvent?: (evt: {
+        event: string;
+        data?: unknown;
+        id?: string;
+        raw?: string;
+    }) => void;
+    onError?: (error: Error) => void;
+    onClose?: () => void;
+}
+export interface SSEOptions {
+    headers?: HeadersInit;
+    withCredentials?: boolean;
+    signal?: AbortSignal;
+}
+export interface SSEConnection {
+    close(): void;
+}
+/**
+ * Open an SSE connection using either native EventSource (browser, cookie auth)
+ * or fetch streaming (Node 18+ and modern browsers) when custom headers are needed.
+ */
+export declare function openSSE(url: string, handlers: SSEHandlers, opts?: SSEOptions): SSEConnection;

package/dist/utils/sse.js

@@ -0,0 +1,122 @@
+/**
+ * Open an SSE connection using either native EventSource (browser, cookie auth)
+ * or fetch streaming (Node 18+ and modern browsers) when custom headers are needed.
+ */
+export function openSSE(url, handlers, opts) {
+    const { onOpen, onEvent, onError, onClose } = handlers;
+    const { headers, withCredentials, signal } = opts ?? {};
+    const shouldUseEventSource = () => typeof window !== 'undefined' &&
+        'EventSource' in window &&
+        withCredentials === true &&
+        (!headers || Object.keys(headers).length === 0);
+    const parseJSON = (text) => {
+        try {
+            return text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            return text || undefined;
+        }
+    };
+    const createEventSourceConnection = () => {
+        const ES = window.EventSource;
+        const es = new ES(url, { withCredentials: true });
+        const onOpenHandler = () => onOpen?.();
+        const onErrorHandler = (e) => onError?.(e instanceof Error ? e : new Error('EventSource error'));
+        const onRunEvent = (e) => {
+            const raw = String(e.data ?? '');
+            const parsed = parseJSON(raw);
+            onEvent?.({ event: 'run.event', data: parsed, id: e.lastEventId, raw });
+        };
+        const onPing = (e) => {
+            const raw = String(e.data ?? '');
+            const parsed = parseJSON(raw);
+            onEvent?.({ event: 'ping', data: parsed, id: e.lastEventId, raw });
+        };
+        es.addEventListener('open', onOpenHandler);
+        es.addEventListener('error', onErrorHandler);
+        es.addEventListener('run.event', onRunEvent);
+        es.addEventListener('ping', onPing);
+        if (signal) {
+            const onAbort = () => {
+                es.close();
+                onClose?.();
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        return {
+            close() {
+                es.close();
+                onClose?.();
+            },
+        };
+    };
+    const createFetchConnection = () => {
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        if (signal)
+            signal.addEventListener('abort', abort, { once: true });
+        const parseFrame = (frame) => {
+            let event = 'message';
+            let data = '';
+            let id;
+            for (const line of frame.split(/\r?\n/)) {
+                if (!line || line.startsWith(':'))
+                    continue;
+                const idx = line.indexOf(':');
+                const field = idx === -1 ? line : line.slice(0, idx);
+                const value = idx === -1 ? '' : line.slice(idx + 1).trimStart();
+                if (field === 'event')
+                    event = value;
+                else if (field === 'data')
+                    data += (data ? '\n' : '') + value;
+                else if (field === 'id')
+                    id = value;
+            }
+            const parsed = parseJSON(data);
+            return { event, data: parsed, id, raw: frame };
+        };
+        (async () => {
+            try {
+                const res = await fetch(url, {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        ...(headers ?? {}),
+                    },
+                    credentials: withCredentials ? 'include' : 'same-origin',
+                    signal: controller.signal,
+                });
+                if (!res.ok || !res.body)
+                    throw new Error(`SSE HTTP ${res.status}`);
+                onOpen?.();
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    const chunk = decoder.decode(value, { stream: true });
+                    const parts = (buffer + chunk).split(/\r?\n\r?\n/);
+                    buffer = parts.pop() ?? '';
+                    for (const frame of parts) {
+                        const evt = parseFrame(frame);
+                        onEvent?.(evt);
+                    }
+                }
+                onClose?.();
+            }
+            catch (err) {
+                onError?.(err instanceof Error ? err : new Error(String(err)));
+            }
+        })();
+        return {
+            close() {
+                abort();
+                onClose?.();
+            },
+        };
+    };
+    return shouldUseEventSource() ? createEventSourceConnection() : createFetchConnection();
+}

package/dist/vault/VaultClient.d.ts

@@ -0,0 +1,55 @@
+import type { GetVaultEntriesFilters, VaultEntry, VaultTfaCode } from './types.js';
+export declare class VaultClient {
+    private readonly makeRequest;
+    private readonly encryptionKey;
+    constructor(makeRequest: <T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: any) => Promise<T>, encryptionKey: string);
+    /**
+     * Creates a new vault entry
+     */
+    create(domain: string, permissioned_user_id: string, options?: Partial<Omit<VaultEntry, 'id' | 'created_at' | 'domain' | 'permissioned_user_id'>>): Promise<VaultEntry>;
+    /**
+     * Gets vault entries, optionally filtered
+     * @param filters - Optional filters for the request
+     * @param filters.permissioned_user_id - Filter by user ID
+     * @param filters.domain - Filter by domain
+     * @param filters.decryptCredentials - Whether to decrypt sensitive fields (default: true)
+     */
+    get(filters?: GetVaultEntriesFilters): Promise<VaultEntry[]>;
+    /**
+     * Gets the current 2FA code for a single vault entry.
+     *
+     * The code returned depends on the credential's 2FA method:
+     * - Authenticator (TOTP): a freshly generated code, with `expires_in_seconds`.
+     * - Email: the most recently received code (within the freshness window), with `received_at`.
+     *
+     * SMS and magic-link credentials are not supported (the endpoint returns 409).
+     *
+     * @param permissioned_user_id - User identifier for the vault entry
+     * @param domain - Target domain of the vault entry
+     */
+    getTfaCode(permissioned_user_id: string, domain: string): Promise<VaultTfaCode>;
+    /**
+     * Updates an existing vault entry
+     * @param updates - Vault entry updates including required fields
+     * @param updates.permissioned_user_id - Required: User identifier for the vault entry
+     * @param updates.user_name - Required: Username or email
+     * @param updates.password - Required: User password
+     * @param updates.domain - Required: Target domain for the credentials
+     */
+    update(updates: Partial<VaultEntry> & {
+        permissioned_user_id: string;
+        user_name: string;
+        password: string;
+        domain: string;
+    }): Promise<VaultEntry>;
+    /**
+     * Deletes a vault entry by domain and permissioned user ID
+     * @param params - Object containing domain and permissioned_user_id
+     * @param params.domain - The domain of the vault entry to delete
+     * @param params.permissioned_user_id - The permissioned user ID of the vault entry to delete
+     */
+    delete(params: {
+        domain: string;
+        permissioned_user_id: string;
+    }): Promise<void>;
+}

package/dist/vault/VaultClient.js

@@ -0,0 +1,115 @@
+import { encryptSensitiveFields, decryptSensitiveFields } from './utils.js';
+export class VaultClient {
+    makeRequest;
+    encryptionKey;
+    constructor(makeRequest, encryptionKey) {
+        this.makeRequest = makeRequest;
+        this.encryptionKey = encryptionKey;
+    }
+    /**
+     * Creates a new vault entry
+     */
+    async create(domain, permissioned_user_id, options) {
+        const entry = {
+            domain,
+            permissioned_user_id,
+            ...options
+        };
+        let processedEntry = { ...entry };
+        // Encrypt sensitive fields
+        processedEntry = await encryptSensitiveFields(processedEntry, this.encryptionKey);
+        const response = await this.makeRequest('POST', '/vault', processedEntry);
+        // Decrypt response using encryption key
+        return await decryptSensitiveFields(response, this.encryptionKey);
+    }
+    /**
+     * Gets vault entries, optionally filtered
+     * @param filters - Optional filters for the request
+     * @param filters.permissioned_user_id - Filter by user ID
+     * @param filters.domain - Filter by domain
+     * @param filters.decryptCredentials - Whether to decrypt sensitive fields (default: true)
+     */
+    async get(filters) {
+        let path = '/vault';
+        if (filters && (filters.permissioned_user_id || filters.domain)) {
+            const params = new URLSearchParams();
+            if (filters.permissioned_user_id) {
+                params.append('permissioned_user_id', filters.permissioned_user_id);
+            }
+            if (filters.domain) {
+                params.append('domain', filters.domain);
+            }
+            path += `?${params.toString()}`;
+        }
+        const response = await this.makeRequest('GET', path);
+        let entries = Array.isArray(response) ? response : [response];
+        // Conditionally decrypt sensitive fields based on decryptCredentials flag
+        const shouldDecrypt = filters?.decryptCredentials !== false;
+        if (shouldDecrypt) {
+            entries = await Promise.all(entries.map(entry => decryptSensitiveFields(entry, this.encryptionKey)));
+        }
+        return entries;
+    }
+    /**
+     * Gets the current 2FA code for a single vault entry.
+     *
+     * The code returned depends on the credential's 2FA method:
+     * - Authenticator (TOTP): a freshly generated code, with `expires_in_seconds`.
+     * - Email: the most recently received code (within the freshness window), with `received_at`.
+     *
+     * SMS and magic-link credentials are not supported (the endpoint returns 409).
+     *
+     * @param permissioned_user_id - User identifier for the vault entry
+     * @param domain - Target domain of the vault entry
+     */
+    async getTfaCode(permissioned_user_id, domain) {
+        if (!permissioned_user_id) {
+            throw new Error('permissioned_user_id is required to get a TFA code');
+        }
+        if (!domain) {
+            throw new Error('domain is required to get a TFA code');
+        }
+        const params = new URLSearchParams();
+        params.append('permissioned_user_id', permissioned_user_id);
+        params.append('domain', domain);
+        return await this.makeRequest('GET', `/vault/tfa-code?${params.toString()}`);
+    }
+    /**
+     * Updates an existing vault entry
+     * @param updates - Vault entry updates including required fields
+     * @param updates.permissioned_user_id - Required: User identifier for the vault entry
+     * @param updates.user_name - Required: Username or email
+     * @param updates.password - Required: User password
+     * @param updates.domain - Required: Target domain for the credentials
+     */
+    async update(updates) {
+        // Validate required fields
+        if (!updates.permissioned_user_id) {
+            throw new Error('permissioned_user_id is required for vault updates');
+        }
+        if (!updates.user_name) {
+            throw new Error('user_name is required for vault updates');
+        }
+        if (!updates.password) {
+            throw new Error('password is required for vault updates');
+        }
+        if (!updates.domain) {
+            throw new Error('domain is required for vault updates');
+        }
+        let processedEntry = { ...updates };
+        // Encrypt sensitive fields
+        processedEntry = await encryptSensitiveFields(processedEntry, this.encryptionKey);
+        const response = await this.makeRequest('PUT', '/vault', processedEntry);
+        // Decrypt response using encryption key
+        return await decryptSensitiveFields(response, this.encryptionKey);
+    }
+    /**
+     * Deletes a vault entry by domain and permissioned user ID
+     * @param params - Object containing domain and permissioned_user_id
+     * @param params.domain - The domain of the vault entry to delete
+     * @param params.permissioned_user_id - The permissioned user ID of the vault entry to delete
+     */
+    async delete(params) {
+        await this.makeRequest('DELETE', '/vault', params);
+    }
+}