feat: add example client script demonstrating flow control, step monitoring, run retrieval,

and event subscription

- Introduces a new example TypeScript file with multiple usage scenarios
- Implements functions to start flows, monitor steps, retrieve previous runs, and subscribe
to events
- Demonstrates typed interactions with the client library and proper event handling
- Provides a comprehensive usage guide for the client library features in a single script

Author: jumski

pkgs/client/examples/basic.ts

@@ -0,0 +1,181 @@
+import { createClient } from '@supabase/supabase-js';
+import { AnalyzeWebsite } from '@pgflow/dsl/src/example-flow.js';
+import { PgflowClient } from '../src/lib/PgflowClient';
+import { FlowRunStatus, FlowStepStatus } from '../src/lib/types';
+
+// Create example client
+const supabaseUrl = 'https://example.supabase.co';
+const supabaseKey = 'your-supabase-key';
+const supabase = createClient(supabaseUrl, supabaseKey);
+
+// Create PgflowClient instance
+const client = new PgflowClient(supabase);
+
+/**
+ * Example 1: Start a flow and wait for completion
+ */
+async function startFlowAndWait() {
+  console.log('Starting flow...');
+
+  // Start the flow with specific input - TypeScript will enforce correct input shape
+  const run = await client.startFlow(AnalyzeWebsite.slug, {
+    url: 'https://example.com',
+  });
+
+  console.log(`Flow started with ID: ${run.run_id}`);
+
+  // Access run properties with proper typing
+  console.log(`Current status: ${run.status}`);
+  console.log(`Input: ${JSON.stringify(run.input)}`);
+
+  // Wait for the run to reach a terminal state
+  console.log('Waiting for flow to complete...');
+  const completed = await run.waitForStatus(FlowRunStatus.Completed, {
+    timeoutMs: 30000,
+  });
+  // Output is fully typed according to flow definition
+  console.log(`Flow completed!`);
+  console.log(`Output: ${JSON.stringify(completed.output)}`);
+
+  return completed;
+}
+
+/**
+ * Example 2: Monitor individual steps
+ */
+async function monitorSteps() {
+  // Start the flow - use Flow type directly rather than typeof
+  const run = await client.startFlow(
+    AnalyzeWebsite.slug,
+    {
+      url: 'https://example.com/blog',
+    }
+  );
+
+  console.log(`Monitoring steps for flow: ${run.run_id}`);
+
+  // Access a specific step - step slug is typed
+  const sentimentStep = run.step('sentiment');
+
+  // Register event handlers with proper typing
+  sentimentStep.on('started', (event) => {
+    console.log(`Sentiment analysis started at: ${event.started_at}`);
+  });
+
+  sentimentStep.on('completed', (event) => {
+    // Output is typed according to step definition
+    // Need to cast the output to the expected type
+    console.log(`Sentiment score: ${(event.output as { score: number }).score}`);
+  });
+
+  // Wait for the step to complete
+  await sentimentStep.waitForStatus(FlowStepStatus.Completed, {
+    timeoutMs: 20000,
+  });
+
+  // Get step state
+  console.log(`Step status: ${sentimentStep.status}`);
+  console.log(`Step output: ${JSON.stringify(sentimentStep.output)}`);
+
+  return run;
+}
+
+/**
+ * Example 3: Get a previous run
+ */
+async function getRun(runId: string) {
+  console.log(`Looking up run: ${runId}`);
+
+  // Fetch an existing run
+  const run = await client.getRun(runId);
+
+  if (!run) {
+    console.log(`Run not found: ${runId}`);
+    return null;
+  }
+
+  console.log(`Found run: ${run.run_id}`);
+  console.log(`Status: ${run.status}`);
+
+  // Check all steps
+  console.log('Steps:');
+  for (const stepSlug of ['website', 'sentiment', 'summary', 'saveToDb']) {
+    const step = run.step(stepSlug);
+    console.log(`  ${stepSlug}: ${step.status}`);
+
+    if (step.status === FlowStepStatus.Completed) {
+      console.log(`    Output: ${JSON.stringify(step.output)}`);
+    } else if (step.status === FlowStepStatus.Failed) {
+      console.log(`    Error: ${step.error_message}`);
+    }
+  }
+
+  return run;
+}
+
+/**
+ * Example 4: Using event listeners and run lifecycle
+ */
+async function subscribeToRunEvents() {
+  // Start the flow
+  const run = await client.startFlow(AnalyzeWebsite.slug, {
+    url: 'https://example.com/subscribe',
+  });
+
+  console.log(`Subscribed to run: ${run.run_id}`);
+
+  // Register global events listener
+  run.on('*', (event) => {
+    console.log(`Event received: ${event.status}`);
+  });
+
+  // Register specific event handlers
+  run.on('completed', (event) => {
+    console.log(`Run completed at: ${event.completed_at}`);
+    console.log(`Output: ${JSON.stringify(event.output)}`);
+  });
+
+  run.on('failed', (event) => {
+    console.log(`Run failed at: ${event.failed_at}`);
+    console.log(`Error: ${event.error_message}`);
+  });
+
+  // Wait for completion and then clean up
+  await run.waitForStatus(FlowRunStatus.Completed);
+
+  // Dispose the run when done to clean up resources
+  run.dispose();
+
+  return run.run_id;
+}
+
+/**
+ * Main function to run all examples
+ */
+async function main() {
+  try {
+    console.log('=== Example 1: Start flow and wait ===');
+    const completedRun = await startFlowAndWait();
+
+    console.log('\n=== Example 2: Monitor steps ===');
+    await monitorSteps();
+
+    console.log('\n=== Example 3: Get previous run ===');
+    await getRun(completedRun.run_id);
+
+    console.log('\n=== Example 4: Subscribe to events ===');
+    await subscribeToRunEvents();
+  } catch (error) {
+    console.error('Error running examples:', error);
+  } finally {
+    // Clean up all resources
+    client.disposeAll();
+  }
+}
+
+// Only execute if run directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { startFlowAndWait, monitorSteps, getRun, subscribeToRunEvents };