@pgflow/client 0.0.0-array-map-steps-fixed-types-38a198ae-20251011160533 → 0.0.0-control-plane-a947cb71-20251121164755

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

@@ -1 +1 @@
-{"version":3,"file":"PgflowClient.d.ts","sourceRoot":"","sources":["../../../src/lib/PgflowClient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EAEZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC;;GAEG;AACH,qBAAa,YAAY,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,CAAE,YAAW,WAAW,CAAC,KAAK,CAAC;;IAOtF;;;;OAIG;gBACS,cAAc,EAAE,cAAc;IAwB1C;;;;;;;OAOG;IACG,SAAS,CAAC,aAAa,SAAS,KAAK,EACzC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,gBAAgB,CAAC,aAAa,CAAC,EACtC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAwDlC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAc5B;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM;;;;IAI3C;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,WAAW;IAIrE;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,WAAW;IAIvE;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAIzD;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM;;;;IAIrC;;;;;OAKG;IACG,MAAM,CAAC,aAAa,SAAS,KAAK,GAAG,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;CA6E1G"}
+{"version":3,"file":"PgflowClient.d.ts","sourceRoot":"","sources":["../../../src/lib/PgflowClient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EAEZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC;;GAEG;AACH,qBAAa,YAAY,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,CAAE,YAAW,WAAW,CAAC,KAAK,CAAC;;IAOtF;;;;;OAKG;gBAED,cAAc,EAAE,cAAc,EAC9B,IAAI,GAAE;QACJ,4BAA4B,CAAC,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,EAAE,OAAO,UAAU,CAAC;KACzB;IA4BR;;;;;;;OAOG;IACG,SAAS,CAAC,aAAa,SAAS,KAAK,EACzC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,gBAAgB,CAAC,aAAa,CAAC,EACtC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAwDlC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAc5B;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM;;;;IAI3C;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,WAAW;IAIrE;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,WAAW;IAIvE;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAIzD;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM;;;;IAIrC;;;;;OAKG;IACG,MAAM,CAAC,aAAa,SAAS,KAAK,GAAG,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;CA6E1G"}

package/dist/src/lib/PgflowClient.js

@@ -0,0 +1,227 @@
+import { v4 as uuidv4 } from 'uuid';
+import { FlowRunStatus } from './types.js';
+import { SupabaseBroadcastAdapter } from './SupabaseBroadcastAdapter.js';
+import { FlowRun } from './FlowRun.js';
+import { toTypedRunEvent, toTypedStepEvent } from './eventAdapters.js';
+/**
+ * Client for interacting with pgflow
+ */
+export class PgflowClient {
+    #supabase;
+    #realtimeAdapter;
+    // Use the widest event type - keeps the compiler happy but
+    // still provides the structural API we need (updateState/step/...)
+    #runs = new Map();
+    /**
+     * Creates a new PgflowClient instance
+     *
+     * @param supabaseClient - Supabase client instance
+     * @param opts - Optional configuration
+     */
+    constructor(supabaseClient, opts = {}) {
+        this.#supabase = supabaseClient;
+        this.#realtimeAdapter = new SupabaseBroadcastAdapter(supabaseClient, {
+            stabilizationDelayMs: opts.realtimeStabilizationDelayMs,
+            schedule: opts.schedule,
+        });
+        // Set up global event listeners - properly typed
+        this.#realtimeAdapter.onRunEvent((event) => {
+            const run = this.#runs.get(event.run_id);
+            if (run) {
+                // Convert broadcast event to typed event before updating state
+                run.updateState(toTypedRunEvent(event));
+            }
+        });
+        this.#realtimeAdapter.onStepEvent((event) => {
+            const run = this.#runs.get(event.run_id);
+            if (run) {
+                // Always materialize the step before updating to avoid event loss
+                // This ensures we cache all steps even if they were never explicitly requested
+                const stepSlug = event.step_slug;
+                run.step(stepSlug).updateState(toTypedStepEvent(event));
+            }
+        });
+    }
+    /**
+     * Start a flow with optional run_id
+     *
+     * @param flow_slug - Flow slug to start
+     * @param input - Input data for the flow
+     * @param run_id - Optional run ID (will be generated if not provided)
+     * @returns Promise that resolves with the FlowRun instance
+     */
+    async startFlow(flow_slug, input, run_id) {
+        // Generate a run_id if not provided
+        const id = run_id || uuidv4();
+        // Create initial state for the flow run
+        const initialState = {
+            run_id: id,
+            flow_slug,
+            status: FlowRunStatus.Started,
+            input: input,
+            output: null,
+            error: null,
+            error_message: null,
+            started_at: null,
+            completed_at: null,
+            failed_at: null,
+            remaining_steps: -1, // Use -1 to indicate unknown until first snapshot arrives
+        };
+        // Create the flow run instance
+        const run = new FlowRun(initialState);
+        // Store the run
+        this.#runs.set(id, run);
+        // Set up subscription for run and step events (wait for subscription confirmation)
+        await this.#realtimeAdapter.subscribeToRun(id);
+        // Start the flow with the predetermined run_id (only after subscription is ready)
+        const { data, error } = await this.#supabase.schema('pgflow').rpc('start_flow_with_states', {
+            flow_slug: flow_slug,
+            input: input,
+            run_id: id
+        });
+        if (error) {
+            // Clean up subscription and run instance
+            this.dispose(id);
+            throw error;
+        }
+        // Apply the run state snapshot (no events)
+        if (data.run) {
+            run.applySnapshot(data.run);
+        }
+        // Apply step state snapshots (no events)
+        if (data.steps && Array.isArray(data.steps)) {
+            for (const stepState of data.steps) {
+                run.step(stepState.step_slug).applySnapshot(stepState);
+            }
+        }
+        return run;
+    }
+    /**
+     * Dispose a specific flow run
+     *
+     * @param runId - Run ID to dispose
+     */
+    dispose(runId) {
+        const run = this.#runs.get(runId);
+        if (run) {
+            // First unsubscribe from the realtime adapter
+            this.#realtimeAdapter.unsubscribe(runId);
+            // Then dispose the run
+            run.dispose();
+            // Finally remove from the runs map
+            this.#runs.delete(runId);
+        }
+    }
+    /**
+     * Dispose all flow runs
+     */
+    disposeAll() {
+        for (const runId of this.#runs.keys()) {
+            this.dispose(runId);
+        }
+    }
+    // Delegate IFlowRealtime methods to the adapter
+    /**
+     * Fetch flow definition metadata
+     */
+    async fetchFlowDefinition(flow_slug) {
+        return this.#realtimeAdapter.fetchFlowDefinition(flow_slug);
+    }
+    /**
+     * Register a callback for run events
+     * @returns Function to unsubscribe from the event
+     */
+    onRunEvent(callback) {
+        return this.#realtimeAdapter.onRunEvent(callback);
+    }
+    /**
+     * Register a callback for step events
+     * @returns Function to unsubscribe from the event
+     */
+    onStepEvent(callback) {
+        return this.#realtimeAdapter.onStepEvent(callback);
+    }
+    /**
+     * Subscribe to a flow run's events
+     */
+    async subscribeToRun(run_id) {
+        return await this.#realtimeAdapter.subscribeToRun(run_id);
+    }
+    /**
+     * Fetch current state of a run and its steps
+     */
+    async getRunWithStates(run_id) {
+        return this.#realtimeAdapter.getRunWithStates(run_id);
+    }
+    /**
+     * Get a flow run by ID
+     *
+     * @param run_id - ID of the run to get
+     * @returns Promise that resolves with the FlowRun instance or null if not found
+     */
+    async getRun(run_id) {
+        // Check if we already have this run cached
+        const existingRun = this.#runs.get(run_id);
+        if (existingRun) {
+            return existingRun;
+        }
+        try {
+            // Fetch the run state from the database
+            const { run, steps } = await this.getRunWithStates(run_id);
+            if (!run) {
+                return null;
+            }
+            // Validate required fields
+            if (!run.run_id || !run.flow_slug || !run.status) {
+                throw new Error('Invalid run data: missing required fields');
+            }
+            // Validate status is a valid FlowRunStatus
+            const validStatuses = Object.values(FlowRunStatus);
+            if (!validStatuses.includes(run.status)) {
+                throw new Error(`Invalid run data: invalid status '${run.status}'`);
+            }
+            // Create flow run with minimal initial state
+            const initialState = {
+                run_id: run.run_id,
+                flow_slug: run.flow_slug,
+                status: run.status,
+                input: run.input,
+                output: null,
+                error: null,
+                error_message: null,
+                started_at: null,
+                completed_at: null,
+                failed_at: null,
+                remaining_steps: 0,
+            };
+            // Create the flow run instance
+            const flowRun = new FlowRun(initialState);
+            // Apply the complete state from database snapshot
+            flowRun.applySnapshot(run);
+            // Store the run
+            this.#runs.set(run_id, flowRun);
+            // Set up subscription for run and step events
+            await this.#realtimeAdapter.subscribeToRun(run_id);
+            // Initialize steps from snapshot
+            if (steps && Array.isArray(steps)) {
+                for (const stepState of steps) {
+                    // Validate step has required fields
+                    if (!stepState.step_slug || !stepState.status) {
+                        throw new Error('Invalid step data: missing required fields');
+                    }
+                    // Apply snapshot state directly (no events)
+                    flowRun.step(stepState.step_slug).applySnapshot(stepState);
+                }
+            }
+            return flowRun;
+        }
+        catch (error) {
+            console.error('Error getting run:', error);
+            // Re-throw if it's a validation error
+            if (error instanceof Error && (error.message.includes('Invalid run data') || error.message.includes('Invalid step data'))) {
+                throw error;
+            }
+            return null;
+        }
+    }
+}

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

