@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,206 +1,206 @@
-# Batch API Ingestion Templates
-
-> **Production-ready Batch API ingestion templates**
-> Import inventory data to Fluent Commerce (INVENTORY only)
-
-## Overview
-
-This directory contains 8 production-ready templates for ingesting inventory data using Fluent Commerce Batch API. The Batch API is **INVENTORY ONLY** - use GraphQL mutations or Event API for other entity types.
-
-## All Templates
-
-| Template | Source | Format | Complexity |
-|----------|--------|--------|------------|
-| [S3 CSV Inventory](./template-ingestion-s3-csv-inventory-batch.md) | S3 | CSV | Beginner |
-| [S3 JSON Inventory](./template-ingestion-s3-json-inventory-batch.md) | S3 | JSON | Beginner |
-| [S3 XML Inventory](./template-ingestion-s3-xml-inventory-batch.md) | S3 | XML | Medium |
-| [SFTP CSV Inventory](./template-ingestion-sftp-csv-inventory-batch.md) | SFTP | CSV | Medium |
-| [SFTP JSON Inventory](./template-ingestion-sftp-json-inventory-batch.md) | SFTP | JSON | Medium |
-| [SFTP XML Inventory](./template-ingestion-sftp-xml-inventory-batch.md) | SFTP | XML | Medium |
-| [Cycle Count Reconciliation](./template-ingestion-cycle-count-reconciliation.md) | S3/SFTP | CSV | Advanced |
-| [Multi-Channel Inventory Sync](./template-ingestion-multi-channel-inventory-sync.md) | Multiple | Multiple | Advanced |
-
-## Quick Selection
-
-### By Source
-
-**S3** (4 templates)
-- [CSV](./template-ingestion-s3-csv-inventory-batch.md) - Beginner
-- [JSON](./template-ingestion-s3-json-inventory-batch.md) - Beginner
-- [XML](./template-ingestion-s3-xml-inventory-batch.md) - Medium
-
-**SFTP** (4 templates)
-- [CSV](./template-ingestion-sftp-csv-inventory-batch.md) - Medium
-- [JSON](./template-ingestion-sftp-json-inventory-batch.md) - Medium
-- [XML](./template-ingestion-sftp-xml-inventory-batch.md) - Medium
-
-**Advanced** (2 templates)
-- [Cycle Count](./template-ingestion-cycle-count-reconciliation.md) - Advanced
-- [Multi-Channel Sync](./template-ingestion-multi-channel-inventory-sync.md) - Advanced
-
-## Batch API Limitations
-
-**CRITICAL: Batch API is INVENTORY ONLY**
-
-| Feature | Supported | Notes |
-|---------|-----------|-------|
-| **Entity Type** | ✅ INVENTORY ONLY | ❌ Cannot use for ORDER, PRODUCT, LOCATION |
-| **Action** | ✅ UPSERT ONLY | ❌ No DELETE, CREATE-only, UPDATE-only |
-| **Alternative** | GraphQL mutations | For other entities |
-
-See [parent directory](../) for Event API and GraphQL templates.
-
-## retailerId Requirement
-
-**CRITICAL:** Batch API requires `retailerId` for both `createJob()` and job payload operations.
-
-**SDK Validation (v0.1.40+):**
-- SDK validates `retailerId` is set before calling `createJob()`
-- If missing, throws: `"retailerId is required for Job/Batch API. Set via ctx.connectionVariables.retailerId or client.setRetailerId()"`
-- Validation happens **before** any data processing, ensuring fail-fast behavior
-
-**Configuration Options:**
-
-### Option 1: Pass in Job Payload (Explicit)
-```typescript
-const job = await client.createJob({
-  name: 'inventory-sync',
-  retailerId: '1', // ✅ Explicit - recommended for multi-tenant
-});
-```
-
-### Option 2: Set on Client (Recommended for Versori)
-```typescript
-// In Versori workflow
-const fluentRetailerId = activation.getVariable('FLUENT_RETAILER_ID');
-client.setRetailerId(fluentRetailerId);
-
-const job = await client.createJob({
-  name: 'inventory-sync' // ✅ retailerId inherited from client
-});
-```
-
-### 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
-```
-
-**Validation Error Example:**
-```typescript
-// ❌ This will throw error:
-const job = await client.createJob({ name: 'test' });
-// Error: retailerId is required for Job/Batch API...
-
-// ✅ This works:
-client.setRetailerId('1');
-const job = await client.createJob({ name: 'test' });
-```
-
-## Automatic Retry Behavior (v0.1.40+)
-
-**All Batch API Methods Protected:**
-
-The SDK automatically retries transient failures for all Batch API operations:
-- `createJob()` - Job creation with retry
-- `sendBatch()` - **NEW:** Now includes retry protection
-- `getJobStatus()` - Status polling with retry
-- `getBatchStatus()` - Batch status with retry
-- `getJobResults()` - Results retrieval with retry
-
-### 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:** ALL Batch API methods
-- **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
-
-**Example scenario:**
-```typescript
-// Token expires 1 second before job creation
-const job = await client.createJob({ name: 'inventory', retailerId: '1' });
-// ✅ SDK detects 401, waits 1s for platform refresh, retries successfully
-```
-
-### 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 Batch API methods
-- **Log message:** `"[fc-connect-sdk:retry] Request failed, retrying (attempt X/3)"`
-
-### 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 Batch API methods including `sendBatch()`
-
-### sendBatch() Retry Protection (NEW in v0.1.40)
-
-**Previously:** `sendBatch()` used direct `ctx.fetch()` without retry
-**Now:** `sendBatch()` uses `fetchWithRetry()` for full protection
-
-**Impact:**
-- Batch submission failures due to transient network issues now auto-retry
-- Protects significant data processing work (file download, parse, transform)
-- Job expiry detection remains application responsibility (use JobTracker patterns)
-
-**Example:**
-```typescript
-// User processes 10,000 inventory records (30 seconds)
-const entities = await processInventoryFile(); // Heavy lifting
-
-// Network hiccup during batch submission
-await client.sendBatch(jobId, { entities, action: 'UPSERT' });
-// ✅ SDK auto-retries transient network failure
-// ✅ Batch submitted successfully on retry #2
-// ✅ 30 seconds of processing NOT wasted
-```
-
-### 4xx Client Error Behavior (No Retry)
-
-**Fail-fast for client errors:**
-- **400 Bad Request:** Immediate failure (invalid payload)
-- **403 Forbidden:** Immediate failure (permission denied)
-- **422 Unprocessable:** Immediate failure (validation error)
-
-**Why no retry:** Client errors require application code changes, not retry
-
-### Retry Logging
-
-**Monitor retry behavior via Versori logs:**
-```typescript
-// Typical log sequence for 401 retry:
-// [INFO] [fc-connect-sdk:job] Creating job "inventory-sync"
-// [WARN] [fc-connect-sdk:auth] Platform auth failure (401), retrying after 1000ms
-// [INFO] [fc-connect-sdk:job] Job created successfully (id: job-123)
-```
-
-**Alert on excessive retries:**
-- Frequent 401 retries → Check Versori connection token refresh settings
-- Frequent 5xx retries → Check Fluent API status page
-
-## Job Expiry and Orchestration
-
-**Note:** SDK retry logic handles **transient failures**, not job expiry.
-
-**Job Expiry Detection:** Application responsibility
-- Use `JobTracker` pattern (see templates)
-- Poll `getJobStatus()` with timeout logic
-- Recreate job if expired (status: `EXPIRED`)
-
-**Orchestrator Patterns:**
-- **BatchAPIManager** - High-level orchestration with job expiry handling
-- **Manual orchestration** - Custom retry logic for job recreation
+# Batch API Ingestion Templates
+
+> **Production-ready Batch API ingestion templates**
+> Import inventory data to Fluent Commerce (INVENTORY only)
+
+## Overview
+
+This directory contains 8 production-ready templates for ingesting inventory data using Fluent Commerce Batch API. The Batch API is **INVENTORY ONLY** - use GraphQL mutations or Event API for other entity types.
+
+## All Templates
+
+| Template | Source | Format | Complexity |
+|----------|--------|--------|------------|
+| [S3 CSV Inventory](./template-ingestion-s3-csv-inventory-batch.md) | S3 | CSV | Beginner |
+| [S3 JSON Inventory](./template-ingestion-s3-json-inventory-batch.md) | S3 | JSON | Beginner |
+| [S3 XML Inventory](./template-ingestion-s3-xml-inventory-batch.md) | S3 | XML | Medium |
+| [SFTP CSV Inventory](./template-ingestion-sftp-csv-inventory-batch.md) | SFTP | CSV | Medium |
+| [SFTP JSON Inventory](./template-ingestion-sftp-json-inventory-batch.md) | SFTP | JSON | Medium |
+| [SFTP XML Inventory](./template-ingestion-sftp-xml-inventory-batch.md) | SFTP | XML | Medium |
+| [Cycle Count Reconciliation](./template-ingestion-cycle-count-reconciliation.md) | S3/SFTP | CSV | Advanced |
+| [Multi-Channel Inventory Sync](./template-ingestion-multi-channel-inventory-sync.md) | Multiple | Multiple | Advanced |
+
+## Quick Selection
+
+### By Source
+
+**S3** (4 templates)
+- [CSV](./template-ingestion-s3-csv-inventory-batch.md) - Beginner
+- [JSON](./template-ingestion-s3-json-inventory-batch.md) - Beginner
+- [XML](./template-ingestion-s3-xml-inventory-batch.md) - Medium
+
+**SFTP** (4 templates)
+- [CSV](./template-ingestion-sftp-csv-inventory-batch.md) - Medium
+- [JSON](./template-ingestion-sftp-json-inventory-batch.md) - Medium
+- [XML](./template-ingestion-sftp-xml-inventory-batch.md) - Medium
+
+**Advanced** (2 templates)
+- [Cycle Count](./template-ingestion-cycle-count-reconciliation.md) - Advanced
+- [Multi-Channel Sync](./template-ingestion-multi-channel-inventory-sync.md) - Advanced
+
+## Batch API Limitations
+
+**CRITICAL: Batch API is INVENTORY ONLY**
+
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| **Entity Type** | ✅ INVENTORY ONLY | ❌ Cannot use for ORDER, PRODUCT, LOCATION |
+| **Action** | ✅ UPSERT ONLY | ❌ No DELETE, CREATE-only, UPDATE-only |
+| **Alternative** | GraphQL mutations | For other entities |
+
+See [parent directory](../) for Event API and GraphQL templates.
+
+## retailerId Requirement
+
+**CRITICAL:** Batch API requires `retailerId` for both `createJob()` and job payload operations.
+
+**SDK Validation (v0.1.40+):**
+- SDK validates `retailerId` is set before calling `createJob()`
+- If missing, throws: `"retailerId is required for Job/Batch API. Set via ctx.connectionVariables.retailerId or client.setRetailerId()"`
+- Validation happens **before** any data processing, ensuring fail-fast behavior
+
+**Configuration Options:**
+
+### Option 1: Pass in Job Payload (Explicit)
+```typescript
+const job = await client.createJob({
+  name: 'inventory-sync',
+  retailerId: '1', // ✅ Explicit - recommended for multi-tenant
+});
+```
+
+### Option 2: Set on Client (Recommended for Versori)
+```typescript
+// In Versori workflow
+const fluentRetailerId = activation.getVariable('FLUENT_RETAILER_ID');
+client.setRetailerId(fluentRetailerId);
+
+const job = await client.createJob({
+  name: 'inventory-sync' // ✅ retailerId inherited from client
+});
+```
+
+### 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
+```
+
+**Validation Error Example:**
+```typescript
+// ❌ This will throw error:
+const job = await client.createJob({ name: 'test' });
+// Error: retailerId is required for Job/Batch API...
+
+// ✅ This works:
+client.setRetailerId('1');
+const job = await client.createJob({ name: 'test' });
+```
+
+## Automatic Retry Behavior (v0.1.40+)
+
+**All Batch API Methods Protected:**
+
+The SDK automatically retries transient failures for all Batch API operations:
+- `createJob()` - Job creation with retry
+- `sendBatch()` - **NEW:** Now includes retry protection
+- `getJobStatus()` - Status polling with retry
+- `getBatchStatus()` - Batch status with retry
+- `getJobResults()` - Results retrieval with retry
+
+### 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:** ALL Batch API methods
+- **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
+
+**Example scenario:**
+```typescript
+// Token expires 1 second before job creation
+const job = await client.createJob({ name: 'inventory', retailerId: '1' });
+// ✅ SDK detects 401, waits 1s for platform refresh, retries successfully
+```
+
+### 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 Batch API methods
+- **Log message:** `"[fc-connect-sdk:retry] Request failed, retrying (attempt X/3)"`
+
+### 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 Batch API methods including `sendBatch()`
+
+### sendBatch() Retry Protection (NEW in v0.1.40)
+
+**Previously:** `sendBatch()` used direct `ctx.fetch()` without retry
+**Now:** `sendBatch()` uses `fetchWithRetry()` for full protection
+
+**Impact:**
+- Batch submission failures due to transient network issues now auto-retry
+- Protects significant data processing work (file download, parse, transform)
+- Job expiry detection remains application responsibility (use JobTracker patterns)
+
+**Example:**
+```typescript
+// User processes 10,000 inventory records (30 seconds)
+const entities = await processInventoryFile(); // Heavy lifting
+
+// Network hiccup during batch submission
+await client.sendBatch(jobId, { entities, action: 'UPSERT' });
+// ✅ SDK auto-retries transient network failure
+// ✅ Batch submitted successfully on retry #2
+// ✅ 30 seconds of processing NOT wasted
+```
+
+### 4xx Client Error Behavior (No Retry)
+
+**Fail-fast for client errors:**
+- **400 Bad Request:** Immediate failure (invalid payload)
+- **403 Forbidden:** Immediate failure (permission denied)
+- **422 Unprocessable:** Immediate failure (validation error)
+
+**Why no retry:** Client errors require application code changes, not retry
+
+### Retry Logging
+
+**Monitor retry behavior via Versori logs:**
+```typescript
+// Typical log sequence for 401 retry:
+// [INFO] [fc-connect-sdk:job] Creating job "inventory-sync"
+// [WARN] [fc-connect-sdk:auth] Platform auth failure (401), retrying after 1000ms
+// [INFO] [fc-connect-sdk:job] Job created successfully (id: job-123)
+```
+
+**Alert on excessive retries:**
+- Frequent 401 retries → Check Versori connection token refresh settings
+- Frequent 5xx retries → Check Fluent API status page
+
+## Job Expiry and Orchestration
+
+**Note:** SDK retry logic handles **transient failures**, not job expiry.
+
+**Job Expiry Detection:** Application responsibility
+- Use `JobTracker` pattern (see templates)
+- Poll `getJobStatus()` with timeout logic
+- Recreate job if expired (status: `EXPIRED`)
+
+**Orchestrator Patterns:**
+- **BatchAPIManager** - High-level orchestration with job expiry handling
+- **Manual orchestration** - Custom retry logic for job recreation