@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/workflows/workflows-overview-guide.md

@@ -1,646 +1,646 @@
-# Versori Scheduled Workflows - Use Case Guide
-
-**FC Connect SDK** - Production-ready patterns for scheduled workflows on the Versori platform.
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
----
-
-## Overview
-
-This directory contains verified, production-ready use case guides organized by entity type. Each guide includes:
-
-✅ **Complete working code** - Copy-paste ready
-✅ **SDK method verification** - All signatures checked against SDK source
-✅ **Best practices** - Error handling, state management, archiving
-✅ **Configuration examples** - Activation variables, mappings, resolvers
-
----
-
-## Quick Navigation by Entity Type
-
-### 🔗 Rubix Webhook Patterns ⭐ NEW
-
-**Location**: `rubix-webhooks/`
-
-| Use Case | Description | Complexity | File |
-|----------|-------------|------------|------|
-| Fluent Rubix Webhook Pattern | Receive webhooks from Rubix workflows, validate signature, query entity, do logic | Medium | [template-fluent-rubix-webhook-pattern.md](rubix-webhooks/template-fluent-rubix-webhook-pattern.md) |
-
-**Key Features:**
-- ✅ Complete Rubix workflow configuration guide
-- ✅ Webhook signature validation using FluentClient
-- ✅ Entity extraction from payload
-- ✅ GraphQL queries to fetch entity details
-- ✅ Business logic processing
-- ✅ Structured response handling
-
-### 📦 Inventory Management
-
-**Location**: `inventory/`
-
-| Use Case                   | Source         | Format | API           | Complexity | File                                                                         |
-| -------------------------- | -------------- | ------ | ------------- | ---------- | ---------------------------------------------------------------------------- |
-| S3 → Inventory Batch       | S3             | CSV    | Batch API     | Medium     | [template-ingestion-s3-csv-inventory-batch.md](ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)       |
-| SFTP → Inventory Batch     | SFTP           | CSV    | Batch API     | Medium     | [template-ingestion-sftp-csv-inventory-batch.md](ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)   |
-| Cycle Count Reconciliation | S3             | CSV    | GraphQL       | High       | [cycle-count-reconciliation.md](ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md)     |
-| Multi-Channel Sync         | Fluent GraphQL | -      | External APIs | High       | [multi-channel-inventory-sync.md](ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md) |
-
-### 🏷️ Product Management
-
-**Location**: `ingestion/event-api/`
-
-| Use Case                     | Source | Format     | API       | Complexity | File                                                                                                                        |
-| ---------------------------- | ------ | ---------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
-| SFTP CSV → Product Event     | SFTP   | CSV        | Event API | Medium     | [template-ingestion-sftp-csv-product-event.md](ingestion/event-api/template-ingestion-sftp-csv-product-event.md) ✅   |
-| SFTP JSON → Product Event    | SFTP   | JSON/JSONL | Event API | Medium     | [template-ingestion-sftp-json-product-event.md](ingestion/event-api/template-ingestion-sftp-json-product-event.md) ✅ |
-| S3 CSV → Product Event       | S3     | CSV        | Event API | Medium     | [s3-csv-product-event.md](ingestion/event-api/template-ingestion-s3-csv-product-event.md)                                                      |
-| S3 JSON → Product Event      | S3     | JSON       | Event API | Medium     | [s3-json-product-event.md](ingestion/event-api/template-ingestion-s3-json-product-event.md)                                                    |
-| S3 XML → Product Event       | S3     | XML        | Event API | Medium     | [s3-xml-product-event.md](ingestion/event-api/template-ingestion-s3-xml-product-event.md)                                                      |
-| S3 Parquet → Product Event   | S3     | Parquet    | Event API | Medium     | [s3-parquet-product-event.md](ingestion/event-api/template-ingestion-s3-parquet-product-event.md)                                              |
-| SFTP XML → Product Event     | SFTP   | XML        | Event API | Medium     | [sftp-xml-product-event.md](ingestion/event-api/template-ingestion-sftp-xml-product-event.md)                                                  |
-| SFTP Parquet → Product Event | SFTP   | Parquet    | Event API | Medium     | [sftp-parquet-product-event.md](ingestion/event-api/template-ingestion-sftp-parquet-product-event.md)                                          |
-
-### 🎛️ Control Management ⭐ NEW
-
-**Location**: `ingestion/graphql-mutations/`
-
-| Use Case                   | Source | Format | API               | Complexity  | File                                                                                                                                  |
-| -------------------------- | ------ | ------ | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| S3 CSV → Control GraphQL   | S3     | CSV    | GraphQL Mutations | Medium-High | [template-ingestion-s3-csv-control-graphql.md](ingestion/graphql-mutations/template-ingestion-s3-csv-control-graphql.md) ✅     |
-| SFTP CSV → Control GraphQL | SFTP   | CSV    | GraphQL Mutations | Medium-High | [template-ingestion-sftp-csv-control-graphql.md](ingestion/graphql-mutations/template-ingestion-sftp-csv-control-graphql.md) ✅ |
-
-**Key Features:**
-
-- ✅ **Simplified CSV format** - Single `catalogRef` field (works for both EXCLUSION and QUANTITY_BUFFER)
-- ✅ **3 CSV pattern options** - Pre-built refs, component-based, hybrid
-- ✅ **Bulk GraphQL queries** - 5x faster than individual queries, pagination-aware
-- ✅ **Schema validation** - ControlSchemaValidator ensures spec compliance
-- ✅ **3-level duplicate detection** - File-level, row-level, cross-file tracking
-- ✅ **20+ metrics** - Comprehensive ControlMetricsCollector
-- ✅ **Smart upsert** - Auto-detect create vs update with ControlRefTracker
-- ✅ **Batch mutations** - 12x faster than sequential processing
-
-**SFTP-Specific Enhancements:**
-
-- ✅ Connection pooling with keep-alive
-- ✅ Automatic retry logic with exponential backoff
-- ✅ Network resilience (handles timeouts, disconnects)
-- ✅ Proper connection disposal in finally blocks
-
-### 💰 Price Management
-
-**Location**: `price/`
-
-| Use Case               | Source | Format | API               | Complexity | File                                                           |
-| ---------------------- | ------ | ------ | ----------------- | ---------- | -------------------------------------------------------------- |
-| S3 CSV → Price GraphQL | S3     | CSV    | GraphQL Mutations | Medium     | [s3-csv-price-to-graphql.md](ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md) |
-
----
-
-## Pattern Matrix
-
-### By Data Source
-
-| Source             | Inventory             | Product                         | Control          | Price            |
-| ------------------ | --------------------- | ------------------------------- | ---------------- | ---------------- |
-| **S3**             | ✅ CSV → Batch        | ✅ CSV/JSON/XML/Parquet → Event | ✅ CSV → GraphQL | ✅ CSV → GraphQL |
-| **SFTP**           | ✅ CSV → Batch        | ✅ CSV/JSON/XML/Parquet → Event | ✅ CSV → GraphQL | -                |
-| **Fluent GraphQL** | ✅ Multi-channel sync | -                               | -                | -                |
-
-### By File Format
-
-| Format         | Inventory   | Product     | Control     | Price | Parser                 |
-| -------------- | ----------- | ----------- | ----------- | ----- | ---------------------- |
-| **CSV**        | ✅ S3, SFTP | ✅ S3, SFTP | ✅ S3, SFTP | ✅ S3 | `CSVParserService`     |
-| **JSON/JSONL** | -           | ✅ S3, SFTP | -           | -     | `JSONParserService`    |
-| **XML**        | -           | ✅ S3, SFTP | -           | -     | `XMLParserService`     |
-| **Parquet**    | -           | ✅ S3, SFTP | -           | -     | `ParquetParserService` |
-
-### By API Pattern
-
-| API                   | Use Cases                           | When to Use                                                 |
-| --------------------- | ----------------------------------- | ----------------------------------------------------------- |
-| **Batch API**         | Inventory sync (S3, SFTP)           | High-volume inventory updates with BPP change detection     |
-| **Event API**         | Product sync (all sources)          | Product/location/customer upserts needing workflow triggers |
-| **GraphQL Mutations** | Control, price updates, cycle count | Control groups, rules, prices, single-entity operations     |
-| **GraphQL Queries**   | Multi-channel sync, control lookup  | Extraction, ATP calculations, bulk control existence checks |
-
----
-
-## Common Patterns Across All Use Cases
-
-### 1. Universal Client Creation
-
-All workflows use the same client factory:
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Auto-detects Versori context and configures OAuth2 from connections
-const client = await createClient(ctx);
-```
-
-### 2. Data Source Configuration
-
-**S3DataSource:**
-
-```typescript
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-const s3 = new S3DataSource(
-  {
-    type: 'S3_CSV', // or S3_JSON, S3_XML, S3_PARQUET
-    connectionId: 'unique-id',
-    name: 'Human-readable name',
-    s3Config: {
-      bucket: 'bucket-name',
-      region: 'us-east-1',
-      accessKeyId: 'xxx',
-      secretAccessKey: 'yyy',
-    },
-  },
-  logger
-);
-```
-
-**SftpDataSource:**
-
-```typescript
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-const sftp = new SftpDataSource(
-  {
-    type: 'SFTP_CSV', // or SFTP_JSON, SFTP_JSONL, SFTP_XML, SFTP_PARQUET
-    connectionId: 'unique-id',
-    name: 'Human-readable name',
-    settings: {
-      host: 'sftp.example.com',
-      port: 22,
-      username: 'user',
-      password: 'pass', // OR privateKey
-      remotePath: '/incoming',
-      filePattern: '*.csv',
-    },
-  },
-  logger
-);
-```
-
-### 3. Universal Mapping Pattern
-
-One mapping engine for all formats (CSV, JSON, XML, Parquet):
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(
-  {
-    fields: {
-      locationRef: { source: 'location', required: true, resolver: 'sdk.trim' },
-      skuRef: { source: 'sku', required: true, resolver: 'sdk.trim' },
-      qty: { source: 'quantity', required: true, resolver: 'sdk.parseInt' },
-      type: { value: 'ADJUSTMENT', required: true },
-      status: { source: 'status', resolver: 'sdk.uppercase', defaultValue: 'ACTIVE' },
-    },
-  },
-  {
-    customResolvers: {
-      'custom.splitByPipe': (value, sourceData, config, helpers) => {
-        return helpers.ensureArray(value?.split('|') || []);
-      },
-    },
-  }
-);
-
-// Transform data
-const result = await mapper.map(sourceData);
-// Returns: { success: boolean, data: any, errors?: string[] }
-```
-
-### 4. State Management (Duplicate Prevention)
-
-```typescript
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-const fileTracker = new VersoriFileTracker(ctx.openKv(':project:'), 'workflow-prefix');
-
-// Check if already processed
-const alreadyProcessed = await fileTracker.wasFileProcessed(fileName);
-if (alreadyProcessed) {
-  console.log('Skipping duplicate file');
-  continue;
-}
-
-// Mark as processed after success
-await fileTracker.markFileProcessed(fileName, { recordCount: 100 });
-```
-
-### 5. File Operations (All Data Sources)
-
-**List Files:**
-
-```typescript
-const files = await dataSource.listFiles({
-  remotePath: '/path', // SFTP only
-  prefix: 'prefix/', // S3 only
-  filePattern: '*.csv', // SFTP only
-});
-```
-
-**Download File:**
-
-```typescript
-const content = await dataSource.downloadFile(filePath, {
-  encoding: 'utf8', // For text files
-});
-```
-
-**Archive/Move File:**
-
-```typescript
-await dataSource.moveFile(
-  '/incoming/file.csv',
-  '/archive/file.csv',
-  true // overwrite if exists
-);
-```
-
-**Copy File:**
-
-```typescript
-await dataSource.copyFile(
-  '/incoming/file.csv',
-  '/backup/file.csv',
-  false // don't overwrite
-);
-```
-
-**Delete File:**
-
-```typescript
-await dataSource.deleteFile('/temp/file.csv');
-```
-
----
-
-## API Decision Guide
-
-### When to Use Batch API (Inventory Only)
-
-✅ **Use Batch API for:**
-
-- High-volume inventory updates (1000s+ records)
-- Full inventory snapshots
-- Daily/hourly inventory sync
-- Scenarios needing BPP (Batch Pre-Processing) change detection
-
-❌ **Don't Use Batch API for:**
-
-- Products, Locations, Customers (use Event API)
-- Low-volume updates (<100 records)
-- Real-time updates
-
-**Example:**
-
-```typescript
-const job = await client.createJob({
-  name: 'Daily Inventory Sync',
-  retailerId: 'my-retailer',
-  // BPP enabled by default
-});
-
-await client.sendBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  source: 'S3_CSV',
-  event: 'INVENTORY_SYNC',
-  entities: inventoryRecords,
-});
-```
-
-### When to Use Event API
-
-✅ **Use Event API for:**
-
-- **Products**: Catalog sync, variant updates
-- **Locations**: Store/warehouse setup
-- **Customers**: Registration, profile updates
-- **Orders**: Single order creation
-- **Custom Entities**: Any entity needing workflow triggers
-
-**Example:**
-
-```typescript
-await client.sendEvent(
-  {
-    name: 'UPSERT_PRODUCT',
-    entityType: 'PRODUCT',
-    entitySubtype: 'VARIANT',
-    entityRef: catalogueRef,
-    rootEntityType: 'PRODUCT_CATALOGUE',
-    rootEntityRef: catalogueRef,
-    attributes: productData,
-  },
-  'async' // or 'sync'
-);
-```
-
-### When to Use GraphQL Mutations
-
-✅ **Use GraphQL for:**
-
-- Price updates (no Event API support)
-- Single-entity operations
-- Complex queries with relationships
-- Testing/debugging
-
-**Example:**
-
-```typescript
-await client.graphql({
-  query: `
-    mutation UpdatePrice($input: UpdatePriceInput!) {
-      updatePrice(input: $input) {
-        id
-        ref
-      }
-    }
-  `,
-  variables: { input: priceData },
-});
-```
-
----
-
-## Troubleshooting Common Issues
-
-### Issue: "Missing required field: connectionId"
-
-**Solution**: All data sources now require `connectionId` and `name` fields:
-
-```typescript
-new S3DataSource({
-  type: 'S3_CSV',
-  connectionId: 'unique-id', // ← Required
-  name: 'Friendly Name', // ← Required
-  s3Config: { ... }
-}, logger);
-```
-
-### Issue: "sendBatch requires action, entityType, source, event"
-
-**Solution**: Batch API payloads must include all required fields:
-
-```typescript
-await client.sendBatch(jobId, {
-  action: 'UPSERT', // ← Required
-  entityType: 'INVENTORY', // ← Required
-  source: 'S3_CSV', // ← Required
-  event: 'INVENTORY_SYNC', // ← Required
-  entities: records,
-});
-```
-
-### Issue: "UniversalMapper: cannot use logger option"
-
-**Solution**: UniversalMapper constructor changed - no longer accepts `{ logger, fluentClient }`:
-
-```typescript
-// ❌ Old (incorrect):
-new UniversalMapper(config, { logger, fluentClient });
-
-// ✅ New (correct):
-new UniversalMapper(config, { customResolvers });
-```
-
-### Issue: "wasFileProcessed is not a function"
-
-**Solution**: Use correct method name:
-
-```typescript
-// ❌ Old:
-await fileTracker.isFileProcessed(fileName);
-
-// ✅ Correct:
-await fileTracker.wasFileProcessed(fileName);
-```
-
----
-
-## Best Practices
-
-### 1. Always Use State Management
-
-Prevent duplicate processing across workflow runs:
-
-```typescript
-const fileTracker = new VersoriFileTracker(ctx.openKv(':project:'), 'unique-prefix');
-```
-
-### 2. Archive Files After Processing
-
-```typescript
-// file.name contains just filename, file.path contains full path
-await dataSource.moveFile(file.path, `${archivePath}/${file.name}`);
-```
-
-### 3. Use BPP for Full Snapshots
-
-For full inventory snapshots, let BPP filter unchanged records:
-
-```typescript
-const job = await client.createJob({
-  name: 'Daily Full Inventory',
-  retailerId: 'my-retailer',
-  // BPP enabled by default
-});
-```
-
-### 4. Skip BPP for Delta Feeds
-
-For pre-filtered delta feeds:
-
-```typescript
-const job = await client.createJob({
-  name: 'Hourly Deltas',
-  retailerId: 'my-retailer',
-  meta: {
-    preprocessing: 'skip', // Skip BPP
-  },
-});
-```
-
-### 5. Use Async Mode for Events
-
-For scalability and throughput:
-
-```typescript
-await client.sendEvent(event, 'async'); // Recommended
-```
-
-### 6. MemoryInterpreter Pattern (Local Testing)
-
-When developing workflows locally, use MemoryInterpreter for testing:
-
-```typescript
-// index.ts - Entry point for local development/testing
-import { MemoryInterpreter } from '@versori/run';
-import { dailyInventorySync } from './src/workflows/scheduled/daily-inventory-sync';
-import { adhocInventorySync } from './src/workflows/webhook/adhoc-inventory-sync';
-
-async function main(): Promise<void> {
-  const mi = await MemoryInterpreter.newInstance();
-  mi.register(dailyInventorySync);
-  mi.register(adhocInventorySync);
-  await mi.start();
-}
-
-main().then().catch((err) => console.error('Failed to run main()', err));
-```
-
-**Important:** MemoryInterpreter is for local development only - Versori platform handles workflow registration automatically when deployed.
-
-### 7. Optional Feature Toggles
-
-Use activation variables to enable/disable optional features:
-
-```typescript
-// Optional: Disable file tracking for testing (enabled by default)
-const enableFileTracking = activation.getVariable('enableFileTracking') !== 'false';
-
-if (enableFileTracking) {
-  const alreadyProcessed = await fileTracker.wasFileProcessed(fileName);
-  if (alreadyProcessed) {
-    log.info('Skipping duplicate file');
-    continue;
-  }
-}
-
-// Optional: Enable detailed logging for debugging (disabled by default)
-const detailedLogging = activation.getVariable('detailedLogging') === 'true';
-
-if (detailedLogging) {
-  log.info('Detailed processing metrics', {
-    fileSize: file.size,
-    parseTime: parseEndTime - parseStartTime,
-    mappingTime: mapEndTime - mapStartTime,
-    uploadTime: uploadEndTime - uploadStartTime,
-  });
-}
-
-// Optional: Control BPP behavior
-const bppEnabled = activation.getVariable('bppEnabled') !== 'false';
-
-const job = await client.createJob({
-  name: 'Inventory Sync',
-  retailerId: 'my-retailer',
-  meta: bppEnabled ? {} : { preprocessing: 'skip' },
-});
-```
-
-**Common Feature Toggles:**
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `enableFileTracking` | `true` | Prevent duplicate file processing |
-| `detailedLogging` | `false` | Enable verbose logging for debugging |
-| `bppEnabled` | `true` | Enable Batch Pre-Processing change detection |
-| `maxFilesPerRun` | `10` | Limit files processed per workflow execution |
-
-### 8. Emoji Logging Best Practices
-
-Use emojis in logs for better readability in Versori UI:
-
-```typescript
-// Execution status
-log.info('✅ EXECUTION COMPLETED', { jobId, filesProcessed: 5 });
-log.error('❌ EXECUTION FAILED', { jobId, error: 'Connection timeout' });
-log.warn('⚠️ PARTIAL SUCCESS', { jobId, filesProcessed: 3, filesFailed: 2 });
-
-// Processing stages
-log.info('📦 Starting file processing', { fileName: 'inventory.xml' });
-log.info('✅ File processed successfully', { fileName: 'inventory.xml', recordCount: 1000 });
-log.error('❌ File processing failed', { fileName: 'inventory.xml', error: 'Parse error' });
-
-// Configuration
-log.info('⚙️ Configuration loaded', { sftpHost, remotePath, batchSize });
-log.warn('⚠️ Using default configuration', { reason: 'Missing activation variable' });
-
-// State management
-log.info('🔍 Checking file status', { fileName: 'inventory.xml' });
-log.info('⏭️ Skipping duplicate file', { fileName: 'inventory.xml' });
-log.info('📝 Marking file as processed', { fileName: 'inventory.xml' });
-```
-
-**Recommended Emojis:**
-
-| Emoji | Use Case | Example |
-|-------|----------|---------|
-| ✅ | Success | `'✅ File uploaded successfully'` |
-| ❌ | Error | `'❌ Failed to connect to SFTP'` |
-| ⚠️ | Warning | `'⚠️ File already exists, skipping'` |
-| 📦 | Processing | `'📦 Processing batch 1 of 10'` |
-| 🔍 | Discovery | `'🔍 Found 5 files to process'` |
-| ⏭️ | Skipping | `'⏭️ Skipping already processed file'` |
-| 📝 | State change | `'📝 Marking file as processed'` |
-| ⚙️ | Configuration | `'⚙️ Initializing SFTP connection'` |
-
-**Guidelines:**
-
-- Use emojis for high-level status logs (execution start/end, major milestones)
-- Don't overuse - limit to important log entries
-- Be consistent across workflows (same emoji = same meaning)
-- Combine with structured data for filtering: `log.info('✅ Success', { status: 'completed' })`
-
----
-
-## Caveats and gotchas (S3 and SFTP)
-
-Use these safeguards across all scheduled guides to avoid common pitfalls:
-
-- S3 cross-bucket moves: `moveFile(sourceKey, destKey, { sourceBucket })` is required when the source object is not in the configured destination bucket. Copy succeeds cross-bucket, but delete must be signed against the source bucket. The SDK handles this via a temporary presigner when you pass `sourceBucket`.
-- S3 move semantics: There is no native move; it's copy then delete. If delete fails after copy, the destination remains. Treat moves as idempotent; retries may leave the destination already present. Prefer archive paths that are safe to overwrite or add timestamps.
-- S3 metadata on copy: Use `copyFile(source, dest, { metadata })` to replace metadata; S3 "metadata-directive: REPLACE" behavior is applied. If omitted, S3 copies existing metadata.
-- S3 content encodings: For text files use `{ encoding: 'utf8' }`. For binary (Parquet) omit encoding to receive a Buffer.
-- SFTP overwrite: `moveFile`, `copyFile` support an `overwrite` boolean. Set `true` to replace existing files at the destination.
-- SFTP directory creation: Use `createDirectory(path, true)` before uploads if parent folders may not exist, or pass `{ createDirectories: true }` in `uploadFile()` options.
-- SFTP path format: Paths are POSIX-style with forward slashes. Avoid Windows backslashes in remote paths.
-- Disposing SFTP connections: Always `await sftp.dispose()` in a `finally` block to close sockets in scheduled workflows.
-- CSV delimiters: Respect `csvDelimiter` activation variable; defaults to `,`. Mismatches cause mapping errors.
-- Batch API BPP: Enabled by default. For delta feeds, set `meta: { preprocessing: 'skip' }` when creating the job.
-- Mapping imports: When importing mapping JSON in TypeScript, ensure `tsconfig.json` has `"resolveJsonModule": true`.
-- Attributes array vs object: Fluent APIs often expect arrays (e.g., attributes). If mapping to an object, convert to array before sending, or use a custom resolver to emit an array.
-
-Referenced guides with examples implementing these:
-
-- Inventory (S3): `ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md` → Advanced S3 file operations
-- Inventory (SFTP): `ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md` → Advanced SFTP file operations and `dispose()`
-
----
-
-## Additional Resources
-
-- **SDK Documentation**: [fc-connect-sdk README](../../../../readme.md)
-- **Universal Mapping Guide**: [UNIVERSAL-MAPPING.md](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
-- **Decision Tree**: [DECISION-TREE.md](../../../00-START-HERE/decision-tree.md)
-- **Troubleshooting**: [troubleshooting-quick-reference.md](../../../00-START-HERE/troubleshooting-quick-reference.md)
-- **SDK Philosophy**: [SDK-PHILOSOPHY.md](../../../00-START-HERE/sdk-philosophy.md)
-
----
-
-## Contributing
-
-When adding new use cases:
-
-1. Place in appropriate category folder (inventory/, product/, price/)
-2. Follow naming convention: `{source}-{format}-{entity}-to-{api}.md`
-3. Include complete working code
-4. Verify all SDK method signatures
-5. Add entry to this README
-
----
-
-**✅ All use cases verified against SDK ^0.1.27**
-**📅 Last updated**: 2025-10-30
+# Versori Scheduled Workflows - Use Case Guide
+
+**FC Connect SDK** - Production-ready patterns for scheduled workflows on the Versori platform.
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+---
+
+## Overview
+
+This directory contains verified, production-ready use case guides organized by entity type. Each guide includes:
+
+✅ **Complete working code** - Copy-paste ready
+✅ **SDK method verification** - All signatures checked against SDK source
+✅ **Best practices** - Error handling, state management, archiving
+✅ **Configuration examples** - Activation variables, mappings, resolvers
+
+---
+
+## Quick Navigation by Entity Type
+
+### 🔗 Rubix Webhook Patterns ⭐ NEW
+
+**Location**: `rubix-webhooks/`
+
+| Use Case | Description | Complexity | File |
+|----------|-------------|------------|------|
+| Fluent Rubix Webhook Pattern | Receive webhooks from Rubix workflows, validate signature, query entity, do logic | Medium | [template-fluent-rubix-webhook-pattern.md](rubix-webhooks/template-fluent-rubix-webhook-pattern.md) |
+
+**Key Features:**
+- ✅ Complete Rubix workflow configuration guide
+- ✅ Webhook signature validation using FluentClient
+- ✅ Entity extraction from payload
+- ✅ GraphQL queries to fetch entity details
+- ✅ Business logic processing
+- ✅ Structured response handling
+
+### 📦 Inventory Management
+
+**Location**: `inventory/`
+
+| Use Case                   | Source         | Format | API           | Complexity | File                                                                         |
+| -------------------------- | -------------- | ------ | ------------- | ---------- | ---------------------------------------------------------------------------- |
+| S3 → Inventory Batch       | S3             | CSV    | Batch API     | Medium     | [template-ingestion-s3-csv-inventory-batch.md](ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)       |
+| SFTP → Inventory Batch     | SFTP           | CSV    | Batch API     | Medium     | [template-ingestion-sftp-csv-inventory-batch.md](ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)   |
+| Cycle Count Reconciliation | S3             | CSV    | GraphQL       | High       | [cycle-count-reconciliation.md](ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md)     |
+| Multi-Channel Sync         | Fluent GraphQL | -      | External APIs | High       | [multi-channel-inventory-sync.md](ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md) |
+
+### 🏷️ Product Management
+
+**Location**: `ingestion/event-api/`
+
+| Use Case                     | Source | Format     | API       | Complexity | File                                                                                                                        |
+| ---------------------------- | ------ | ---------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
+| SFTP CSV → Product Event     | SFTP   | CSV        | Event API | Medium     | [template-ingestion-sftp-csv-product-event.md](ingestion/event-api/template-ingestion-sftp-csv-product-event.md) ✅   |
+| SFTP JSON → Product Event    | SFTP   | JSON/JSONL | Event API | Medium     | [template-ingestion-sftp-json-product-event.md](ingestion/event-api/template-ingestion-sftp-json-product-event.md) ✅ |
+| S3 CSV → Product Event       | S3     | CSV        | Event API | Medium     | [s3-csv-product-event.md](ingestion/event-api/template-ingestion-s3-csv-product-event.md)                                                      |
+| S3 JSON → Product Event      | S3     | JSON       | Event API | Medium     | [s3-json-product-event.md](ingestion/event-api/template-ingestion-s3-json-product-event.md)                                                    |
+| S3 XML → Product Event       | S3     | XML        | Event API | Medium     | [s3-xml-product-event.md](ingestion/event-api/template-ingestion-s3-xml-product-event.md)                                                      |
+| S3 Parquet → Product Event   | S3     | Parquet    | Event API | Medium     | [s3-parquet-product-event.md](ingestion/event-api/template-ingestion-s3-parquet-product-event.md)                                              |
+| SFTP XML → Product Event     | SFTP   | XML        | Event API | Medium     | [sftp-xml-product-event.md](ingestion/event-api/template-ingestion-sftp-xml-product-event.md)                                                  |
+| SFTP Parquet → Product Event | SFTP   | Parquet    | Event API | Medium     | [sftp-parquet-product-event.md](ingestion/event-api/template-ingestion-sftp-parquet-product-event.md)                                          |
+
+### 🎛️ Control Management ⭐ NEW
+
+**Location**: `ingestion/graphql-mutations/`
+
+| Use Case                   | Source | Format | API               | Complexity  | File                                                                                                                                  |
+| -------------------------- | ------ | ------ | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| S3 CSV → Control GraphQL   | S3     | CSV    | GraphQL Mutations | Medium-High | [template-ingestion-s3-csv-control-graphql.md](ingestion/graphql-mutations/template-ingestion-s3-csv-control-graphql.md) ✅     |
+| SFTP CSV → Control GraphQL | SFTP   | CSV    | GraphQL Mutations | Medium-High | [template-ingestion-sftp-csv-control-graphql.md](ingestion/graphql-mutations/template-ingestion-sftp-csv-control-graphql.md) ✅ |
+
+**Key Features:**
+
+- ✅ **Simplified CSV format** - Single `catalogRef` field (works for both EXCLUSION and QUANTITY_BUFFER)
+- ✅ **3 CSV pattern options** - Pre-built refs, component-based, hybrid
+- ✅ **Bulk GraphQL queries** - 5x faster than individual queries, pagination-aware
+- ✅ **Schema validation** - ControlSchemaValidator ensures spec compliance
+- ✅ **3-level duplicate detection** - File-level, row-level, cross-file tracking
+- ✅ **20+ metrics** - Comprehensive ControlMetricsCollector
+- ✅ **Smart upsert** - Auto-detect create vs update with ControlRefTracker
+- ✅ **Batch mutations** - 12x faster than sequential processing
+
+**SFTP-Specific Enhancements:**
+
+- ✅ Connection pooling with keep-alive
+- ✅ Automatic retry logic with exponential backoff
+- ✅ Network resilience (handles timeouts, disconnects)
+- ✅ Proper connection disposal in finally blocks
+
+### 💰 Price Management
+
+**Location**: `price/`
+
+| Use Case               | Source | Format | API               | Complexity | File                                                           |
+| ---------------------- | ------ | ------ | ----------------- | ---------- | -------------------------------------------------------------- |
+| S3 CSV → Price GraphQL | S3     | CSV    | GraphQL Mutations | Medium     | [s3-csv-price-to-graphql.md](ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md) |
+
+---
+
+## Pattern Matrix
+
+### By Data Source
+
+| Source             | Inventory             | Product                         | Control          | Price            |
+| ------------------ | --------------------- | ------------------------------- | ---------------- | ---------------- |
+| **S3**             | ✅ CSV → Batch        | ✅ CSV/JSON/XML/Parquet → Event | ✅ CSV → GraphQL | ✅ CSV → GraphQL |
+| **SFTP**           | ✅ CSV → Batch        | ✅ CSV/JSON/XML/Parquet → Event | ✅ CSV → GraphQL | -                |
+| **Fluent GraphQL** | ✅ Multi-channel sync | -                               | -                | -                |
+
+### By File Format
+
+| Format         | Inventory   | Product     | Control     | Price | Parser                 |
+| -------------- | ----------- | ----------- | ----------- | ----- | ---------------------- |
+| **CSV**        | ✅ S3, SFTP | ✅ S3, SFTP | ✅ S3, SFTP | ✅ S3 | `CSVParserService`     |
+| **JSON/JSONL** | -           | ✅ S3, SFTP | -           | -     | `JSONParserService`    |
+| **XML**        | -           | ✅ S3, SFTP | -           | -     | `XMLParserService`     |
+| **Parquet**    | -           | ✅ S3, SFTP | -           | -     | `ParquetParserService` |
+
+### By API Pattern
+
+| API                   | Use Cases                           | When to Use                                                 |
+| --------------------- | ----------------------------------- | ----------------------------------------------------------- |
+| **Batch API**         | Inventory sync (S3, SFTP)           | High-volume inventory updates with BPP change detection     |
+| **Event API**         | Product sync (all sources)          | Product/location/customer upserts needing workflow triggers |
+| **GraphQL Mutations** | Control, price updates, cycle count | Control groups, rules, prices, single-entity operations     |
+| **GraphQL Queries**   | Multi-channel sync, control lookup  | Extraction, ATP calculations, bulk control existence checks |
+
+---
+
+## Common Patterns Across All Use Cases
+
+### 1. Universal Client Creation
+
+All workflows use the same client factory:
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Auto-detects Versori context and configures OAuth2 from connections
+const client = await createClient(ctx);
+```
+
+### 2. Data Source Configuration
+
+**S3DataSource:**
+
+```typescript
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+const s3 = new S3DataSource(
+  {
+    type: 'S3_CSV', // or S3_JSON, S3_XML, S3_PARQUET
+    connectionId: 'unique-id',
+    name: 'Human-readable name',
+    s3Config: {
+      bucket: 'bucket-name',
+      region: 'us-east-1',
+      accessKeyId: 'xxx',
+      secretAccessKey: 'yyy',
+    },
+  },
+  logger
+);
+```
+
+**SftpDataSource:**
+
+```typescript
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+const sftp = new SftpDataSource(
+  {
+    type: 'SFTP_CSV', // or SFTP_JSON, SFTP_JSONL, SFTP_XML, SFTP_PARQUET
+    connectionId: 'unique-id',
+    name: 'Human-readable name',
+    settings: {
+      host: 'sftp.example.com',
+      port: 22,
+      username: 'user',
+      password: 'pass', // OR privateKey
+      remotePath: '/incoming',
+      filePattern: '*.csv',
+    },
+  },
+  logger
+);
+```
+
+### 3. Universal Mapping Pattern
+
+One mapping engine for all formats (CSV, JSON, XML, Parquet):
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(
+  {
+    fields: {
+      locationRef: { source: 'location', required: true, resolver: 'sdk.trim' },
+      skuRef: { source: 'sku', required: true, resolver: 'sdk.trim' },
+      qty: { source: 'quantity', required: true, resolver: 'sdk.parseInt' },
+      type: { value: 'ADJUSTMENT', required: true },
+      status: { source: 'status', resolver: 'sdk.uppercase', defaultValue: 'ACTIVE' },
+    },
+  },
+  {
+    customResolvers: {
+      'custom.splitByPipe': (value, sourceData, config, helpers) => {
+        return helpers.ensureArray(value?.split('|') || []);
+      },
+    },
+  }
+);
+
+// Transform data
+const result = await mapper.map(sourceData);
+// Returns: { success: boolean, data: any, errors?: string[] }
+```
+
+### 4. State Management (Duplicate Prevention)
+
+```typescript
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+const fileTracker = new VersoriFileTracker(ctx.openKv(':project:'), 'workflow-prefix');
+
+// Check if already processed
+const alreadyProcessed = await fileTracker.wasFileProcessed(fileName);
+if (alreadyProcessed) {
+  console.log('Skipping duplicate file');
+  continue;
+}
+
+// Mark as processed after success
+await fileTracker.markFileProcessed(fileName, { recordCount: 100 });
+```
+
+### 5. File Operations (All Data Sources)
+
+**List Files:**
+
+```typescript
+const files = await dataSource.listFiles({
+  remotePath: '/path', // SFTP only
+  prefix: 'prefix/', // S3 only
+  filePattern: '*.csv', // SFTP only
+});
+```
+
+**Download File:**
+
+```typescript
+const content = await dataSource.downloadFile(filePath, {
+  encoding: 'utf8', // For text files
+});
+```
+
+**Archive/Move File:**
+
+```typescript
+await dataSource.moveFile(
+  '/incoming/file.csv',
+  '/archive/file.csv',
+  true // overwrite if exists
+);
+```
+
+**Copy File:**
+
+```typescript
+await dataSource.copyFile(
+  '/incoming/file.csv',
+  '/backup/file.csv',
+  false // don't overwrite
+);
+```
+
+**Delete File:**
+
+```typescript
+await dataSource.deleteFile('/temp/file.csv');
+```
+
+---
+
+## API Decision Guide
+
+### When to Use Batch API (Inventory Only)
+
+✅ **Use Batch API for:**
+
+- High-volume inventory updates (1000s+ records)
+- Full inventory snapshots
+- Daily/hourly inventory sync
+- Scenarios needing BPP (Batch Pre-Processing) change detection
+
+❌ **Don't Use Batch API for:**
+
+- Products, Locations, Customers (use Event API)
+- Low-volume updates (<100 records)
+- Real-time updates
+
+**Example:**
+
+```typescript
+const job = await client.createJob({
+  name: 'Daily Inventory Sync',
+  retailerId: 'my-retailer',
+  // BPP enabled by default
+});
+
+await client.sendBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  source: 'S3_CSV',
+  event: 'INVENTORY_SYNC',
+  entities: inventoryRecords,
+});
+```
+
+### When to Use Event API
+
+✅ **Use Event API for:**
+
+- **Products**: Catalog sync, variant updates
+- **Locations**: Store/warehouse setup
+- **Customers**: Registration, profile updates
+- **Orders**: Single order creation
+- **Custom Entities**: Any entity needing workflow triggers
+
+**Example:**
+
+```typescript
+await client.sendEvent(
+  {
+    name: 'UPSERT_PRODUCT',
+    entityType: 'PRODUCT',
+    entitySubtype: 'VARIANT',
+    entityRef: catalogueRef,
+    rootEntityType: 'PRODUCT_CATALOGUE',
+    rootEntityRef: catalogueRef,
+    attributes: productData,
+  },
+  'async' // or 'sync'
+);
+```
+
+### When to Use GraphQL Mutations
+
+✅ **Use GraphQL for:**
+
+- Price updates (no Event API support)
+- Single-entity operations
+- Complex queries with relationships
+- Testing/debugging
+
+**Example:**
+
+```typescript
+await client.graphql({
+  query: `
+    mutation UpdatePrice($input: UpdatePriceInput!) {
+      updatePrice(input: $input) {
+        id
+        ref
+      }
+    }
+  `,
+  variables: { input: priceData },
+});
+```
+
+---
+
+## Troubleshooting Common Issues
+
+### Issue: "Missing required field: connectionId"
+
+**Solution**: All data sources now require `connectionId` and `name` fields:
+
+```typescript
+new S3DataSource({
+  type: 'S3_CSV',
+  connectionId: 'unique-id', // ← Required
+  name: 'Friendly Name', // ← Required
+  s3Config: { ... }
+}, logger);
+```
+
+### Issue: "sendBatch requires action, entityType, source, event"
+
+**Solution**: Batch API payloads must include all required fields:
+
+```typescript
+await client.sendBatch(jobId, {
+  action: 'UPSERT', // ← Required
+  entityType: 'INVENTORY', // ← Required
+  source: 'S3_CSV', // ← Required
+  event: 'INVENTORY_SYNC', // ← Required
+  entities: records,
+});
+```
+
+### Issue: "UniversalMapper: cannot use logger option"
+
+**Solution**: UniversalMapper constructor changed - no longer accepts `{ logger, fluentClient }`:
+
+```typescript
+// ❌ Old (incorrect):
+new UniversalMapper(config, { logger, fluentClient });
+
+// ✅ New (correct):
+new UniversalMapper(config, { customResolvers });
+```
+
+### Issue: "wasFileProcessed is not a function"
+
+**Solution**: Use correct method name:
+
+```typescript
+// ❌ Old:
+await fileTracker.isFileProcessed(fileName);
+
+// ✅ Correct:
+await fileTracker.wasFileProcessed(fileName);
+```
+
+---
+
+## Best Practices
+
+### 1. Always Use State Management
+
+Prevent duplicate processing across workflow runs:
+
+```typescript
+const fileTracker = new VersoriFileTracker(ctx.openKv(':project:'), 'unique-prefix');
+```
+
+### 2. Archive Files After Processing
+
+```typescript
+// file.name contains just filename, file.path contains full path
+await dataSource.moveFile(file.path, `${archivePath}/${file.name}`);
+```
+
+### 3. Use BPP for Full Snapshots
+
+For full inventory snapshots, let BPP filter unchanged records:
+
+```typescript
+const job = await client.createJob({
+  name: 'Daily Full Inventory',
+  retailerId: 'my-retailer',
+  // BPP enabled by default
+});
+```
+
+### 4. Skip BPP for Delta Feeds
+
+For pre-filtered delta feeds:
+
+```typescript
+const job = await client.createJob({
+  name: 'Hourly Deltas',
+  retailerId: 'my-retailer',
+  meta: {
+    preprocessing: 'skip', // Skip BPP
+  },
+});
+```
+
+### 5. Use Async Mode for Events
+
+For scalability and throughput:
+
+```typescript
+await client.sendEvent(event, 'async'); // Recommended
+```
+
+### 6. MemoryInterpreter Pattern (Local Testing)
+
+When developing workflows locally, use MemoryInterpreter for testing:
+
+```typescript
+// index.ts - Entry point for local development/testing
+import { MemoryInterpreter } from '@versori/run';
+import { dailyInventorySync } from './src/workflows/scheduled/daily-inventory-sync';
+import { adhocInventorySync } from './src/workflows/webhook/adhoc-inventory-sync';
+
+async function main(): Promise<void> {
+  const mi = await MemoryInterpreter.newInstance();
+  mi.register(dailyInventorySync);
+  mi.register(adhocInventorySync);
+  await mi.start();
+}
+
+main().then().catch((err) => console.error('Failed to run main()', err));
+```
+
+**Important:** MemoryInterpreter is for local development only - Versori platform handles workflow registration automatically when deployed.
+
+### 7. Optional Feature Toggles
+
+Use activation variables to enable/disable optional features:
+
+```typescript
+// Optional: Disable file tracking for testing (enabled by default)
+const enableFileTracking = activation.getVariable('enableFileTracking') !== 'false';
+
+if (enableFileTracking) {
+  const alreadyProcessed = await fileTracker.wasFileProcessed(fileName);
+  if (alreadyProcessed) {
+    log.info('Skipping duplicate file');
+    continue;
+  }
+}
+
+// Optional: Enable detailed logging for debugging (disabled by default)
+const detailedLogging = activation.getVariable('detailedLogging') === 'true';
+
+if (detailedLogging) {
+  log.info('Detailed processing metrics', {
+    fileSize: file.size,
+    parseTime: parseEndTime - parseStartTime,
+    mappingTime: mapEndTime - mapStartTime,
+    uploadTime: uploadEndTime - uploadStartTime,
+  });
+}
+
+// Optional: Control BPP behavior
+const bppEnabled = activation.getVariable('bppEnabled') !== 'false';
+
+const job = await client.createJob({
+  name: 'Inventory Sync',
+  retailerId: 'my-retailer',
+  meta: bppEnabled ? {} : { preprocessing: 'skip' },
+});
+```
+
+**Common Feature Toggles:**
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `enableFileTracking` | `true` | Prevent duplicate file processing |
+| `detailedLogging` | `false` | Enable verbose logging for debugging |
+| `bppEnabled` | `true` | Enable Batch Pre-Processing change detection |
+| `maxFilesPerRun` | `10` | Limit files processed per workflow execution |
+
+### 8. Emoji Logging Best Practices
+
+Use emojis in logs for better readability in Versori UI:
+
+```typescript
+// Execution status
+log.info('✅ EXECUTION COMPLETED', { jobId, filesProcessed: 5 });
+log.error('❌ EXECUTION FAILED', { jobId, error: 'Connection timeout' });
+log.warn('⚠️ PARTIAL SUCCESS', { jobId, filesProcessed: 3, filesFailed: 2 });
+
+// Processing stages
+log.info('📦 Starting file processing', { fileName: 'inventory.xml' });
+log.info('✅ File processed successfully', { fileName: 'inventory.xml', recordCount: 1000 });
+log.error('❌ File processing failed', { fileName: 'inventory.xml', error: 'Parse error' });
+
+// Configuration
+log.info('⚙️ Configuration loaded', { sftpHost, remotePath, batchSize });
+log.warn('⚠️ Using default configuration', { reason: 'Missing activation variable' });
+
+// State management
+log.info('🔍 Checking file status', { fileName: 'inventory.xml' });
+log.info('⏭️ Skipping duplicate file', { fileName: 'inventory.xml' });
+log.info('📝 Marking file as processed', { fileName: 'inventory.xml' });
+```
+
+**Recommended Emojis:**
+
+| Emoji | Use Case | Example |
+|-------|----------|---------|
+| ✅ | Success | `'✅ File uploaded successfully'` |
+| ❌ | Error | `'❌ Failed to connect to SFTP'` |
+| ⚠️ | Warning | `'⚠️ File already exists, skipping'` |
+| 📦 | Processing | `'📦 Processing batch 1 of 10'` |
+| 🔍 | Discovery | `'🔍 Found 5 files to process'` |
+| ⏭️ | Skipping | `'⏭️ Skipping already processed file'` |
+| 📝 | State change | `'📝 Marking file as processed'` |
+| ⚙️ | Configuration | `'⚙️ Initializing SFTP connection'` |
+
+**Guidelines:**
+
+- Use emojis for high-level status logs (execution start/end, major milestones)
+- Don't overuse - limit to important log entries
+- Be consistent across workflows (same emoji = same meaning)
+- Combine with structured data for filtering: `log.info('✅ Success', { status: 'completed' })`
+
+---
+
+## Caveats and gotchas (S3 and SFTP)
+
+Use these safeguards across all scheduled guides to avoid common pitfalls:
+
+- S3 cross-bucket moves: `moveFile(sourceKey, destKey, { sourceBucket })` is required when the source object is not in the configured destination bucket. Copy succeeds cross-bucket, but delete must be signed against the source bucket. The SDK handles this via a temporary presigner when you pass `sourceBucket`.
+- S3 move semantics: There is no native move; it's copy then delete. If delete fails after copy, the destination remains. Treat moves as idempotent; retries may leave the destination already present. Prefer archive paths that are safe to overwrite or add timestamps.
+- S3 metadata on copy: Use `copyFile(source, dest, { metadata })` to replace metadata; S3 "metadata-directive: REPLACE" behavior is applied. If omitted, S3 copies existing metadata.
+- S3 content encodings: For text files use `{ encoding: 'utf8' }`. For binary (Parquet) omit encoding to receive a Buffer.
+- SFTP overwrite: `moveFile`, `copyFile` support an `overwrite` boolean. Set `true` to replace existing files at the destination.
+- SFTP directory creation: Use `createDirectory(path, true)` before uploads if parent folders may not exist, or pass `{ createDirectories: true }` in `uploadFile()` options.
+- SFTP path format: Paths are POSIX-style with forward slashes. Avoid Windows backslashes in remote paths.
+- Disposing SFTP connections: Always `await sftp.dispose()` in a `finally` block to close sockets in scheduled workflows.
+- CSV delimiters: Respect `csvDelimiter` activation variable; defaults to `,`. Mismatches cause mapping errors.
+- Batch API BPP: Enabled by default. For delta feeds, set `meta: { preprocessing: 'skip' }` when creating the job.
+- Mapping imports: When importing mapping JSON in TypeScript, ensure `tsconfig.json` has `"resolveJsonModule": true`.
+- Attributes array vs object: Fluent APIs often expect arrays (e.g., attributes). If mapping to an object, convert to array before sending, or use a custom resolver to emit an array.
+
+Referenced guides with examples implementing these:
+
+- Inventory (S3): `ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md` → Advanced S3 file operations
+- Inventory (SFTP): `ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md` → Advanced SFTP file operations and `dispose()`
+
+---
+
+## Additional Resources
+
+- **SDK Documentation**: [fc-connect-sdk README](../../../../readme.md)
+- **Universal Mapping Guide**: [UNIVERSAL-MAPPING.md](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
+- **Decision Tree**: [DECISION-TREE.md](../../../00-START-HERE/decision-tree.md)
+- **Troubleshooting**: [troubleshooting-quick-reference.md](../../../00-START-HERE/troubleshooting-quick-reference.md)
+- **SDK Philosophy**: [SDK-PHILOSOPHY.md](../../../00-START-HERE/sdk-philosophy.md)
+
+---
+
+## Contributing
+
+When adding new use cases:
+
+1. Place in appropriate category folder (inventory/, product/, price/)
+2. Follow naming convention: `{source}-{format}-{entity}-to-{api}.md`
+3. Include complete working code
+4. Verify all SDK method signatures
+5. Add entry to this README
+
+---
+
+**✅ All use cases verified against SDK ^0.1.27**
+**📅 Last updated**: 2025-10-30