@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/readme.md

@@ -1,957 +1,957 @@
-# FC Connect SDK - Template Guides
-
-**Complete catalog of production-ready templates** for building Fluent Commerce integrations.
-
-Last Updated: 2025-01-27
-
----
-
-## 🎯 Quick Decision Tree
-
-**Not sure which template to use?** Follow this flowchart:
-
-```
-START: What do you want to build?
-│
-├─ I need a PATTERN (concept/technique) ────────────────────────┐
-│                                                                 │
-├─ I'm building for VERSORI PLATFORM ────────────────────────────┤
-│                                                                 │
-└─ I'm building STANDALONE (Node.js/Deno) ───────────────────────┤
-                                                                  │
-                                                                  ▼
-```
-
-### 1️⃣ What Runtime Are You Using?
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  Where will your integration run?                            │
-└──────────────────────────────────────────────────────────────┘
-                          │
-        ┌─────────────────┼─────────────────┐
-        │                 │                 │
-        ▼                 ▼                 ▼
-   VERSORI           STANDALONE         JUST A
-  PLATFORM         NODE.JS/DENO        PATTERN
-```
-
----
-
-## 🅰️ Versori Platform Templates
-
-### Webhook-Triggered Workflows (7)
-
-#### XML Order Ingestion
-**File**: [`versori/webhooks/template-webhook-xml-order-ingestion.md`](versori/webhooks/template-webhook-xml-order-ingestion.md)
-
-**Description**: Build a Versori HTTP webhook that receives SFCC/Radial XML orders and creates orders in Fluent Commerce using GraphQL mutations. Includes nodes processing for nested XML extraction, custom resolvers with async API calls, and complete audit trail.
-
-**Complexity**: Medium | **Lines**: ~500
-
-**SDK Methods**:
-- `createClient(ctx)` - Versori context auto-detected
-- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - XML → GraphQL mapping
-- `mapper.mapWithNodes(data)` - Process nodes config (resolvers from constructor)
-- `mapWithNodes()` returns query automatically (no need for buildMutation())
-- `client.graphql({ query, variables })` - Execute mutation
-
-**Key Patterns**:
-- Versori connection setup with auto-authentication
-- Nodes configuration (extracting nested/escaped XML)
-- Custom resolvers with context and async API calls
-- GraphQL mutation generation and execution
-- Error handling with structured responses
-
-**Use When**: Receiving XML webhooks (SFCC, Radial, custom), need to extract nested XML documents, transforming XML to Fluent orders/entities
-
----
-
-#### Generic XML Order
-**File**: [`versori/webhooks/template-webhook-generic-xml-order.md`](versori/webhooks/template-webhook-generic-xml-order.md)
-
-**Description**: Generic, vendor-agnostic XML order ingestion via Versori webhook using `GraphQLMutationMapper`. Includes optional nodes extraction, custom resolvers, audit trail, and robust error handling.
-
-**Complexity**: Medium | **Lines**: ~450
-
-**Use When**: Any XML order format (not SFCC-specific)
-
----
-
-#### ASN/Purchase Order
-**File**: [`versori/webhooks/template-webhook-asn-purchase-order.md`](versori/webhooks/template-webhook-asn-purchase-order.md)
-
-**Description**: Advanced Shipping Notice (ASN) webhook processing with purchase order matching, shipment tracking, and inventory receiving workflows.
-
-**Complexity**: Medium | **Lines**: ~600
-
-**Use When**: Processing Advanced Shipping Notices
-
----
-
-#### Dropship Routing
-**File**: [`versori/webhooks/template-webhook-dropship-routing.md`](versori/webhooks/template-webhook-dropship-routing.md)
-
-**Description**: Supplier selection logic, PO submission, fallback to warehouse, and order status updates for dropship fulfillment.
-
-**Complexity**: High | **Lines**: ~700
-
-**Use When**: Routing orders to suppliers with fallback
-
----
-
-#### Flash Sale Inventory Reserve
-**File**: [`versori/webhooks/template-webhook-flash-sale-reserve.md`](versori/webhooks/template-webhook-flash-sale-reserve.md)
-
-**Description**: Time-bound inventory reservations, distributed locking, real-time decrement pattern, and periodic reconciliation for flash sales.
-
-**Complexity**: High | **Lines**: ~700
-
-**SDK Methods**:
-- `createClient(ctx)`
-- `VersoriKVAdapter` - Distributed locking
-- `StateService` - Reservation tracking
-- Custom resolvers (time-bound checks, quantity validation)
-
-**Key Patterns**:
-- Time-bound reservations (expiry logic)
-- Distributed locking (prevent overselling)
-- Real-time inventory decrement
-- Periodic reconciliation workflow
-
-**Use When**: Managing high-velocity flash sale inventory
-
----
-
-#### RMA/Returns Processing (Comprehensive)
-**File**: [`versori/webhooks/template-webhook-rma-returns-comprehensive.md`](versori/webhooks/template-webhook-rma-returns-comprehensive.md)
-
-**Description**: Complete RMA lifecycle: return initiation → RMA creation → shipping label → quality inspection → refund/exchange → inventory restock. Includes 5 separate webhooks for full workflow.
-
-**Complexity**: Medium-High | **Lines**: ~1700
-
-**Webhooks**:
-1. `createRmaFromReturn` - Creates RMA from return request
-2. `trackReturnShipment` - Tracks return shipment
-3. `qualityInspection` - Processes warehouse inspection
-4. `processRefundOrExchange` - Handles refund/exchange
-5. `getRmaStatus` - Query endpoint for RMA status
-
-**Use When**: Full return/exchange workflow
-
----
-
-#### Payment Gateway Integration (Adyen)
-**File**: [`versori/webhooks/template-webhook-payment-gateway-integration.md`](versori/webhooks/template-webhook-payment-gateway-integration.md)
-
-**Description**: Complete payment gateway integration with 4 webhooks: Capture, Refund, Auth Cancel, and ReAuth. Modular architecture allows easy swapping of payment providers (Adyen → Stripe).
-
-**Complexity**: Medium-High | **Lines**: ~1500
-
-**SDK Methods**:
-- `createClient(ctx)` - Versori context auto-detected
-- `client.setRetailerId()` - Required for Event API
-- `client.sendEvent()` - Send events to Fluent Commerce Event API
-- `VersoriKVAdapter(ctx.openKv(':project:'))` - Idempotency tracking
-
-**Key Patterns**:
-- Payment provider abstraction (easy to swap Adyen → Stripe)
-- Trigger source validation (ORDER_FULFILLMENT vs PAYMENT_ENTITY)
-- Shared services (webhook validation, event sending, idempotency)
-- Event mapping (payment provider → Fluent event format)
-
-**Use When**: Integrating payment gateways (Adyen, Stripe, PayPal)
-
----
-
-### Scheduled Workflows (6)
-
-#### CSV Inventory Sync (S3)
-**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md`](versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)
-
-**Description**: Build a Versori scheduled workflow (cron-based) that reads inventory CSV files from S3 and updates Fluent Commerce inventory via Batch API. Includes VersoriKV state management for duplicate prevention and file archival.
-
-**Complexity**: Medium | **Lines**: ~600
-
-**SDK Methods**:
-- `createClient(ctx)` - Versori client
-- `S3DataSource(config, logger)` - S3 operations
-- `UniversalMapper(mappingConfig)` - Field transformations
-- `mapper.map(record)` - Transform record
-- `client.createJob({ name, retailerId })` - Create Batch job
-- `client.sendBatch(jobId, { entities })` - Send inventory batch
-- `VersoriKVAdapter(openKv())` - State management
-- `VersoriFileTracker` - File tracking
-
-**Key Patterns**:
-- Versori scheduled triggers (cron expressions)
-- S3 file operations (list, download, archive)
-- UniversalMapper with SDK resolvers
-- Batch API processing with chunking
-- VersoriKV state management (duplicate prevention)
-- File archival after processing
-
-**Use When**: Scheduled inventory sync (daily, hourly), reading CSV from S3, need duplicate prevention
-
----
-
-#### SFTP CSV Ingestion
-**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md`](versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
-
-**Description**: Scheduled/manual ingestion from SFTP CSV with `CSVParserService` and `UniversalMapper`, duplicate prevention with `VersoriFileTracker`, and robust retry/backoff for downloads and batch sends.
-
-**Complexity**: Medium | **Lines**: ~700
-
-**SDK Methods**:
-- `createClient(ctx)`
-- `SftpDataSource.listFiles`, `downloadFile`, `moveFile`
-- `CSVParserService.parse`
-- `UniversalMapper.map`
-- `VersoriFileTracker`, `VersoriKVAdapter`, `StateService`
-- `client.createJob`, `client.sendBatch`
-
-**Key Patterns**:
-- SFTP connection and file operations
-- CSV parsing with validation
-- File tracking and duplicate prevention
-- Retry logic with exponential backoff
-- File archival (processed/error folders)
-
-**Use When**: Scheduled SFTP polling for CSV files
-
----
-
-#### Cycle Count Reconciliation
-**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md`](versori/workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md)
-
-**Description**: Scheduled cycle count import with variance detection, adjustment workflows, and reporting.
-
-**Complexity**: Medium | **Lines**: ~650
-
-**Use When**: Scheduled cycle count imports with variance handling
-
----
-
-#### Multi-Channel Inventory Sync
-**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md`](versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md)
-
-**Description**: ATP computation, channel-specific allocation rules, delta sync optimization, and rate-limit handling for multi-channel inventory distribution.
-
-**Complexity**: High | **Lines**: ~750
-
-**SDK Methods**:
-- `createClient(ctx)`
-- `client.graphql` - Query inventory
-- `UniversalMapper` - Transform for channels
-- Channel-specific custom resolvers
-- Rate limiting logic
-
-**Key Patterns**:
-- ATP (Available-To-Promise) calculation
-- Channel allocation rules
-- Delta sync (only changed inventory)
-- Rate limiting per channel
-- Multi-channel distribution
-
-**Use When**: Distributing inventory across multiple sales channels
-
----
-
-#### Event API Templates
-**File**: [`versori/workflows/ingestion/event-api/`](versori/workflows/ingestion/event-api/)
-
-**Description**: Product, location, and control entity ingestion via Event API with GraphQL mutations. Supports CSV, JSON, XML, and Parquet formats from S3 and SFTP sources.
-
-**Available Templates**:
-- S3 CSV Product Event → [`template-ingestion-s3-csv-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md)
-- SFTP CSV Product Event → [`template-ingestion-sftp-csv-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md)
-- S3 JSON Product Event → [`template-ingestion-s3-json-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-json-product-event.md)
-- SFTP JSON Product Event → [`template-ingestion-sftp-json-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-json-product-event.md)
-- S3 XML Product Event → [`template-ingestion-s3-xml-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-xml-product-event.md)
-- SFTP XML Product Event → [`template-ingestion-sftp-xml-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-xml-product-event.md)
-- S3 Parquet Product Event → [`template-ingestion-s3-parquet-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-parquet-product-event.md)
-- SFTP Parquet Product Event → [`template-ingestion-sftp-parquet-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-parquet-product-event.md)
-
-**Complexity**: Medium | **Lines**: ~550-700
-
-**Use When**: Ingesting products, locations, or control entities via Event API
-
----
-
-#### GraphQL Mutation Templates
-**File**: [`versori/workflows/ingestion/graphql-mutations/`](versori/workflows/ingestion/graphql-mutations/)
-
-**Description**: Direct GraphQL mutation templates for creating/updating locations, prices, and control entities.
-
-**Available Templates**:
-- S3 CSV Location GraphQL → [`template-ingestion-s3-csv-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-location-graphql.md)
-- SFTP CSV Location GraphQL → [`template-ingestion-sftp-csv-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-csv-location-graphql.md)
-- S3 JSON Location GraphQL → [`template-ingestion-s3-json-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-json-location-graphql.md)
-- SFTP JSON Location GraphQL → [`template-ingestion-sftp-json-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-json-location-graphql.md)
-- S3 XML Location GraphQL → [`template-ingestion-s3-xml-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-xml-location-graphql.md)
-- S3 CSV Price GraphQL → [`template-ingestion-s3-csv-price-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md)
-- S3 CSV Control GraphQL → [`template-ingestion-s3-csv-control-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-control-graphql.md)
-- SFTP CSV Control GraphQL → [`template-ingestion-sftp-csv-control-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-csv-control-graphql.md)
-
-**Complexity**: Medium | **Lines**: ~600-800
-
-**Use When**: Direct GraphQL mutations for entities not supported by Event API
-
----
-
-### Versori Patterns (3)
-
-#### KV State Management
-**File**: [`versori/patterns/kv-state-management.md`](versori/patterns/kv-state-management.md)
-
-**Description**: Comprehensive guide on using Versori KV storage for state management, duplicate prevention, checkpoints, and file tracking. Includes 6 complete patterns from simple file tracking to advanced indexed tracking.
-
-**Complexity**: Low-Medium | **Lines**: ~400
-
-**SDK Methods**:
-- `VersoriKVAdapter(openKv())` - Wrap Versori KV
-- `VersoriFileTracker(kvAdapter)` - Track files
-- `StateService(kvAdapter)` - High-level state operations
-- `stateService.isFileProcessed(key)` - Check if processed
-- `stateService.markFileProcessed(key, metadata)` - Mark complete
-- `stateService.saveCheckpoint(key, data)` - Save checkpoint
-- `stateService.getCheckpoint(key)` - Restore checkpoint
-
-**Key Patterns**:
-- Simple file duplicate prevention
-- Distributed locking (prevent concurrent workflows)
-- Checkpoint & resume (long-running workflows)
-- Daily job management (reuse jobs)
-- Error state management (retry logic)
-- Advanced indexed tracking (list files)
-
-**Use When**: Preventing duplicate file processing, need checkpoint/resume capabilities, distributed workflow coordination
-
----
-
-#### XML Response Patterns
-**File**: [`versori/patterns/xml-response-patterns.md`](versori/patterns/xml-response-patterns.md)
-
-**Description**: CRITICAL guide on returning non-JSON content (XML, HTML, CSV) from Versori webhooks using custom Response objects.
-
-**Complexity**: Low-Medium | **Lines**: ~300
-
-**SDK Methods**:
-- `webhook('name', { response: { mode, onSuccess, onError } })` - Custom handlers
-- `XMLBuilder(options)` - Build XML responses
-- `builder.build(data)` - Generate XML string
-- `new Response(body, { status, headers })` - Custom response objects
-
-**Key Patterns**:
-- Why custom Response objects are needed (JSON encoding problem)
-- onSuccess handler pattern (return Response)
-- onError handler pattern (error responses)
-- Content-Type headers (application/xml, text/html, text/csv)
-
-**Use When**: Returning XML responses (SOAP, RSS, custom), HTML status pages, CSV downloads, CRITICAL for SFCC order detail responses
-
----
-
-#### Dual Workflow Connector
-**File**: [`versori/patterns/dual-workflow-connector.md`](versori/patterns/dual-workflow-connector.md)
-
-**Description**: Build a complete Versori connector with multiple workflows (ingestion + extraction), shared resolvers, proper index.ts structure, and package.json configuration.
-
-**Complexity**: Medium | **Lines**: ~500
-
-**Key Patterns**:
-- Multi-workflow index structure (clean exports)
-- Shared resolvers library (domain-organized)
-- Bidirectional data flow (ingestion vs extraction)
-- Package.json configuration (Versori-specific)
-- Testing multi-workflow connectors
-
-**Use When**: Building complete bidirectional integration, multiple workflows sharing code, production Versori connector
-
----
-
-### Business Use Case Examples (4)
-
-#### GraphQL → Parquet Extraction
-**File**: [`versori/business-examples/graphql-parquet-extraction.md`](versori/business-examples/graphql-parquet-extraction.md)
-
-**Description**: Scheduled/manual Versori workflow that extracts via GraphQL with auto-pagination, transforms with `UniversalMapper`, partitions by date/entity/size, and uploads Parquet parts to S3 with incremental KV state.
-
-**Complexity**: Medium | **Lines**: ~600
-
-**SDK Methods**:
-- `createClient(ctx)` with Versori connection
-- `client.graphql({ pagination })`
-- `UniversalMapper`
-- `VersoriKVAdapter`, `StateService`
-- `S3DataSource.writeParquetContent`, `S3DataSource.uploadFile`
-
-**Key Patterns**:
-- Auto-pagination extraction
-- Data transformation with UniversalMapper
-- Parquet file generation
-- Partitioning strategies (date, entity, size)
-- Incremental state tracking
-
-**Use When**: Extracting data from Fluent to data warehouse
-
----
-
-#### Dropship Order Routing
-**File**: [`versori/business-examples/dropship-order-routing.md`](versori/business-examples/dropship-order-routing.md)
-
-**Description**: Intelligent supplier selection with fallback logic and complete order orchestration workflow.
-
-**Complexity**: High | **Lines**: ~700
-
-**Use When**: Complex dropship routing with fallback logic
-
----
-
-#### Inter-Location Transfers
-**File**: [`versori/business-examples/inter-location-transfers.md`](versori/business-examples/inter-location-transfers.md)
-
-**Description**: Transfer order creation, fulfillment workflow, and receiving processes for inter-location inventory movement.
-
-**Complexity**: Medium-High | **Lines**: ~650
-
-**Use When**: Moving inventory between locations
-
----
-
-#### Pre-Order Allocation
-**File**: [`versori/business-examples/pre-order-allocation.md`](versori/business-examples/pre-order-allocation.md)
-
-**Description**: Pre-order reservation system, allocation rules engine, and fulfillment on inventory availability.
-
-**Complexity**: High | **Lines**: ~750
-
-**SDK Methods**:
-- `createClient(ctx)`
-- `VersoriKVAdapter` - Reservation tracking
-- Allocation rules engine
-- Fulfillment triggers
-
-**Use When**: Managing pre-orders with allocation logic
-
----
-
-## 🅱️ Standalone Node.js / Deno Templates
-
-### Ingestion (External → Fluent)
-
-#### S3 CSV → Batch API
-**File**: [`standalone/s3-csv-batch-api.md`](standalone/s3-csv-batch-api.md)
-
-**Description**: Read CSV inventory files from S3, transform with `UniversalMapper`, and update Fluent via Batch API with chunking and archival.
-
-**Complexity**: Medium | **Lines**: ~450-500
-
-**SDK Methods**:
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })`
-- `S3DataSource`, `CSVParserService`, `UniversalMapper`
-- `client.createJob`, `client.sendBatch`
-
-**Use When**: Simple S3 CSV ingestion with field mapping
-
----
-
-#### SFTP XML → GraphQL Mutation
-**File**: [`standalone/sftp-xml-graphql.md`](standalone/sftp-xml-graphql.md)
-
-**Description**: Standalone Node.js script that reads XML order files from SFTP and creates orders in Fluent Commerce using GraphQL mutations. Includes SFTP connection, XML parsing, and file archival.
-
-**Complexity**: Medium | **Lines**: ~600
-
-**SDK Methods**:
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2
-- `SftpDataSource(config, logger)` - SFTP operations
-- `XMLParserService` - XML parsing
-- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - XML → GraphQL
-- `mapper.mapWithNodes(xmlData)` - Transform with custom resolvers (from constructor)
-- `mapper.map(xmlData)` - Transform without custom resolvers (built-in SDK resolvers only)
-- `client.graphql({ query, variables })` - Execute mutation
-
-**Key Patterns**:
-- SFTP connection & file operations
-- XML parsing & validation
-- GraphQL mutation mapping
-- Custom resolvers for complex logic
-- File management (archive/error folders)
-
-**Deployment**: Local, Docker, Cron/Systemd
-
-**Use When**: Polling SFTP for XML orders
-
----
-
-#### Webhook Payload Processing
-**File**: [`standalone/webhook-payload-processing.md`](standalone/webhook-payload-processing.md)
-
-**Description**: Process stored webhook payloads offline with signature validation, payload parsing, and file-based queue.
-
-**Complexity**: Low-Medium | **Lines**: ~250
-
-**Use When**: Processing stored webhook payloads offline
-
----
-
-#### ASN Inbound Processing
-**File**: [`standalone/asn-inbound-processing.md`](standalone/asn-inbound-processing.md)
-
-**Description**: Process Advanced Shipping Notice (ASN) files with PO matching and inventory updates.
-
-**Complexity**: Medium | **Lines**: ~500
-
-**Use When**: Processing inbound shipment notices
-
----
-
-### Extraction (Fluent → External)
-
-#### GraphQL Query → Parquet Export
-**File**: [`standalone/graphql-query-export.md`](standalone/graphql-query-export.md)
-
-**Description**: Standalone Node.js script that extracts inventory/orders from Fluent Commerce via GraphQL queries and exports to S3 as Parquet files. Includes auto-pagination and incremental extraction.
-
-**Complexity**: Medium | **Lines**: ~500
-
-**SDK Methods**:
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2
-- `client.graphql({ query, variables })` - Execute GraphQL query
-- `detectPaginationVariables(query)` - Auto-detect pagination
-- `hasMorePages(response)` - Check for next page
-- `UniversalMapper(extractionConfig)` - Transform for export
-- `ParquetParserService.write(data, outputPath)` - Generate Parquet
-- `S3DataSource.uploadFile(path, buffer)` - Upload to S3
-
-**Deployment**: Local, Scheduled (cron), AWS Lambda
-
-**Use When**: Extracting inventory/orders to S3 as Parquet
-
----
-
-#### GraphQL → Partitioned Parquet on S3
-**File**: [`standalone/graphql-to-parquet-partitioned-s3.md`](standalone/graphql-to-parquet-partitioned-s3.md)
-
-**Description**: Extract entities via GraphQL with auto-pagination, transform with `UniversalMapper`, and write multiple Parquet files to S3 with date/entity/size partitioning and incremental state.
-
-**Complexity**: Medium | **Lines**: ~550
-
-**SDK Methods**:
-- `createClient`, `client.graphql({ pagination })`
-- `UniversalMapper`
-- `S3DataSource.writeParquetContent`, `S3DataSource.uploadFile`
-
-**Key Patterns**:
-- Auto-pagination extraction
-- Data transformation with UniversalMapper
-- Parquet file generation
-- Partitioning strategies (date, entity, size)
-- Incremental state tracking
-
-**Use When**: Large-scale extraction with date/entity partitioning
-
----
-
-### Complex Workflows
-
-#### Multi-Source Aggregation
-**File**: [`standalone/multi-source-aggregation.md`](standalone/multi-source-aggregation.md)
-
-**Description**: Standalone Node.js script that aggregates inventory from multiple sources (SFTP CSV + S3 JSON), reconciles with Fluent Commerce current state, and updates differences. Includes comprehensive reporting.
-
-**Complexity**: High | **Lines**: ~800
-
-**SDK Methods**:
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2
-- `SftpDataSource(...)` - SFTP operations
-- `S3DataSource(...)` - S3 operations
-- `CSVParserService` - Parse SFTP CSV
-- `client.graphql({ query, variables })` - Query current inventory
-- `UniversalMapper(...)` - Transform aggregated data
-
-**Deployment**: Scheduled (hourly), Manual, Containerized
-
-**Use When**: Combining inventory from multiple sources
-
----
-
-#### Multi-Channel Inventory Sync
-**File**: [`standalone/multi-channel-inventory-sync.md`](standalone/multi-channel-inventory-sync.md)
-
-**Description**: Node.js script that aggregates Available-to-Promise (ATP) inventory from Fluent Commerce and pushes real-time updates to multiple marketplaces (Amazon, eBay, Walmart).
-
-**Complexity**: High | **Lines**: ~950
-
-**SDK Methods**:
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
-- `client.graphql({ query, variables, pagination })` - Query with auto-pagination
-- `UniversalMapper(mappingConfig)` - Transform Fluent data to marketplace formats
-- `createConsoleLogger()` - Simple console logger
-- `toStructuredLogger(logger, context)` - Add context to logs
-- `generateCorrelationId()` - Generate unique correlation IDs
-- State tracking for incremental updates
-
-**Key Patterns**:
-- GraphQL pagination → external marketplace APIs
-- ATP (Available-to-Promise) aggregation across multiple locations
-- Marketplace-specific buffer stock calculations
-- Parallel marketplace updates with rate limiting
-- Per-marketplace error handling and retry logic
-- SLA tracking (15-minute sync requirement)
-
-**Use When**: Standalone multi-channel distribution (different from Versori template - this pushes TO marketplaces)
-
----
-
-## 🅲️ Pattern Guides (Reusable Concepts)
-
-### Universal Field Mapping
-**File**: [`patterns/field-mapping-universal.md`](patterns/field-mapping-universal.md)
-
-**Description**: Focused guide on UniversalMapper for field transformations. Covers basic mapping, SDK resolvers, custom resolvers, nested fields, arrays, and error handling.
-
-**Lines**: ~150-200
-
-**SDK Methods**:
-- `UniversalMapper(config)` - Create mapper
-- `mapper.map(sourceData)` - Transform record
-- SDK Resolvers: `sdk.*` prefix (15+ built-in)
-- Custom resolvers: User-defined functions
-
-**Patterns Covered**:
-- Basic field mapping
-- SDK resolver usage (string, number, date, type, utility)
-- Custom resolver patterns (simple, helper-based, context-aware)
-- Nested field mapping (dot notation)
-- Array transformations
-- Error handling in mapping
-
----
-
-### Custom Resolvers
-**File**: [`patterns/custom-resolvers.md`](patterns/custom-resolvers.md)
-
-**Description**: Focused guide on writing custom resolvers. Covers 4-parameter signature, async resolvers, helper functions, and best practices.
-
-**Lines**: ~100-150
-
-**Resolver Signature**:
-```typescript
-(value, sourceData, helpers, config) => any | Promise<any>
-```
-
-**Helper Functions**:
-- Path access (get, set)
-- Type coercion (parseFloatSafe, parseIntSafe, parseBool)
-- Date operations (formatDate, parseDate, addDays)
-- Array operations (ensureArray, coalesce, groupBy)
-- String operations (toCamelCase, toSnakeCase, template)
-
----
-
-### Error Handling & Retry Strategies
-**File**: [`patterns/error-handling-retry.md`](patterns/error-handling-retry.md)
-
-**Description**: Focused guide on error handling and retry strategies. Covers try/catch, exponential backoff, circuit breaker, batch error isolation, and graceful degradation.
-
-**Lines**: ~100-150
-
-**SDK Error Classes**:
-- `ConfigurationError` - Config validation
-- `AggregateIngestionError` - Multiple failures
-- `IngestionErrorFactory` - Create structured errors
-
-**Patterns Covered**:
-- Basic try/catch with logging
-- Exponential backoff retry
-- Circuit breaker pattern
-- Batch error isolation
-- Graceful degradation
-
----
-
-### State Management & Duplicate Prevention
-**File**: [`patterns/state-duplicate-prevention.md`](patterns/state-duplicate-prevention.md)
-
-**Description**: Focused guide on state management and duplicate prevention. Covers file tracking, checkpoints, distributed locking, and idempotency.
-
-**Lines**: ~100-150
-
-**SDK Methods**:
-- `StateService(kvAdapter)` - State management
-- `VersoriKVAdapter(openKv())` - Versori KV wrapper
-- `VersoriFileTracker` - File tracking
-
----
-
-### Pagination & Streaming
-**File**: [`patterns/pagination-streaming.md`](patterns/pagination-streaming.md)
-
-**Description**: Focused guide on handling large datasets with pagination and streaming. Covers GraphQL auto-pagination, CSV/Parquet streaming, and memory optimization.
-
-**Lines**: ~150-200
-
-**SDK Methods**:
-- `detectPaginationVariables(query)` - Auto-detect
-- `hasMorePages(response)` - Check for next page
-- `extractCursor(response)` - Get cursor
-- `buildPaginationVariables(variables, cursor)` - Build next query
-- CSV/Parquet streaming APIs
-
----
-
-### CSV Schema Validation + Rejection Report
-**File**: [`patterns/csv-schema-validation-and-rejection-report.md`](patterns/csv-schema-validation-and-rejection-report.md)
-
-**Description**: Validate CSV headers and rows; generate a rejection report CSV and upload to S3. Fits into both S3 and SFTP ingestion flows before mapping.
-
-**Complexity**: Low-Medium | **Lines**: ~220
-
----
-
-### Large File Splitting
-**File**: [`patterns/large-file-splitting.md`](patterns/large-file-splitting.md)
-
-**Description**: Chunk large files for memory-efficient processing.
-
-**Use When**: Handling files too large for memory
-
----
-
-### Master Data ETL
-**File**: [`patterns/master-data-etl.md`](patterns/master-data-etl.md)
-
-**Description**: Generic patterns for products, locations, networks ingestion.
-
-**Use When**: Master data ingestion best practices
-
----
-
-## 🔍 Find Templates By Use Case
-
-### I want to...
-
-#### Import Inventory
-- **From S3 CSV** → [S3 CSV Inventory Batch](versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md) (Versori) or [S3 CSV Batch API](standalone/s3-csv-batch-api.md) (Standalone)
-- **From SFTP CSV** → [SFTP CSV Ingestion](versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
-- **From Multiple Sources** → [Multi-Source Aggregation](standalone/multi-source-aggregation.md)
-
-#### Import Orders
-- **From XML Webhooks** → [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
-- **From SFTP XML** → [SFTP XML GraphQL](standalone/sftp-xml-graphql.md)
-- **Generic XML** → [Generic XML Order](versori/webhooks/template-webhook-generic-xml-order.md)
-
-#### Import Products/Locations
-- **Event API** → [Event API Templates](versori/workflows/ingestion/event-api/)
-- **GraphQL Mutations** → [GraphQL Mutation Templates](versori/workflows/ingestion/graphql-mutations/)
-
-#### Export Data
-- **To Parquet** → [GraphQL Query Export](standalone/graphql-query-export.md)
-- **To Partitioned Parquet** → [GraphQL to Parquet Partitioned S3](standalone/graphql-to-parquet-partitioned-s3.md)
-- **With Versori** → [GraphQL Parquet Extraction](versori/business-examples/graphql-parquet-extraction.md)
-
-#### Process Returns
-- **Complete RMA Flow** → [RMA Returns Comprehensive](versori/webhooks/template-webhook-rma-returns-comprehensive.md)
-
-#### Manage Pricing
-- **Bulk Updates** → [S3 CSV Price GraphQL](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md)
-
-#### Advanced Workflows
-- **Dropship Routing** → [Dropship Routing](versori/webhooks/template-webhook-dropship-routing.md) or [Business Example](versori/business-examples/dropship-order-routing.md)
-- **Flash Sales** → [Flash Sale Reserve](versori/webhooks/template-webhook-flash-sale-reserve.md)
-- **Multi-Channel Sync** → [Multi-Channel Sync](versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md) (Versori) or [Standalone](standalone/multi-channel-inventory-sync.md)
-- **Inter-Location Transfers** → [Inter-Location Transfers](versori/business-examples/inter-location-transfers.md)
-- **Pre-Orders** → [Pre-Order Allocation](versori/business-examples/pre-order-allocation.md)
-
----
-
-## 💡 Quick Recommendations
-
-### For Beginners
-Start with these guides (easiest to hardest):
-
-1. **[Field Mapping Universal](patterns/field-mapping-universal.md)** - Learn core mapping concepts
-2. **[S3 CSV Batch API](standalone/s3-csv-batch-api.md)** - Simple standalone ingestion
-3. **[CSV Inventory Sync](versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Versori scheduled workflow
-4. **[XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)** - Webhook with advanced features
-
-### For Production Deployments
-These guides are production-tested:
-
-- **Inventory Ingestion**: [SFTP CSV Ingestion](versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
-- **Order Processing**: [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
-- **Data Extraction**: [GraphQL to Parquet Partitioned S3](standalone/graphql-to-parquet-partitioned-s3.md)
-- **State Management**: [KV State Management](versori/patterns/kv-state-management.md)
-
-### For Complex Integrations
-These guides show advanced patterns:
-
-- [Multi-Source Aggregation](standalone/multi-source-aggregation.md)
-- [Dropship Order Routing](versori/business-examples/dropship-order-routing.md)
-- [Flash Sale Reserve](versori/webhooks/template-webhook-flash-sale-reserve.md)
-- [Pre-Order Allocation](versori/business-examples/pre-order-allocation.md)
-
----
-
-## 📖 How to Use These Templates
-
-### For Developers
-
-1. **Pick a template** - Use the decision tree above or browse by use case
-2. **Copy the code** - All examples are production-ready
-3. **Customize** environment variables and configurations
-4. **Test locally** with provided sample data
-5. **Deploy** using deployment options in each guide
-
-**Need Help?** Check our comprehensive [**FAQ**](faq.md) for troubleshooting.
-
-### For AI / LLM Prompts
-
-These templates are optimized for AI consumption:
-
-```
-Build a Versori connector that receives SFCC XML orders via HTTP webhook
-and creates orders in Fluent Commerce.
-
-Context: Use patterns from docs/01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md
-```
-
-AI gets **focused context** without API reference overload.
-
----
-
-## ✅ What's Included in Each Template
-
-Every template provides:
-
-- ✅ **Complete working code** (400-800 lines)
-- ✅ **Real SDK methods** with proper usage
-- ✅ **Production patterns** from actual connectors
-- ✅ **Environment setup** and configuration
-- ✅ **Testing instructions** with sample data
-- ✅ **Deployment options** (Docker, Lambda, cron, etc.)
-- ✅ **Common issues** with solutions
-- ✅ **Related guides** for deeper dives
-
----
-
-## 🚀 Quick Start Examples
-
-### Versori HTTP Webhook
-
-```typescript
-import { createClient, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-export default async function processOrder(ctx) {
-  const client = await createClient(ctx); // Auto-detects Versori context
-  const mapper = new GraphQLMutationMapper(mappingConfig, ctx.log, { fluentClient: client });
-  const result = await mapper.mapWithNodes(ctx.body, customResolvers);
-  
-  // Check success (errors are returned, not thrown)
-  if (!result.success) {
-    throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
-  }
-  
-  // Execute mutation (query is auto-generated in result)
-  return await client.graphql({ 
-    query: result.query, 
-    variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
-  });
-}
-```
-
-### Standalone Node.js Script
-
-```typescript
-import { createClient, S3DataSource, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-  },
-});
-
-const s3Source = new S3DataSource(config, logger);
-const mapper = new UniversalMapper(mappingConfig);
-const files = await s3Source.listFiles();
-// ... process files
-```
-
----
-
-## 📚 Additional Resources
-
-- **[FAQ - Troubleshooting](faq.md)** - Consolidated solutions to common issues
-- **[API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete SDK method reference
-- **[SDK Philosophy](../00-START-HERE/sdk-philosophy.md)** - Design principles
-- **[Complete Documentation](../readme.md)** - All guides and references
-
----
-
-## 🎓 Learning Path
-
-**New to SDK?**
-
-1. Start with [SDK Philosophy](../00-START-HERE/sdk-philosophy.md)
-2. Read [Getting Started](../00-START-HERE/getting-started.md)
-3. Pick a **Standalone** template (simpler, no Versori)
-4. Try a **Versori** template if deploying to Versori
-5. Use **Pattern** guides for specific concepts
-
-**Building Connectors?**
-
-1. Pick matching use case template
-2. Review **Pattern** guides for concepts
-3. Check [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) for details
-4. Deploy and monitor
-
----
-
-## 📊 Template Statistics
-
-- **38+ Total Templates**
-  - 20 Versori Platform templates
-    - 7 Webhook-triggered workflows
-    - 6 Scheduled workflows (Batch API)
-    - 8 Event API templates
-    - 9 GraphQL mutation templates
-    - 3 Versori patterns
-    - 4 Business use case examples
-  - 9 Standalone Node.js/Deno templates
-  - 9 Reusable Pattern guides
-- **~15,000+ lines** of production-ready code
-- **100% tested** patterns from real connectors
-- **Organized by trigger type** for easy navigation
-
----
-
-## 🆘 Still Can't Decide?
-
-### Answer These Questions:
-
-1. **Runtime**: Versori or Standalone?
-2. **Direction**: Ingestion (IN) or Extraction (OUT)?
-3. **Trigger**: Webhook, Schedule, or Manual?
-4. **Format**: CSV, XML, JSON, or Parquet?
-5. **Complexity**: Simple, Medium, or High?
-
-**Then use the decision tree above to find your template!**
-
----
-
-## 🆘 Need Help?
-
-- **Issues**: [GitHub Issues](https://github.com/fluentcommerce/fc-connect-sdk/issues)
-- **Documentation**: [Complete Docs](../readme.md)
-- **API Reference**: [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)
-- **Troubleshooting**: [FAQ](faq.md)
-- **Examples**: Check individual template files
-
----
-
-*Last Updated: 2025-01-27*
+# FC Connect SDK - Template Guides
+
+**Complete catalog of production-ready templates** for building Fluent Commerce integrations.
+
+Last Updated: 2025-01-27
+
+---
+
+## 🎯 Quick Decision Tree
+
+**Not sure which template to use?** Follow this flowchart:
+
+```
+START: What do you want to build?
+│
+├─ I need a PATTERN (concept/technique) ────────────────────────┐
+│                                                                 │
+├─ I'm building for VERSORI PLATFORM ────────────────────────────┤
+│                                                                 │
+└─ I'm building STANDALONE (Node.js/Deno) ───────────────────────┤
+                                                                  │
+                                                                  ▼
+```
+
+### 1️⃣ What Runtime Are You Using?
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Where will your integration run?                            │
+└──────────────────────────────────────────────────────────────┘
+                          │
+        ┌─────────────────┼─────────────────┐
+        │                 │                 │
+        ▼                 ▼                 ▼
+   VERSORI           STANDALONE         JUST A
+  PLATFORM         NODE.JS/DENO        PATTERN
+```
+
+---
+
+## 🅰️ Versori Platform Templates
+
+### Webhook-Triggered Workflows (7)
+
+#### XML Order Ingestion
+**File**: [`versori/webhooks/template-webhook-xml-order-ingestion.md`](versori/webhooks/template-webhook-xml-order-ingestion.md)
+
+**Description**: Build a Versori HTTP webhook that receives SFCC/Radial XML orders and creates orders in Fluent Commerce using GraphQL mutations. Includes nodes processing for nested XML extraction, custom resolvers with async API calls, and complete audit trail.
+
+**Complexity**: Medium | **Lines**: ~500
+
+**SDK Methods**:
+- `createClient(ctx)` - Versori context auto-detected
+- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - XML → GraphQL mapping
+- `mapper.mapWithNodes(data)` - Process nodes config (resolvers from constructor)
+- `mapWithNodes()` returns query automatically (no need for buildMutation())
+- `client.graphql({ query, variables })` - Execute mutation
+
+**Key Patterns**:
+- Versori connection setup with auto-authentication
+- Nodes configuration (extracting nested/escaped XML)
+- Custom resolvers with context and async API calls
+- GraphQL mutation generation and execution
+- Error handling with structured responses
+
+**Use When**: Receiving XML webhooks (SFCC, Radial, custom), need to extract nested XML documents, transforming XML to Fluent orders/entities
+
+---
+
+#### Generic XML Order
+**File**: [`versori/webhooks/template-webhook-generic-xml-order.md`](versori/webhooks/template-webhook-generic-xml-order.md)
+
+**Description**: Generic, vendor-agnostic XML order ingestion via Versori webhook using `GraphQLMutationMapper`. Includes optional nodes extraction, custom resolvers, audit trail, and robust error handling.
+
+**Complexity**: Medium | **Lines**: ~450
+
+**Use When**: Any XML order format (not SFCC-specific)
+
+---
+
+#### ASN/Purchase Order
+**File**: [`versori/webhooks/template-webhook-asn-purchase-order.md`](versori/webhooks/template-webhook-asn-purchase-order.md)
+
+**Description**: Advanced Shipping Notice (ASN) webhook processing with purchase order matching, shipment tracking, and inventory receiving workflows.
+
+**Complexity**: Medium | **Lines**: ~600
+
+**Use When**: Processing Advanced Shipping Notices
+
+---
+
+#### Dropship Routing
+**File**: [`versori/webhooks/template-webhook-dropship-routing.md`](versori/webhooks/template-webhook-dropship-routing.md)
+
+**Description**: Supplier selection logic, PO submission, fallback to warehouse, and order status updates for dropship fulfillment.
+
+**Complexity**: High | **Lines**: ~700
+
+**Use When**: Routing orders to suppliers with fallback
+
+---
+
+#### Flash Sale Inventory Reserve
+**File**: [`versori/webhooks/template-webhook-flash-sale-reserve.md`](versori/webhooks/template-webhook-flash-sale-reserve.md)
+
+**Description**: Time-bound inventory reservations, distributed locking, real-time decrement pattern, and periodic reconciliation for flash sales.
+
+**Complexity**: High | **Lines**: ~700
+
+**SDK Methods**:
+- `createClient(ctx)`
+- `VersoriKVAdapter` - Distributed locking
+- `StateService` - Reservation tracking
+- Custom resolvers (time-bound checks, quantity validation)
+
+**Key Patterns**:
+- Time-bound reservations (expiry logic)
+- Distributed locking (prevent overselling)
+- Real-time inventory decrement
+- Periodic reconciliation workflow
+
+**Use When**: Managing high-velocity flash sale inventory
+
+---
+
+#### RMA/Returns Processing (Comprehensive)
+**File**: [`versori/webhooks/template-webhook-rma-returns-comprehensive.md`](versori/webhooks/template-webhook-rma-returns-comprehensive.md)
+
+**Description**: Complete RMA lifecycle: return initiation → RMA creation → shipping label → quality inspection → refund/exchange → inventory restock. Includes 5 separate webhooks for full workflow.
+
+**Complexity**: Medium-High | **Lines**: ~1700
+
+**Webhooks**:
+1. `createRmaFromReturn` - Creates RMA from return request
+2. `trackReturnShipment` - Tracks return shipment
+3. `qualityInspection` - Processes warehouse inspection
+4. `processRefundOrExchange` - Handles refund/exchange
+5. `getRmaStatus` - Query endpoint for RMA status
+
+**Use When**: Full return/exchange workflow
+
+---
+
+#### Payment Gateway Integration (Adyen)
+**File**: [`versori/webhooks/template-webhook-payment-gateway-integration.md`](versori/webhooks/template-webhook-payment-gateway-integration.md)
+
+**Description**: Complete payment gateway integration with 4 webhooks: Capture, Refund, Auth Cancel, and ReAuth. Modular architecture allows easy swapping of payment providers (Adyen → Stripe).
+
+**Complexity**: Medium-High | **Lines**: ~1500
+
+**SDK Methods**:
+- `createClient(ctx)` - Versori context auto-detected
+- `client.setRetailerId()` - Required for Event API
+- `client.sendEvent()` - Send events to Fluent Commerce Event API
+- `VersoriKVAdapter(ctx.openKv(':project:'))` - Idempotency tracking
+
+**Key Patterns**:
+- Payment provider abstraction (easy to swap Adyen → Stripe)
+- Trigger source validation (ORDER_FULFILLMENT vs PAYMENT_ENTITY)
+- Shared services (webhook validation, event sending, idempotency)
+- Event mapping (payment provider → Fluent event format)
+
+**Use When**: Integrating payment gateways (Adyen, Stripe, PayPal)
+
+---
+
+### Scheduled Workflows (6)
+
+#### CSV Inventory Sync (S3)
+**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md`](versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)
+
+**Description**: Build a Versori scheduled workflow (cron-based) that reads inventory CSV files from S3 and updates Fluent Commerce inventory via Batch API. Includes VersoriKV state management for duplicate prevention and file archival.
+
+**Complexity**: Medium | **Lines**: ~600
+
+**SDK Methods**:
+- `createClient(ctx)` - Versori client
+- `S3DataSource(config, logger)` - S3 operations
+- `UniversalMapper(mappingConfig)` - Field transformations
+- `mapper.map(record)` - Transform record
+- `client.createJob({ name, retailerId })` - Create Batch job
+- `client.sendBatch(jobId, { entities })` - Send inventory batch
+- `VersoriKVAdapter(openKv())` - State management
+- `VersoriFileTracker` - File tracking
+
+**Key Patterns**:
+- Versori scheduled triggers (cron expressions)
+- S3 file operations (list, download, archive)
+- UniversalMapper with SDK resolvers
+- Batch API processing with chunking
+- VersoriKV state management (duplicate prevention)
+- File archival after processing
+
+**Use When**: Scheduled inventory sync (daily, hourly), reading CSV from S3, need duplicate prevention
+
+---
+
+#### SFTP CSV Ingestion
+**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md`](versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
+
+**Description**: Scheduled/manual ingestion from SFTP CSV with `CSVParserService` and `UniversalMapper`, duplicate prevention with `VersoriFileTracker`, and robust retry/backoff for downloads and batch sends.
+
+**Complexity**: Medium | **Lines**: ~700
+
+**SDK Methods**:
+- `createClient(ctx)`
+- `SftpDataSource.listFiles`, `downloadFile`, `moveFile`
+- `CSVParserService.parse`
+- `UniversalMapper.map`
+- `VersoriFileTracker`, `VersoriKVAdapter`, `StateService`
+- `client.createJob`, `client.sendBatch`
+
+**Key Patterns**:
+- SFTP connection and file operations
+- CSV parsing with validation
+- File tracking and duplicate prevention
+- Retry logic with exponential backoff
+- File archival (processed/error folders)
+
+**Use When**: Scheduled SFTP polling for CSV files
+
+---
+
+#### Cycle Count Reconciliation
+**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md`](versori/workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md)
+
+**Description**: Scheduled cycle count import with variance detection, adjustment workflows, and reporting.
+
+**Complexity**: Medium | **Lines**: ~650
+
+**Use When**: Scheduled cycle count imports with variance handling
+
+---
+
+#### Multi-Channel Inventory Sync
+**File**: [`versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md`](versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md)
+
+**Description**: ATP computation, channel-specific allocation rules, delta sync optimization, and rate-limit handling for multi-channel inventory distribution.
+
+**Complexity**: High | **Lines**: ~750
+
+**SDK Methods**:
+- `createClient(ctx)`
+- `client.graphql` - Query inventory
+- `UniversalMapper` - Transform for channels
+- Channel-specific custom resolvers
+- Rate limiting logic
+
+**Key Patterns**:
+- ATP (Available-To-Promise) calculation
+- Channel allocation rules
+- Delta sync (only changed inventory)
+- Rate limiting per channel
+- Multi-channel distribution
+
+**Use When**: Distributing inventory across multiple sales channels
+
+---
+
+#### Event API Templates
+**File**: [`versori/workflows/ingestion/event-api/`](versori/workflows/ingestion/event-api/)
+
+**Description**: Product, location, and control entity ingestion via Event API with GraphQL mutations. Supports CSV, JSON, XML, and Parquet formats from S3 and SFTP sources.
+
+**Available Templates**:
+- S3 CSV Product Event → [`template-ingestion-s3-csv-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md)
+- SFTP CSV Product Event → [`template-ingestion-sftp-csv-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md)
+- S3 JSON Product Event → [`template-ingestion-s3-json-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-json-product-event.md)
+- SFTP JSON Product Event → [`template-ingestion-sftp-json-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-json-product-event.md)
+- S3 XML Product Event → [`template-ingestion-s3-xml-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-xml-product-event.md)
+- SFTP XML Product Event → [`template-ingestion-sftp-xml-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-xml-product-event.md)
+- S3 Parquet Product Event → [`template-ingestion-s3-parquet-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-s3-parquet-product-event.md)
+- SFTP Parquet Product Event → [`template-ingestion-sftp-parquet-product-event.md`](versori/workflows/ingestion/event-api/template-ingestion-sftp-parquet-product-event.md)
+
+**Complexity**: Medium | **Lines**: ~550-700
+
+**Use When**: Ingesting products, locations, or control entities via Event API
+
+---
+
+#### GraphQL Mutation Templates
+**File**: [`versori/workflows/ingestion/graphql-mutations/`](versori/workflows/ingestion/graphql-mutations/)
+
+**Description**: Direct GraphQL mutation templates for creating/updating locations, prices, and control entities.
+
+**Available Templates**:
+- S3 CSV Location GraphQL → [`template-ingestion-s3-csv-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-location-graphql.md)
+- SFTP CSV Location GraphQL → [`template-ingestion-sftp-csv-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-csv-location-graphql.md)
+- S3 JSON Location GraphQL → [`template-ingestion-s3-json-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-json-location-graphql.md)
+- SFTP JSON Location GraphQL → [`template-ingestion-sftp-json-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-json-location-graphql.md)
+- S3 XML Location GraphQL → [`template-ingestion-s3-xml-location-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-xml-location-graphql.md)
+- S3 CSV Price GraphQL → [`template-ingestion-s3-csv-price-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md)
+- S3 CSV Control GraphQL → [`template-ingestion-s3-csv-control-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-control-graphql.md)
+- SFTP CSV Control GraphQL → [`template-ingestion-sftp-csv-control-graphql.md`](versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-csv-control-graphql.md)
+
+**Complexity**: Medium | **Lines**: ~600-800
+
+**Use When**: Direct GraphQL mutations for entities not supported by Event API
+
+---
+
+### Versori Patterns (3)
+
+#### KV State Management
+**File**: [`versori/patterns/kv-state-management.md`](versori/patterns/kv-state-management.md)
+
+**Description**: Comprehensive guide on using Versori KV storage for state management, duplicate prevention, checkpoints, and file tracking. Includes 6 complete patterns from simple file tracking to advanced indexed tracking.
+
+**Complexity**: Low-Medium | **Lines**: ~400
+
+**SDK Methods**:
+- `VersoriKVAdapter(openKv())` - Wrap Versori KV
+- `VersoriFileTracker(kvAdapter)` - Track files
+- `StateService(kvAdapter)` - High-level state operations
+- `stateService.isFileProcessed(key)` - Check if processed
+- `stateService.markFileProcessed(key, metadata)` - Mark complete
+- `stateService.saveCheckpoint(key, data)` - Save checkpoint
+- `stateService.getCheckpoint(key)` - Restore checkpoint
+
+**Key Patterns**:
+- Simple file duplicate prevention
+- Distributed locking (prevent concurrent workflows)
+- Checkpoint & resume (long-running workflows)
+- Daily job management (reuse jobs)
+- Error state management (retry logic)
+- Advanced indexed tracking (list files)
+
+**Use When**: Preventing duplicate file processing, need checkpoint/resume capabilities, distributed workflow coordination
+
+---
+
+#### XML Response Patterns
+**File**: [`versori/patterns/xml-response-patterns.md`](versori/patterns/xml-response-patterns.md)
+
+**Description**: CRITICAL guide on returning non-JSON content (XML, HTML, CSV) from Versori webhooks using custom Response objects.
+
+**Complexity**: Low-Medium | **Lines**: ~300
+
+**SDK Methods**:
+- `webhook('name', { response: { mode, onSuccess, onError } })` - Custom handlers
+- `XMLBuilder(options)` - Build XML responses
+- `builder.build(data)` - Generate XML string
+- `new Response(body, { status, headers })` - Custom response objects
+
+**Key Patterns**:
+- Why custom Response objects are needed (JSON encoding problem)
+- onSuccess handler pattern (return Response)
+- onError handler pattern (error responses)
+- Content-Type headers (application/xml, text/html, text/csv)
+
+**Use When**: Returning XML responses (SOAP, RSS, custom), HTML status pages, CSV downloads, CRITICAL for SFCC order detail responses
+
+---
+
+#### Dual Workflow Connector
+**File**: [`versori/patterns/dual-workflow-connector.md`](versori/patterns/dual-workflow-connector.md)
+
+**Description**: Build a complete Versori connector with multiple workflows (ingestion + extraction), shared resolvers, proper index.ts structure, and package.json configuration.
+
+**Complexity**: Medium | **Lines**: ~500
+
+**Key Patterns**:
+- Multi-workflow index structure (clean exports)
+- Shared resolvers library (domain-organized)
+- Bidirectional data flow (ingestion vs extraction)
+- Package.json configuration (Versori-specific)
+- Testing multi-workflow connectors
+
+**Use When**: Building complete bidirectional integration, multiple workflows sharing code, production Versori connector
+
+---
+
+### Business Use Case Examples (4)
+
+#### GraphQL → Parquet Extraction
+**File**: [`versori/business-examples/graphql-parquet-extraction.md`](versori/business-examples/graphql-parquet-extraction.md)
+
+**Description**: Scheduled/manual Versori workflow that extracts via GraphQL with auto-pagination, transforms with `UniversalMapper`, partitions by date/entity/size, and uploads Parquet parts to S3 with incremental KV state.
+
+**Complexity**: Medium | **Lines**: ~600
+
+**SDK Methods**:
+- `createClient(ctx)` with Versori connection
+- `client.graphql({ pagination })`
+- `UniversalMapper`
+- `VersoriKVAdapter`, `StateService`
+- `S3DataSource.writeParquetContent`, `S3DataSource.uploadFile`
+
+**Key Patterns**:
+- Auto-pagination extraction
+- Data transformation with UniversalMapper
+- Parquet file generation
+- Partitioning strategies (date, entity, size)
+- Incremental state tracking
+
+**Use When**: Extracting data from Fluent to data warehouse
+
+---
+
+#### Dropship Order Routing
+**File**: [`versori/business-examples/dropship-order-routing.md`](versori/business-examples/dropship-order-routing.md)
+
+**Description**: Intelligent supplier selection with fallback logic and complete order orchestration workflow.
+
+**Complexity**: High | **Lines**: ~700
+
+**Use When**: Complex dropship routing with fallback logic
+
+---
+
+#### Inter-Location Transfers
+**File**: [`versori/business-examples/inter-location-transfers.md`](versori/business-examples/inter-location-transfers.md)
+
+**Description**: Transfer order creation, fulfillment workflow, and receiving processes for inter-location inventory movement.
+
+**Complexity**: Medium-High | **Lines**: ~650
+
+**Use When**: Moving inventory between locations
+
+---
+
+#### Pre-Order Allocation
+**File**: [`versori/business-examples/pre-order-allocation.md`](versori/business-examples/pre-order-allocation.md)
+
+**Description**: Pre-order reservation system, allocation rules engine, and fulfillment on inventory availability.
+
+**Complexity**: High | **Lines**: ~750
+
+**SDK Methods**:
+- `createClient(ctx)`
+- `VersoriKVAdapter` - Reservation tracking
+- Allocation rules engine
+- Fulfillment triggers
+
+**Use When**: Managing pre-orders with allocation logic
+
+---
+
+## 🅱️ Standalone Node.js / Deno Templates
+
+### Ingestion (External → Fluent)
+
+#### S3 CSV → Batch API
+**File**: [`standalone/s3-csv-batch-api.md`](standalone/s3-csv-batch-api.md)
+
+**Description**: Read CSV inventory files from S3, transform with `UniversalMapper`, and update Fluent via Batch API with chunking and archival.
+
+**Complexity**: Medium | **Lines**: ~450-500
+
+**SDK Methods**:
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })`
+- `S3DataSource`, `CSVParserService`, `UniversalMapper`
+- `client.createJob`, `client.sendBatch`
+
+**Use When**: Simple S3 CSV ingestion with field mapping
+
+---
+
+#### SFTP XML → GraphQL Mutation
+**File**: [`standalone/sftp-xml-graphql.md`](standalone/sftp-xml-graphql.md)
+
+**Description**: Standalone Node.js script that reads XML order files from SFTP and creates orders in Fluent Commerce using GraphQL mutations. Includes SFTP connection, XML parsing, and file archival.
+
+**Complexity**: Medium | **Lines**: ~600
+
+**SDK Methods**:
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2
+- `SftpDataSource(config, logger)` - SFTP operations
+- `XMLParserService` - XML parsing
+- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - XML → GraphQL
+- `mapper.mapWithNodes(xmlData)` - Transform with custom resolvers (from constructor)
+- `mapper.map(xmlData)` - Transform without custom resolvers (built-in SDK resolvers only)
+- `client.graphql({ query, variables })` - Execute mutation
+
+**Key Patterns**:
+- SFTP connection & file operations
+- XML parsing & validation
+- GraphQL mutation mapping
+- Custom resolvers for complex logic
+- File management (archive/error folders)
+
+**Deployment**: Local, Docker, Cron/Systemd
+
+**Use When**: Polling SFTP for XML orders
+
+---
+
+#### Webhook Payload Processing
+**File**: [`standalone/webhook-payload-processing.md`](standalone/webhook-payload-processing.md)
+
+**Description**: Process stored webhook payloads offline with signature validation, payload parsing, and file-based queue.
+
+**Complexity**: Low-Medium | **Lines**: ~250
+
+**Use When**: Processing stored webhook payloads offline
+
+---
+
+#### ASN Inbound Processing
+**File**: [`standalone/asn-inbound-processing.md`](standalone/asn-inbound-processing.md)
+
+**Description**: Process Advanced Shipping Notice (ASN) files with PO matching and inventory updates.
+
+**Complexity**: Medium | **Lines**: ~500
+
+**Use When**: Processing inbound shipment notices
+
+---
+
+### Extraction (Fluent → External)
+
+#### GraphQL Query → Parquet Export
+**File**: [`standalone/graphql-query-export.md`](standalone/graphql-query-export.md)
+
+**Description**: Standalone Node.js script that extracts inventory/orders from Fluent Commerce via GraphQL queries and exports to S3 as Parquet files. Includes auto-pagination and incremental extraction.
+
+**Complexity**: Medium | **Lines**: ~500
+
+**SDK Methods**:
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2
+- `client.graphql({ query, variables })` - Execute GraphQL query
+- `detectPaginationVariables(query)` - Auto-detect pagination
+- `hasMorePages(response)` - Check for next page
+- `UniversalMapper(extractionConfig)` - Transform for export
+- `ParquetParserService.write(data, outputPath)` - Generate Parquet
+- `S3DataSource.uploadFile(path, buffer)` - Upload to S3
+
+**Deployment**: Local, Scheduled (cron), AWS Lambda
+
+**Use When**: Extracting inventory/orders to S3 as Parquet
+
+---
+
+#### GraphQL → Partitioned Parquet on S3
+**File**: [`standalone/graphql-to-parquet-partitioned-s3.md`](standalone/graphql-to-parquet-partitioned-s3.md)
+
+**Description**: Extract entities via GraphQL with auto-pagination, transform with `UniversalMapper`, and write multiple Parquet files to S3 with date/entity/size partitioning and incremental state.
+
+**Complexity**: Medium | **Lines**: ~550
+
+**SDK Methods**:
+- `createClient`, `client.graphql({ pagination })`
+- `UniversalMapper`
+- `S3DataSource.writeParquetContent`, `S3DataSource.uploadFile`
+
+**Key Patterns**:
+- Auto-pagination extraction
+- Data transformation with UniversalMapper
+- Parquet file generation
+- Partitioning strategies (date, entity, size)
+- Incremental state tracking
+
+**Use When**: Large-scale extraction with date/entity partitioning
+
+---
+
+### Complex Workflows
+
+#### Multi-Source Aggregation
+**File**: [`standalone/multi-source-aggregation.md`](standalone/multi-source-aggregation.md)
+
+**Description**: Standalone Node.js script that aggregates inventory from multiple sources (SFTP CSV + S3 JSON), reconciles with Fluent Commerce current state, and updates differences. Includes comprehensive reporting.
+
+**Complexity**: High | **Lines**: ~800
+
+**SDK Methods**:
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2
+- `SftpDataSource(...)` - SFTP operations
+- `S3DataSource(...)` - S3 operations
+- `CSVParserService` - Parse SFTP CSV
+- `client.graphql({ query, variables })` - Query current inventory
+- `UniversalMapper(...)` - Transform aggregated data
+
+**Deployment**: Scheduled (hourly), Manual, Containerized
+
+**Use When**: Combining inventory from multiple sources
+
+---
+
+#### Multi-Channel Inventory Sync
+**File**: [`standalone/multi-channel-inventory-sync.md`](standalone/multi-channel-inventory-sync.md)
+
+**Description**: Node.js script that aggregates Available-to-Promise (ATP) inventory from Fluent Commerce and pushes real-time updates to multiple marketplaces (Amazon, eBay, Walmart).
+
+**Complexity**: High | **Lines**: ~950
+
+**SDK Methods**:
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
+- `client.graphql({ query, variables, pagination })` - Query with auto-pagination
+- `UniversalMapper(mappingConfig)` - Transform Fluent data to marketplace formats
+- `createConsoleLogger()` - Simple console logger
+- `toStructuredLogger(logger, context)` - Add context to logs
+- `generateCorrelationId()` - Generate unique correlation IDs
+- State tracking for incremental updates
+
+**Key Patterns**:
+- GraphQL pagination → external marketplace APIs
+- ATP (Available-to-Promise) aggregation across multiple locations
+- Marketplace-specific buffer stock calculations
+- Parallel marketplace updates with rate limiting
+- Per-marketplace error handling and retry logic
+- SLA tracking (15-minute sync requirement)
+
+**Use When**: Standalone multi-channel distribution (different from Versori template - this pushes TO marketplaces)
+
+---
+
+## 🅲️ Pattern Guides (Reusable Concepts)
+
+### Universal Field Mapping
+**File**: [`patterns/field-mapping-universal.md`](patterns/field-mapping-universal.md)
+
+**Description**: Focused guide on UniversalMapper for field transformations. Covers basic mapping, SDK resolvers, custom resolvers, nested fields, arrays, and error handling.
+
+**Lines**: ~150-200
+
+**SDK Methods**:
+- `UniversalMapper(config)` - Create mapper
+- `mapper.map(sourceData)` - Transform record
+- SDK Resolvers: `sdk.*` prefix (15+ built-in)
+- Custom resolvers: User-defined functions
+
+**Patterns Covered**:
+- Basic field mapping
+- SDK resolver usage (string, number, date, type, utility)
+- Custom resolver patterns (simple, helper-based, context-aware)
+- Nested field mapping (dot notation)
+- Array transformations
+- Error handling in mapping
+
+---
+
+### Custom Resolvers
+**File**: [`patterns/custom-resolvers.md`](patterns/custom-resolvers.md)
+
+**Description**: Focused guide on writing custom resolvers. Covers 4-parameter signature, async resolvers, helper functions, and best practices.
+
+**Lines**: ~100-150
+
+**Resolver Signature**:
+```typescript
+(value, sourceData, helpers, config) => any | Promise<any>
+```
+
+**Helper Functions**:
+- Path access (get, set)
+- Type coercion (parseFloatSafe, parseIntSafe, parseBool)
+- Date operations (formatDate, parseDate, addDays)
+- Array operations (ensureArray, coalesce, groupBy)
+- String operations (toCamelCase, toSnakeCase, template)
+
+---
+
+### Error Handling & Retry Strategies
+**File**: [`patterns/error-handling-retry.md`](patterns/error-handling-retry.md)
+
+**Description**: Focused guide on error handling and retry strategies. Covers try/catch, exponential backoff, circuit breaker, batch error isolation, and graceful degradation.
+
+**Lines**: ~100-150
+
+**SDK Error Classes**:
+- `ConfigurationError` - Config validation
+- `AggregateIngestionError` - Multiple failures
+- `IngestionErrorFactory` - Create structured errors
+
+**Patterns Covered**:
+- Basic try/catch with logging
+- Exponential backoff retry
+- Circuit breaker pattern
+- Batch error isolation
+- Graceful degradation
+
+---
+
+### State Management & Duplicate Prevention
+**File**: [`patterns/state-duplicate-prevention.md`](patterns/state-duplicate-prevention.md)
+
+**Description**: Focused guide on state management and duplicate prevention. Covers file tracking, checkpoints, distributed locking, and idempotency.
+
+**Lines**: ~100-150
+
+**SDK Methods**:
+- `StateService(kvAdapter)` - State management
+- `VersoriKVAdapter(openKv())` - Versori KV wrapper
+- `VersoriFileTracker` - File tracking
+
+---
+
+### Pagination & Streaming
+**File**: [`patterns/pagination-streaming.md`](patterns/pagination-streaming.md)
+
+**Description**: Focused guide on handling large datasets with pagination and streaming. Covers GraphQL auto-pagination, CSV/Parquet streaming, and memory optimization.
+
+**Lines**: ~150-200
+
+**SDK Methods**:
+- `detectPaginationVariables(query)` - Auto-detect
+- `hasMorePages(response)` - Check for next page
+- `extractCursor(response)` - Get cursor
+- `buildPaginationVariables(variables, cursor)` - Build next query
+- CSV/Parquet streaming APIs
+
+---
+
+### CSV Schema Validation + Rejection Report
+**File**: [`patterns/csv-schema-validation-and-rejection-report.md`](patterns/csv-schema-validation-and-rejection-report.md)
+
+**Description**: Validate CSV headers and rows; generate a rejection report CSV and upload to S3. Fits into both S3 and SFTP ingestion flows before mapping.
+
+**Complexity**: Low-Medium | **Lines**: ~220
+
+---
+
+### Large File Splitting
+**File**: [`patterns/large-file-splitting.md`](patterns/large-file-splitting.md)
+
+**Description**: Chunk large files for memory-efficient processing.
+
+**Use When**: Handling files too large for memory
+
+---
+
+### Master Data ETL
+**File**: [`patterns/master-data-etl.md`](patterns/master-data-etl.md)
+
+**Description**: Generic patterns for products, locations, networks ingestion.
+
+**Use When**: Master data ingestion best practices
+
+---
+
+## 🔍 Find Templates By Use Case
+
+### I want to...
+
+#### Import Inventory
+- **From S3 CSV** → [S3 CSV Inventory Batch](versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md) (Versori) or [S3 CSV Batch API](standalone/s3-csv-batch-api.md) (Standalone)
+- **From SFTP CSV** → [SFTP CSV Ingestion](versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
+- **From Multiple Sources** → [Multi-Source Aggregation](standalone/multi-source-aggregation.md)
+
+#### Import Orders
+- **From XML Webhooks** → [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
+- **From SFTP XML** → [SFTP XML GraphQL](standalone/sftp-xml-graphql.md)
+- **Generic XML** → [Generic XML Order](versori/webhooks/template-webhook-generic-xml-order.md)
+
+#### Import Products/Locations
+- **Event API** → [Event API Templates](versori/workflows/ingestion/event-api/)
+- **GraphQL Mutations** → [GraphQL Mutation Templates](versori/workflows/ingestion/graphql-mutations/)
+
+#### Export Data
+- **To Parquet** → [GraphQL Query Export](standalone/graphql-query-export.md)
+- **To Partitioned Parquet** → [GraphQL to Parquet Partitioned S3](standalone/graphql-to-parquet-partitioned-s3.md)
+- **With Versori** → [GraphQL Parquet Extraction](versori/business-examples/graphql-parquet-extraction.md)
+
+#### Process Returns
+- **Complete RMA Flow** → [RMA Returns Comprehensive](versori/webhooks/template-webhook-rma-returns-comprehensive.md)
+
+#### Manage Pricing
+- **Bulk Updates** → [S3 CSV Price GraphQL](versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md)
+
+#### Advanced Workflows
+- **Dropship Routing** → [Dropship Routing](versori/webhooks/template-webhook-dropship-routing.md) or [Business Example](versori/business-examples/dropship-order-routing.md)
+- **Flash Sales** → [Flash Sale Reserve](versori/webhooks/template-webhook-flash-sale-reserve.md)
+- **Multi-Channel Sync** → [Multi-Channel Sync](versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md) (Versori) or [Standalone](standalone/multi-channel-inventory-sync.md)
+- **Inter-Location Transfers** → [Inter-Location Transfers](versori/business-examples/inter-location-transfers.md)
+- **Pre-Orders** → [Pre-Order Allocation](versori/business-examples/pre-order-allocation.md)
+
+---
+
+## 💡 Quick Recommendations
+
+### For Beginners
+Start with these guides (easiest to hardest):
+
+1. **[Field Mapping Universal](patterns/field-mapping-universal.md)** - Learn core mapping concepts
+2. **[S3 CSV Batch API](standalone/s3-csv-batch-api.md)** - Simple standalone ingestion
+3. **[CSV Inventory Sync](versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Versori scheduled workflow
+4. **[XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)** - Webhook with advanced features
+
+### For Production Deployments
+These guides are production-tested:
+
+- **Inventory Ingestion**: [SFTP CSV Ingestion](versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
+- **Order Processing**: [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
+- **Data Extraction**: [GraphQL to Parquet Partitioned S3](standalone/graphql-to-parquet-partitioned-s3.md)
+- **State Management**: [KV State Management](versori/patterns/kv-state-management.md)
+
+### For Complex Integrations
+These guides show advanced patterns:
+
+- [Multi-Source Aggregation](standalone/multi-source-aggregation.md)
+- [Dropship Order Routing](versori/business-examples/dropship-order-routing.md)
+- [Flash Sale Reserve](versori/webhooks/template-webhook-flash-sale-reserve.md)
+- [Pre-Order Allocation](versori/business-examples/pre-order-allocation.md)
+
+---
+
+## 📖 How to Use These Templates
+
+### For Developers
+
+1. **Pick a template** - Use the decision tree above or browse by use case
+2. **Copy the code** - All examples are production-ready
+3. **Customize** environment variables and configurations
+4. **Test locally** with provided sample data
+5. **Deploy** using deployment options in each guide
+
+**Need Help?** Check our comprehensive [**FAQ**](faq.md) for troubleshooting.
+
+### For AI / LLM Prompts
+
+These templates are optimized for AI consumption:
+
+```
+Build a Versori connector that receives SFCC XML orders via HTTP webhook
+and creates orders in Fluent Commerce.
+
+Context: Use patterns from docs/01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md
+```
+
+AI gets **focused context** without API reference overload.
+
+---
+
+## ✅ What's Included in Each Template
+
+Every template provides:
+
+- ✅ **Complete working code** (400-800 lines)
+- ✅ **Real SDK methods** with proper usage
+- ✅ **Production patterns** from actual connectors
+- ✅ **Environment setup** and configuration
+- ✅ **Testing instructions** with sample data
+- ✅ **Deployment options** (Docker, Lambda, cron, etc.)
+- ✅ **Common issues** with solutions
+- ✅ **Related guides** for deeper dives
+
+---
+
+## 🚀 Quick Start Examples
+
+### Versori HTTP Webhook
+
+```typescript
+import { createClient, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+export default async function processOrder(ctx) {
+  const client = await createClient(ctx); // Auto-detects Versori context
+  const mapper = new GraphQLMutationMapper(mappingConfig, ctx.log, { fluentClient: client });
+  const result = await mapper.mapWithNodes(ctx.body, customResolvers);
+  
+  // Check success (errors are returned, not thrown)
+  if (!result.success) {
+    throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
+  }
+  
+  // Execute mutation (query is auto-generated in result)
+  return await client.graphql({ 
+    query: result.query, 
+    variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
+  });
+}
+```
+
+### Standalone Node.js Script
+
+```typescript
+import { createClient, S3DataSource, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+  },
+});
+
+const s3Source = new S3DataSource(config, logger);
+const mapper = new UniversalMapper(mappingConfig);
+const files = await s3Source.listFiles();
+// ... process files
+```
+
+---
+
+## 📚 Additional Resources
+
+- **[FAQ - Troubleshooting](faq.md)** - Consolidated solutions to common issues
+- **[API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete SDK method reference
+- **[SDK Philosophy](../00-START-HERE/sdk-philosophy.md)** - Design principles
+- **[Complete Documentation](../readme.md)** - All guides and references
+
+---
+
+## 🎓 Learning Path
+
+**New to SDK?**
+
+1. Start with [SDK Philosophy](../00-START-HERE/sdk-philosophy.md)
+2. Read [Getting Started](../00-START-HERE/getting-started.md)
+3. Pick a **Standalone** template (simpler, no Versori)
+4. Try a **Versori** template if deploying to Versori
+5. Use **Pattern** guides for specific concepts
+
+**Building Connectors?**
+
+1. Pick matching use case template
+2. Review **Pattern** guides for concepts
+3. Check [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) for details
+4. Deploy and monitor
+
+---
+
+## 📊 Template Statistics
+
+- **38+ Total Templates**
+  - 20 Versori Platform templates
+    - 7 Webhook-triggered workflows
+    - 6 Scheduled workflows (Batch API)
+    - 8 Event API templates
+    - 9 GraphQL mutation templates
+    - 3 Versori patterns
+    - 4 Business use case examples
+  - 9 Standalone Node.js/Deno templates
+  - 9 Reusable Pattern guides
+- **~15,000+ lines** of production-ready code
+- **100% tested** patterns from real connectors
+- **Organized by trigger type** for easy navigation
+
+---
+
+## 🆘 Still Can't Decide?
+
+### Answer These Questions:
+
+1. **Runtime**: Versori or Standalone?
+2. **Direction**: Ingestion (IN) or Extraction (OUT)?
+3. **Trigger**: Webhook, Schedule, or Manual?
+4. **Format**: CSV, XML, JSON, or Parquet?
+5. **Complexity**: Simple, Medium, or High?
+
+**Then use the decision tree above to find your template!**
+
+---
+
+## 🆘 Need Help?
+
+- **Issues**: [GitHub Issues](https://github.com/fluentcommerce/fc-connect-sdk/issues)
+- **Documentation**: [Complete Docs](../readme.md)
+- **API Reference**: [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)
+- **Troubleshooting**: [FAQ](faq.md)
+- **Examples**: Check individual template files
+
+---
+
+*Last Updated: 2025-01-27*