@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/event-api-guide.md

@@ -1,321 +1,321 @@
-# Event API Ingestion Templates
-
-> **Production-ready Event API ingestion templates**
-> Import data using Fluent Commerce Event API
-
-## Overview
-
-This directory contains 10 production-ready templates for ingesting data using Fluent Commerce Event API. Event API triggers Rubix workflows and supports multiple entity types.
-
-## All Templates
-
-### File-Based Templates (8 templates)
-
-| Template | Source | Format | Entity | Complexity |
-|----------|--------|--------|--------|------------|
-| [S3 CSV Product](./template-ingestion-s3-csv-product-event.md) | S3 | CSV | Product | Beginner |
-| [S3 JSON Product](./template-ingestion-s3-json-product-event.md) | S3 | JSON | Product | Beginner |
-| [S3 XML Product](./template-ingestion-s3-xml-product-event.md) | S3 | XML | Product | Medium |
-| [S3 Parquet Product](./template-ingestion-s3-parquet-product-event.md) | S3 | Parquet | Product | Advanced |
-| [SFTP CSV Product](./template-ingestion-sftp-csv-product-event.md) | SFTP | CSV | Product | Medium |
-| [SFTP JSON Product](./template-ingestion-sftp-json-product-event.md) | SFTP | JSON | Product | Medium |
-| [SFTP XML Product](./template-ingestion-sftp-xml-product-event.md) | SFTP | XML | Product | Medium |
-| [SFTP Parquet Product](./template-ingestion-sftp-parquet-product-event.md) | SFTP | Parquet | Product | Advanced |
-
-### Payload-Based Templates (2 templates)
-
-| Template | Source | Format | Entity | Complexity |
-|----------|--------|--------|--------|------------|
-| [Payload JSON Order Cancel](./template-ingestion-payload-json-order-cancel-event.md) | Webhook | JSON | Order | Beginner |
-| [Payload XML Order Cancel](./template-ingestion-payload-xml-order-cancel-event.md) | Webhook | XML | Order | Beginner |
-
-## Quick Selection
-
-### By Source
-
-**S3** (4 templates)
-- [CSV](./template-ingestion-s3-csv-product-event.md) - Beginner
-- [JSON](./template-ingestion-s3-json-product-event.md) - Beginner
-- [XML](./template-ingestion-s3-xml-product-event.md) - Medium
-- [Parquet](./template-ingestion-s3-parquet-product-event.md) - Advanced
-
-**SFTP** (4 templates)
-- [CSV](./template-ingestion-sftp-csv-product-event.md) - Medium
-- [JSON](./template-ingestion-sftp-json-product-event.md) - Medium
-- [XML](./template-ingestion-sftp-xml-product-event.md) - Medium
-- [Parquet](./template-ingestion-sftp-parquet-product-event.md) - Advanced
-
-**Webhook Payload** (2 templates)
-- [JSON Order Cancel](./template-ingestion-payload-json-order-cancel-event.md) - Beginner
-- [XML Order Cancel](./template-ingestion-payload-xml-order-cancel-event.md) - Beginner
-
-### By Format
-
-**CSV** (2 templates) - Beginner/Medium
-**JSON** (3 templates) - Beginner (includes payload-based)
-**XML** (3 templates) - Medium (includes payload-based)
-**Parquet** (2 templates) - Advanced
-
-### By Entity
-
-**Product** (8 templates) - File-based ingestion from S3/SFTP
-**Order** (2 templates) - Payload-based webhook ingestion
-
-## Event API Features
-
-- **Workflow Triggers** - Triggers Rubix workflows
-- **Multiple Entities** - Products, Orders, Locations
-- **Flexible Schema** - Custom event types
-- **Asynchronous** - Non-blocking processing
-
-## When to Use Payload-Based Templates
-
-Use payload-based templates when:
-- ✅ Receiving data directly via webhook (not from files)
-- ✅ Need immediate processing (no file discovery/download)
-- ✅ Simple event payloads (e.g., order cancel with just order reference)
-- ✅ Real-time event processing
-
-Use file-based templates when:
-- ✅ Processing files from S3 or SFTP
-- ✅ Batch processing multiple records
-- ✅ Need file tracking and archiving
-- ✅ Scheduled ingestion workflows
-
-See [parent directory](../) for Batch API and GraphQL templates.
-
-## retailerId Requirement
-
-**CRITICAL:** Event API requires `retailerId` for all `sendEvent()` calls.
-
-**SDK Validation (v0.1.40+):**
-- SDK validates `retailerId` before calling `sendEvent()`
-- Checks: `event.retailerId || client.retailerId`
-- If both missing, throws: `"retailerId is required for Event API. Set via ctx.connectionVariables.retailerId or client.setRetailerId()"`
-- Validation happens **before** API call, ensuring fail-fast behavior
-
-**Configuration Options:**
-
-### Option 1: Pass in Event Payload (Explicit)
-```typescript
-await client.sendEvent({
-  name: 'UPSERT_PRODUCT',
-  entityType: 'PRODUCT',
-  entityRef: 'SKU-123',
-  retailerId: '1', // ✅ Explicit - overrides client setting
-  attributes: productData
-});
-```
-
-### Option 2: Set on Client (Recommended for Versori)
-```typescript
-// In Versori workflow
-const fluentRetailerId = activation.getVariable('FLUENT_RETAILER_ID');
-client.setRetailerId(fluentRetailerId);
-
-// All events inherit retailerId
-await client.sendEvent({
-  name: 'UPSERT_PRODUCT',
-  entityType: 'PRODUCT',
-  entityRef: 'SKU-123', // ✅ retailerId inherited from client
-  attributes: productData
-});
-```
-
-### Option 3: Via Connection Variables
-```typescript
-// Configure in Versori Connection UI:
-// Custom Parameters (JSON): { "retailerId": "1" }
-
-// SDK auto-detects:
-const client = await createClient(ctx);
-// ✅ retailerId = ctx.connectionVariables.retailerId
-
-await client.sendEvent(event); // ✅ Works automatically
-```
-
-**Validation Error Example:**
-```typescript
-// ❌ This will throw error:
-const client = await createClient(ctx); // No retailerId in connection
-await client.sendEvent({
-  name: 'UPSERT_PRODUCT',
-  entityType: 'PRODUCT',
-  entityRef: 'SKU-123'
-  // Missing retailerId
-});
-// Error: retailerId is required for Event API...
-
-// ✅ This works:
-client.setRetailerId('1');
-await client.sendEvent({
-  name: 'UPSERT_PRODUCT',
-  entityType: 'PRODUCT',
-  entityRef: 'SKU-123'
-});
-```
-
-**Priority Order:**
-1. `event.retailerId` (highest priority)
-2. `client.retailerId` (set via setRetailerId())
-3. `ctx.connectionVariables.retailerId` (auto-detected during createClient())
-
-## Automatic Retry Behavior (v0.1.40+)
-
-**All Event API Calls Protected:**
-
-The SDK automatically retries transient failures for Event API operations:
-- `sendEvent()` - Both `async` and `sync` modes
-
-### 401 Authentication Retry
-
-**Automatic Platform Auth Refresh:**
-- **Max retries:** 3 attempts for 401 errors
-- **Delay:** Exponential backoff (1s → 2s → 4s, capped at 5s)
-- **Applies to:** Both async and sync event modes
-- **Log message:** `"[fc-connect-sdk:auth] Platform auth failure (401), retrying after {delay}ms"`
-
-**Why this matters:**
-- Platform-managed OAuth2 tokens can expire between validation and use
-- Clock skew between Versori and Fluent API can cause timing issues
-- SDK automatically waits for platform token refresh without failing your workflow
-
-**Example scenario:**
-```typescript
-// Token expires during batch processing
-for (const record of records) {
-  await client.sendEvent({
-    name: 'UPSERT_PRODUCT',
-    entityType: 'PRODUCT',
-    entityRef: record.sku,
-    attributes: record
-  });
-  // On 100th event, token expires
-  // ✅ SDK detects 401, waits 1s for platform refresh, retries successfully
-  // ✅ Workflow continues without failure
-}
-```
-
-### 5xx Server Error Retry
-
-**Automatic Transient Error Handling:**
-- **Max retries:** 3 attempts for 5xx errors
-- **Delay:** Exponential backoff (1s → 2s → 4s, capped at 10s)
-- **Applies to:** All `sendEvent()` calls
-- **Log message:** `"[fc-connect-sdk:retry] Request failed, retrying (attempt X/3)"`
-
-**Why this matters:**
-- Fluent API may experience transient failures (503 Service Unavailable)
-- Network issues between Versori and Fluent can cause timeouts
-- SDK retries automatically without losing your event data
-
-### Network Error Retry
-
-**Automatic Network Failure Handling:**
-- **Max retries:** 3 attempts for network errors
-- **Delay:** Exponential backoff (1s → 2s → 4s, capped at 10s)
-- **Applies to:** All `sendEvent()` calls
-
-**Example:**
-```typescript
-// Processing 1,000 product events
-for (const product of products) {
-  await client.sendEvent({
-    name: 'UPSERT_PRODUCT',
-    entityType: 'PRODUCT',
-    entityRef: product.sku,
-    attributes: product
-  });
-  // Network hiccup on event #500
-  // ✅ SDK retries automatically
-  // ✅ Event submitted successfully on retry #2
-  // ✅ Workflow continues processing remaining 500 events
-}
-```
-
-### 4xx Client Error Behavior (No Retry)
-
-**Fail-fast for client errors:**
-- **400 Bad Request:** Immediate failure (invalid event payload)
-- **403 Forbidden:** Immediate failure (permission denied)
-- **422 Unprocessable:** Immediate failure (event validation error)
-
-**Why no retry:** Client errors require application code changes or data fixes
-
-**Example:**
-```typescript
-try {
-  await client.sendEvent({
-    name: 'UPSERT_PRODUCT',
-    entityType: 'PRODUCT',
-    entityRef: 'SKU-123',
-    attributes: { invalid: 'data' } // ❌ Validation error
-  });
-} catch (error) {
-  // 422 error - fix data and retry manually
-  log.error('Event validation failed', { error: error.message });
-  // Handle error: log to dead letter queue, notify admin, etc.
-}
-```
-
-### Per-Event Error Handling
-
-**Best Practice:** Wrap individual `sendEvent()` calls in try/catch
-
-```typescript
-const results = { success: 0, failed: 0, errors: [] };
-
-for (const record of records) {
-  try {
-    await client.sendEvent({
-      name: 'UPSERT_PRODUCT',
-      entityType: 'PRODUCT',
-      entityRef: record.sku,
-      attributes: record
-    });
-    results.success++;
-  } catch (error) {
-    results.failed++;
-    results.errors.push({ sku: record.sku, error: error.message });
-    // SDK already retried 401/5xx errors - this is a non-retryable error
-  }
-}
-
-log.info('Event processing complete', results);
-```
-
-### Retry Logging
-
-**Monitor retry behavior via Versori logs:**
-```typescript
-// Typical log sequence for 401 retry:
-// [INFO] [fc-connect-sdk:event] Sending event "UPSERT_PRODUCT" (PRODUCT:SKU-123)
-// [WARN] [fc-connect-sdk:auth] Platform auth failure (401), retrying after 1000ms
-// [INFO] [fc-connect-sdk:event] Event "UPSERT_PRODUCT" sent successfully (id: evt-456)
-```
-
-**Alert on excessive retries:**
-- Frequent 401 retries → Check Versori connection token refresh settings
-- Frequent 5xx retries → Check Fluent API status page
-- Individual event failures → Review event payload validation
-
-## Event Modes
-
-**Async Mode** (Default - Recommended):
-```typescript
-await client.sendEvent(event, 'async');
-// ✅ Fast response (event queued)
-// ✅ Non-blocking workflow execution
-// ✅ Rubix processes asynchronously
-```
-
-**Sync Mode** (Use for critical events):
-```typescript
-await client.sendEvent(event, 'sync');
-// ✅ Waits for Rubix workflow completion
-// ✅ Returns workflow result
-// ⚠️ Slower response time
-// ⚠️ Blocks workflow execution
-```
-
-**Recommendation:** Use `async` mode for most ingestion workflows to maximize throughput.
+# Event API Ingestion Templates
+
+> **Production-ready Event API ingestion templates**
+> Import data using Fluent Commerce Event API
+
+## Overview
+
+This directory contains 10 production-ready templates for ingesting data using Fluent Commerce Event API. Event API triggers Rubix workflows and supports multiple entity types.
+
+## All Templates
+
+### File-Based Templates (8 templates)
+
+| Template | Source | Format | Entity | Complexity |
+|----------|--------|--------|--------|------------|
+| [S3 CSV Product](./template-ingestion-s3-csv-product-event.md) | S3 | CSV | Product | Beginner |
+| [S3 JSON Product](./template-ingestion-s3-json-product-event.md) | S3 | JSON | Product | Beginner |
+| [S3 XML Product](./template-ingestion-s3-xml-product-event.md) | S3 | XML | Product | Medium |
+| [S3 Parquet Product](./template-ingestion-s3-parquet-product-event.md) | S3 | Parquet | Product | Advanced |
+| [SFTP CSV Product](./template-ingestion-sftp-csv-product-event.md) | SFTP | CSV | Product | Medium |
+| [SFTP JSON Product](./template-ingestion-sftp-json-product-event.md) | SFTP | JSON | Product | Medium |
+| [SFTP XML Product](./template-ingestion-sftp-xml-product-event.md) | SFTP | XML | Product | Medium |
+| [SFTP Parquet Product](./template-ingestion-sftp-parquet-product-event.md) | SFTP | Parquet | Product | Advanced |
+
+### Payload-Based Templates (2 templates)
+
+| Template | Source | Format | Entity | Complexity |
+|----------|--------|--------|--------|------------|
+| [Payload JSON Order Cancel](./template-ingestion-payload-json-order-cancel-event.md) | Webhook | JSON | Order | Beginner |
+| [Payload XML Order Cancel](./template-ingestion-payload-xml-order-cancel-event.md) | Webhook | XML | Order | Beginner |
+
+## Quick Selection
+
+### By Source
+
+**S3** (4 templates)
+- [CSV](./template-ingestion-s3-csv-product-event.md) - Beginner
+- [JSON](./template-ingestion-s3-json-product-event.md) - Beginner
+- [XML](./template-ingestion-s3-xml-product-event.md) - Medium
+- [Parquet](./template-ingestion-s3-parquet-product-event.md) - Advanced
+
+**SFTP** (4 templates)
+- [CSV](./template-ingestion-sftp-csv-product-event.md) - Medium
+- [JSON](./template-ingestion-sftp-json-product-event.md) - Medium
+- [XML](./template-ingestion-sftp-xml-product-event.md) - Medium
+- [Parquet](./template-ingestion-sftp-parquet-product-event.md) - Advanced
+
+**Webhook Payload** (2 templates)
+- [JSON Order Cancel](./template-ingestion-payload-json-order-cancel-event.md) - Beginner
+- [XML Order Cancel](./template-ingestion-payload-xml-order-cancel-event.md) - Beginner
+
+### By Format
+
+**CSV** (2 templates) - Beginner/Medium
+**JSON** (3 templates) - Beginner (includes payload-based)
+**XML** (3 templates) - Medium (includes payload-based)
+**Parquet** (2 templates) - Advanced
+
+### By Entity
+
+**Product** (8 templates) - File-based ingestion from S3/SFTP
+**Order** (2 templates) - Payload-based webhook ingestion
+
+## Event API Features
+
+- **Workflow Triggers** - Triggers Rubix workflows
+- **Multiple Entities** - Products, Orders, Locations
+- **Flexible Schema** - Custom event types
+- **Asynchronous** - Non-blocking processing
+
+## When to Use Payload-Based Templates
+
+Use payload-based templates when:
+- ✅ Receiving data directly via webhook (not from files)
+- ✅ Need immediate processing (no file discovery/download)
+- ✅ Simple event payloads (e.g., order cancel with just order reference)
+- ✅ Real-time event processing
+
+Use file-based templates when:
+- ✅ Processing files from S3 or SFTP
+- ✅ Batch processing multiple records
+- ✅ Need file tracking and archiving
+- ✅ Scheduled ingestion workflows
+
+See [parent directory](../) for Batch API and GraphQL templates.
+
+## retailerId Requirement
+
+**CRITICAL:** Event API requires `retailerId` for all `sendEvent()` calls.
+
+**SDK Validation (v0.1.40+):**
+- SDK validates `retailerId` before calling `sendEvent()`
+- Checks: `event.retailerId || client.retailerId`
+- If both missing, throws: `"retailerId is required for Event API. Set via ctx.connectionVariables.retailerId or client.setRetailerId()"`
+- Validation happens **before** API call, ensuring fail-fast behavior
+
+**Configuration Options:**
+
+### Option 1: Pass in Event Payload (Explicit)
+```typescript
+await client.sendEvent({
+  name: 'UPSERT_PRODUCT',
+  entityType: 'PRODUCT',
+  entityRef: 'SKU-123',
+  retailerId: '1', // ✅ Explicit - overrides client setting
+  attributes: productData
+});
+```
+
+### Option 2: Set on Client (Recommended for Versori)
+```typescript
+// In Versori workflow
+const fluentRetailerId = activation.getVariable('FLUENT_RETAILER_ID');
+client.setRetailerId(fluentRetailerId);
+
+// All events inherit retailerId
+await client.sendEvent({
+  name: 'UPSERT_PRODUCT',
+  entityType: 'PRODUCT',
+  entityRef: 'SKU-123', // ✅ retailerId inherited from client
+  attributes: productData
+});
+```
+
+### Option 3: Via Connection Variables
+```typescript
+// Configure in Versori Connection UI:
+// Custom Parameters (JSON): { "retailerId": "1" }
+
+// SDK auto-detects:
+const client = await createClient(ctx);
+// ✅ retailerId = ctx.connectionVariables.retailerId
+
+await client.sendEvent(event); // ✅ Works automatically
+```
+
+**Validation Error Example:**
+```typescript
+// ❌ This will throw error:
+const client = await createClient(ctx); // No retailerId in connection
+await client.sendEvent({
+  name: 'UPSERT_PRODUCT',
+  entityType: 'PRODUCT',
+  entityRef: 'SKU-123'
+  // Missing retailerId
+});
+// Error: retailerId is required for Event API...
+
+// ✅ This works:
+client.setRetailerId('1');
+await client.sendEvent({
+  name: 'UPSERT_PRODUCT',
+  entityType: 'PRODUCT',
+  entityRef: 'SKU-123'
+});
+```
+
+**Priority Order:**
+1. `event.retailerId` (highest priority)
+2. `client.retailerId` (set via setRetailerId())
+3. `ctx.connectionVariables.retailerId` (auto-detected during createClient())
+
+## Automatic Retry Behavior (v0.1.40+)
+
+**All Event API Calls Protected:**
+
+The SDK automatically retries transient failures for Event API operations:
+- `sendEvent()` - Both `async` and `sync` modes
+
+### 401 Authentication Retry
+
+**Automatic Platform Auth Refresh:**
+- **Max retries:** 3 attempts for 401 errors
+- **Delay:** Exponential backoff (1s → 2s → 4s, capped at 5s)
+- **Applies to:** Both async and sync event modes
+- **Log message:** `"[fc-connect-sdk:auth] Platform auth failure (401), retrying after {delay}ms"`
+
+**Why this matters:**
+- Platform-managed OAuth2 tokens can expire between validation and use
+- Clock skew between Versori and Fluent API can cause timing issues
+- SDK automatically waits for platform token refresh without failing your workflow
+
+**Example scenario:**
+```typescript
+// Token expires during batch processing
+for (const record of records) {
+  await client.sendEvent({
+    name: 'UPSERT_PRODUCT',
+    entityType: 'PRODUCT',
+    entityRef: record.sku,
+    attributes: record
+  });
+  // On 100th event, token expires
+  // ✅ SDK detects 401, waits 1s for platform refresh, retries successfully
+  // ✅ Workflow continues without failure
+}
+```
+
+### 5xx Server Error Retry
+
+**Automatic Transient Error Handling:**
+- **Max retries:** 3 attempts for 5xx errors
+- **Delay:** Exponential backoff (1s → 2s → 4s, capped at 10s)
+- **Applies to:** All `sendEvent()` calls
+- **Log message:** `"[fc-connect-sdk:retry] Request failed, retrying (attempt X/3)"`
+
+**Why this matters:**
+- Fluent API may experience transient failures (503 Service Unavailable)
+- Network issues between Versori and Fluent can cause timeouts
+- SDK retries automatically without losing your event data
+
+### Network Error Retry
+
+**Automatic Network Failure Handling:**
+- **Max retries:** 3 attempts for network errors
+- **Delay:** Exponential backoff (1s → 2s → 4s, capped at 10s)
+- **Applies to:** All `sendEvent()` calls
+
+**Example:**
+```typescript
+// Processing 1,000 product events
+for (const product of products) {
+  await client.sendEvent({
+    name: 'UPSERT_PRODUCT',
+    entityType: 'PRODUCT',
+    entityRef: product.sku,
+    attributes: product
+  });
+  // Network hiccup on event #500
+  // ✅ SDK retries automatically
+  // ✅ Event submitted successfully on retry #2
+  // ✅ Workflow continues processing remaining 500 events
+}
+```
+
+### 4xx Client Error Behavior (No Retry)
+
+**Fail-fast for client errors:**
+- **400 Bad Request:** Immediate failure (invalid event payload)
+- **403 Forbidden:** Immediate failure (permission denied)
+- **422 Unprocessable:** Immediate failure (event validation error)
+
+**Why no retry:** Client errors require application code changes or data fixes
+
+**Example:**
+```typescript
+try {
+  await client.sendEvent({
+    name: 'UPSERT_PRODUCT',
+    entityType: 'PRODUCT',
+    entityRef: 'SKU-123',
+    attributes: { invalid: 'data' } // ❌ Validation error
+  });
+} catch (error) {
+  // 422 error - fix data and retry manually
+  log.error('Event validation failed', { error: error.message });
+  // Handle error: log to dead letter queue, notify admin, etc.
+}
+```
+
+### Per-Event Error Handling
+
+**Best Practice:** Wrap individual `sendEvent()` calls in try/catch
+
+```typescript
+const results = { success: 0, failed: 0, errors: [] };
+
+for (const record of records) {
+  try {
+    await client.sendEvent({
+      name: 'UPSERT_PRODUCT',
+      entityType: 'PRODUCT',
+      entityRef: record.sku,
+      attributes: record
+    });
+    results.success++;
+  } catch (error) {
+    results.failed++;
+    results.errors.push({ sku: record.sku, error: error.message });
+    // SDK already retried 401/5xx errors - this is a non-retryable error
+  }
+}
+
+log.info('Event processing complete', results);
+```
+
+### Retry Logging
+
+**Monitor retry behavior via Versori logs:**
+```typescript
+// Typical log sequence for 401 retry:
+// [INFO] [fc-connect-sdk:event] Sending event "UPSERT_PRODUCT" (PRODUCT:SKU-123)
+// [WARN] [fc-connect-sdk:auth] Platform auth failure (401), retrying after 1000ms
+// [INFO] [fc-connect-sdk:event] Event "UPSERT_PRODUCT" sent successfully (id: evt-456)
+```
+
+**Alert on excessive retries:**
+- Frequent 401 retries → Check Versori connection token refresh settings
+- Frequent 5xx retries → Check Fluent API status page
+- Individual event failures → Review event payload validation
+
+## Event Modes
+
+**Async Mode** (Default - Recommended):
+```typescript
+await client.sendEvent(event, 'async');
+// ✅ Fast response (event queued)
+// ✅ Non-blocking workflow execution
+// ✅ Rubix processes asynchronously
+```
+
+**Sync Mode** (Use for critical events):
+```typescript
+await client.sendEvent(event, 'sync');
+// ✅ Waits for Rubix workflow completion
+// ✅ Returns workflow result
+// ⚠️ Slower response time
+// ⚠️ Blocks workflow execution
+```
+
+**Recommendation:** Use `async` mode for most ingestion workflows to maximize throughput.