@pgflow/client 0.0.0-update-supabase-ba45e13a-20251119080026 → 0.0.0-worker-management-a4f969d1-20251208095931

package/dist/src/lib/SupabaseBroadcastAdapter.d.ts

@@ -0,0 +1,65 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { FlowRow, StepRow, RunRow, StepStateRow } from '@pgflow/core';
+import type { IFlowRealtime, BroadcastRunEvent, BroadcastStepEvent, Unsubscribe } from './types.js';
+/**
+ * Adapter to handle realtime communication with Supabase
+ */
+export declare class SupabaseBroadcastAdapter implements IFlowRealtime {
+    #private;
+    /**
+     * Creates a new instance of SupabaseBroadcastAdapter
+     *
+     * @param supabase - Supabase client instance
+     */
+    constructor(supabase: SupabaseClient, opts?: {
+        reconnectDelayMs?: number;
+        stabilizationDelayMs?: number;
+        schedule?: typeof setTimeout;
+    });
+    /**
+     * Fetches flow definition metadata from the database
+     *
+     * @param flow_slug - Flow slug to fetch
+     */
+    fetchFlowDefinition(flow_slug: string): Promise<{
+        flow: FlowRow;
+        steps: StepRow[];
+    }>;
+    /**
+     * Registers a callback for run events
+     *
+     * @param callback - Function to call when run events are received
+     * @returns Function to unsubscribe from the event
+     */
+    onRunEvent(callback: (event: BroadcastRunEvent) => void): Unsubscribe;
+    /**
+     * Registers a callback for step events
+     *
+     * @param callback - Function to call when step events are received
+     * @returns Function to unsubscribe from the event
+     */
+    onStepEvent(callback: (event: BroadcastStepEvent) => void): Unsubscribe;
+    /**
+     * Subscribes to a flow run's events
+     *
+     * @param run_id - Run ID to subscribe to
+     * @returns Function to unsubscribe
+     */
+    subscribeToRun(run_id: string): Promise<() => void>;
+    /**
+     * Unsubscribes from a run's events
+     *
+     * @param run_id - Run ID to unsubscribe from
+     */
+    unsubscribe(run_id: string): void;
+    /**
+     * Fetches current state of a run and its steps
+     *
+     * @param run_id - Run ID to fetch
+     */
+    getRunWithStates(run_id: string): Promise<{
+        run: RunRow;
+        steps: StepStateRow[];
+    }>;
+}
+//# sourceMappingURL=SupabaseBroadcastAdapter.d.ts.map

package/dist/src/lib/SupabaseBroadcastAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseBroadcastAdapter.d.ts","sourceRoot":"","sources":["../../../src/lib/SupabaseBroadcastAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACZ,MAAM,YAAY,CAAC;AAQpB;;GAEG;AACH,qBAAa,wBAAyB,YAAW,aAAa;;IAS5D;;;;OAIG;gBAED,QAAQ,EAAE,cAAc,EACxB,IAAI,GAAE;QACJ,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,EAAE,OAAO,UAAU,CAAC;KACzB;IAmLR;;;;OAIG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QACpD,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EAAE,OAAO,EAAE,CAAC;KAClB,CAAC;IAiCF;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,WAAW;IAYrE;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,WAAW;IAevE;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAgEzD;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAC9C,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,YAAY,EAAE,CAAC;KACvB,CAAC;CAiCH"}

package/dist/src/lib/SupabaseBroadcastAdapter.js

