simplex-ts 3.6.18 → 3.6.20

package/README.md

@@ -2,241 +2,288 @@
 
 Official TypeScript SDK for the Simplex API.
 
+This guide provides practical examples for integrating Simplex into your TypeScript applications.
+
 ## Installation
 
 ```bash
 npm install simplex-ts
 ```
 
-## Quick Start
+## Initializing the client
 
 ```typescript
 import { SimplexClient } from 'simplex-ts';
 
 const client = new SimplexClient({
-  apiKey: 'YOUR_API_KEY_HERE'
-});
-
-// Run a workflow without variables
-const result = await client.workflows.run('workflow-id');
-
-// Run a workflow with variables
-const resultWithVars = await client.workflows.run('workflow-id', {
-  variables: {
-    username: 'john_doe',
-    product_id: '12345'
-  }
+  apiKey: process.env.SIMPLEX_API_KEY
 });
-
-console.log('Session ID:', result.session_id);
 ```
 
-## Configuration
+### Configuration options
 
 ```typescript
 const client = new SimplexClient({
-  apiKey: 'YOUR_API_KEY_HERE',
-  timeout: 30000,      // Optional: Request timeout in ms (default: 30000)
-  maxRetries: 3,       // Optional: Number of retries (default: 3)
-  retryDelay: 1000     // Optional: Delay between retries in ms (default: 1000)
+  apiKey: process.env.SIMPLEX_API_KEY,
+  timeout: 30000,      // Request timeout in ms (default: 30000)
+  maxRetries: 3,       // Number of retry attempts (default: 3)
+  retryDelay: 1000     // Delay between retries in ms (default: 1000)
 });
 ```
 
-## API Methods
-
-### Workflows
+## Running workflows
 
-#### Run a workflow
+### Basic workflow execution
 
 ```typescript
-// Run without any options
-const result = await client.workflows.run('workflow-id');
-
-// Run with variables
-const result = await client.workflows.run('workflow-id', {
-  variables: { key: 'value' }
+const result = await client.workflows.run('workflow_id', {
+  variables: {
+    username: 'user@example.com',
+    search_query: 'order #12345'
+  }
 });
 
-// Run with all options
-const result = await client.workflows.run('workflow-id', {
-  variables: { key: 'value' },
-  metadata: 'optional-metadata',
-  webhookUrl: 'https://your-webhook.com'
+console.log('Session ID:', result.session_id);
+```
+
+### With debug webhook callback (useful for local testing)
+
+```typescript
+const result = await client.workflows.run('workflow_id', {
+  variables: {
+    patient_id: 'P-12345'
+  },
+  webhookUrl: 'https://59d9f4dbc.ngrok-free.app/api/webhook',
+  metadata: 'req-789'
 });
 ```
 
-#### Search workflows
+## Handling webhook responses
 
-Search for workflows by name and/or metadata. Both parameters support partial matching.
+### Next.js App Router
 
 ```typescript
-// Search by workflow name (partial match)
-const results = await client.workflows.search({
-  workflowName: 'copy'
-});
+// app/api/simplex-webhook/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { verifySimplexWebhook, WebhookPayload } from 'simplex-ts';
+
+export async function POST(request: NextRequest) {
+  const body = await request.text();
+  const headers: Record<string, string> = {};
+  request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  try {
+    verifySimplexWebhook(body, headers, process.env.SIMPLEX_WEBHOOK_SECRET!);
+    const payload: WebhookPayload = JSON.parse(body);
+
+    if (payload.success) {
+      // Process successful workflow
+      await processResult(payload);
+    } else {
+      // Handle failed workflow
+      await handleFailure(payload);
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+  }
+}
 
-console.log(`Found ${results.count} workflows`);
-results.workflows.forEach(workflow => {
-  console.log(`- ${workflow.workflow_name} (${workflow.workflow_id})`);
-  console.log(`  Metadata: ${workflow.metadata || 'None'}`);
-});
+async function processResult(payload: WebhookPayload) {
+  const { session_id, structured_output, metadata } = payload;
 
-// Search by metadata (partial match)
-const results = await client.workflows.search({
-  metadata: 'prod'
-});
+  // Your business logic here
+  console.log('Processing session:', session_id);
 
-// Search by both name and metadata
-const results = await client.workflows.search({
-  workflowName: 'copy',
-  metadata: 'staging'
-});
+  if (structured_output) {
+    // Handle extracted data
+    await saveToDatabase(structured_output);
+  }
+}
 
-// At least one parameter is required
-try {
-  await client.workflows.search({}); // This will throw an error
-} catch (error) {
-  console.error('Error: At least one search parameter required');
+async function handleFailure(payload: WebhookPayload) {
+  console.error('Workflow failed:', payload.session_id);
+  // Alert, retry, or log the failure
 }
 ```
 
