@d34dman/flowdrop 0.0.37 → 0.0.39

package/dist/services/interruptService.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Interrupt Service
+ *
+ * Handles API interactions for Human-in-the-Loop (HITL) interrupts,
+ * including fetching interrupt details, resolving interrupts with user
+ * responses, and optional dedicated polling for interrupt status.
+ *
+ * @module services/interruptService
+ */
+import type { Interrupt, InterruptPollingConfig } from '../types/interrupt.js';
+/**
+ * Interrupt Service class
+ *
+ * Provides methods to interact with interrupt API endpoints including
+ * fetching, resolving, cancelling, and listing interrupts.
+ * Supports optional dedicated polling for interrupt status.
+ */
+export declare class InterruptService {
+    private static instance;
+    private pollingInterval;
+    private pollingSessionId;
+    private currentBackoff;
+    private pollingConfig;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Get the singleton instance of InterruptService
+     *
+     * @returns The InterruptService singleton instance
+     */
+    static getInstance(): InterruptService;
+    /**
+     * Configure interrupt polling settings
+     *
+     * @param config - Polling configuration options
+     */
+    setPollingConfig(config: Partial<InterruptPollingConfig>): void;
+    /**
+     * Get the current polling configuration
+     *
+     * @returns Current polling configuration
+     */
+    getPollingConfig(): InterruptPollingConfig;
+    /**
+     * Check if interrupt endpoints are configured
+     *
+     * @returns True if interrupt endpoints are available
+     */
+    isConfigured(): boolean;
+    /**
+     * Get the endpoint configuration
+     *
+     * @throws Error if endpoint configuration is not set
+     * @returns The endpoint configuration
+     */
+    private getConfig;
+    /**
+     * Generic API request helper
+     *
+     * @param url - The URL to fetch
+     * @param options - Fetch options
+     * @returns The parsed JSON response
+     */
+    private request;
+    /**
+     * Get interrupt details by ID
+     *
+     * @param interruptId - The interrupt UUID
+     * @returns The interrupt details
+     */
+    getInterrupt(interruptId: string): Promise<Interrupt>;
+    /**
+     * Resolve an interrupt with user response
+     *
+     * @param interruptId - The interrupt UUID
+     * @param value - The user's response value
+     * @returns The updated interrupt
+     */
+    resolveInterrupt(interruptId: string, value: unknown): Promise<Interrupt>;
+    /**
+     * Cancel a pending interrupt
+     *
+     * @param interruptId - The interrupt UUID
+     * @returns The updated interrupt
+     */
+    cancelInterrupt(interruptId: string): Promise<Interrupt>;
+    /**
+     * List interrupts for a playground session
+     *
+     * @param sessionId - The session UUID
+     * @returns Array of interrupts for the session
+     */
+    listSessionInterrupts(sessionId: string): Promise<Interrupt[]>;
+    /**
+     * List interrupts for a pipeline
+     *
+     * @param pipelineId - The pipeline UUID
+     * @returns Array of interrupts for the pipeline
+     */
+    listPipelineInterrupts(pipelineId: string): Promise<Interrupt[]>;
+    /**
+     * Start polling for interrupts in a session
+     *
+     * This is optional - interrupts are typically detected via message metadata.
+     * Use this for scenarios where dedicated polling is preferred.
+     *
+     * @param sessionId - The session UUID to poll
+     * @param callback - Callback function to handle new interrupts
+     */
+    startPolling(sessionId: string, callback: (interrupts: Interrupt[]) => void): void;
+    /**
+     * Stop polling for interrupts
+     */
+    stopPolling(): void;
+    /**
+     * Check if polling is active
+     *
+     * @returns True if polling is active
+     */
+    isPolling(): boolean;
+    /**
+     * Get the current polling session ID
+     *
+     * @returns The session ID being polled, or null
+     */
+    getPollingSessionId(): string | null;
+}
+/**
+ * Export singleton instance
+ */
+export declare const interruptService: InterruptService;

package/dist/services/interruptService.js