@@ -0,0 +1,332 @@
+import { createNanoEvents } from 'nanoevents';
+/**
+ * Adapter to handle realtime communication with Supabase
+ */
+export class SupabaseBroadcastAdapter {
+    #supabase;
+    #channels = new Map();
+    #emitter = createNanoEvents();
+    #reconnectionDelay;
+    #stabilizationDelay;
+    #schedule;
+    /**
+     * Creates a new instance of SupabaseBroadcastAdapter
+     *
+     * @param supabase - Supabase client instance
+     */
+    constructor(supabase, opts = {}) {
+        this.#supabase = supabase;
+        this.#reconnectionDelay = opts.reconnectDelayMs ?? 2000;
+        this.#stabilizationDelay = opts.stabilizationDelayMs ?? 300;
+        this.#schedule = opts.schedule ?? setTimeout;
+    }
+    /**
+     * Handle broadcast messages from Supabase
+     * @param payload - The message payload
+     */
+    #handleBroadcastMessage(msg) {
+        const { event, payload } = msg;
+        // run_id is already inside the payload coming from the database trigger
+        // so just preserve it without overwriting
+        const eventData = payload;
+        // Auto-parse JSON strings in broadcast data (realtime sends JSONB as strings)
+        this.#parseJsonFields(eventData);
+        if (event.startsWith('run:')) {
+            // Handle run events
+            this.#emitter.emit('runEvent', eventData);
+        }
+        else if (event.startsWith('step:')) {
+            // Handle step events
+            this.#emitter.emit('stepEvent', eventData);
+        }
+    }
+    /**
+     * Parse JSON string fields in broadcast event data
+     * @param eventData - The event data object to parse
+     */
+    #parseJsonFields(eventData) {
+        // Parse output field if it's a JSON string
+        if ('output' in eventData && typeof eventData.output === 'string') {
+            try {
+                eventData.output = JSON.parse(eventData.output);
+            }
+            catch {
+                // Keep as string if not valid JSON
+            }
+        }
+        // Parse input field if it's a JSON string
+        if ('input' in eventData && typeof eventData.input === 'string') {
+            try {
+                eventData.input = JSON.parse(eventData.input);
+            }
+            catch {
+                // Keep as string if not valid JSON
+            }
+        }
+    }
+    /**
+     * Handle channel errors and reconnection
+     * @param run_id - The run ID
+     * @param channelName - The channel name
+     * @param channel - The RealtimeChannel instance
+     * @param error - The error object
+     */
+    async #handleChannelError(run_id, channelName, channel, error) {
+        console.error(`Channel ${channelName} error:`, error);
+        // Schedule reconnection attempt
+        this.#schedule(async () => {
+            if (this.#channels.has(run_id)) {
+                await this.#reconnectChannel(run_id, channelName);
+            }
+        }, this.#reconnectionDelay);
+    }
+    /**
+     * Creates and configures a channel for a run
+     * @param run_id - The run ID
+     * @param channelName - The channel name
+     * @returns The configured RealtimeChannel
+     */
+    #createAndConfigureChannel(run_id, channelName) {
+        const channel = this.#supabase.channel(channelName);
+        // Listen to *all* broadcast messages; filter inside the handler.
+        // Using the 3-arg overload with event filter for proper Supabase v2 client compatibility.
+        channel.on('broadcast', { event: '*' }, this.#handleBroadcastMessage.bind(this));
+        // Note: Lifecycle event listeners (subscribed, closed, error) are handled 
+        // by the calling code to avoid conflicts when multiple listeners try to 
+        // handle the same events.
+        return channel;
+    }
+    /**
+     * Reconnect to a channel and refresh state
+     * @param run_id - The run ID
+     * @param channelName - The channel name
+     */
+    async #reconnectChannel(run_id, channelName) {
+        console.log(`Attempting to reconnect to ${channelName}`);
+        try {
+            // Fetch current state to avoid missing events during disconnection
+            const currentState = await this.getRunWithStates(run_id);
+            // Update state based on current data
+            this.#refreshStateFromSnapshot(run_id, currentState);
+            // Create a new channel as the old one can't be reused
+            const newChannel = this.#createAndConfigureChannel(run_id, channelName);
+            // Set up lifecycle event handlers for reconnection
+            newChannel.on('system', { event: 'subscribed' }, () => {
+                console.log(`Reconnected and subscribed to channel ${channelName}`);
+            });
+            newChannel.on('system', { event: 'closed' }, () => {
+                console.log(`Reconnected channel ${channelName} closed`);
+            });
+            newChannel.on('system', { event: 'error' }, (payload) => this.#handleChannelError(run_id, channelName, newChannel, payload.error));
+            // Subscribe and update the channels map
+            newChannel.subscribe();
+            this.#channels.set(run_id, newChannel);
+        }
+        catch (e) {
+            console.error(`Failed to reconnect to ${channelName}:`, e);
+        }
+    }
+    /**
+     * Refresh client state from a state snapshot
+     * @param run_id - The run ID
+     * @param state - The state snapshot
+     */
+    #refreshStateFromSnapshot(run_id, state) {
+        if (!state || !state.run)
+            return;
+        // Create proper run event with correct event_type
+        const runEvent = {
+            event_type: `run:${state.run.status}`,
+            ...state.run
+        };
+        // Emit run event
+        this.#emitter.emit('runEvent', runEvent);
+        // Emit events for each step state
+        if (state.steps && Array.isArray(state.steps)) {
+            for (const step of state.steps) {
+                // Create proper step event with correct event_type
+                const stepEvent = {
+                    event_type: `step:${step.status}`,
+                    ...step
+                };
+                // Emit step event
+                this.#emitter.emit('stepEvent', stepEvent);
+            }
+        }
+    }
+    /**
+     * Fetches flow definition metadata from the database
+     *
+     * @param flow_slug - Flow slug to fetch
+     */
+    async fetchFlowDefinition(flow_slug) {
+        // Fetch flow details and steps in parallel
+        const [flowResult, stepsResult] = await Promise.all([
+            this.#supabase
+                .schema('pgflow')
+                .from('flows')
+                .select('*')
+                .eq('flow_slug', flow_slug)
+                .single(),
+            this.#supabase
+                .schema('pgflow')
+                .from('steps')
+                .select('*')
+                .eq('flow_slug', flow_slug)
+                .order('step_index', { ascending: true })
+        ]);
+        // Handle flow result
+        if (flowResult.error)
+            throw flowResult.error;
+        if (!flowResult.data)
+            throw new Error(`Flow "${flow_slug}" not found`);
+        // Handle steps result
+        if (stepsResult.error)
+            throw stepsResult.error;
+        // Ensure steps is always an array, even if it's null or undefined
+        const stepsArray = Array.isArray(stepsResult.data) ? stepsResult.data : [];
+        return {
+            flow: flowResult.data,
+            steps: stepsArray,
+        };
+    }
+    /**
+     * Registers a callback for run events
+     *
+     * @param callback - Function to call when run events are received
+     * @returns Function to unsubscribe from the event
+     */
+    onRunEvent(callback) {
+        // Add a guard to prevent errors if called after emitter is deleted
+        const unsubscribe = this.#emitter.on('runEvent', callback);
+        return () => {
+            try {
+                unsubscribe();
+            }
+            catch (e) {
+                console.warn('Could not unsubscribe from run event - emitter may have been disposed', e);
+            }
+        };
+    }
+    /**
+     * Registers a callback for step events
+     *
+     * @param callback - Function to call when step events are received
+     * @returns Function to unsubscribe from the event
+     */
+    onStepEvent(callback) {
+        // Add a guard to prevent errors if called after emitter is deleted
+        const unsubscribe = this.#emitter.on('stepEvent', callback);
+        return () => {
+            try {
+                unsubscribe();
+            }
+            catch (e) {
+                console.warn('Could not unsubscribe from step event - emitter may have been disposed', e);
+            }
+        };
+    }
+    // Store unsubscribe functions per run ID for reference equality
+    #unsubscribeFunctions = new Map();
+    /**
+     * Subscribes to a flow run's events
+     *
+     * @param run_id - Run ID to subscribe to
+     * @returns Function to unsubscribe
+     */
+    async subscribeToRun(run_id) {
+        const channelName = `pgflow:run:${run_id}`;
+        // If already subscribed, return the existing unsubscribe function
+        if (this.#channels.has(run_id)) {
+            const existingUnsubscribe = this.#unsubscribeFunctions.get(run_id);
+            if (existingUnsubscribe) {
+                return existingUnsubscribe;
+            }
+            // If channel exists but no unsubscribe function, something went wrong
+            // Let's clean up and recreate
+            this.#unsubscribe(run_id);
+        }
+        const channel = this.#supabase.channel(channelName);
+        // Listen to *all* broadcast messages; filter inside the handler.
+        // Using the 3-arg overload with event filter for proper Supabase v2 client compatibility.
+        channel.on('broadcast', { event: '*' }, this.#handleBroadcastMessage.bind(this));
+        // Set up error handling
+        channel.on('system', { event: 'closed' }, () => {
+            console.log(`Channel ${channelName} closed`);
+        });
+        channel.on('system', { event: 'error' }, (payload) => {
+            console.log(`Channel ${channelName} error:`, payload);
+            this.#handleChannelError(run_id, channelName, channel, payload.error);
+        });
+        // Subscribe to channel and wait for confirmation (like the working realtime-send test)
+        console.log(`Subscribing to channel ${channelName}...`);
+        const subscriptionPromise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error(`Subscription timeout for channel ${channelName}`));
+            }, 20000); // Increased from 5s to 20s for slower CI environments
+            channel.subscribe((status) => {
+                console.log(`Channel ${channelName} subscription status:`, status);
+                if (status === 'SUBSCRIBED') {
+                    clearTimeout(timeout);
+                    resolve();
+                }
+                // Don't reject on CHANNEL_ERROR - it's a transient state
+                // Only reject on timeout
+            });
+        });
+        // Wait for the 'SUBSCRIBED' acknowledgment to avoid race conditions
+        await subscriptionPromise;
+        // Stabilization delay - known Supabase Realtime limitation
+        // The SUBSCRIBED event is emitted before backend routing is fully established.
+        // This delay ensures the backend can receive messages sent immediately after subscription.
+        // See: https://github.com/supabase/supabase-js/issues/1599
+        await new Promise(resolve => this.#schedule(resolve, this.#stabilizationDelay));
+        this.#channels.set(run_id, channel);
+        const unsubscribe = () => this.unsubscribe(run_id);
+        this.#unsubscribeFunctions.set(run_id, unsubscribe);
+        return unsubscribe;
+    }
+    /**
+     * Unsubscribes from a run's events
+     *
+     * @param run_id - Run ID to unsubscribe from
+     */
+    unsubscribe(run_id) {
+        this.#unsubscribe(run_id);
+    }
+    /**
+     * Fetches current state of a run and its steps
+     *
+     * @param run_id - Run ID to fetch
+     */
+    async getRunWithStates(run_id) {
+        // Call the RPC function which returns a JSONB object
+        const { data, error } = await this.#supabase
+            .schema('pgflow')
+            .rpc('get_run_with_states', { run_id });
+        if (error)
+            throw error;
+        if (!data)
+            throw new Error(`No data returned for run ${run_id}`);
+        return data;
+    }
+    /**
+     * Unsubscribes from a run's events
+     *
+     * @param run_id - Run ID to unsubscribe from
+     */
+    #unsubscribe(run_id) {
+        const channel = this.#channels.get(run_id);
+        if (channel) {
+            // Close the channel
+            channel.unsubscribe();
+            this.#channels.delete(run_id);
+            // Also clean up the unsubscribe function reference
+            this.#unsubscribeFunctions.delete(run_id);
+            // We don't need to explicitly remove event listeners from the emitter
+            // as they will be garbage collected when no longer referenced.
+            // The event listeners are bound to specific callbacks provided by the client,
+            // which will retain references if they're still in use.
+        }
+    }
+}