@@ -1,7 +1,6 @@
-import { IFlowRealtime, BroadcastRunEvent, BroadcastStepEvent, Unsubscribe } from './types.js';
-import { FlowRow, StepRow, RunRow, StepStateRow } from '../../../core/src/index.ts';
-import { SupabaseClient } from '@supabase/supabase-js';
-
+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
  */
@@ -14,6 +13,7 @@ export declare class SupabaseBroadcastAdapter implements IFlowRealtime {
      */
     constructor(supabase: SupabaseClient, opts?: {
         reconnectDelayMs?: number;
+        stabilizationDelayMs?: number;
         schedule?: typeof setTimeout;
     });
     /**

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

@@ -1 +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;;IAQ5D;;;;OAIG;gBAED,QAAQ,EAAE,cAAc,EACxB,IAAI,GAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,UAAU,CAAA;KAAO;IAkLxE;;;;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;IA0DzD;;;;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"}
+{"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

@@ -1,7 +1,6 @@
-import { BroadcastRunEvent, BroadcastStepEvent, FlowRunEvent, StepEvent } from './types.js';
-import { RunRow, StepStateRow } from '../../../core/src/index.ts';
-import { AnyFlow, ExtractFlowSteps } from '../../../dsl/src/index.ts';
-
+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
  */