@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-09-signature-reference.md

@@ -1,766 +1,766 @@
-# Module 9: Complete TypeScript Signature Reference
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 9 of 8** | **Level**: Reference | **Time**: Quick Reference
-
----
-
-## Purpose
-
-This module provides the complete, authoritative TypeScript signatures for all @versori/run v0.4.4 functions, types, and interfaces. Use this as a quick reference when building Versori connectors.
-
-**Based on**: @versori/run v0.4.4
-**Last Updated**: 2025-10-30
-
----
-
-## Trigger Functions
-
-### webhook()
-
-**Purpose**: Create HTTP webhook endpoint
-
-**Signature**:
-```typescript
-function webhook(
-  id: string,
-  options?: WebhookOptions
-): Trigger<WebhookData>
-```
-
-**Parameters**:
-- `id: string` - Unique workflow identifier (used in URL path)
-- `options?: WebhookOptions` - Optional configuration
-
-**Returns**: `Trigger<WebhookData>` - Must be chained with `.then()`
-
-**WebhookOptions**:
-```typescript
-type WebhookOptions = {
-  cors?: WebhookCorsOptions;
-  response?: WebhookResponseOptions;
-  connection?: string;          // Optional - for webhook authentication
-  method?: 'all' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
-  request?: WebhookRequestOptions;
-}
-```
-
-**WebhookResponseOptions**:
-```typescript
-type WebhookResponseOptions = {
-  mode?: 'sync' | 'async';
-  onSuccess?: <T>(ctx: Context<T>) => Response;
-  onError?: <T>(ctx: Context<T>) => Response;
-}
-```
-
-**Usage**:
-```typescript
-// Basic webhook
-export const basic = webhook('my-webhook')
-  .then(fn('handler', async (ctx) => { /* ... */ }));
-
-// With XML response
-export const xmlWebhook = webhook('xml-webhook', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('generate-xml', () => '<?xml version="1.0"?><response>...</response>'));
-```
-
----
-
-### schedule()
-
-**Purpose**: Create time-based recurring workflow
-
-**⚠️ CRITICAL**: schedule() does NOT accept handler or options as parameters!
-
-**Signature**:
-```typescript
-function schedule(
-  id: string,
-  schedule: string,
-  activationPredicate?: ActivationPredicate
-): Workflow<ScheduleData>
-```
-
-**Parameters**:
-- `id: string` - Workflow identifier
-- `schedule: string` - Cron expression (e.g., `'0 0 * * *'`)
-- `activationPredicate?: ActivationPredicate` - Optional filter for activations
-
-**Returns**: `Workflow<ScheduleData>` where `ScheduleData = Record<string, never>` (empty object)
-
-**ActivationPredicate**:
-```typescript
-type ActivationPredicate =
-  | 'all'                                    // Run for all activations
-  | ((a?: Activation) => boolean)            // Custom filter function
-```
-
-**Common Cron Patterns**:
-```typescript
-'* * * * *'      // Every minute
-'0 * * * *'      // Every hour
-'0 */6 * * *'    // Every 6 hours
-'0 0 * * *'      // Daily at midnight
-'0 2 * * *'      // Daily at 2 AM
-'0 9 * * 1-5'    // Weekdays at 9 AM
-'0 0 1 * *'      // First of month at midnight
-```
-
-**Usage**:
-```typescript
-// ❌ WRONG - schedule does NOT accept handler as 4th parameter
-export const wrong = schedule('daily', '0 0 * * *', { connection: 'fluent' }, handler);
-
-// ✅ CORRECT - schedule + fn (KV only)
-export const dailyTask = schedule('daily', '0 0 * * *')
-  .then(fn('task', async (ctx) => {
-    // Only KV and logging
-  }));
-
-// ✅ CORRECT - schedule + http (with API access)
-export const dailySync = schedule('daily-sync', '0 0 * * *')
-  .then(http('sync', { connection: 'fluent_commerce' }, async (ctx) => {
-    const client = await createClient(ctx);
-    // ... sync logic
-  }));
-
-// ✅ CORRECT - with activation predicate
-export const prodOnly = schedule('prod-only', '0 * * * *', (a) => a?.id?.startsWith('prod'))
-  .then(fn('task', async (ctx) => { /* ... */ }));
-```
-
----
-
-## Task Functions
-
-### fn()
-
-**Purpose**: Internal processing task (no external API access)
-
-**Signature**:
-```typescript
-function fn<I, O, Index = void>(
-  id: string,
-  fn: ContextFunc<I, O, Index>
-): Task<I, O>
-```
-
-**Parameters**:
-- `id: string` - Task identifier (for tracing/logging)
-- `fn: ContextFunc<I, O, Index>` - Handler function (sync or async)
-
-**Returns**: `Task<I, O>` - Can be chained with `.then()`, `.catch()`
-
-**ContextFunc**:
-```typescript
-type ContextFunc<Input, Output, Index> =
-  | ((ctx: Context<Input>, idx: Index) => Promise<Output>)
-  | ((ctx: Context<Input>, idx: Index) => Output)
-```
-
-**Context Available**:
-- ✅ `ctx.data` - Input data
-- ✅ `ctx.log` - Logger
-- ✅ `ctx.activation` - Activation variables
-- ✅ `ctx.openKv()` - KV storage access
-- ✅ `ctx.request()` - HTTP request object (when in webhook chain)
-- ❌ `ctx.fetch` - NOT available (no external API)
-- ❌ `ctx.connectionVariables` - NOT available
-
-**Usage**:
-```typescript
-// Simple transformation
-const transform = fn('transform', (ctx) => {
-  return { transformed: ctx.data.value * 2 };
-});
-
-// Async with KV storage
-const trackFile = fn('track', async (ctx) => {
-  const kv = ctx.openKv(':project:');
-  await kv.set('file', ctx.data.fileName);
-  return { tracked: true };
-});
-
-// With index (for array processing)
-const processItem = fn('process', (ctx, idx: number) => {
-  ctx.log.info(`Processing item ${idx}`);
-  return { index: idx, data: ctx.data };
-});
-```
-
----
-
-### http()
-
-**Purpose**: External API call task (with authentication)
-
-**Signature**:
-```typescript
-function http<In = any, Out = any, PageParams = unknown>(
-  taskId: string,
-  opts: HttpOptions<PageParams>,
-  fn: HttpContextFunc<In, Out, PageParams>
-): Task<In, Out>
-```
-
-**Parameters**:
-- `taskId: string` - Task identifier
-- `opts: HttpOptions<PageParams>` - Configuration with connection
-- `fn: HttpContextFunc<In, Out, PageParams>` - Handler function
-
-**Returns**: `Task<In, Out>` - Can be chained
-
-**HttpOptions**:
-```typescript
-type HttpOptions<PageParams> = {
-  connection: string;              // REQUIRED - connection name
-  pagination?: PaginateOptions<PageParams>;
-}
-```
-
-**HttpContextFunc**:
-```typescript
-type HttpContextFunc<In, Out, PageParams> = (
-  ctx: HttpContext<In, PageParams>
-) => Promise<Out>
-```
-
-**HttpContext Interface** (extends Context):
-```typescript
-interface HttpContext<Data, PageParams = undefined> extends Context<Data> {
-  // All Context properties plus:
-  fetch: typeof fetch;                          // ✅ Authenticated fetch
-  connectionVariables: Record<string, any>;     // ✅ Connection config vars
-  pageParams?: PageParams;                      // ✅ Current pagination params
-  nextPage: (nextParams: PageParams) => Promise<void>;
-  baseUrl: Promise<string>;                     // ✅ Connection base URL
-}
-```
-
-**Usage**:
-```typescript
-// Call Fluent API
-const callAPI = http(
-  'call-fluent',
-  { connection: 'fluent_commerce' },
-  async (ctx) => {
-    // ctx.fetch is authenticated
-    const client = await createClient(ctx);
-    const result = await client.graphql({ query: '...' });
-    return { data: result.data };
-  }
-);
-
-// Access connection variables
-http('use-vars', { connection: 'fluent' }, async (ctx) => {
-  const retailerId = ctx.connectionVariables.retailerId;
-  const baseUrl = await ctx.baseUrl;
-  ctx.log.info('Connection info', { retailerId, baseUrl });
-});
-```
-
----
-
-## Array Processing Methods
-
-### `.unpack()` and `.parallel()`
-
-**Purpose**: Process arrays in parallel
-
-**Signatures**:
-```typescript
-// On Task<In, Out[]>
-unpack<NextOut = Out extends Array<infer Elem> ? Elem : Out>(): ArrayTask<In, NextOut>
-
-// On ArrayTask<In, OutElem>
-parallel<NextOut>(task: Taskable<OutElem, NextOut, number>): Task<In, NextOut[]>
-```
-
-**⚠️ CRITICAL LIMITATION**: `.parallel()` has all-or-nothing error behavior. If ANY task fails, the ENTIRE workflow fails with NO partial results. For batch processing with expected failures, use `Promise.allSettled` instead. See [Module 4: Error Behavior Warning](./platforms-versori-04-workflows.md#-critical-parallel-error-behavior).
-
-**Usage**:
-```typescript
-// ❌ RISKY - One failure loses ALL results
-schedule('process', '0 2 * * *')
-  .then(fn('fetch', () => ['item1', 'item2', 'item3']))
-  .unpack()
-  .parallel(fn('process', async (ctx) => {
-    return await processItem(ctx.data);  // If ANY fails, all results lost
-  }));
-
-// ✅ SAFER - Return error objects instead of throwing
-schedule('process', '0 2 * * *')
-  .then(fn('fetch', () => ['item1', 'item2', 'item3']))
-  .unpack()
-  .parallel(fn('process', async (ctx) => {
-    try {
-      const result = await processItem(ctx.data);
-      return { success: true, item: ctx.data, result };
-    } catch (error) {
-      return { success: false, item: ctx.data, error: error.message };
-    }
-  }))
-  .then(fn('handle-results', (ctx) => {
-    const successes = ctx.data.filter(r => r.success);
-    const failures = ctx.data.filter(r => !r.success);
-    return { successes, failures };
-  }));
-
-// ✅ RECOMMENDED - Use Promise.allSettled for fault tolerance
-schedule('process', '0 2 * * *')
-  .then(fn('process-all', async (ctx) => {
-    const items = ['item1', 'item2', 'item3'];
-
-    const results = await Promise.allSettled(
-      items.map(item => processItem(item))
-    );
-
-    const successes = results.filter(r => r.status === 'fulfilled');
-    const failures = results.filter(r => r.status === 'rejected');
-
-    return { successes, failures };
-  }));
-```
-
-**When to use `.parallel()`:**
-- ✅ Small number of items (3-10)
-- ✅ All tasks MUST succeed (transactional)
-- ✅ Fast, reliable operations
-- ❌ NOT for batch processing with expected failures
-
-**See also**: [workflow-task-types.md](../platforms-versori-workflow-task-types.md#recommended-parallel-processing-patterns)
-
----
-
-## Context Types
-
-### Base Context Interface
-
-**Used by**: `fn()`, webhook handlers
-
-```typescript
-interface Context<D> {
-  // Read-only properties
-  readonly log: Logger;
-  readonly executionId: string;
-  readonly startTime: Date;
-  readonly data: D;
-
-  // Mutable property
-  activation: ActivationImpl;
-
-  // Methods
-  openKv(scope?: KeyValueScope): KeyValue;
-  start(workflowId: string, workflowOpts: WorkflowOpts): Promise<AsyncWorkflow>;
-  // Note: For connection access, use activation.connections (recommended)
-  // See: ../s3-sftp-configuration-guide.md for complete credential patterns
-  destroy(scope: KeyValueScope): Promise<void>;
-  createIssue(issue: CreateIssue, options?: { deduplicate?: boolean }): Promise<Issue | null>;
-  request(): express.Request | undefined;
-}
-```
-
-**Key Methods**:
-
-#### `openKv(scope?: KeyValueScope)`
-Opens KV storage at specified scope.
-
-**Scopes**:
-- `':execution:'` - Per execution (ephemeral)
-- `':project:'` - Project-wide (persistent)
-- `':organization:'` - Organization-wide (shared)
-
-**Example**:
-```typescript
-const kv = ctx.openKv(':project:');
-await kv.set('key', 'value');
-const value = await kv.get('key');
-```
-
-#### `request(): express.Request | undefined`
-Access raw HTTP request (when in webhook/HTTP workflow).
-
-**Example**:
-```typescript
-const req = ctx.request();
-const apiKey = req?.headers['x-api-key'] as string;
-const contentType = req?.headers['content-type'];
-```
-
----
-
-### HttpContext Interface
-
-**Used by**: `http()` tasks
-
-```typescript
-interface HttpContext<Data, PageParams = undefined> extends Context<Data> {
-  // Additional HTTP-specific properties
-  fetch: typeof fetch;
-  connectionVariables: Record<string, any>;
-  pageParams?: PageParams;
-  nextPage: (nextParams: PageParams) => Promise<void>;
-  baseUrl: Promise<string>;
-}
-```
-
-**Properties**:
-
-#### `fetch: typeof fetch`
-Authenticated fetch function with connection credentials.
-
-**Example**:
-```typescript
-http('call-api', { connection: 'my-api' }, async (ctx) => {
-  // fetch is pre-authenticated with connection
-  const response = await ctx.fetch('/users');
-  return response.json();
-});
-```
-
-#### `connectionVariables: Record<string, any>`
-Connection configuration variables.
-
-**Example**:
-```typescript
-http('use-vars', { connection: 'fluent' }, async (ctx) => {
-  const retailerId = ctx.connectionVariables.retailerId;
-  const apiVersion = ctx.connectionVariables.version;
-  ctx.log.info('Connection vars', { retailerId, apiVersion });
-});
-```
-
-#### `baseUrl: Promise<string>`
-Connection's base URL (resolved asynchronously).
-
-**Example**:
-```typescript
-http('show-url', { connection: 'fluent' }, async (ctx) => {
-  const url = await ctx.baseUrl;
-  ctx.log.info('Base URL', { url });
-  // url = 'https://api.fluentcommerce.com'
-});
-```
-
----
-
-### ActivationImpl
-
-**Access via**: `ctx.activation`
-
-```typescript
-class ActivationImpl implements Activation {
-  // Properties
-  get id(): string;
-  get user(): EndUser;
-  get environment(): ProjectEnvironment | undefined;          // ✅ NEW in v0.4.x
-  get connections(): Array<Connection> | undefined;           // ✅ NEW in v0.4.x
-  get dynamicVariables(): DynamicVariables | undefined;       // ✅ NEW in v0.4.x
-
-  // Methods
-  getVariable<T = unknown>(name: string): T | undefined;
-  setVariable(name: string, value: unknown): Promise<void>;
-}
-```
-
-**EndUser**:
-```typescript
-type EndUser = {
-  id: string;
-  createdAt: string;
-  updatedAt: string;
-  displayName: string;
-  externalId: string;
-  organisationId: string;
-}
-```
-
-**Connection** (v0.4.x+):
-```typescript
-type Connection = {
-  id: string;
-  name: string;
-  templateId: string;
-  dynamic: boolean;
-  baseUrl: string;
-  createdAt: string;
-  updatedAt: string;
-  credentials: ConnectionCredential[];
-}
-```
-
-**Usage Examples**:
-```typescript
-// Access user info
-fn('log-user', (ctx) => {
-  const user = ctx.activation.user;
-  ctx.log.info('User', {
-    displayName: user.displayName,
-    externalId: user.externalId
-  });
-});
-
-// Access all connections (NEW in v0.4.x)
-fn('list-connections', (ctx) => {
-  const connections = ctx.activation.connections;
-  ctx.log.info('Available connections', {
-    count: connections?.length,
-    names: connections?.map(c => c.name)
-  });
-});
-
-// Get/set variables
-fn('use-variables', async (ctx) => {
-  // Get variable
-  const apiKey = ctx.activation.getVariable<string>('API_KEY');
-
-  // Set variable
-  await ctx.activation.setVariable('LAST_RUN', Date.now());
-});
-
-// Access environment (NEW in v0.4.x)
-fn('check-env', (ctx) => {
-  const env = ctx.activation.environment;
-  ctx.log.info('Environment', {
-    id: env?.id,
-    name: env?.name
-  });
-});
-```
-
----
-
-## Helper Types
-
-### KeyValueScope
-
-```typescript
-type KeyValueScope = ':execution:' | ':project:' | ':organization:'
-```
-
-**Usage**:
-- `':execution:'` - Ephemeral, cleared after execution
-- `':project:'` - Persistent, shared across executions in project
-- `':organization:'` - Persistent, shared across projects in organization
-
----
-
-### WebhookData & ScheduleData
-
-```typescript
-type WebhookData = Record<string, never>  // Empty object
-type ScheduleData = Record<string, never>  // Empty object
-```
-
-**Note**: These are empty because actual data comes from:
-- **Webhook**: `ctx.data` contains parsed request body
-- **Schedule**: `ctx.data` is empty, use activation variables instead
-
----
-
-## Complete Workflow Patterns
-
-### Pattern 1: webhook() + fn() + http()
-
-```typescript
-export const processOrder = webhook('process-order')
-  // Step 1: Parse and validate (fn - no API)
-  .then(fn('validate', (ctx) => {
-    if (!ctx.data?.orderId) {
-      throw new Error('Missing orderId');
-    }
-    return { orderId: ctx.data.orderId, items: ctx.data.items };
-  }))
-
-  // Step 2: Send to Fluent (http - API access)
-  .then(http('send-to-fluent', { connection: 'fluent_commerce' }, async (ctx) => {
-    const client = await createClient(ctx);
-    // ... create order
-    return { success: true, fluentOrderId: '...' };
-  }))
-
-  .catch(({ data }) => ({
-    success: false,
-    error: data instanceof Error ? data.message : 'Unknown error'
-  }));
-```
-
-### Pattern 2: schedule() + fn() (KV only)
-
-```typescript
-export const dailyCleanup = schedule('daily-cleanup', '0 3 * * *')
-  .then(fn('cleanup', async (ctx) => {
-    const kv = ctx.openKv(':project:');
-    // ... cleanup logic
-    return { cleaned: true };
-  }));
-```
-
-### Pattern 3: schedule() + http() (API access)
-
-```typescript
-export const hourlySync = schedule('hourly-sync', '0 * * * *')
-  .then(http('sync', { connection: 'fluent_commerce' }, async (ctx) => {
-    const client = await createClient(ctx);
-    // ... sync logic
-    return { synced: true };
-  }));
-```
-
-### Pattern 4: Multi-step with state
-
-```typescript
-export const statefulWorkflow = schedule('stateful', '0 * * * *')
-  // Check state
-  .then(fn('check-state', async (ctx) => {
-    const kv = ctx.openKv(':project:');
-    const lastRun = await kv.get('last-run');
-    if (Date.now() - lastRun < 3600000) {
-      throw new Error('SKIP');
-    }
-    return { shouldProcess: true };
-  }))
-
-  // Process
-  .then(http('process', { connection: 'fluent' }, async (ctx) => {
-    const client = await createClient(ctx);
-    // ... process
-    return { processed: true };
-  }))
-
-  // Update state
-  .then(fn('update-state', async (ctx) => {
-    const kv = ctx.openKv(':project:');
-    await kv.set('last-run', Date.now());
-    return { stateUpdated: true };
-  }))
-
-  .catch(({ data }) => {
-    if (data.message === 'SKIP') {
-      return { skipped: true };
-    }
-    return { error: data.message };
-  });
-```
-
----
-
-## Decision Tree
-
-### When to use each workflow type?
-
-```
-Need to receive HTTP requests?
-  ├─ Yes → webhook()
-  └─ No → Continue
-
-Run on schedule?
-  ├─ Yes → schedule()
-  └─ No → http() (for on-demand API calls)
-
-Need external API access (Fluent, S3 presigned URLs)?
-  ├─ Yes → Use http() task
-  └─ No → Use fn() task
-
-Need to access HTTP headers?
-  → Use ctx.request() in any task type
-  → Available in fn(), webhook handlers, and http()
-
-Need multiple connections?
-  → Access via ctx.activation.connections (v0.4.x+)
-
-Need environment-specific logic?
-  → Use ctx.activation.environment (v0.4.x+)
-```
-
----
-
-## Common Mistakes to Avoid
-
-### ❌ WRONG: schedule() with 4th parameter
-
-```typescript
-// This does NOT work in @versori/run v0.4.4
-export const wrong = schedule('daily', '0 0 * * *', { connection: 'fluent' }, async (ctx) => {
-  // ...
-});
-```
-
-### ✅ CORRECT: schedule() + .then()
-
-```typescript
-export const correct = schedule('daily', '0 0 * * *')
-  .then(http('task', { connection: 'fluent' }, async (ctx) => {
-    // ...
-  }));
-```
-
----
-
-### ❌ WRONG: Accessing ctx.headers
-
-```typescript
-// ctx.headers doesn't exist!
-const apiKey = ctx.headers?.get?.('x-api-key');
-```
-
-### ✅ CORRECT: Using ctx.request()
-
-```typescript
-const req = ctx.request();
-const apiKey = req?.headers['x-api-key'];
-```
-
----
-
-### ❌ WRONG: Using fn() for external API
-
-```typescript
-// fn() doesn't have ctx.fetch - this will fail!
-fn('call-api', async (ctx) => {
-  const client = await createClient(ctx);  // ❌ Error!
-});
-```
-
-### ✅ CORRECT: Using http() for external API
-
-```typescript
-http('call-api', { connection: 'fluent_commerce' }, async (ctx) => {
-  const client = await createClient(ctx);  // ✅ Works!
-});
-```
-
----
-
-## Version Compatibility
-
-This reference is based on **@versori/run v0.4.4**.
-
-**Major changes from v0.3.x**:
-- ✅ Added `activation.connections` array
-- ✅ Added `activation.environment` property
-- ✅ Added `activation.dynamicVariables` property
-- ⚠️ `schedule()` signature unchanged (never had 4th parameter)
-
-**Migration**: If you're using old patterns from unofficial docs, update to correct patterns shown above.
-
----
-
-## Related Documentation
-
-- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Practical workflow examples
-- [Module 5: Connections](./platforms-versori-05-connections.md) - Connection management
-
----
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+# Module 9: Complete TypeScript Signature Reference
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 9 of 8** | **Level**: Reference | **Time**: Quick Reference
+
+---
+
+## Purpose
+
+This module provides the complete, authoritative TypeScript signatures for all @versori/run v0.4.4 functions, types, and interfaces. Use this as a quick reference when building Versori connectors.
+
+**Based on**: @versori/run v0.4.4
+**Last Updated**: 2025-10-30
+
+---
+
+## Trigger Functions
+
+### webhook()
+
+**Purpose**: Create HTTP webhook endpoint
+
+**Signature**:
+```typescript
+function webhook(
+  id: string,
+  options?: WebhookOptions
+): Trigger<WebhookData>
+```
+
+**Parameters**:
+- `id: string` - Unique workflow identifier (used in URL path)
+- `options?: WebhookOptions` - Optional configuration
+
+**Returns**: `Trigger<WebhookData>` - Must be chained with `.then()`
+
+**WebhookOptions**:
+```typescript
+type WebhookOptions = {
+  cors?: WebhookCorsOptions;
+  response?: WebhookResponseOptions;
+  connection?: string;          // Optional - for webhook authentication
+  method?: 'all' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+  request?: WebhookRequestOptions;
+}
+```
+
+**WebhookResponseOptions**:
+```typescript
+type WebhookResponseOptions = {
+  mode?: 'sync' | 'async';
+  onSuccess?: <T>(ctx: Context<T>) => Response;
+  onError?: <T>(ctx: Context<T>) => Response;
+}
+```
+
+**Usage**:
+```typescript
+// Basic webhook
+export const basic = webhook('my-webhook')
+  .then(fn('handler', async (ctx) => { /* ... */ }));
+
+// With XML response
+export const xmlWebhook = webhook('xml-webhook', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('generate-xml', () => '<?xml version="1.0"?><response>...</response>'));
+```
+
+---
+
+### schedule()
+
+**Purpose**: Create time-based recurring workflow
+
+**⚠️ CRITICAL**: schedule() does NOT accept handler or options as parameters!
+
+**Signature**:
+```typescript
+function schedule(
+  id: string,
+  schedule: string,
+  activationPredicate?: ActivationPredicate
+): Workflow<ScheduleData>
+```
+
+**Parameters**:
+- `id: string` - Workflow identifier
+- `schedule: string` - Cron expression (e.g., `'0 0 * * *'`)
+- `activationPredicate?: ActivationPredicate` - Optional filter for activations
+
+**Returns**: `Workflow<ScheduleData>` where `ScheduleData = Record<string, never>` (empty object)
+
+**ActivationPredicate**:
+```typescript
+type ActivationPredicate =
+  | 'all'                                    // Run for all activations
+  | ((a?: Activation) => boolean)            // Custom filter function
+```
+
+**Common Cron Patterns**:
+```typescript
+'* * * * *'      // Every minute
+'0 * * * *'      // Every hour
+'0 */6 * * *'    // Every 6 hours
+'0 0 * * *'      // Daily at midnight
+'0 2 * * *'      // Daily at 2 AM
+'0 9 * * 1-5'    // Weekdays at 9 AM
+'0 0 1 * *'      // First of month at midnight
+```
+
+**Usage**:
+```typescript
+// ❌ WRONG - schedule does NOT accept handler as 4th parameter
+export const wrong = schedule('daily', '0 0 * * *', { connection: 'fluent' }, handler);
+
+// ✅ CORRECT - schedule + fn (KV only)
+export const dailyTask = schedule('daily', '0 0 * * *')
+  .then(fn('task', async (ctx) => {
+    // Only KV and logging
+  }));
+
+// ✅ CORRECT - schedule + http (with API access)
+export const dailySync = schedule('daily-sync', '0 0 * * *')
+  .then(http('sync', { connection: 'fluent_commerce' }, async (ctx) => {
+    const client = await createClient(ctx);
+    // ... sync logic
+  }));
+
+// ✅ CORRECT - with activation predicate
+export const prodOnly = schedule('prod-only', '0 * * * *', (a) => a?.id?.startsWith('prod'))
+  .then(fn('task', async (ctx) => { /* ... */ }));
+```
+
+---
+
+## Task Functions
+
+### fn()
+
+**Purpose**: Internal processing task (no external API access)
+
+**Signature**:
+```typescript
+function fn<I, O, Index = void>(
+  id: string,
+  fn: ContextFunc<I, O, Index>
+): Task<I, O>
+```
+
+**Parameters**:
+- `id: string` - Task identifier (for tracing/logging)
+- `fn: ContextFunc<I, O, Index>` - Handler function (sync or async)
+
+**Returns**: `Task<I, O>` - Can be chained with `.then()`, `.catch()`
+
+**ContextFunc**:
+```typescript
+type ContextFunc<Input, Output, Index> =
+  | ((ctx: Context<Input>, idx: Index) => Promise<Output>)
+  | ((ctx: Context<Input>, idx: Index) => Output)
+```
+
+**Context Available**:
+- ✅ `ctx.data` - Input data
+- ✅ `ctx.log` - Logger
+- ✅ `ctx.activation` - Activation variables
+- ✅ `ctx.openKv()` - KV storage access
+- ✅ `ctx.request()` - HTTP request object (when in webhook chain)
+- ❌ `ctx.fetch` - NOT available (no external API)
+- ❌ `ctx.connectionVariables` - NOT available
+
+**Usage**:
+```typescript
+// Simple transformation
+const transform = fn('transform', (ctx) => {
+  return { transformed: ctx.data.value * 2 };
+});
+
+// Async with KV storage
+const trackFile = fn('track', async (ctx) => {
+  const kv = ctx.openKv(':project:');
+  await kv.set('file', ctx.data.fileName);
+  return { tracked: true };
+});
+
+// With index (for array processing)
+const processItem = fn('process', (ctx, idx: number) => {
+  ctx.log.info(`Processing item ${idx}`);
+  return { index: idx, data: ctx.data };
+});
+```
+
+---
+
+### http()
+
+**Purpose**: External API call task (with authentication)
+
+**Signature**:
+```typescript
+function http<In = any, Out = any, PageParams = unknown>(
+  taskId: string,
+  opts: HttpOptions<PageParams>,
+  fn: HttpContextFunc<In, Out, PageParams>
+): Task<In, Out>
+```
+
+**Parameters**:
+- `taskId: string` - Task identifier
+- `opts: HttpOptions<PageParams>` - Configuration with connection
+- `fn: HttpContextFunc<In, Out, PageParams>` - Handler function
+
+**Returns**: `Task<In, Out>` - Can be chained
+
+**HttpOptions**:
+```typescript
+type HttpOptions<PageParams> = {
+  connection: string;              // REQUIRED - connection name
+  pagination?: PaginateOptions<PageParams>;
+}
+```
+
+**HttpContextFunc**:
+```typescript
+type HttpContextFunc<In, Out, PageParams> = (
+  ctx: HttpContext<In, PageParams>
+) => Promise<Out>
+```
+
+**HttpContext Interface** (extends Context):
+```typescript
+interface HttpContext<Data, PageParams = undefined> extends Context<Data> {
+  // All Context properties plus:
+  fetch: typeof fetch;                          // ✅ Authenticated fetch
+  connectionVariables: Record<string, any>;     // ✅ Connection config vars
+  pageParams?: PageParams;                      // ✅ Current pagination params
+  nextPage: (nextParams: PageParams) => Promise<void>;
+  baseUrl: Promise<string>;                     // ✅ Connection base URL
+}
+```
+
+**Usage**:
+```typescript
+// Call Fluent API
+const callAPI = http(
+  'call-fluent',
+  { connection: 'fluent_commerce' },
+  async (ctx) => {
+    // ctx.fetch is authenticated
+    const client = await createClient(ctx);
+    const result = await client.graphql({ query: '...' });
+    return { data: result.data };
+  }
+);
+
+// Access connection variables
+http('use-vars', { connection: 'fluent' }, async (ctx) => {
+  const retailerId = ctx.connectionVariables.retailerId;
+  const baseUrl = await ctx.baseUrl;
+  ctx.log.info('Connection info', { retailerId, baseUrl });
+});
+```
+
+---
+
+## Array Processing Methods
+
+### `.unpack()` and `.parallel()`
+
+**Purpose**: Process arrays in parallel
+
+**Signatures**:
+```typescript
+// On Task<In, Out[]>
+unpack<NextOut = Out extends Array<infer Elem> ? Elem : Out>(): ArrayTask<In, NextOut>
+
+// On ArrayTask<In, OutElem>
+parallel<NextOut>(task: Taskable<OutElem, NextOut, number>): Task<In, NextOut[]>
+```
+
+**⚠️ CRITICAL LIMITATION**: `.parallel()` has all-or-nothing error behavior. If ANY task fails, the ENTIRE workflow fails with NO partial results. For batch processing with expected failures, use `Promise.allSettled` instead. See [Module 4: Error Behavior Warning](./platforms-versori-04-workflows.md#-critical-parallel-error-behavior).
+
+**Usage**:
+```typescript
+// ❌ RISKY - One failure loses ALL results
+schedule('process', '0 2 * * *')
+  .then(fn('fetch', () => ['item1', 'item2', 'item3']))
+  .unpack()
+  .parallel(fn('process', async (ctx) => {
+    return await processItem(ctx.data);  // If ANY fails, all results lost
+  }));
+
+// ✅ SAFER - Return error objects instead of throwing
+schedule('process', '0 2 * * *')
+  .then(fn('fetch', () => ['item1', 'item2', 'item3']))
+  .unpack()
+  .parallel(fn('process', async (ctx) => {
+    try {
+      const result = await processItem(ctx.data);
+      return { success: true, item: ctx.data, result };
+    } catch (error) {
+      return { success: false, item: ctx.data, error: error.message };
+    }
+  }))
+  .then(fn('handle-results', (ctx) => {
+    const successes = ctx.data.filter(r => r.success);
+    const failures = ctx.data.filter(r => !r.success);
+    return { successes, failures };
+  }));
+
+// ✅ RECOMMENDED - Use Promise.allSettled for fault tolerance
+schedule('process', '0 2 * * *')
+  .then(fn('process-all', async (ctx) => {
+    const items = ['item1', 'item2', 'item3'];
+
+    const results = await Promise.allSettled(
+      items.map(item => processItem(item))
+    );
+
+    const successes = results.filter(r => r.status === 'fulfilled');
+    const failures = results.filter(r => r.status === 'rejected');
+
+    return { successes, failures };
+  }));
+```
+
+**When to use `.parallel()`:**
+- ✅ Small number of items (3-10)
+- ✅ All tasks MUST succeed (transactional)
+- ✅ Fast, reliable operations
+- ❌ NOT for batch processing with expected failures
+
+**See also**: [workflow-task-types.md](../platforms-versori-workflow-task-types.md#recommended-parallel-processing-patterns)
+
+---
+
+## Context Types
+
+### Base Context Interface
+
+**Used by**: `fn()`, webhook handlers
+
+```typescript
+interface Context<D> {
+  // Read-only properties
+  readonly log: Logger;
+  readonly executionId: string;
+  readonly startTime: Date;
+  readonly data: D;
+
+  // Mutable property
+  activation: ActivationImpl;
+
+  // Methods
+  openKv(scope?: KeyValueScope): KeyValue;
+  start(workflowId: string, workflowOpts: WorkflowOpts): Promise<AsyncWorkflow>;
+  // Note: For connection access, use activation.connections (recommended)
+  // See: ../s3-sftp-configuration-guide.md for complete credential patterns
+  destroy(scope: KeyValueScope): Promise<void>;
+  createIssue(issue: CreateIssue, options?: { deduplicate?: boolean }): Promise<Issue | null>;
+  request(): express.Request | undefined;
+}
+```
+
+**Key Methods**:
+
+#### `openKv(scope?: KeyValueScope)`
+Opens KV storage at specified scope.
+
+**Scopes**:
+- `':execution:'` - Per execution (ephemeral)
+- `':project:'` - Project-wide (persistent)
+- `':organization:'` - Organization-wide (shared)
+
+**Example**:
+```typescript
+const kv = ctx.openKv(':project:');
+await kv.set('key', 'value');
+const value = await kv.get('key');
+```
+
+#### `request(): express.Request | undefined`
+Access raw HTTP request (when in webhook/HTTP workflow).
+
+**Example**:
+```typescript
+const req = ctx.request();
+const apiKey = req?.headers['x-api-key'] as string;
+const contentType = req?.headers['content-type'];
+```
+
+---
+
+### HttpContext Interface
+
+**Used by**: `http()` tasks
+
+```typescript
+interface HttpContext<Data, PageParams = undefined> extends Context<Data> {
+  // Additional HTTP-specific properties
+  fetch: typeof fetch;
+  connectionVariables: Record<string, any>;
+  pageParams?: PageParams;
+  nextPage: (nextParams: PageParams) => Promise<void>;
+  baseUrl: Promise<string>;
+}
+```
+
+**Properties**:
+
+#### `fetch: typeof fetch`
+Authenticated fetch function with connection credentials.
+
+**Example**:
+```typescript
+http('call-api', { connection: 'my-api' }, async (ctx) => {
+  // fetch is pre-authenticated with connection
+  const response = await ctx.fetch('/users');
+  return response.json();
+});
+```
+
+#### `connectionVariables: Record<string, any>`
+Connection configuration variables.
+
+**Example**:
+```typescript
+http('use-vars', { connection: 'fluent' }, async (ctx) => {
+  const retailerId = ctx.connectionVariables.retailerId;
+  const apiVersion = ctx.connectionVariables.version;
+  ctx.log.info('Connection vars', { retailerId, apiVersion });
+});
+```
+
+#### `baseUrl: Promise<string>`
+Connection's base URL (resolved asynchronously).
+
+**Example**:
+```typescript
+http('show-url', { connection: 'fluent' }, async (ctx) => {
+  const url = await ctx.baseUrl;
+  ctx.log.info('Base URL', { url });
+  // url = 'https://api.fluentcommerce.com'
+});
+```
+
+---
+
+### ActivationImpl
+
+**Access via**: `ctx.activation`
+
+```typescript
+class ActivationImpl implements Activation {
+  // Properties
+  get id(): string;
+  get user(): EndUser;
+  get environment(): ProjectEnvironment | undefined;          // ✅ NEW in v0.4.x
+  get connections(): Array<Connection> | undefined;           // ✅ NEW in v0.4.x
+  get dynamicVariables(): DynamicVariables | undefined;       // ✅ NEW in v0.4.x
+
+  // Methods
+  getVariable<T = unknown>(name: string): T | undefined;
+  setVariable(name: string, value: unknown): Promise<void>;
+}
+```
+
+**EndUser**:
+```typescript
+type EndUser = {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  displayName: string;
+  externalId: string;
+  organisationId: string;
+}
+```
+
+**Connection** (v0.4.x+):
+```typescript
+type Connection = {
+  id: string;
+  name: string;
+  templateId: string;
+  dynamic: boolean;
+  baseUrl: string;
+  createdAt: string;
+  updatedAt: string;
+  credentials: ConnectionCredential[];
+}
+```
+
+**Usage Examples**:
+```typescript
+// Access user info
+fn('log-user', (ctx) => {
+  const user = ctx.activation.user;
+  ctx.log.info('User', {
+    displayName: user.displayName,
+    externalId: user.externalId
+  });
+});
+
+// Access all connections (NEW in v0.4.x)
+fn('list-connections', (ctx) => {
+  const connections = ctx.activation.connections;
+  ctx.log.info('Available connections', {
+    count: connections?.length,
+    names: connections?.map(c => c.name)
+  });
+});
+
+// Get/set variables
+fn('use-variables', async (ctx) => {
+  // Get variable
+  const apiKey = ctx.activation.getVariable<string>('API_KEY');
+
+  // Set variable
+  await ctx.activation.setVariable('LAST_RUN', Date.now());
+});
+
+// Access environment (NEW in v0.4.x)
+fn('check-env', (ctx) => {
+  const env = ctx.activation.environment;
+  ctx.log.info('Environment', {
+    id: env?.id,
+    name: env?.name
+  });
+});
+```
+
+---
+
+## Helper Types
+
+### KeyValueScope
+
+```typescript
+type KeyValueScope = ':execution:' | ':project:' | ':organization:'
+```
+
+**Usage**:
+- `':execution:'` - Ephemeral, cleared after execution
+- `':project:'` - Persistent, shared across executions in project
+- `':organization:'` - Persistent, shared across projects in organization
+
+---
+
+### WebhookData & ScheduleData
+
+```typescript
+type WebhookData = Record<string, never>  // Empty object
+type ScheduleData = Record<string, never>  // Empty object
+```
+
+**Note**: These are empty because actual data comes from:
+- **Webhook**: `ctx.data` contains parsed request body
+- **Schedule**: `ctx.data` is empty, use activation variables instead
+
+---
+
+## Complete Workflow Patterns
+
+### Pattern 1: webhook() + fn() + http()
+
+```typescript
+export const processOrder = webhook('process-order')
+  // Step 1: Parse and validate (fn - no API)
+  .then(fn('validate', (ctx) => {
+    if (!ctx.data?.orderId) {
+      throw new Error('Missing orderId');
+    }
+    return { orderId: ctx.data.orderId, items: ctx.data.items };
+  }))
+
+  // Step 2: Send to Fluent (http - API access)
+  .then(http('send-to-fluent', { connection: 'fluent_commerce' }, async (ctx) => {
+    const client = await createClient(ctx);
+    // ... create order
+    return { success: true, fluentOrderId: '...' };
+  }))
+
+  .catch(({ data }) => ({
+    success: false,
+    error: data instanceof Error ? data.message : 'Unknown error'
+  }));
+```
+
+### Pattern 2: schedule() + fn() (KV only)
+
+```typescript
+export const dailyCleanup = schedule('daily-cleanup', '0 3 * * *')
+  .then(fn('cleanup', async (ctx) => {
+    const kv = ctx.openKv(':project:');
+    // ... cleanup logic
+    return { cleaned: true };
+  }));
+```
+
+### Pattern 3: schedule() + http() (API access)
+
+```typescript
+export const hourlySync = schedule('hourly-sync', '0 * * * *')
+  .then(http('sync', { connection: 'fluent_commerce' }, async (ctx) => {
+    const client = await createClient(ctx);
+    // ... sync logic
+    return { synced: true };
+  }));
+```
+
+### Pattern 4: Multi-step with state
+
+```typescript
+export const statefulWorkflow = schedule('stateful', '0 * * * *')
+  // Check state
+  .then(fn('check-state', async (ctx) => {
+    const kv = ctx.openKv(':project:');
+    const lastRun = await kv.get('last-run');
+    if (Date.now() - lastRun < 3600000) {
+      throw new Error('SKIP');
+    }
+    return { shouldProcess: true };
+  }))
+
+  // Process
+  .then(http('process', { connection: 'fluent' }, async (ctx) => {
+    const client = await createClient(ctx);
+    // ... process
+    return { processed: true };
+  }))
+
+  // Update state
+  .then(fn('update-state', async (ctx) => {
+    const kv = ctx.openKv(':project:');
+    await kv.set('last-run', Date.now());
+    return { stateUpdated: true };
+  }))
+
+  .catch(({ data }) => {
+    if (data.message === 'SKIP') {
+      return { skipped: true };
+    }
+    return { error: data.message };
+  });
+```
+
+---
+
+## Decision Tree
+
+### When to use each workflow type?
+
+```
+Need to receive HTTP requests?
+  ├─ Yes → webhook()
+  └─ No → Continue
+
+Run on schedule?
+  ├─ Yes → schedule()
+  └─ No → http() (for on-demand API calls)
+
+Need external API access (Fluent, S3 presigned URLs)?
+  ├─ Yes → Use http() task
+  └─ No → Use fn() task
+
+Need to access HTTP headers?
+  → Use ctx.request() in any task type
+  → Available in fn(), webhook handlers, and http()
+
+Need multiple connections?
+  → Access via ctx.activation.connections (v0.4.x+)
+
+Need environment-specific logic?
+  → Use ctx.activation.environment (v0.4.x+)
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ WRONG: schedule() with 4th parameter
+
+```typescript
+// This does NOT work in @versori/run v0.4.4
+export const wrong = schedule('daily', '0 0 * * *', { connection: 'fluent' }, async (ctx) => {
+  // ...
+});
+```
+
+### ✅ CORRECT: schedule() + .then()
+
+```typescript
+export const correct = schedule('daily', '0 0 * * *')
+  .then(http('task', { connection: 'fluent' }, async (ctx) => {
+    // ...
+  }));
+```
+
+---
+
+### ❌ WRONG: Accessing ctx.headers
+
+```typescript
+// ctx.headers doesn't exist!
+const apiKey = ctx.headers?.get?.('x-api-key');
+```
+
+### ✅ CORRECT: Using ctx.request()
+
+```typescript
+const req = ctx.request();
+const apiKey = req?.headers['x-api-key'];
+```
+
+---
+
+### ❌ WRONG: Using fn() for external API
+
+```typescript
+// fn() doesn't have ctx.fetch - this will fail!
+fn('call-api', async (ctx) => {
+  const client = await createClient(ctx);  // ❌ Error!
+});
+```
+
+### ✅ CORRECT: Using http() for external API
+
+```typescript
+http('call-api', { connection: 'fluent_commerce' }, async (ctx) => {
+  const client = await createClient(ctx);  // ✅ Works!
+});
+```
+
+---
+
+## Version Compatibility
+
+This reference is based on **@versori/run v0.4.4**.
+
+**Major changes from v0.3.x**:
+- ✅ Added `activation.connections` array
+- ✅ Added `activation.environment` property
+- ✅ Added `activation.dynamicVariables` property
+- ⚠️ `schedule()` signature unchanged (never had 4th parameter)
+
+**Migration**: If you're using old patterns from unofficial docs, update to correct patterns shown above.
+
+---
+
+## Related Documentation
+
+- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Practical workflow examples
+- [Module 5: Connections](./platforms-versori-05-connections.md) - Connection management
+
+---
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)