-#### Update workflow metadata
-
-Update the metadata string for a specific workflow.
+### Express
 
 ```typescript
-// Update metadata for a workflow
-const result = await client.workflows.updateMetadata(
-  'workflow-id-here',
-  'production'
-);
+import express from 'express';
+import { verifySimplexWebhook, WebhookPayload } from 'simplex-ts';
 
-console.log('Updated workflow:', result.workflow_id);
-console.log('New metadata:', result.metadata);
+const app = express();
 
-// Use metadata for categorization
-await client.workflows.updateMetadata('workflow-1', 'production');
-await client.workflows.updateMetadata('workflow-2', 'staging');
-await client.workflows.updateMetadata('workflow-3', 'development');
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const body = req.body.toString('utf8');
+  const signature = req.headers['x-simplex-signature'] as string;
 
-// Then search by category
-const prodWorkflows = await client.workflows.search({
-  metadata: 'prod'  // Will match 'production'
-});
-```
+  try {
+    verifySimplexWebhook(body, req.headers, process.env.SIMPLEX_WEBHOOK_SECRET!);
+    const payload: WebhookPayload = JSON.parse(body);
 
-#### Create a workflow session
+    // Process asynchronously
+    processWebhook(payload).catch(console.error);
 
-```typescript
-const session = await client.workflows.createWorkflowSession(
-  'my-workflow-name',
-  'https://example.com',
-  {
-    sessionData: { key: 'value' },
-    proxies: false
+    res.json({ received: true });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid signature' });
   }
-);
+});
 
-console.log('Session ID:', session.session_id);
+app.listen(3000);
 ```
 
-#### Run an agent task
+## Polling session status
 
-Execute a specific task using the agentic endpoint:
+Use polling when you can't receive webhooks or need to check status synchronously:
 
 ```typescript
-const result = await client.workflows.agentic(
-  'Find and click the login button',
-  'session-id',
-  {
-    maxSteps: 10,
-    actionsToExclude: ['scroll', 'wait'],
-    variables: { username: 'user@example.com' }
-  }
-);
-
-console.log('Task succeeded:', result.succeeded);
-console.log('Result:', result.result);
+const status = await client.getSessionStatus('session_id');
+
+if (status.in_progress) {
+  console.log('Session still running...');
+} else if (status.success) {
+  console.log('Session completed successfully');
+  console.log('Files:', status.file_metadata);
+  console.log('Scraper outputs:', status.scraper_outputs);
+} else {
+  console.log('Session failed');
+}
 ```
 
-#### Run a named agent
+## Resuming paused flows
 
-Run a pre-configured agent by name:
+When a flow script calls `pause()`, you can resume it programmatically:
 
 ```typescript
-const result = await client.workflows.run_agent(
-  'my-agent-name',
-  'session-id',
-  {
-    key1: 'value1',
-    key2: 'value2'
-  }
-);
+const result = await client.resume('session_id');
 
-console.log('Agent succeeded:', result.succeeded);
-console.log('Session ID:', result.session_id);
-console.log('Result:', result.result);
+if (result.succeeded) {
+  console.log('Flow resumed successfully');
+} else {
+  console.log('Failed to resume:', result.error);
+}
 ```
 
-### Session Management
-
-#### Retrieve session replay video
+## Retrieving session data
 
-Download the MP4 video recording of a session:
+### Get session replay
 
 ```typescript
-const videoBuffer = await client.retrieveSessionReplay('session-id');
+import fs from 'fs';
 
-// Save to file
-import * as fs from 'fs';
-fs.writeFileSync('session-replay.mp4', videoBuffer);
-```
+const replay = await client.retrieveSessionReplay('session_id');
 
-#### Retrieve session logs
+// Returns a Buffer containing the MP4 video recording
+fs.writeFileSync('session-replay.mp4', Buffer.from(replay));
+```
 
-Get the JSON logs for a completed session:
+### Get session logs
 
 ```typescript
-const logs = await client.retrieveSessionLogs('session-id');
+const logs = await client.retrieveSessionLogs('session_id');
 
-console.log('Session logs:', logs);
+// Returns JSON session logs
+console.log('Session logs:', JSON.stringify(logs, null, 2));
+```
 
-// Save to file
-import * as fs from 'fs';
-fs.writeFileSync('session-logs.json', JSON.stringify(logs, null, 2));
+### Download session files
+
+```typescript
+// Download all files as a zip
+const allFiles = await client.downloadSessionFiles('session_id');
 ```
 
-#### Get session store
+## Batch processing
 
-Retrieve metadata about files downloaded during a session:
+### Running multiple workflows
 
 ```typescript
-const sessionStore = await client.getSessionStore('session-id');
+const patients = ['P-001', 'P-002', 'P-003', 'P-004', 'P-005'];
+
+// Run workflows in parallel with concurrency limit
+const results = await Promise.all(
+  patients.map(async (patientId) => {
+    try {
+      return await client.workflows.run('verification_workflow', {
+        variables: { patient_id: patientId },
+        webhookUrl: 'https://your-domain.com/webhook',
+        metadata: patientId
+      });
+    } catch (error) {
+      console.error(`Failed to start workflow for ${patientId}:`, error);
+      return null;
+    }
+  })
+);
 
-console.log('Session store:', sessionStore);
+const successful = results.filter(Boolean);
+console.log(`Started ${successful.length}/${patients.length} workflows`);
 ```
 
-#### Download session files
+### With rate limiting
 
-Download files that were saved during a session:
+```typescript
+async function runWithRateLimit<T>(
+  items: T[],
+  fn: (item: T) => Promise<unknown>,
+  concurrency: number = 5,
+  delayMs: number = 1000
+) {
+  const results = [];
+
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency);
+    const batchResults = await Promise.all(batch.map(fn));
+    results.push(...batchResults);
+
+    if (i + concurrency < items.length) {
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+  }
+
+  return results;
+}
+
+// Usage
+await runWithRateLimit(
+  patients,
+  (patientId) => client.workflows.run('workflow_id', {
+    variables: { patient_id: patientId }
+  }),
+  5,  // 5 concurrent
+  1000 // 1 second between batches
+);
+```
+
+## Searching workflows
 
 ```typescript