package/dist/src/lib/eventAdapters.d.ts

@@ -0,0 +1,20 @@
+import type { AnyFlow, ExtractFlowSteps } from '@pgflow/dsl';
+import type { RunRow, StepStateRow } from '@pgflow/core';
+import type { BroadcastRunEvent, BroadcastStepEvent, FlowRunEvent, StepEvent } from './types.js';
+/**
+ * Convert a broadcast run event to a typed run event
+ */
+export declare function toTypedRunEvent<TFlow extends AnyFlow>(evt: BroadcastRunEvent): FlowRunEvent<TFlow>;
+/**
+ * Convert a broadcast step event to a typed step event
+ */
+export declare function toTypedStepEvent<TFlow extends AnyFlow, TStepSlug extends keyof ExtractFlowSteps<TFlow> & string>(evt: BroadcastStepEvent): StepEvent<TFlow, TStepSlug>;
+/**
+ * Convert a database run row to a typed run event
+ */
+export declare function runRowToTypedEvent<TFlow extends AnyFlow>(row: RunRow): FlowRunEvent<TFlow>;
+/**
+ * Convert a database step state row to a typed step event
+ */
+export declare function stepStateRowToTypedEvent<TFlow extends AnyFlow, TStepSlug extends keyof ExtractFlowSteps<TFlow> & string>(row: StepStateRow): StepEvent<TFlow, TStepSlug>;
+//# sourceMappingURL=eventAdapters.d.ts.map