@@ -0,0 +1,279 @@
+/**
+ * Interrupt Service
+ *
+ * Handles API interactions for Human-in-the-Loop (HITL) interrupts,
+ * including fetching interrupt details, resolving interrupts with user
+ * responses, and optional dedicated polling for interrupt status.
+ *
+ * @module services/interruptService
+ */
+import { defaultInterruptPollingConfig } from '../types/interrupt.js';
+import { buildEndpointUrl, getEndpointHeaders } from '../config/endpoints.js';
+import { getEndpointConfig } from './api.js';
+/**
+ * Interrupt Service class
+ *
+ * Provides methods to interact with interrupt API endpoints including
+ * fetching, resolving, cancelling, and listing interrupts.
+ * Supports optional dedicated polling for interrupt status.
+ */
+export class InterruptService {
+    static instance;
+    pollingInterval = null;
+    pollingSessionId = null;
+    currentBackoff;
+    pollingConfig;
+    /**
+     * Private constructor for singleton pattern
+     */
+    constructor() {
+        this.pollingConfig = { ...defaultInterruptPollingConfig };
+        this.currentBackoff = this.pollingConfig.interval ?? 2000;
+    }
+    /**
+     * Get the singleton instance of InterruptService
+     *
+     * @returns The InterruptService singleton instance
+     */
+    static getInstance() {
+        if (!InterruptService.instance) {
+            InterruptService.instance = new InterruptService();
+        }
+        return InterruptService.instance;
+    }
+    /**
+     * Configure interrupt polling settings
+     *
+     * @param config - Polling configuration options
+     */
+    setPollingConfig(config) {
+        this.pollingConfig = { ...this.pollingConfig, ...config };
+        this.currentBackoff = this.pollingConfig.interval ?? 2000;
+    }
+    /**
+     * Get the current polling configuration
+     *
+     * @returns Current polling configuration
+     */
+    getPollingConfig() {
+        return { ...this.pollingConfig };
+    }
+    /**
+     * Check if interrupt endpoints are configured
+     *
+     * @returns True if interrupt endpoints are available
+     */
+    isConfigured() {
+        const config = getEndpointConfig();
+        return Boolean(config?.endpoints?.interrupts);
+    }
+    /**
+     * Get the endpoint configuration
+     *
+     * @throws Error if endpoint configuration is not set
+     * @returns The endpoint configuration
+     */
+    getConfig() {
+        const config = getEndpointConfig();
+        if (!config) {
+            throw new Error('Endpoint configuration not set. Call setEndpointConfig() first.');
+        }
+        if (!config.endpoints.interrupts) {
+            throw new Error('Interrupt endpoints not configured.');
+        }
+        return config;
+    }
+    /**
+     * Generic API request helper
+     *
+     * @param url - The URL to fetch
+     * @param options - Fetch options
+     * @returns The parsed JSON response
+     */
+    async request(url, options = {}) {
+        const config = this.getConfig();
+        const headers = getEndpointHeaders(config, 'interrupts');
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                ...headers,
+                ...options.headers
+            }
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            const errorMessage = errorData.error ||
+                errorData.message ||
+                `HTTP ${response.status}: ${response.statusText}`;
+            throw new Error(errorMessage);
+        }
+        return response.json();
+    }
+    // =========================================================================
+    // Interrupt Operations
+    // =========================================================================
+    /**
+     * Get interrupt details by ID
+     *
+     * @param interruptId - The interrupt UUID
+     * @returns The interrupt details
+     */
+    async getInterrupt(interruptId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.get, {
+            interruptId
+        });
+        const response = await this.request(url);
+        if (!response.data) {
+            throw new Error('Interrupt not found');
+        }
+        return response.data;
+    }
+    /**
+     * Resolve an interrupt with user response
+     *
+     * @param interruptId - The interrupt UUID
+     * @param value - The user's response value
+     * @returns The updated interrupt
+     */
+    async resolveInterrupt(interruptId, value) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.resolve, {
+            interruptId
+        });
+        const resolution = { value };
+        const response = await this.request(url, {
+            method: 'POST',
+            body: JSON.stringify(resolution)
+        });
+        if (!response.data) {
+            throw new Error('Failed to resolve interrupt: No data returned');
+        }
+        return response.data;
+    }
+    /**
+     * Cancel a pending interrupt
+     *
+     * @param interruptId - The interrupt UUID
+     * @returns The updated interrupt
+     */
+    async cancelInterrupt(interruptId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.cancel, {
+            interruptId
+        });
+        const response = await this.request(url, {
+            method: 'POST'
+        });
+        if (!response.data) {
+            throw new Error('Failed to cancel interrupt: No data returned');
+        }
+        return response.data;
+    }
+    /**
+     * List interrupts for a playground session
+     *
+     * @param sessionId - The session UUID
+     * @returns Array of interrupts for the session
+     */
+    async listSessionInterrupts(sessionId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.listBySession, {
+            sessionId
+        });
+        const response = await this.request(url);
+        return response.data ?? [];
+    }
+    /**
+     * List interrupts for a pipeline
+     *
+     * @param pipelineId - The pipeline UUID
+     * @returns Array of interrupts for the pipeline
+     */
+    async listPipelineInterrupts(pipelineId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.interrupts.listByPipeline, {
+            pipelineId
+        });
+        const response = await this.request(url);
+        return response.data ?? [];
+    }
+    // =========================================================================
+    // Polling (Optional)
+    // =========================================================================
+    /**
+     * Start polling for interrupts in a session
+     *
+     * This is optional - interrupts are typically detected via message metadata.
+     * Use this for scenarios where dedicated polling is preferred.
+     *
+     * @param sessionId - The session UUID to poll
+     * @param callback - Callback function to handle new interrupts
+     */
+    startPolling(sessionId, callback) {
+        if (!this.pollingConfig.enabled) {
+            console.warn('[InterruptService] Polling is disabled. Enable via setPollingConfig().');
+            return;
+        }
+        // Stop any existing polling
+        this.stopPolling();
+        this.pollingSessionId = sessionId;
+        this.currentBackoff = this.pollingConfig.interval ?? 2000;
+        const poll = async () => {
+            if (this.pollingSessionId !== sessionId) {
+                return;
+            }
+            try {
+                const interrupts = await this.listSessionInterrupts(sessionId);
+                const pendingInterrupts = interrupts.filter((i) => i.status === 'pending');
+                // Reset backoff on successful request
+                this.currentBackoff = this.pollingConfig.interval ?? 2000;
+                // Call the callback with pending interrupts
+                callback(pendingInterrupts);
+            }
+            catch (error) {
+                console.error('[InterruptService] Polling error:', error);
+                // Exponential backoff on error
+                const maxBackoff = this.pollingConfig.maxBackoff ?? 10000;
+                this.currentBackoff = Math.min(this.currentBackoff * 2, maxBackoff);
+            }
+            // Schedule next poll
+            if (this.pollingSessionId === sessionId) {
+                this.pollingInterval = setTimeout(poll, this.currentBackoff);
+            }
+        };
+        // Start polling immediately
+        void poll();
+    }
+    /**
+     * Stop polling for interrupts
+     */
+    stopPolling() {
+        if (this.pollingInterval) {
+            clearTimeout(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+        this.pollingSessionId = null;
+        this.currentBackoff = this.pollingConfig.interval ?? 2000;
+    }
+    /**
+     * Check if polling is active
+     *
+     * @returns True if polling is active
+     */
+    isPolling() {
+        return this.pollingSessionId !== null;
+    }
+    /**
+     * Get the current polling session ID
+     *
+     * @returns The session ID being polled, or null
+     */
+    getPollingSessionId() {
+        return this.pollingSessionId;
+    }
+}
+/**
+ * Export singleton instance
+ */
+export const interruptService = InterruptService.getInstance();

package/dist/stores/interruptStore.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Interrupt Store
+ *
+ * Svelte stores for managing interrupt state using a lightweight state machine.
+ * Ensures valid state transitions and prevents deadlocks.
+ *
+ * @module stores/interruptStore
+ */
+import type { Interrupt, InterruptStatus } from '../types/interrupt.js';
+import { type InterruptState, type TransitionResult } from '../types/interruptState.js';
+/**
+ * Extended interrupt with state machine
+ */
+export interface InterruptWithState extends Interrupt {
+    /** State machine state for UI interaction tracking */
+    machineState: InterruptState;
+}
+/**
+ * Map of all interrupts by ID
+ * Key: interrupt ID, Value: Interrupt object with state
+ */
+export declare const interrupts: import("svelte/store").Writable<Map<string, InterruptWithState>>;
+/**
+ * Derived store for pending interrupt IDs
+ */
+export declare const pendingInterruptIds: import("svelte/store").Readable<string[]>;
+/**
+ * Derived store for pending interrupts array
+ */
+export declare const pendingInterrupts: import("svelte/store").Readable<InterruptWithState[]>;
+/**
+ * Derived store for count of pending interrupts
+ */
+export declare const pendingInterruptCount: import("svelte/store").Readable<number>;
+/**
+ * Derived store for resolved interrupts
+ */
+export declare const resolvedInterrupts: import("svelte/store").Readable<InterruptWithState[]>;
+/**
+ * Derived store to check if any interrupt is currently submitting
+ */
+export declare const isAnySubmitting: import("svelte/store").Readable<boolean>;
+/**
+ * Legacy derived store for submitting interrupt IDs
+ * @deprecated Use interrupt.machineState.status === "submitting" instead
+ */
+export declare const submittingInterrupts: import("svelte/store").Readable<Set<string>>;
+/**
+ * Legacy derived store for interrupt errors
+ * @deprecated Use interrupt.machineState.error instead
+ */
+export declare const interruptErrors: import("svelte/store").Readable<Map<string, string>>;
+/**
+ * Interrupt store actions for modifying state
+ */
+export declare const interruptActions: {
+    /**
+     * Add or update an interrupt in the store
+     *
+     * @param interrupt - The interrupt to add or update
+     */
+    addInterrupt: (interrupt: Interrupt) => void;
+    /**
+     * Add multiple interrupts to the store
+     *
+     * @param interruptList - Array of interrupts to add
+     */
+    addInterrupts: (interruptList: Interrupt[]) => void;
+    /**
+     * Start submitting an interrupt (user clicked submit)
+     *
+     * @param interruptId - The interrupt ID
+     * @param value - The value being submitted
+     * @returns Transition result
+     */
+    startSubmit: (interruptId: string, value: unknown) => TransitionResult;
+    /**
+     * Start cancelling an interrupt (user clicked cancel)
+     *
+     * @param interruptId - The interrupt ID
+     * @returns Transition result
+     */
+    startCancel: (interruptId: string) => TransitionResult;
+    /**
+     * Mark submission as successful
+     *
+     * @param interruptId - The interrupt ID
+     * @returns Transition result
+     */
+    submitSuccess: (interruptId: string) => TransitionResult;
+    /**
+     * Mark submission as failed
+     *
+     * @param interruptId - The interrupt ID
+     * @param error - Error message
+     * @returns Transition result
+     */
+    submitFailure: (interruptId: string, error: string) => TransitionResult;
+    /**
+     * Retry a failed submission
+     *
+     * @param interruptId - The interrupt ID
+     * @returns Transition result
+     */
+    retry: (interruptId: string) => TransitionResult;
+    /**
+     * Reset an interrupt to idle state
+     *
+     * @param interruptId - The interrupt ID
+     * @returns Transition result
+     */
+    resetInterrupt: (interruptId: string) => TransitionResult;
+    /**
+     * Update an interrupt's status (legacy)
+     * @deprecated Use startSubmit/submitSuccess/submitFailure instead
+     */
+    updateStatus: (interruptId: string, status: InterruptStatus, responseValue?: unknown) => void;
+    /**
+     * Mark an interrupt as resolved with the user's response (legacy)
+     * @deprecated Use startSubmit + submitSuccess instead
+     */
+    resolveInterrupt: (interruptId: string, value: unknown) => void;
+    /**
+     * Mark an interrupt as cancelled (legacy)
+     * @deprecated Use startCancel + submitSuccess instead
+     */
+    cancelInterrupt: (interruptId: string) => void;
+    /**
+     * Set submitting state for an interrupt (legacy)
+     * @deprecated State is automatically managed by startSubmit/submitSuccess
+     */
+    setSubmitting: (interruptId: string, isSubmitting: boolean) => void;
+    /**
+     * Set error for an interrupt (legacy)
+     * @deprecated Use submitFailure() instead
+     */
+    setError: (interruptId: string, error: string | null) => void;
+    /**
+     * Remove an interrupt from the store
+     *
+     * @param interruptId - The interrupt ID to remove
+     */
+    removeInterrupt: (interruptId: string) => void;
+    /**
+     * Clear all interrupts for a specific session
+     *
+     * @param sessionId - The session ID to clear interrupts for
+     */
+    clearSessionInterrupts: (sessionId: string) => void;
+    /**
+     * Alias for clearSessionInterrupts
+     */
+    clearInterrupts: () => void;
+    /**
+     * Reset all interrupt state
+     */
+    reset: () => void;
+};
+/**
+ * Get an interrupt by ID
+ *
+ * @param interruptId - The interrupt ID
+ * @returns The interrupt or undefined
+ */
+export declare function getInterrupt(interruptId: string): InterruptWithState | undefined;
+/**
+ * Check if an interrupt is pending (not resolved or cancelled)
+ *
+ * @param interruptId - The interrupt ID
+ * @returns True if the interrupt exists and is pending
+ */
+export declare function isInterruptPending(interruptId: string): boolean;
+/**
+ * Check if an interrupt is currently submitting
+ *
+ * @param interruptId - The interrupt ID
+ * @returns True if the interrupt is being submitted
+ */
+export declare function isInterruptSubmitting(interruptId: string): boolean;
+/**
+ * Get the error for an interrupt
+ *
+ * @param interruptId - The interrupt ID
+ * @returns The error message or undefined
+ */
+export declare function getInterruptError(interruptId: string): string | undefined;
+/**
+ * Get an interrupt by its associated message ID
+ *
+ * @param messageId - The message ID
+ * @returns The interrupt or undefined
+ */
+export declare function getInterruptByMessageId(messageId: string): InterruptWithState | undefined;
+/**
+ * Check if an interrupt has an error
+ *
+ * @param interruptId - The interrupt ID
+ * @returns True if the interrupt has an error
+ */
+export declare function interruptHasError(interruptId: string): boolean;