-// Download all files as a zip
-const zipBuffer = await client.downloadSessionFiles('session-id');
-fs.writeFileSync('session-files.zip', zipBuffer);
+// Search for workflows by name or metadata
+const results = await client.workflows.search({
+  workflowName: 'insurance'  // Partial matching supported
+});
 
-// Download a specific file
-const fileBuffer = await client.downloadSessionFiles('session-id', 'filename.pdf');
-fs.writeFileSync('filename.pdf', fileBuffer);
+for (const workflow of results.workflows) {
+  console.log(`${workflow.workflow_name}: ${workflow.workflow_id}`);
+}
 ```
 
-## Error Handling
+## Updating workflow metadata
 
-The SDK provides typed error classes for different error scenarios:
+```typescript
+await client.workflows.updateMetadata('workflow_id', 'verification-high');
+```
+
+## Error handling
 
 ```typescript
-import {
-  SimplexClient,
+import { SimplexClient,
   WorkflowError,
   ValidationError,
   AuthenticationError,
@@ -244,62 +291,84 @@ import {
   NetworkError
 } from 'simplex-ts';
 
-try {
-  const result = await client.workflows.run('workflow-id');
-} catch (error) {
-  if (error instanceof WorkflowError) {
-    console.error('Workflow failed:', error.message);
-  } else if (error instanceof ValidationError) {
-    console.error('Invalid request:', error.message);
-  } else if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', error.message);
-  } else if (error instanceof RateLimitError) {
-    console.error('Rate limited. Retry after:', error.retryAfter);
-  } else if (error instanceof NetworkError) {
-    console.error('Network error:', error.message);
+async function runWorkflowSafely(workflowId: string, variables: Record<string, string>) {
+  try {
+    return await client.workflows.run(workflowId, { variables });
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      console.error('Invalid API key');
+      throw error;
+    }
+
+    if (error instanceof RateLimitError) {
+      console.log('Rate limited, retrying after delay...');
+      await new Promise(resolve => setTimeout(resolve, 5000));
+      return client.workflows.run(workflowId, { variables });
+    }
+
+    if (error instanceof ValidationError) {
+      console.error('Invalid parameters:', error.message);
+      throw error;
+    }
+
+    if (error instanceof WorkflowError) {
+      console.error('Workflow execution failed:', error.message);
+      throw error;
+    }
+
+    if (error instanceof NetworkError) {
+      console.error('Network issue:', error.message);
+      throw error;
+    }
+
+    throw error;
   }
 }
 ```
 
-## Examples
-
-The SDK includes several example files to demonstrate different use cases:
-
-- **`examples/run-workflow.ts`** - Basic workflow execution
-- **`examples/create-workflow.ts`** - Creating workflow sessions with agentic tasks
-- **`examples/download-file.ts`** - Download files from workflow sessions
-- **`examples/session-replay-and-logs.ts`** - Retrieve session replays and logs
-- **`examples/search-and-metadata.ts`** - Search workflows and manage metadata
-- **`examples/webhook-express.ts`** - Webhook verification with Express
-- **`examples/webhook-nextjs.ts`** - Webhook verification with Next.js
-
-Run examples with:
-```bash
-npx tsx examples/run-workflow.ts
-npx tsx examples/session-replay-and-logs.ts
-npx tsx examples/download-file.ts
-```
-
-## Development
+## TypeScript types
 
-### Build the SDK
+The SDK exports types for all API responses:
 
-```bash
-npm run build
-```
-
-### Watch mode
+```typescript
+import type {
+  WebhookPayload,
+  RunWorkflowResponse,
+  FileMetadata
+} from 'simplex-ts';
 
-```bash
-npm run dev
+function handleWebhook(payload: WebhookPayload) {
+  const {
+    success,
+    session_id,
+    agent_response,
+    structured_output,
+    session_metadata,
+    file_metadata
+  } = payload;
+
+  // TypeScript knows all the types
+}
 ```
 
-### Clean build files
+## Environment configuration
 
-```bash
-npm run clean
+```typescript
+// config.ts
+export const simplexConfig = {
+  apiKey: process.env.SIMPLEX_API_KEY!,
+  webhookSecret: process.env.SIMPLEX_WEBHOOK_SECRET!,
+  webhookUrl: process.env.NODE_ENV === 'production'
+    ? 'https://your-domain.com/api/webhook'
+    : process.env.NGROK_URL + '/api/webhook'
+};
+
+// Validate config on startup
+if (!simplexConfig.apiKey) {
+  throw new Error('SIMPLEX_API_KEY is required');
+}
 ```
 
 ## License
 
-MIT
+MIT

package/dist/SimplexClient.d.ts

@@ -1,18 +1,9 @@
 import { Workflow } from './resources/Workflow';
-import { WorkflowSession } from './resources/WorkflowSession';
-import { SimplexClientOptions, GetSessionStoreResponse, Add2FAConfigResponse, SessionStatusResponse } from './types';
+import { SimplexClientOptions, SessionStatusResponse, ResumeSessionResponse } from './types';
 export declare class SimplexClient {
     private httpClient;
     workflows: Workflow;
     constructor(options: SimplexClientOptions);
-    createWorkflowSession(options: {
-        name: string;
-        url: string;
-        proxies?: boolean;
-        sessionData?: any;
-        metadata?: string;
-    }): Promise<WorkflowSession>;
-    getSessionStore(sessionId: string): Promise<GetSessionStoreResponse>;
     /**
      * Poll session status to check progress and get results.
      * Use this to monitor long-running sessions without webhooks.
@@ -21,16 +12,40 @@ export declare class SimplexClient {
      * @returns Session status including in_progress flag and available data
      */
     getSessionStatus(sessionId: string): Promise<SessionStatusResponse>;
+    /**
+     * Download all files from a session as a zip archive.
+     *
+     * @param sessionId - The session ID to download files from
+     * @returns Buffer containing the zip file
+     */
     downloadSessionFiles(sessionId: string): Promise<Buffer>;
-    add2FAConfig(config: {
-        seed: string;
-        name?: string;
-        partialUrl?: string;
-    }): Promise<Add2FAConfigResponse>;
-    updateApiKey(apiKey: string): void;
-    setCustomHeader(key: string, value: string): void;
-    removeCustomHeader(key: string): void;
+    /**
+     * Retrieve the session replay video (MP4).
+     *
+     * @param sessionId - The session ID to get replay for
+     * @returns Buffer containing the MP4 video
+     */
     retrieveSessionReplay(sessionId: string): Promise<Buffer>;
+    /**
+     * Retrieve the session logs as JSON.
+     *
+     * @param sessionId - The session ID to get logs for
+     * @returns Parsed JSON logs
+     */
     retrieveSessionLogs(sessionId: string): Promise<any>;
+    /**
+     * Resume a paused flow in a session.
+     * Call this when a flow script has called pause() and is waiting to be resumed.
+     *
+     * @param sessionId - The session ID to resume
+     * @returns Resume response with succeeded flag and optional pause key
+     */
+    resume(sessionId: string): Promise<ResumeSessionResponse>;
+    /**
+     * Update the API key used for requests.
+     *
+     * @param apiKey - The new API key
+     */
+    updateApiKey(apiKey: string): void;
 }
 //# sourceMappingURL=SimplexClient.d.ts.map

package/dist/SimplexClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimplexClient.d.ts","sourceRoot":"","sources":["../src/SimplexClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAA+D,uBAAuB,EAA0D,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAI1O,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAa;IACxB,SAAS,EAAE,QAAQ,CAAC;gBAGf,OAAO,EAAE,oBAAoB;IAYnC,qBAAqB,CAAC,OAAO,EAAE;QACnC,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,GAAG,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,eAAe,CAAC;IAmCtB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAe1E;;;;;;OAMG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAenE,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuCxD,YAAY,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgCjC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIlC,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjD,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI/B,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBzD,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;CAkB3D"}
+{"version":3,"file":"SimplexClient.d.ts","sourceRoot":"","sources":["../src/SimplexClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EAEtB,MAAM,SAAS,CAAC;AAGjB,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAa;IACxB,SAAS,EAAE,QAAQ,CAAC;gBAEf,OAAO,EAAE,oBAAoB;IAYzC;;;;;;OAMG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAezE;;;;;OAKG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC9D;;;;;OAKG;IACG,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB/D;;;;;OAKG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAkB1D;;;;;;OAMG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4B/D;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAGnC"}