package/dist/src/lib/eventAdapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventAdapters.d.ts","sourceRoot":"","sources":["../../../src/lib/eventAdapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAGP,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKzD,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,OAAO,EACnD,GAAG,EAAE,iBAAiB,GACrB,YAAY,CAAC,KAAK,CAAC,CA+BrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,SAAS,OAAO,EACrB,SAAS,SAAS,MAAM,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxD,GAAG,EAAE,kBAAkB,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CA6BtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,OAAO,EACtD,GAAG,EAAE,MAAM,GACV,YAAY,CAAC,KAAK,CAAC,CAiCrB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,SAAS,OAAO,EACrB,SAAS,SAAS,MAAM,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxD,GAAG,EAAE,YAAY,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAgChD"}

package/dist/src/lib/eventAdapters.js

@@ -0,0 +1,142 @@
+import { FlowStepStatus, FlowRunStatus, } from './types.js';
+/**
+ * Convert a broadcast run event to a typed run event
+ */
+export function toTypedRunEvent(evt) {
+    switch (evt.status) {
+        case FlowRunStatus.Started:
+            return {
+                event_type: 'run:started',
+                run_id: evt.run_id,
+                flow_slug: evt.flow_slug,
+                status: FlowRunStatus.Started,
+                started_at: evt.started_at,
+                remaining_steps: evt.remaining_steps,
+                input: evt.input,
+            };
+        case FlowRunStatus.Completed:
+            return {
+                event_type: 'run:completed',
+                run_id: evt.run_id,
+                flow_slug: evt.flow_slug,
+                status: FlowRunStatus.Completed,
+                completed_at: evt.completed_at,
+                output: evt.output,
+            };
+        case FlowRunStatus.Failed:
+            return {
+                event_type: 'run:failed',
+                run_id: evt.run_id,
+                flow_slug: evt.flow_slug,
+                status: FlowRunStatus.Failed,
+                failed_at: evt.failed_at,
+                error_message: evt.error_message,
+            };
+    }
+}
+/**
+ * Convert a broadcast step event to a typed step event
+ */
+export function toTypedStepEvent(evt) {
+    switch (evt.status) {
+        case FlowStepStatus.Started:
+            return {
+                event_type: 'step:started',
+                run_id: evt.run_id,
+                step_slug: evt.step_slug,
+                status: FlowStepStatus.Started,
+                started_at: evt.started_at,
+            };
+        case FlowStepStatus.Completed:
+            return {
+                event_type: 'step:completed',
+                run_id: evt.run_id,
+                step_slug: evt.step_slug,
+                status: FlowStepStatus.Completed,
+                completed_at: evt.completed_at,
+                output: evt.output,
+            };
+        case FlowStepStatus.Failed:
+            return {
+                event_type: 'step:failed',
+                run_id: evt.run_id,
+                step_slug: evt.step_slug,
+                status: FlowStepStatus.Failed,
+                failed_at: evt.failed_at,
+                error_message: evt.error_message,
+            };
+    }
+}
+/**
+ * Convert a database run row to a typed run event
+ */
+export function runRowToTypedEvent(row) {
+    switch (row.status) {
+        case 'started':
+            return {
+                event_type: 'run:started',
+                run_id: row.run_id,
+                flow_slug: row.flow_slug,
+                status: FlowRunStatus.Started,
+                started_at: row.started_at,
+                remaining_steps: row.remaining_steps,
+                input: row.input,
+            };
+        case 'completed':
+            return {
+                event_type: 'run:completed',
+                run_id: row.run_id,
+                flow_slug: row.flow_slug,
+                status: FlowRunStatus.Completed,
+                completed_at: row.completed_at,
+                output: row.output,
+            };
+        case 'failed':
+            return {
+                event_type: 'run:failed',
+                run_id: row.run_id,
+                flow_slug: row.flow_slug,
+                status: FlowRunStatus.Failed,
+                failed_at: row.failed_at,
+                error_message: 'Flow failed', // Database doesn't have error_message for runs
+            };
+        default:
+            throw new Error(`Unknown run status: ${row.status}`);
+    }
+}
+/**
+ * Convert a database step state row to a typed step event
+ */
+export function stepStateRowToTypedEvent(row) {
+    switch (row.status) {
+        case 'created':
+        case 'started':
+            return {
+                event_type: 'step:started',
+                run_id: row.run_id,
+                step_slug: row.step_slug,
+                status: FlowStepStatus.Started,
+                started_at: row.started_at,
+            };
+        case 'completed':
+            return {
+                event_type: 'step:completed',
+                run_id: row.run_id,
+                step_slug: row.step_slug,
+                status: FlowStepStatus.Completed,
+                completed_at: row.completed_at,
+                output: {}, // Database doesn't have output in step_states
+            };
+        case 'failed':
+            return {
+                event_type: 'step:failed',
+                run_id: row.run_id,
+                step_slug: row.step_slug,
+                status: FlowStepStatus.Failed,
+                failed_at: row.failed_at,
+                error_message: row.error_message || 'Step failed',
+            };
+        default:
+            throw new Error(`Unknown step status: ${row.status}`);
+    }
+}