@flowdrop/flowdrop 1.0.0

package/dist/services/playgroundService.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Playground Service
+ *
+ * Handles API interactions for the Playground feature including
+ * session management, message handling, and polling for updates.
+ *
+ * @module services/playgroundService
+ */
+import type { PlaygroundSession, PlaygroundMessage, PlaygroundMessagesApiResponse, PlaygroundSessionStatus } from '../types/playground.js';
+/**
+ * Playground Service class
+ *
+ * Provides methods to interact with the playground API endpoints
+ * including session management, message handling, and polling.
+ */
+export declare class PlaygroundService {
+    private static instance;
+    private pollingInterval;
+    private pollingSessionId;
+    private currentBackoff;
+    private lastMessageTimestamp;
+    private constructor();
+    /**
+     * Get the singleton instance of PlaygroundService
+     *
+     * @returns The PlaygroundService singleton instance
+     */
+    static getInstance(): PlaygroundService;
+    /**
+     * 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;
+    /**
+     * List all playground sessions for a workflow
+     *
+     * @param workflowId - The workflow UUID
+     * @param options - Optional pagination parameters
+     * @returns Array of playground sessions
+     */
+    listSessions(workflowId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PlaygroundSession[]>;
+    /**
+     * Create a new playground session
+     *
+     * @param workflowId - The workflow UUID
+     * @param name - Optional session name
+     * @param metadata - Optional session metadata
+     * @returns The created session
+     */
+    createSession(workflowId: string, name?: string, metadata?: Record<string, unknown>): Promise<PlaygroundSession>;
+    /**
+     * Get a playground session by ID
+     *
+     * @param sessionId - The session UUID
+     * @returns The session details
+     */
+    getSession(sessionId: string): Promise<PlaygroundSession>;
+    /**
+     * Delete a playground session
+     *
+     * @param sessionId - The session UUID
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Get messages from a playground session
+     *
+     * @param sessionId - The session UUID
+     * @param since - Optional timestamp to fetch only newer messages (ISO 8601)
+     * @param limit - Maximum number of messages to return
+     * @returns Messages and session status
+     */
+    getMessages(sessionId: string, since?: string, limit?: number): Promise<PlaygroundMessagesApiResponse>;
+    /**
+     * Send a message to a playground session
+     *
+     * @param sessionId - The session UUID
+     * @param content - The message content
+     * @param inputs - Optional additional inputs for workflow nodes
+     * @returns The created message
+     */
+    sendMessage(sessionId: string, content: string, inputs?: Record<string, unknown>): Promise<PlaygroundMessage>;
+    /**
+     * Stop execution in a playground session
+     *
+     * @param sessionId - The session UUID
+     */
+    stopExecution(sessionId: string): Promise<void>;
+    /**
+     * Start polling for new messages
+     *
+     * @param sessionId - The session UUID to poll
+     * @param callback - Callback function to handle new messages
+     * @param interval - Polling interval in milliseconds (default: 1500)
+     * @param shouldStopPolling - Optional override for stop conditions (default: defaultShouldStopPolling)
+     */
+    startPolling(sessionId: string, callback: (response: PlaygroundMessagesApiResponse) => void, interval?: number, shouldStopPolling?: (status: PlaygroundSessionStatus) => boolean): void;
+    /**
+     * Stop polling for messages
+     */
+    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 playgroundService: PlaygroundService;

package/dist/services/playgroundService.js

@@ -0,0 +1,321 @@
+/**
+ * Playground Service
+ *
+ * Handles API interactions for the Playground feature including
+ * session management, message handling, and polling for updates.
+ *
+ * @module services/playgroundService
+ */
+import { defaultShouldStopPolling } from '../types/playground.js';
+import { buildEndpointUrl, getEndpointHeaders } from '../config/endpoints.js';
+import { getEndpointConfig } from './api.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Default polling interval in milliseconds
+ */
+const DEFAULT_POLLING_INTERVAL = 1500;
+/**
+ * Maximum polling backoff interval in milliseconds
+ */
+const MAX_POLLING_BACKOFF = 10000;
+/**
+ * Playground Service class
+ *
+ * Provides methods to interact with the playground API endpoints
+ * including session management, message handling, and polling.
+ */
+export class PlaygroundService {
+    static instance;
+    pollingInterval = null;
+    pollingSessionId = null;
+    currentBackoff = DEFAULT_POLLING_INTERVAL;
+    lastMessageTimestamp = null;
+    constructor() { }
+    /**
+     * Get the singleton instance of PlaygroundService
+     *
+     * @returns The PlaygroundService singleton instance
+     */
+    static getInstance() {
+        if (!PlaygroundService.instance) {
+            PlaygroundService.instance = new PlaygroundService();
+        }
+        return PlaygroundService.instance;
+    }
+    /**
+     * 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.');
+        }
+        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, 'playground');
+        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();
+    }
+    // =========================================================================
+    // Session Management
+    // =========================================================================
+    /**
+     * List all playground sessions for a workflow
+     *
+     * @param workflowId - The workflow UUID
+     * @param options - Optional pagination parameters
+     * @returns Array of playground sessions
+     */
+    async listSessions(workflowId, options) {
+        const config = this.getConfig();
+        let url = buildEndpointUrl(config, config.endpoints.playground.listSessions, {
+            id: workflowId
+        });
+        // Add query parameters
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined) {
+            params.append('limit', options.limit.toString());
+        }
+        if (options?.offset !== undefined) {
+            params.append('offset', options.offset.toString());
+        }
+        const queryString = params.toString();
+        if (queryString) {
+            url = `${url}?${queryString}`;
+        }
+        const response = await this.request(url);
+        return response.data ?? [];
+    }
+    /**
+     * Create a new playground session
+     *
+     * @param workflowId - The workflow UUID
+     * @param name - Optional session name
+     * @param metadata - Optional session metadata
+     * @returns The created session
+     */
+    async createSession(workflowId, name, metadata) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.playground.createSession, {
+            id: workflowId
+        });
+        const response = await this.request(url, {
+            method: 'POST',
+            body: JSON.stringify({ name, metadata })
+        });
+        if (!response.data) {
+            throw new Error('Failed to create session: No data returned');
+        }
+        return response.data;
+    }
+    /**
+     * Get a playground session by ID
+     *
+     * @param sessionId - The session UUID
+     * @returns The session details
+     */
+    async getSession(sessionId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.playground.getSession, {
+            sessionId
+        });
+        const response = await this.request(url);
+        if (!response.data) {
+            throw new Error('Session not found');
+        }
+        return response.data;
+    }
+    /**
+     * Delete a playground session
+     *
+     * @param sessionId - The session UUID
+     */
+    async deleteSession(sessionId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.playground.deleteSession, {
+            sessionId
+        });
+        await this.request(url, {
+            method: 'DELETE'
+        });
+    }
+    // =========================================================================
+    // Message Handling
+    // =========================================================================
+    /**
+     * Get messages from a playground session
+     *
+     * @param sessionId - The session UUID
+     * @param since - Optional timestamp to fetch only newer messages (ISO 8601)
+     * @param limit - Maximum number of messages to return
+     * @returns Messages and session status
+     */
+    async getMessages(sessionId, since, limit) {
+        const config = this.getConfig();
+        let url = buildEndpointUrl(config, config.endpoints.playground.getMessages, {
+            sessionId
+        });
+        // Add query parameters
+        const params = new URLSearchParams();
+        if (since) {
+            params.append('since', since);
+        }
+        if (limit !== undefined) {
+            params.append('limit', limit.toString());
+        }
+        const queryString = params.toString();
+        if (queryString) {
+            url = `${url}?${queryString}`;
+        }
+        return this.request(url);
+    }
+    /**
+     * Send a message to a playground session
+     *
+     * @param sessionId - The session UUID
+     * @param content - The message content
+     * @param inputs - Optional additional inputs for workflow nodes
+     * @returns The created message
+     */
+    async sendMessage(sessionId, content, inputs) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.playground.sendMessage, {
+            sessionId
+        });
+        const requestBody = { content };
+        if (inputs) {
+            requestBody.inputs = inputs;
+        }
+        const response = await this.request(url, {
+            method: 'POST',
+            body: JSON.stringify(requestBody)
+        });
+        if (!response.data) {
+            throw new Error('Failed to send message: No data returned');
+        }
+        return response.data;
+    }
+    /**
+     * Stop execution in a playground session
+     *
+     * @param sessionId - The session UUID
+     */
+    async stopExecution(sessionId) {
+        const config = this.getConfig();
+        const url = buildEndpointUrl(config, config.endpoints.playground.stopExecution, {
+            sessionId
+        });
+        await this.request(url, {
+            method: 'POST'
+        });
+    }
+    // =========================================================================
+    // Polling
+    // =========================================================================
+    /**
+     * Start polling for new messages
+     *
+     * @param sessionId - The session UUID to poll
+     * @param callback - Callback function to handle new messages
+     * @param interval - Polling interval in milliseconds (default: 1500)
+     * @param shouldStopPolling - Optional override for stop conditions (default: defaultShouldStopPolling)
+     */
+    startPolling(sessionId, callback, interval = DEFAULT_POLLING_INTERVAL, shouldStopPolling) {
+        // Stop any existing polling
+        this.stopPolling();
+        this.pollingSessionId = sessionId;
+        this.currentBackoff = interval;
+        this.lastMessageTimestamp = null;
+        const shouldStop = shouldStopPolling ?? defaultShouldStopPolling;
+        const poll = async () => {
+            if (this.pollingSessionId !== sessionId) {
+                return;
+            }
+            try {
+                const response = await this.getMessages(sessionId, this.lastMessageTimestamp ?? undefined);
+                // Update last message timestamp
+                if (response.data && response.data.length > 0) {
+                    const lastMessage = response.data[response.data.length - 1];
+                    this.lastMessageTimestamp = lastMessage.timestamp;
+                }
+                // Reset backoff on successful request
+                this.currentBackoff = interval;
+                // Call the callback with new messages
+                callback(response);
+                // Stop polling if the status matches the stop condition
+                if (response.sessionStatus && shouldStop(response.sessionStatus)) {
+                    this.stopPolling();
+                    return;
+                }
+            }
+            catch (error) {
+                logger.error('Polling error:', error);
+                // Exponential backoff on error
+                this.currentBackoff = Math.min(this.currentBackoff * 2, MAX_POLLING_BACKOFF);
+            }
+            // Schedule next poll
+            if (this.pollingSessionId === sessionId) {
+                this.pollingInterval = setTimeout(poll, this.currentBackoff);
+            }
+        };
+        // Start polling immediately
+        poll();
+    }
+    /**
+     * Stop polling for messages
+     */
+    stopPolling() {
+        if (this.pollingInterval) {
+            clearTimeout(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+        this.pollingSessionId = null;
+        this.lastMessageTimestamp = null;
+        this.currentBackoff = DEFAULT_POLLING_INTERVAL;
+    }
+    /**
+     * 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 playgroundService = PlaygroundService.getInstance();

package/dist/services/portConfigApi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Port Configuration API Service
+ * Handles fetching port configuration from the backend
+ */
+import type { PortConfig } from '../types/index.js';
+import type { EndpointConfig } from '../config/endpoints.js';
+/**
+ * Fetch port configuration from API
+ */
+export declare function fetchPortConfig(endpointConfig: EndpointConfig): Promise<PortConfig>;
+/**
+ * Validate port configuration structure
+ */
+export declare function validatePortConfig(config: PortConfig): boolean;

package/dist/services/portConfigApi.js

@@ -0,0 +1,54 @@
+/**
+ * Port Configuration API Service
+ * Handles fetching port configuration from the backend
+ */
+import { buildEndpointUrl } from '../config/endpoints.js';
+import { DEFAULT_PORT_CONFIG } from '../config/defaultPortConfig.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Fetch port configuration from API
+ */
+export async function fetchPortConfig(endpointConfig) {
+    try {
+        const url = buildEndpointUrl(endpointConfig, endpointConfig.endpoints.portConfig);
+        const response = await fetch(url, {
+            headers: { 'Content-Type': 'application/json' }
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const data = await response.json();
+        const portConfig = data.data ?? data;
+        // Validate the configuration has required fields
+        if (!portConfig.dataTypes || !Array.isArray(portConfig.dataTypes)) {
+            logger.warn('Invalid port config received from API, using default');
+            return DEFAULT_PORT_CONFIG;
+        }
+        return portConfig;
+    }
+    catch (error) {
+        logger.error('Error fetching port configuration:', error);
+        return DEFAULT_PORT_CONFIG;
+    }
+}
+/**
+ * Validate port configuration structure
+ */
+export function validatePortConfig(config) {
+    if (!config || typeof config !== 'object') {
+        return false;
+    }
+    if (!config.dataTypes || !Array.isArray(config.dataTypes)) {
+        return false;
+    }
+    if (!config.defaultDataType || typeof config.defaultDataType !== 'string') {
+        return false;
+    }
+    // Check that all data types have required fields
+    for (const dataType of config.dataTypes) {
+        if (!dataType.id || !dataType.name || !dataType.color) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/services/settingsService.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Settings Service for FlowDrop
+ *
+ * Provides API operations for user preferences/settings using the
+ * configurable endpoint system. Integrates with settingsStore for
+ * hybrid localStorage + API persistence.
+ *
+ * @module services/settingsService
+ */
+import type { FlowDropSettings, PartialSettings } from '../types/settings.js';
+import type { EndpointConfig } from '../config/endpoints.js';
+/**
+ * Set the endpoint configuration for settings API calls
+ *
+ * @param config - Endpoint configuration
+ */
+export declare function setSettingsEndpointConfig(config: EndpointConfig): void;
+/**
+ * Get the current endpoint configuration
+ *
+ * @returns Current endpoint configuration or null
+ */
+export declare function getSettingsEndpointConfig(): EndpointConfig | null;
+/**
+ * Settings API namespace
+ */
+export declare const settingsApi: {
+    /**
+     * Get user preferences from the backend
+     *
+     * @returns User's saved preferences
+     */
+    getPreferences(): Promise<FlowDropSettings>;
+    /**
+     * Save user preferences to the backend
+     *
+     * @param settings - Complete settings to save
+     */
+    savePreferences(settings: FlowDropSettings): Promise<void>;
+    /**
+     * Partially update user preferences
+     *
+     * @param partial - Partial settings to merge
+     */
+    patchPreferences(partial: PartialSettings): Promise<FlowDropSettings>;
+};
+/**
+ * Settings service class for integration with settingsStore
+ *
+ * @example
+ * ```typescript
+ * import { SettingsService } from "@flowdrop/flowdrop";
+ * import { setSettingsService } from "@flowdrop/flowdrop";
+ *
+ * const service = new SettingsService(endpointConfig);
+ * setSettingsService(service);
+ * ```
+ */
+export declare class SettingsService {
+    private config;
+    /**
+     * Create a new settings service instance
+     *
+     * @param config - Endpoint configuration
+     */
+    constructor(config: EndpointConfig);
+    /**
+     * Get user preferences from the backend
+     *
+     * @returns User's saved preferences
+     */
+    getPreferences(): Promise<FlowDropSettings>;
+    /**
+     * Save user preferences to the backend
+     *
+     * @param settings - Complete settings to save
+     */
+    savePreferences(settings: FlowDropSettings): Promise<void>;
+    /**
+     * Partially update user preferences
+     *
+     * @param partial - Partial settings to merge
+     */
+    patchPreferences(partial: PartialSettings): Promise<FlowDropSettings>;
+}
+/**
+ * Create a settings service instance
+ *
+ * @param config - Endpoint configuration
+ * @returns SettingsService instance
+ */
+export declare function createSettingsService(config: EndpointConfig): SettingsService;