@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md

@@ -1,1906 +1,1906 @@
----
-template_id: tpl-webhook-asn-purchase-order
-canonical_filename: template-webhook-asn-purchase-order.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: webhook-xml-json-asn
-destination: fluent-graphql
-entity: inventory-receipt
-format: xml-json
-logging: versori
-status: stable
-features:
-  - webhook-signature-validation
-  - batched-events
-  - attribute-transformation
-  - memory-management
-  - enhanced-logging
----
-
-# Template: Webhook - ASN & Purchase Order Processing
-
-**Template Version:** 2.0.0
-**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
-**🆕 Version 2.0.0 Enhancements:**
-- ✅ **Webhook Signature Validation** - Secure webhook verification with HMAC-SHA256
-- ✅ **Batched Events** - Process events in optimized batches to reduce API calls
-- ✅ **Attribute Transformation** - Handle nested arrays and complex data structures
-- ✅ **Memory Management** - Clear large arrays after processing batches
-- ✅ **Enhanced Logging** - Track batch processing and event submission with emoji indicators
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Process Advanced Ship Notices (ASN) from 3PL warehouse and create expected inventory receipts in Fluent Commerce
-
-**Complexity**: Medium-High
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~750 lines (modular structure)
-
----
-
-## STEP 1: Understand This Template
-
-**What This Template Does:**
-
-- HTTP webhook endpoint receiving ASN data from 3PL/WMS
-- XML/JSON parsing for ASN payload (EDI 856 compatible structure)
-- GraphQL mutation to create expected inventory receipts
-- Container/pallet tracking support
-- Cross-dock scenario handling (direct fulfillment without storage)
-- Expected date calculation (carrier transit time)
-- Custom resolvers for address normalization and SKU validation
-- Audit trail and notification system
-- Error handling for duplicate ASN prevention
-- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
-
-**Key SDK Components:**
-
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `GraphQLMutationMapper` - ASN → GraphQL mutation mapping
-- `XMLParserService` / `JSONParserService` - ASN parsing (EDI 856 format)
-- Native Versori `log` - Use `log` from context
-
-**Entity Type:**
-
-- **InventoryReceipt** - Fluent entity for expected inventory
-- **GraphQL Mutation** - Uses `createInventoryReceipt` mutation
-
-**Critical Patterns:**
-
-- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes ASN in background
-- **External JSON Config**: Mapping configuration in separate JSON file (`config/asn-mapping.json`)
-- **Modular Architecture**: Separate services, workflows, config, types folders
-- **Background Processing**: Long-running operations (GraphQL mutations, validation) happen asynchronously
-- **Error Handling**: Comprehensive error handling with duplicate detection
-
-**When to Use This Template:**
-
-- ✅ ASN processing from 3PL/WMS systems
-- ✅ EDI 856 format (XML or JSON)
-- ✅ Need fast webhook response (don't wait for receipt creation)
-- ✅ Container/pallet tracking
-- ✅ Cross-dock scenarios
-
-**When NOT to Use:**
-
-- ❌ Bulk ASN processing (use Batch API or scheduled workflows)
-- ❌ Real-time inventory updates (use Event API)
-- ❌ Need synchronous receipt creation (wait for result before responding)
-
----
-
-## STEP 2: Implementation Prompt for Claude Code
-
-**Copy this prompt and send to Claude Code to generate the complete implementation:**
-
-```
-Create a Versori webhook workflow for ASN (Advanced Ship Notice) processing to Fluent Commerce.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhook)
-2. Source: ASN data via HTTP POST webhook (XML or JSON, EDI 856 format)
-3. Destination: Fluent Commerce GraphQL API (createInventoryReceipt mutation)
-4. Format: XML or JSON (EDI 856 compatible)
-5. Entity: InventoryReceipt (GraphQL mutation)
-
-KEY FEATURES:
-- Sync + fire-and-forget pattern (fast webhook response, background processing)
-- External JSON mapping configuration (config/asn-mapping.json)
-- Modular architecture (workflows/, services/, config/, types/)
-- XML/JSON parsing with EDI 856 structure support
-- GraphQLMutationMapper for ASN → GraphQL transformation
-- Custom resolvers for address normalization and SKU validation
-- Duplicate ASN detection and prevention
-- Audit trail (save input/output files)
-
-CRITICAL REQUIREMENTS:
-1. Webhook Mode: response: { mode: 'sync' } (fast response)
-2. Background Processing: Fire-and-forget pattern (no await on long operations)
-3. Mapping Config: External JSON file (config/asn-mapping.json)
-4. Modular Structure: Separate services/, config/, types/ folders
-5. Native Logging: Use log from context (no LoggingService)
-6. Error Handling: Duplicate detection, comprehensive error responses
-
-SDK METHODS TO USE:
-- createClient({ ...ctx, log }) - Pass full Versori context
-- new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client }) - Initialize mapper
-- mapper.mapWithNodes(asnData, customResolvers, context) - Map ASN with custom resolvers (REQUIRED for custom resolvers)
-- mapWithNodes() now returns query automatically (no need for buildMutation())
-- client.graphql({ query, variables }) - Execute GraphQL mutation
-
-FORBIDDEN PATTERNS:
-- ❌ Inline mapping config (use external JSON)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ LoggingService (use native log from context)
-- ❌ All code in one file (use modular structure)
-- ❌ async mode webhook (use sync + fire-and-forget)
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. WEBHOOK RECEIVED                                         │
-│    POST https://{workspace}.versori.run/process-asn          │
-│    Content-Type: application/xml or application/json         │
-│    Body: <ShipNotice>...</ShipNotice> or { ... }            │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
-│    - Check fluent_commerce connection exists                 │
-│    - Validate ASN payload present                            │
-│    - Return HTTP 200 OK immediately                         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3a. Initialize Fluent Client                        │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3b. Parse ASN (XML or JSON)                         │  │
-│    │     - XMLParserService or JSONParserService          │  │
-│    │     - Extract ASN identifier                         │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3c. Check for Duplicates                             │  │
-│    │     - Query Fluent for existing receipt              │  │
-│    │     - Return early if duplicate                      │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3d. Map ASN to GraphQL Variables                    │  │
-│    │     - Load mapping config from JSON                 │  │
-│    │     - GraphQLMutationMapper.map()                    │  │
-│    │     - Apply custom resolvers                        │  │
-│    │     - Returns { success, data, query, context }     │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3e. Execute GraphQL Mutation                        │  │
-│    │     - client.graphql({ query: result.query,         │  │
-│    │                        variables: result.variables })│  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3g. Save Audit Trail (Optional)                      │  │
-│    │     - asn-input.json                                │  │
-│    │     - mapped-variables.json                         │  │
-│    │     - graphql-response.json                          │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Background Processing** | ~1000-3000ms | ❌ No (fire-and-forget) |
-| **Total Response Time** | ~10-50ms | ✅ Fast response |
-
-**Key Benefit**: Webhook caller receives immediate acknowledgment (~50ms) while ASN processing happens in background (~2-3s).
-
----
-
-## STEP 4: Production Modular Structure
-
-> **✅ This section shows the COMPLETE production-ready modular structure.**
-> All files are shown with proper imports/exports and folder organization.
-
-### Complete Project Structure
-
-```
-asn-purchase-order-processing/
-├── package.json                              # Dependencies and Versori config
-├── index.ts                                  # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── asn-receipt.ts               # Webhook: Receive ASN notifications
-    │
-    ├── services/
-    │   └── asn-processing.service.ts        # Shared orchestration logic (reusable)
-    │
-    ├── resolvers/
-    │   └── asn-resolvers.ts                 # Custom resolvers for transformations
-    │
-    ├── config/
-    │   └── asn-mapping.json                 # Mapping configuration (external JSON)
-    │
-    └── types/
-        └── asn.types.ts                     # TypeScript interfaces
-```
-
-**Why This Structure?**
-
-- ✅ **Clear separation**: Webhook handlers vs business logic
-- ✅ **Reusable services**: ASN processing logic can be reused
-- ✅ **External config**: Mapping changes don't require code changes
-- ✅ **Custom resolvers**: Separate file for complex transformations
-- ✅ **Type safety**: TypeScript interfaces for better IDE support
-- ✅ **Scalable**: Easy to add new ASN formats or processing steps
-
----
-
-## SDK Methods Used
-
-```typescript
-// Core SDK imports
-import {
-  createClient,
-  GraphQLMutationMapper,
-  XMLParserService,
-  JSONParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Versori imports
-import { webhook } from '@versori/run';
-import { Buffer } from 'node:buffer';                     // Required for Versori runtime
-
-// Key methods
-const logger = { info, warn, error, debug };             // Map Versori log to SDK Logger interface
-const client = await createClient({ ...ctx, log: logger }); // Auto-detects Versori context
-new GraphQLMutationMapper(config, logger, { fluentClient: client });       // Map ASN to GraphQL (uses logger adapter)
-new XMLParserService();                                  // Parse ASN XML (EDI 856)
-mapper.mapWithNodes(asnData, resolvers, context);        // Apply mapping with custom logic
-// mapWithNodes() now returns query automatically - use result.query
-client.graphql({ query, variables });                    // Execute mutation
-```
-
----
-
-## Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-asn-purchase-order-processing/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── asn-receipt.ts           # Webhook: Receive ASN notifications
-    │
-    ├── services/
-    │   └── asn-processing.service.ts     # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── asn-mapping.json             # Mapping configuration
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Scalable (add new workflows without cluttering)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Easy to modify individual workflows without affecting others
-
----
-
-## Complete Working Code
-
-### 1. Entry Point: `index.ts`
-
-```typescript
-/**
- * Entry point - Export all workflows for Versori platform
- *
- * This file exports all workflows to be registered with Versori.
- * Each workflow is defined in its own file for better organization.
- *
- * MEMORY INTERPRETER PATTERN:
- * Versori's interpreter reads this file and registers all exported workflows.
- * Do NOT use dynamic imports or conditional exports.
- */
-
-// Webhook workflows
-export { processAsnWebhook } from './workflows/webhook/asn-receipt';
-export { manualAsnTest } from './workflows/webhook/asn-receipt';
-export { healthCheck } from './workflows/webhook/asn-receipt';
-```
-
-### 2. Main Webhook Workflow: `workflows/webhook/asn-receipt.ts`
-
-```typescript
-/**
- * ASN (Advanced Ship Notice) Processing Webhook
- *
- * Receives ASN notifications from Acme 3PL/WMS and creates expected inventory
- * receipts in Fluent Commerce.
- *
- * ASN = Advanced Ship Notice (EDI 856) - notification that shipment is on the way
- *
- * Flow:
- * 1. Receive ASN webhook (XML or JSON payload from 3PL)
- * 2. Parse ASN structure (shipment header, containers, items)
- * 3. Map to Fluent expected receipt format
- * 4. Calculate expected arrival date (based on carrier and transit time)
- * 5. Create inventory receipt mutation (creates expected inventory)
- * 6. Send confirmation response to 3PL
- * 7. Optional: Send notification to warehouse ops team
- */
-import { webhook } from '@versori/run';
-import { Buffer } from 'node:buffer'; // Required for Versori runtime
-import {
-  createClient,
-  GraphQLMutationMapper,
-  XMLParserService,
-  JSONParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-import { asnResolvers } from '../../resolvers/asn-resolvers';
-import asnMappingConfig from '../../mappings/asn-to-fluent-receipt.json' with { type: 'json' };
-
-/**
- * Main ASN webhook endpoint
- * Expects POST with XML or JSON ASN payload
- */
-export const processAsnWebhook = webhook('process-asn', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    }),
-    onError: (ctx, error) => new Response(JSON.stringify({
-      success: false,
-      error: error.message,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check mapping configuration JSON and verify source paths match incoming ASN structure'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : 'Review error details and check ASN payload structure',
-      timestamp: new Date().toISOString()
-    }), {
-      status: 500,
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
-}, async (ctx) => {
-  const { log, fetch, activation, connections, openKv } = ctx;
-  const startTime = Date.now();
-
-  log.info('🚚 [ASN] Processing Advanced Ship Notice');
-
-  // ? Enhanced: Configuration validation
-  if (!connections || !connections.fluent_commerce) {
-    log.error('❌ [ASN] Configuration error: Missing fluent_commerce connection', {
-      recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials'
-    });
-    throw new Error('Missing fluent_commerce connection');
-  }
-
-  try {
-    // =================================================================
-    // STEP 1: EXTRACT AND PARSE ASN PAYLOAD
-    // =================================================================
-    // Get webhook payload
-    // Supports both XML (EDI 856 format) and JSON
-    const rawPayload = activation?.body;
-    const contentType = activation?.headers?.['content-type'] || 'application/json';
-
-    log.info('📦 [ASN] Payload received', {
-      contentType,
-      payloadSize: JSON.stringify(rawPayload).length,
-    });
-
-    // Determine format and parse
-    let asnData: any;
-    if (contentType.includes('xml') || contentType.includes('text')) {
-      // Parse XML ASN (EDI 856 format)
-      log.info('📄 [ASN] Parsing XML payload');
-      const xmlParser = new XMLParserService();
-      asnData = await xmlParser.parse(rawPayload);
-      log.debug('✅ [ASN] XML parsed successfully', { rootKeys: Object.keys(asnData) });
-    } else {
-      // Assume JSON format
-      log.info('📝 [ASN] Processing JSON payload');
-      asnData = rawPayload;
-    }
-
-    // Extract ASN identifier for tracking
-    // Common paths: ASN.shipment_id, ShipNotice.shipment_number, etc.
-    const asnId =
-      asnData?.ShipNotice?.['@shipment_id'] ||
-      asnData?.ASN?.shipment_number ||
-      asnData?.shipmentId ||
-      'UNKNOWN';
-
-    log.info(`🔍 [ASN] Processing ASN: ${asnId}`);
-
-    // =================================================================
-    // STEP 2: CREATE FLUENT CLIENT
-    // =================================================================
-    // Create SDK logger adapter to map Versori log to SDK Logger interface
-    const logger = {
-      info: (msg: string, ...args: any[]) => log.info(msg, ...args),
-      warn: (msg: string, ...args: any[]) => log.warn(msg, ...args),
-      error: (msg: string, ...args: any[]) => log.error(msg, ...args),
-      debug: (msg: string, ...args: any[]) => log.debug?.(msg, ...args) || log.info(msg, ...args)
-    };
-
-    // Create context for SDK client factory
-    const fluentClient = await createClient({ ...ctx, log: logger }); // Auto-detects Versori context
-
-    log.info('✅ [ASN] Fluent client initialized');
-
-    // =================================================================
-    // STEP 3: VALIDATE CONNECTION
-    // =================================================================
-    log.info('🔌 [ASN] Validating Fluent connection');
-    await fluentClient.validateConnection();
-    log.info('✅ [ASN] Connection validated successfully');
-
-    // =================================================================
-    // STEP 4: VALIDATE ASN (PREVENT DUPLICATES)
-    // =================================================================
-    // Query existing receipts to check if ASN already processed
-    // IMPORTANT: Prevents duplicate expected inventory from same ASN
-    log.info('🔍 [ASN] Checking for duplicate ASN');
-    const duplicateCheckQuery = `
-      query CheckExistingReceipt($ref: String!) {
-        inventoryQuantities(ref: $ref, first: 1) {
-          edges {
-            node {
-              id
-              ref
-              status
-            }
-          }
-        }
-      }`;
-
-    const duplicateCheck = await fluentClient.graphql({
-      query: duplicateCheckQuery,
-      variables: {
-        ref: `ASN-${asnId}`,  // Use ASN ID as ref
-      },
-    });
-
-    const existingReceipt = duplicateCheck.data?.inventoryQuantities?.edges?.[0]?.node;
-
-    if (existingReceipt) {
-      log.warn('⚠️ [ASN] Duplicate detected - ASN already processed', {
-        asnId,
-        existingReceiptId: existingReceipt.id,
-        existingStatus: existingReceipt.status,
-      });
-
-      return {
-        success: false,
-        message: 'ASN already processed (duplicate)',
-        asnId,
-        existingReceiptId: existingReceipt.id,
-        timestamp: new Date().toISOString(),
-        duration: `${Date.now() - startTime}ms`,
-      };
-    }
-
-    // =================================================================
-    // STEP 5: SAVE RAW ASN FOR AUDIT TRAIL (KV Storage - Versori-compatible)
-    // =================================================================
-    log.info('Saving raw payload for audit trail');
-    try {
-      const kv = openKv(':project:');
-      const timestamp = new Date().toISOString();
-      const auditKey = ['asn', 'audit', asnId, timestamp];
-      
-      // Save original payload
-      await kv.set([...auditKey, 'asn-raw'], asnData);
-      
-      log.info('Raw ASN saved to KV storage', { asnId, timestamp });
-    } catch (kvError: any) {
-      log.warn('Failed to save ASN to KV storage', { error: kvError.message });
-    }
-
-    // =================================================================
-    // STEP 6: MAP ASN TO FLUENT EXPECTED RECEIPT FORMAT
-    // =================================================================
-    log.info('🗺️ [ASN] Starting ASN mapping');
-    const mappingStartTime = Date.now();
-
-    const mapper = new GraphQLMutationMapper(
-      asnMappingConfig as any,
-      logger,
-      { fluentClient: fluentClient as any }
-    );
-
-    // Apply mapping with custom resolvers
-    // Context includes fluentClient for API calls (SKU validation, etc.)
-    // Returns MapWithNodesResult with query auto-generated!
-    const mappingResult = await mapper.mapWithNodes(asnData, asnResolvers, {
-      fluentClient: fluentClient as any,
-      asnId,
-      config: {
-        retailerId: process.env.RETAILER_ID || '1',
-        defaultLocation: process.env.DEFAULT_RECEIVING_LOCATION || 'DC-RECEIVING',
-      },
-      helpers: {
-        fluentClient: fluentClient as any,
-      },
-    });
-
-    if (!mappingResult.success) {
-      log.error('❌ [ASN] Mapping failed', {
-        errors: mappingResult.errors,
-        recommendation: 'Check mapping configuration JSON and verify source paths match incoming ASN structure'
-      });
-      throw new Error(`ASN mapping failed: ${mappingResult.errors?.join(', ')}`);
-    }
-
-    log.info('✅ [ASN] Mapping successful', {
-      asnId,
-      itemCount: mappingResult.data?.items?.length || 0,
-      duration: `${Date.now() - mappingStartTime}ms`,
-    });
-
-    // Save mapped data to KV storage
-    try {
-      const kv = openKv(':project:');
-      const timestamp = new Date().toISOString();
-      const auditKey = ['asn', 'audit', asnId, timestamp, 'fluent-mapped'];
-      await kv.set(auditKey, mappingResult.data);
-    } catch (kvError: any) {
-      log.warn('Failed to save mapped data to KV', { error: kvError.message });
-    }
-
-    // =================================================================
-    // STEP 7: CREATE EXPECTED RECEIPT IN FLUENT
-    // =================================================================
-    log.info('🚀 [ASN] Creating expected inventory receipt in Fluent');
-    const mutationStartTime = Date.now();
-
-    // mapWithNodes() auto-generates query - no need to call buildMutation()!
-    // Execute mutation (use result.variables for GraphQL execution)
-    const receiptResult = await fluentClient.graphql({
-      query: mappingResult.query,
-      variables: mappingResult.variables  // ✅ Use variables (wrapped if fields pattern)
-    });
-
-    if (receiptResult.errors) {
-      log.error('❌ [ASN] Receipt creation failed', {
-        errors: receiptResult.errors,
-        recommendation: 'Check GraphQL mutation structure and field types',
-      });
-      throw new Error(`Receipt creation failed: ${JSON.stringify(receiptResult.errors)}`);
-    }
-
-    const createdReceipt = receiptResult.data?.createInventoryQuantity;
-
-    log.info('✅ [ASN] Expected receipt created successfully', {
-      receiptId: createdReceipt?.id,
-      asnId,
-      duration: `${Date.now() - mutationStartTime}ms`,
-    });
-
-    // Save Fluent response to KV storage
-    try {
-      const kv = openKv(':project:');
-      const timestamp = new Date().toISOString();
-      const auditKey = ['asn', 'audit', asnId, timestamp, 'fluent-response'];
-      await kv.set(auditKey, receiptResult);
-    } catch (kvError: any) {
-      log.warn('Failed to save Fluent response to KV', { error: kvError.message });
-    }
-
-    // =================================================================
-    // STEP 8: RETURN SUCCESS RESPONSE TO 3PL
-    // =================================================================
-    const totalDuration = Date.now() - startTime;
-    log.info('🎉 [ASN] Processing completed successfully', {
-      asnId,
-      totalDuration: `${totalDuration}ms`,
-    });
-
-    return {
-      success: true,
-      message: 'ASN processed successfully',
-      data: {
-        asnId,
-        receiptId: createdReceipt?.id,
-        receiptRef: createdReceipt?.ref,
-        itemCount: mappingResult.data?.items?.length || 0,
-        expectedDate: mappingResult.data?.expectedOn,
-        timestamp: new Date().toISOString(),
-        duration: `${totalDuration}ms`,
-      },
-    };
-  } catch (error: any) {
-    // ? Enhanced: Error logging with recommendations
-    const totalDuration = Date.now() - startTime;
-    const errorDetails = {
-      message: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      duration: `${totalDuration}ms`,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check mapping configuration JSON and verify source paths match incoming ASN structure'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : error.message?.includes('validation') || error.message?.includes('required')
-        ? 'Ensure all required fields are present in the ASN webhook payload'
-        : error.message?.includes('duplicate') || error.message?.includes('already processed')
-        ? 'ASN may have been processed already - check existing receipts'
-        : 'Review error details and check ASN payload structure',
-    };
-    log.error('❌ [ASN] Processing failed', errorDetails);
-    throw error; // Let response handler catch it
-  }
-});
-
-/**
- * Manual test endpoint - Upload ASN file for testing
- */
-export const manualAsnTest = webhook('manual-asn-test', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    }),
-    onError: (ctx, error) => new Response(JSON.stringify({
-      success: false,
-      error: error.message,
-      recommendation: 'Check that test ASN file exists at expected path'
-    }), {
-      status: 400,
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
-}, async (ctx) => {
-  const { log } = ctx;
-  const startTime = Date.now();
-
-  log.info('🧪 [TEST] Manual ASN test triggered');
-
-  // Load test ASN data
-  const testAsnPath = path.join(__dirname, '../../data/test-asn-sample.json');
-  if (!fs.existsSync(testAsnPath)) {
-    log.error('❌ [TEST] Test ASN file not found', { expectedPath: testAsnPath });
-    return {
-      success: false,
-      error: 'Test ASN file not found',
-      expectedPath: testAsnPath,
-      recommendation: 'Create test-asn-sample.json in the data/ directory',
-    };
-  }
-
-  const testAsnData = JSON.parse(fs.readFileSync(testAsnPath, 'utf-8'));
-
-  log.info('✅ [TEST] Test ASN loaded', {
-    asnId: testAsnData.shipmentId,
-    duration: `${Date.now() - startTime}ms`,
-  });
-
-  // Note: In production, you would trigger the main workflow via HTTP call
-  // This is a simplified test endpoint for development
-  return {
-    success: true,
-    message: 'Test ASN loaded - trigger processAsnWebhook endpoint to process',
-    asnId: testAsnData.shipmentId,
-    testDataPath: testAsnPath,
-    duration: `${Date.now() - startTime}ms`,
-  };
-});
-
-/**
- * Health check endpoint
- */
-export const healthCheck = webhook('health-check', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
-}, async (ctx) => {
-  const { log } = ctx;
-  log.info('💚 [HEALTH] Health check requested');
-
-  return {
-    success: true,
-    service: 'ASN Processing',
-    status: 'healthy',
-    timestamp: new Date().toISOString(),
-  };
-});
-```
-
-### 2. Mapping Configuration: `mappings/asn-to-fluent-receipt.json`
-
-```json
-{
-  "direction": "ingest",
-  "sourceFormat": "json",
-  "mutation": "createInventoryQuantity",
-  "fields": {
-    "ref": {
-      "resolver": "custom.generateReceiptRef",
-      "comment": "Generate unique receipt ref from ASN ID (REQUIRED)"
-    },
-    "locationRef": {
-      "source": "destination.location_code",
-      "resolver": "custom.normalizeLocationRef",
-      "comment": "Receiving location (REQUIRED)"
-    },
-    "type": {
-      "value": "EXPECTED",
-      "comment": "Expected inventory type (REQUIRED)"
-    },
-    "status": {
-      "value": "EXPECTED",
-      "comment": "Status is EXPECTED until physically received (REQUIRED)"
-    },
-    "expectedOn": {
-      "resolver": "custom.calculateExpectedDate",
-      "comment": "Calculate based on ship date + carrier transit time (REQUIRED)"
-    },
-    "carrier": {
-      "source": "shipment.carrier.name",
-      "resolver": "sdk.trim",
-      "comment": "Shipping carrier name"
-    },
-    "trackingNumber": {
-      "source": "shipment.tracking_number",
-      "resolver": "sdk.trim",
-      "comment": "Carrier tracking number"
-    },
-    "retailer.id": {
-      "resolver": "custom.getRetailerId",
-      "comment": "Retailer ID from config (REQUIRED)"
-    },
-    "items": {
-      "source": "shipment.items",
-      "isArray": true,
-      "comment": "Line items in the shipment",
-      "fields": {
-        "skuRef": {
-          "source": "$.sku",
-          "resolver": "custom.validateAndNormalizeSku",
-          "comment": "Product SKU - must exist in Fluent (REQUIRED)"
-        },
-        "qty": {
-          "source": "$.quantity",
-          "resolver": "sdk.parseInt",
-          "comment": "Expected quantity (REQUIRED)"
-        },
-        "lotNumber": {
-          "source": "$.lot_number",
-          "required": false,
-          "comment": "Lot/batch number if applicable"
-        },
-        "serialNumbers": {
-          "source": "$.serial_numbers",
-          "isArray": true,
-          "required": false,
-          "comment": "Serial numbers for serialized items"
-        },
-        "expiryDate": {
-          "source": "$.expiry_date",
-          "resolver": "sdk.formatDate",
-          "required": false,
-          "comment": "Expiration date for perishable goods"
-        },
-        "containerRef": {
-          "source": "$.container_id",
-          "required": false,
-          "comment": "Container/pallet ID for tracking"
-        }
-      }
-    },
-    "containers": {
-      "source": "shipment.containers",
-      "isArray": true,
-      "required": false,
-      "comment": "Container/pallet tracking information",
-      "fields": {
-        "containerRef": {
-          "source": "$.container_id",
-          "resolver": "sdk.toString"
-        },
-        "containerType": {
-          "source": "$.type",
-          "resolver": "sdk.uppercase",
-          "comment": "PALLET, CARTON, TOTE, etc."
-        },
-        "weight": {
-          "source": "$.weight",
-          "resolver": "sdk.parseFloat"
-        },
-        "weightUnit": {
-          "source": "$.weight_unit",
-          "defaultValue": "LBS"
-        },
-        "dimensions": {
-          "resolver": "custom.formatDimensions",
-          "comment": "Format as length x width x height"
-        }
-      }
-    },
-    "attributes": {
-      "resolver": "custom.buildReceiptAttributes",
-      "comment": "Custom attributes for audit trail and tracking"
-    }
-  }
-}
-```
-
-### 3. Custom Resolvers: `src/resolvers/asn-resolvers.ts`
-
-```typescript
-/**
- * ASN Processing Custom Resolvers
- */
-import type { ResolverMap } from './types';
-
-export const asnResolvers: ResolverMap = {
-  /**
-   * Generate unique receipt reference from ASN ID
-   */
-  'custom.generateReceiptRef': (value: any, data: any, config: any, helpers: any): string => {
-    const asnId = data.shipmentId || data.shipment_id || data.ASN?.id || 'UNKNOWN';
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
-    return `ASN-${asnId}-${timestamp}`;
-  },
-
-  /**
-   * Normalize location reference
-   * Handles different location code formats from various 3PLs
-   */
-  'custom.normalizeLocationRef': (value: any, data: any, config: any, helpers: any): string => {
-    if (!value) {
-      return config.defaultLocation || 'DC-RECEIVING';
-    }
-
-    // Normalize format: uppercase, replace spaces with hyphens
-    return String(value)
-      .toUpperCase()
-      .trim()
-      .replace(/\s+/g, '-');
-  },
-
-  /**
-   * Calculate expected arrival date
-   * Based on ship date + carrier transit time
-   */
-  'custom.calculateExpectedDate': (value: any, data: any, config: any, helpers: any): string => {
-    const shipDate = data.shipment?.ship_date || data.shipDate;
-    const carrier = data.shipment?.carrier?.name || data.carrier;
-
-    // Default transit times by carrier (in days)
-    const transitTimes: Record<string, number> = {
-      'FEDEX_GROUND': 3,
-      'FEDEX_EXPRESS': 1,
-      'UPS_GROUND': 3,
-      'UPS_NEXT_DAY': 1,
-      'USPS': 5,
-      'DHL': 2,
-      'FREIGHT': 7,
-      'DEFAULT': 3,
-    };
-
-    // Get transit time
-    const carrierKey = String(carrier).toUpperCase().replace(/\s+/g, '_');
-    const transitDays = transitTimes[carrierKey] || transitTimes.DEFAULT;
-
-    // Calculate expected date
-    const shipDateObj = shipDate ? new Date(shipDate) : new Date();
-    shipDateObj.setDate(shipDateObj.getDate() + transitDays);
-
-    return shipDateObj.toISOString();
-  },
-
-  /**
-   * Validate and normalize SKU
-   * Ensures SKU exists in Fluent Commerce (ASYNC)
-   */
-  'custom.validateAndNormalizeSku': async (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Promise<string> => {
-    const sku = String(value).trim().toUpperCase();
-
-    if (!helpers.fluentClient) {
-      // If no client, just return normalized SKU
-      return sku;
-    }
-
-    // Query Fluent to validate SKU exists
-    const query = `
-      query ValidateSku($skuRef: [String!]) {
-        products(ref: $skuRef, first: 1) {
-          edges {
-            node {
-              id
-              ref
-            }
-          }
-        }
-      }`;
-
-    try {
-      const result = await helpers.fluentClient.graphql({
-        query,
-        variables: { skuRef: [sku] },
-      });
-
-      const product = result.data?.products?.edges?.[0]?.node;
-
-      if (!product) {
-        helpers.logger?.warn('SKU not found in Fluent Commerce', { sku });
-        // Option 1: Throw error to halt processing
-        // throw new Error(`SKU not found: ${sku}`);
-
-        // Option 2: Return SKU anyway (let Fluent validation handle it)
-        return sku;
-      }
-
-      helpers.logger?.debug('SKU validated successfully', { sku, productId: product.id });
-      return sku;
-    } catch (error: any) {
-      helpers.logger?.error('SKU validation failed', { sku, error: error.message });
-      return sku;  // Return SKU anyway, let Fluent handle validation
-    }
-  },
-
-  /**
-   * Get retailer ID from configuration
-   */
-  'custom.getRetailerId': (value: any, data: any, config: any, helpers: any): string => {
-    return config.retailerId || process.env.RETAILER_ID || '1';
-  },
-
-  /**
-   * Format dimensions as string
-   */
-  'custom.formatDimensions': (value: any, data: any, config: any, helpers: any): string => {
-    const container = data;  // Current container object
-    const length = container.length || 0;
-    const width = container.width || 0;
-    const height = container.height || 0;
-    const unit = container.dimension_unit || 'IN';
-
-    if (!length && !width && !height) {
-      return '';
-    }
-
-    return `${length} x ${width} x ${height} ${unit}`;
-  },
-
-  /**
-   * Build receipt attributes for audit trail
-   */
-  'custom.buildReceiptAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    // Add ASN metadata
-    attributes.push({
-      name: 'asn_id',
-      type: 'STRING',
-      value: config.asnId || data.shipmentId || 'UNKNOWN',
-    });
-
-    attributes.push({
-      name: 'asn_received_date',
-      type: 'STRING',
-      value: new Date().toISOString(),
-    });
-
-    // Add carrier tracking
-    if (data.shipment?.tracking_number) {
-      attributes.push({
-        name: 'tracking_number',
-        type: 'STRING',
-        value: data.shipment.tracking_number,
-      });
-    }
-
-    // Add origin information
-    if (data.shipment?.origin) {
-      attributes.push({
-        name: 'origin_location',
-        type: 'STRING',
-        value: JSON.stringify(data.shipment.origin),
-      });
-    }
-
-    // Add PO number if present
-    if (data.purchase_order_number) {
-      attributes.push({
-        name: 'po_number',
-        type: 'STRING',
-        value: data.purchase_order_number,
-      });
-    }
-
-    // Cross-dock flag
-    if (data.shipment?.is_crossdock) {
-      attributes.push({
-        name: 'is_crossdock',
-        type: 'BOOLEAN',
-        value: 'true',
-      });
-    }
-
-    return attributes;
-  },
-};
-```
-
-### 4. Sample ASN Test Data: `data/test-asn-sample.json`
-
-```json
-{
-  "shipmentId": "ASN-20250117-001",
-  "purchase_order_number": "PO-12345",
-  "shipment": {
-    "ship_date": "2025-01-17T10:00:00Z",
-    "carrier": {
-      "name": "FEDEX_GROUND",
-      "scac": "FXFE"
-    },
-    "tracking_number": "123456789012",
-    "origin": {
-      "name": "Acme Distribution Center",
-      "address": "123 Warehouse Dr",
-      "city": "Memphis",
-      "state": "TN",
-      "zip": "38101"
-    },
-    "is_crossdock": false,
-    "items": [
-      {
-        "sku": "ACME-WIDGET-100",
-        "quantity": 50,
-        "lot_number": "LOT20250115",
-        "container_id": "PALLET-001"
-      },
-      {
-        "sku": "ACME-GADGET-200",
-        "quantity": 100,
-        "container_id": "PALLET-001"
-      },
-      {
-        "sku": "ACME-TOOL-300",
-        "quantity": 25,
-        "lot_number": "LOT20250110",
-        "expiry_date": "2026-01-10T00:00:00Z",
-        "container_id": "PALLET-002"
-      }
-    ],
-    "containers": [
-      {
-        "container_id": "PALLET-001",
-        "type": "PALLET",
-        "weight": 250.5,
-        "weight_unit": "LBS",
-        "length": 48,
-        "width": 40,
-        "height": 60,
-        "dimension_unit": "IN"
-      },
-      {
-        "container_id": "PALLET-002",
-        "type": "PALLET",
-        "weight": 180.0,
-        "weight_unit": "LBS",
-        "length": 48,
-        "width": 40,
-        "height": 48,
-        "dimension_unit": "IN"
-      }
-    ]
-  },
-  "destination": {
-    "location_code": "DC-01-RECEIVING",
-    "name": "Distribution Center 01",
-    "address": "789 Commerce Pkwy",
-    "city": "Atlanta",
-    "state": "GA",
-    "zip": "30301"
-  }
-}
-```
-
-### 5. Package Configuration: `package.json`
-
-```json
-{
-  "name": "asn-processing-connector",
-  "version": "1.0.0",
-  "description": "ASN/Purchase Order processing connector for Acme 3PL integration",
-  "versori": {
-    "workflows": "./workflows/asn-receipt.ts"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "deploy": "versori deploy",
-    "logs": "versori logs",
-    "test": "node -r ts-node/register workflows/asn-receipt.ts"
-  }
-}
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: ASN Duplicate Prevention
-
-**Check for Existing Receipt Before Creating:**
-
-```typescript
-// Query existing receipts using ASN ID as ref
-const duplicateCheckQuery = `
-  query CheckExistingReceipt($ref: String!) {
-    inventoryQuantities(ref: $ref, first: 1) {
-      edges {
-        node {
-          id
-          ref
-          status
-        }
-      }
-    }
-  }`;
-
-const duplicateCheck = await fluentClient.graphql({
-  query: duplicateCheckQuery,
-  variables: {
-    ref: `ASN-${asnId}`,  // Unique ref from ASN shipment ID
-  },
-});
-
-const existingReceipt = duplicateCheck.data?.inventoryQuantities?.edges?.[0]?.node;
-
-if (existingReceipt) {
-  // ASN already processed - return early
-  return {
-    status: 200,
-    body: {
-      success: false,
-      message: 'ASN already processed (duplicate)',
-      existingReceiptId: existingReceipt.id,
-    },
-  };
-}
-```
-
-**Why this matters**: 3PLs may send duplicate ASN notifications due to:
-- Network retries
-- System glitches
-- Manual re-sends
-- Webhook replay
-
-**Without duplicate prevention**: Creates duplicate expected inventory, causing:
-- Inflated ATP calculations
-- Incorrect stock levels
-- Failed physical receipts (already expected)
-
-**Best practices**:
-- Always use ASN shipment ID as part of receipt ref
-- Query before creating
-- Log duplicate attempts for monitoring
-
-### Pattern 2: Expected Date Calculation
-
-**Calculate Arrival Date Based on Carrier Transit Time:**
-
-```typescript
-'custom.calculateExpectedDate': (value, data, config, helpers) => {
-  const shipDate = data.shipment?.ship_date || data.shipDate;
-  const carrier = data.shipment?.carrier?.name || data.carrier;
-
-  // Transit time lookup by carrier
-  const transitTimes = {
-    'FEDEX_GROUND': 3,
-    'FEDEX_EXPRESS': 1,
-    'UPS_GROUND': 3,
-    'UPS_NEXT_DAY': 1,
-    'USPS': 5,
-    'DHL': 2,
-    'FREIGHT': 7,
-    'DEFAULT': 3,
-  };
-
-  const carrierKey = String(carrier).toUpperCase().replace(/\s+/g, '_');
-  const transitDays = transitTimes[carrierKey] || transitTimes.DEFAULT;
-
-  // Add transit days to ship date
-  const shipDateObj = shipDate ? new Date(shipDate) : new Date();
-  shipDateObj.setDate(shipDateObj.getDate() + transitDays);
-
-  return shipDateObj.toISOString();
-};
-```
-
-**Why this matters**: Expected date drives:
-- ATP calculations (Available To Promise)
-- Allocation timing
-- Customer promise dates
-- Warehouse receiving schedules
-
-**Improvements for production:**
-
-```typescript
-// Add business days logic (skip weekends)
-function addBusinessDays(date: Date, days: number): Date {
-  let result = new Date(date);
-  let addedDays = 0;
-
-  while (addedDays < days) {
-    result.setDate(result.getDate() + 1);
-    // Skip weekends (0 = Sunday, 6 = Saturday)
-    if (result.getDay() !== 0 && result.getDay() !== 6) {
-      addedDays++;
-    }
-  }
-
-  return result;
-}
-
-// Add holiday logic
-const holidays = ['2025-01-01', '2025-07-04', '2025-12-25'];
-
-function isHoliday(date: Date): boolean {
-  const dateStr = date.toISOString().substring(0, 10);
-  return holidays.includes(dateStr);
-}
-```
-
-### Pattern 3: SKU Validation (Async Resolver)
-
-**Validate SKU Exists in Fluent Before Creating Receipt:**
-
-```typescript
-'custom.validateAndNormalizeSku': async (value, data, config, helpers) => {
-  const sku = String(value).trim().toUpperCase();
-
-  // Query Fluent to check if SKU exists
-  const query = `
-    query ValidateSku($skuRef: [String!]) {
-      products(ref: $skuRef, first: 1) {
-        edges {
-          node {
-            id
-            ref
-          }
-        }
-      }
-    }
-  `;
-
-  const result = await helpers.fluentClient.graphql({
-    query,
-    variables: { skuRef: [sku] },
-  });
-
-  const product = result.data?.products?.edges?.[0]?.node;
-
-  if (!product) {
-    // SKU not found - options:
-    // 1. Throw error (halt processing)
-    throw new Error(`SKU not found: ${sku}`);
-
-    // 2. Log warning and continue (let Fluent handle validation)
-    helpers.logger?.warn('SKU not found', { sku });
-    return sku;
-  }
-
-  return sku;
-};
-```
-
-**When to use SKU validation**:
-- ✅ **3PL sends ASN before products are created** (prevents invalid receipts)
-- ✅ **SKU format differs between systems** (can normalize)
-- ✅ **Need early warning** (alert on unknown SKUs)
-
-**When to skip**:
-- ❌ **High volume** (100+ SKUs per ASN = slow)
-- ❌ **Products always exist** (pre-synced)
-- ❌ **Performance critical** (let Fluent validation handle it)
-
-**Performance optimization**:
-
-```typescript
-// Cache SKU validation results in resolver context
-const skuCache = new Map<string, boolean>();
-
-if (skuCache.has(sku)) {
-  return sku;  // Already validated
-}
-
-const isValid = await validateSku(sku);
-skuCache.set(sku, isValid);
-```
-
-### Pattern 4: Container/Pallet Tracking
-
-**Track Containers for Efficient Receiving:**
-
-```json
-{
-  "containers": {
-    "source": "shipment.containers",
-    "isArray": true,
-    "fields": {
-      "containerRef": {
-        "source": "$.container_id"
-      },
-      "containerType": {
-        "source": "$.type",
-        "comment": "PALLET, CARTON, TOTE"
-      },
-      "weight": { "source": "$.weight" },
-      "dimensions": {
-        "resolver": "custom.formatDimensions"
-      }
-    }
-  }
-}
-```
-
-**Why container tracking matters**:
-- **Warehouse efficiency**: Receive entire pallets at once
-- **Put-away optimization**: Route containers to correct zones
-- **Cross-docking**: Direct routing without storage
-- **Audit trail**: Track physical container movement
-
-**Real-world example**:
-
-```
-ASN contains:
-- PALLET-001: 50x WIDGET + 100x GADGET
-- PALLET-002: 25x TOOL (refrigerated)
-
-Warehouse receives PALLET-001 first:
-→ Scan PALLET-001 barcode
-→ System shows all 2 SKUs on pallet
-→ Receive all at once (no item-by-item scan)
-→ PALLET-002 still expected
-```
-
-### Pattern 5: Cross-Dock Scenario Handling
-
-**Handle Direct Fulfillment Without Storage:**
-
-```typescript
-// In ASN data
-{
-  "shipment": {
-    "is_crossdock": true,  // Flag for cross-dock shipment
-    "destination_order_ref": "ORDER-12345"
-  }
-}
-
-// Custom resolver for cross-dock logic
-'custom.buildReceiptAttributes': (value, data, config, helpers) => {
-  const attributes = [];
-
-  if (data.shipment?.is_crossdock) {
-    attributes.push({
-      name: 'is_crossdock',
-      type: 'BOOLEAN',
-      value: 'true',
-    });
-
-    // Link to destination order
-    if (data.shipment.destination_order_ref) {
-      attributes.push({
-        name: 'crossdock_order_ref',
-        type: 'STRING',
-        value: data.shipment.destination_order_ref,
-      });
-    }
-
-    // Mark for expedited processing
-    attributes.push({
-      name: 'receiving_priority',
-      type: 'STRING',
-      value: 'HIGH',
-    });
-  }
-
-  return attributes;
-};
-```
-
-**Cross-dock workflow**:
-1. **ASN received** with `is_crossdock: true`
-2. **Expected receipt created** with crossdock flag
-3. **Physical receipt** → immediately allocated to order
-4. **Skip put-away** → direct to packing station
-5. **Ship within hours** (not days)
-
-**Benefits**:
-- Faster order fulfillment (same-day ship)
-- Reduced warehouse touches
-- Lower storage costs
-- Improved customer satisfaction
-
-### Pattern 6: XML vs JSON Payload Handling
-
-**Support Multiple Payload Formats:**
-
-```typescript
-// Detect content type from header
-const contentType = ctx.activation?.headers?.['content-type'] || 'application/json';
-
-let asnData: any;
-
-if (contentType.includes('xml') || contentType.includes('text')) {
-  // Parse XML (EDI 856 format)
-  const xmlParser = new XMLParserService();
-  asnData = await xmlParser.parse(rawPayload);
-} else {
-  // Assume JSON
-  asnData = rawPayload;
-}
-```
-
-**Why support both**:
-- **Enterprise 3PLs**: Often use EDI 856 XML format
-- **Modern 3PLs**: Use JSON REST APIs
-- **Flexibility**: Handle both without separate connectors
-
-**EDI 856 XML example**:
-
-```xml
-<?xml version="1.0"?>
-<ShipNotice shipment_id="ASN-001">
-  <Shipment>
-    <ShipDate>2025-01-17</ShipDate>
-    <Carrier name="FEDEX_GROUND"/>
-    <Items>
-      <Item>
-        <SKU>WIDGET-100</SKU>
-        <Quantity>50</Quantity>
-      </Item>
-    </Items>
-  </Shipment>
-</ShipNotice>
-```
-
-**JSON equivalent**:
-
-```json
-{
-  "shipmentId": "ASN-001",
-  "shipment": {
-    "ship_date": "2025-01-17",
-    "carrier": { "name": "FEDEX_GROUND" },
-    "items": [
-      { "sku": "WIDGET-100", "quantity": 50 }
-    ]
-  }
-}
-```
-
----
-
-## Testing the Workflow
-
-### 1. Create Test ASN File
-
-Already provided in `data/test-asn-sample.json` above.
-
-### 2. Deploy to Versori Platform
-
-```bash
-cd asn-processing-connector
-npm install
-
-# Deploy to Versori
-versori deploy
-
-# Or if using Versori CLI v2+
-npx @versori/cli deploy
-```
-
-### 3. Configure Versori Connections
-
-In the Versori console:
-
-1. Add **Fluent Commerce** connection:
-   - Connection name: `fluent_commerce`
-   - Base URL: `https://api.fluentcommerce.com/graphql`
-   - Auth: OAuth2 (Client Credentials or Password Grant)
-   - Client ID, Client Secret, Username, Password
-
-2. Configure activation variables (optional):
-   - `OUTPUT_DIR`: Where to save audit files
-   - `RETAILER_ID`: Fluent retailer ID
-   - `DEFAULT_RECEIVING_LOCATION`: Default location code
-
-### 4. Test via Webhook
-
-```bash
-# Get webhook URL from Versori console (usually https://{workspace}.versori.io/{workflow})
-# Example: https://acme.versori.io/processAsnWebhook
-
-# Send test ASN via HTTP POST
-curl -X POST https://acme.versori.io/processAsnWebhook \
-  -H "Content-Type: application/json" \
-  -d @data/test-asn-sample.json
-```
-
-### 5. Use Manual Test Endpoint
-
-```bash
-# Trigger manual test (loads test-asn-sample.json from filesystem)
-curl https://acme.versori.io/manualAsnTest
-```
-
-### 6. Check Health Endpoint
-
-```bash
-# Verify service is running
-curl https://acme.versori.io/healthCheck
-```
-
-### 7. Verify in Fluent Commerce
-
-1. Log into Fluent Console
-2. Navigate to Inventory → Inventory Quantities
-3. Filter by status: `EXPECTED`
-4. Find receipt with ref `ASN-20250117-001-*`
-5. Verify:
-   - Quantity matches ASN
-   - Expected date calculated correctly
-   - Attributes contain ASN metadata
-
-### 8. Monitor Logs
-
-```bash
-# View real-time logs in Versori console
-# Or use Versori CLI
-versori logs --workflow=processAsnWebhook --tail
-
-# Check for errors
-versori logs --workflow=processAsnWebhook --level=error
-```
-
----
-
-## Common Issues and Solutions
-
-### Issue 1: "Duplicate entity" Error from Fluent
-
-**Symptoms:**
-- GraphQL error: "Entity with ref already exists"
-- Second ASN attempt fails
-
-**Root Cause:**
-- Receipt ref not unique
-- Missing timestamp in ref generation
-
-**Solution:**
-
-```typescript
-// Ensure unique ref with timestamp
-'custom.generateReceiptRef': (value, data, config, helpers) => {
-  const asnId = data.shipmentId || 'UNKNOWN';
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
-  const randomSuffix = Math.random().toString(36).substring(7);
-
-  // Format: ASN-{asnId}-{timestamp}-{random}
-  return `ASN-${asnId}-${timestamp}-${randomSuffix}`;
-};
-```
-
-### Issue 2: Expected Date in the Past
-
-**Symptoms:**
-- Expected date shows yesterday or earlier
-- ATP calculation incorrect
-
-**Root Cause:**
-- Ship date from ASN is in the past
-- Transit time calculation starts from old date
-
-**Solution:**
-
-```typescript
-'custom.calculateExpectedDate': (value, data, config, helpers) => {
-  const shipDate = data.shipment?.ship_date;
-  const carrier = data.shipment?.carrier?.name;
-
-  // Get transit days
-  const transitDays = getTransitDays(carrier);
-
-  // Use ship date or TODAY (whichever is later)
-  const baseDate = shipDate ? new Date(shipDate) : new Date();
-  const today = new Date();
-
-  // If ship date is in the past, use today instead
-  if (baseDate < today) {
-    baseDate.setTime(today.getTime());
-  }
-
-  // Add transit days
-  baseDate.setDate(baseDate.getDate() + transitDays);
-
-  return baseDate.toISOString();
-};
-```
-
-### Issue 3: SKU Validation Slows Processing
-
-**Symptoms:**
-- Webhook timeouts (>30 seconds)
-- ASN with 100+ SKUs fails
-
-**Root Cause:**
-- Sequential SKU validation queries
-- No caching
-
-**Solution:**
-
-```typescript
-// Batch validate all SKUs in single query
-'custom.validateAllSkus': async (value, data, config, helpers) => {
-  const allSkus = data.shipment?.items?.map((item: any) => item.sku) || [];
-
-  // Single query for all SKUs
-  const query = `
-    query ValidateSkus($skuRefs: [String!]) {
-      products(ref: $skuRefs, first: 200) {
-        edges {
-          node {
-            id
-            ref
-          }
-        }
-      }
-    }
-  `;
-
-  const result = await helpers.fluentClient.graphql({
-    query,
-    variables: { skuRefs: allSkus },
-  });
-
-  const validSkus = new Set(
-    result.data?.products?.edges?.map((e: any) => e.node.ref) || []
-  );
-
-  // Check for missing SKUs
-  const missingSkus = allSkus.filter(sku => !validSkus.has(sku));
-
-  if (missingSkus.length > 0) {
-    helpers.logger?.warn('Invalid SKUs found', { missingSkus });
-    // Option: throw error or continue
-  }
-
-  return validSkus;
-};
-```
-
-### Issue 4: Cross-Dock Flag Not Honored
-
-**Symptoms:**
-- Cross-dock inventory goes to storage
-- Fulfillment delayed
-
-**Root Cause:**
-- Warehouse receiving app doesn't check attributes
-- Missing workflow trigger
-
-**Solution:**
-
-**Option 1: Create Fluent Event**
-
-```typescript
-// After creating receipt, send event if cross-dock
-if (data.shipment?.is_crossdock) {
-  await fluentClient.sendEvent({
-    name: 'InventoryReceiptCrossDock',
-    entityType: 'INVENTORY',
-    entityRef: createdReceipt.ref,
-    data: {
-      destinationOrderRef: data.shipment.destination_order_ref,
-      priority: 'HIGH',
-    },
-  });
-}
-```
-
-**Option 2: Use Different Location**
-
-```typescript
-// Route cross-dock receipts to special location
-'custom.normalizeLocationRef': (value, data, config, helpers) => {
-  if (data.shipment?.is_crossdock) {
-    return 'DC-CROSSDOCK-RECEIVING';  // Special receiving zone
-  }
-  return value || config.defaultLocation;
-};
-```
-
-### Issue 5: Container Data Not Appearing in Fluent
-
-**Symptoms:**
-- Container/pallet info missing in Fluent
-- Can't track containers
-
-**Root Cause:**
-- Fluent schema doesn't support container arrays directly
-- Need to use attributes
-
-**Solution:**
-
-```typescript
-// Store containers in attributes instead of separate field
-'custom.buildReceiptAttributes': (value, data, config, helpers) => {
-  const attributes = [];
-
-  // Serialize containers to JSON attribute
-  if (data.shipment?.containers) {
-    attributes.push({
-      name: 'containers',
-      type: 'STRING',
-      value: JSON.stringify(data.shipment.containers),
-    });
-
-    // Also add container count for quick reference
-    attributes.push({
-      name: 'container_count',
-      type: 'INTEGER',
-      value: String(data.shipment.containers.length),
-    });
-  }
-
-  return attributes;
-};
-```
-
----
-
-## Related Guides
-
-- **[Connector Platform Scheduled: Cycle Count Reconciliation](../workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md)** - Reconciliation patterns
-- **[Universal Mapping Guide](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Field mapping patterns
-- **[GraphQL Mutation Mapper](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)** - Mutation generation
-- **[XML Parsing Guide](../../../02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md)** - EDI 856 XML handling
-
----
-
-## Production Checklist
-
-Before deploying to production:
-- [ ] Test with real 3PL ASN payloads (XML and JSON)
-- [ ] Configure carrier transit times based on real data
-- [ ] Set up duplicate ASN monitoring/alerting
-- [ ] Verify SKU validation strategy (batch vs individual)
-- [ ] Test cross-dock scenario if applicable
-- [ ] Configure webhook retry policy in 3PL system
-- [ ] Set up error notifications (email/Slack)
-- [ ] Document ASN format variations by 3PL
-- [ ] Test large ASNs (100+ SKUs, 10+ containers)
-- [ ] Verify expected date business days logic
-
----
-
-## Performance Considerations
-
-**Large ASNs (100+ SKUs)**:
-
-```typescript
-// Process items in chunks to avoid timeouts
-const CHUNK_SIZE = 50;
-
-for (let i = 0; i < items.length; i += CHUNK_SIZE) {
-  const chunk = items.slice(i, i + CHUNK_SIZE);
-  await processItemChunk(chunk);
-}
-```
-
-**High Volume (1000+ ASNs/day)**:
-
-```typescript
-// Use background processing with queue
-export const processAsnWebhookQueued = webhook('queue-asn', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
-      status: 202, // Accepted
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
-}, async (ctx) => {
-  const { activation } = ctx;
-
-  // Immediately acknowledge receipt
-  const asnId = activation.body.shipmentId;
-
-  // Queue for async processing (implement queueAsnForProcessing function)
-  await queueAsnForProcessing(asnId, activation.body);
-
-  return {
-    success: true,
-    message: 'ASN queued for processing',
-    asnId,
-  };
-});
-```
-
----
-
-## Next Steps
-
-1. **Add Receipt Confirmation**: Send confirmation back to 3PL when receipt created
-2. **Implement Discrepancy Handling**: Compare expected vs actual receipt quantities
-3. **Add Serial Number Tracking**: Full serial number lifecycle
-4. **Integrate with WMS**: Push ASN to warehouse management system
-5. **Build Dashboard**: Real-time ASN status monitoring
-6. **Add Carrier Tracking Integration**: Real-time shipment tracking via carrier APIs
-
----
-
-**Need Help?**
-- Review SDK documentation: `/docs/readme.md`
-- Check example connectors: `/connectors/Sample versori connectors/`
-- Connector platform documentation: Check your platform's docs
+---
+template_id: tpl-webhook-asn-purchase-order
+canonical_filename: template-webhook-asn-purchase-order.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: webhook-xml-json-asn
+destination: fluent-graphql
+entity: inventory-receipt
+format: xml-json
+logging: versori
+status: stable
+features:
+  - webhook-signature-validation
+  - batched-events
+  - attribute-transformation
+  - memory-management
+  - enhanced-logging
+---
+
+# Template: Webhook - ASN & Purchase Order Processing
+
+**Template Version:** 2.0.0
+**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+**🆕 Version 2.0.0 Enhancements:**
+- ✅ **Webhook Signature Validation** - Secure webhook verification with HMAC-SHA256
+- ✅ **Batched Events** - Process events in optimized batches to reduce API calls
+- ✅ **Attribute Transformation** - Handle nested arrays and complex data structures
+- ✅ **Memory Management** - Clear large arrays after processing batches
+- ✅ **Enhanced Logging** - Track batch processing and event submission with emoji indicators
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Process Advanced Ship Notices (ASN) from 3PL warehouse and create expected inventory receipts in Fluent Commerce
+
+**Complexity**: Medium-High
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~750 lines (modular structure)
+
+---
+
+## STEP 1: Understand This Template
+
+**What This Template Does:**
+
+- HTTP webhook endpoint receiving ASN data from 3PL/WMS
+- XML/JSON parsing for ASN payload (EDI 856 compatible structure)
+- GraphQL mutation to create expected inventory receipts
+- Container/pallet tracking support
+- Cross-dock scenario handling (direct fulfillment without storage)
+- Expected date calculation (carrier transit time)
+- Custom resolvers for address normalization and SKU validation
+- Audit trail and notification system
+- Error handling for duplicate ASN prevention
+- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
+
+**Key SDK Components:**
+
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `GraphQLMutationMapper` - ASN → GraphQL mutation mapping
+- `XMLParserService` / `JSONParserService` - ASN parsing (EDI 856 format)
+- Native Versori `log` - Use `log` from context
+
+**Entity Type:**
+
+- **InventoryReceipt** - Fluent entity for expected inventory
+- **GraphQL Mutation** - Uses `createInventoryReceipt` mutation
+
+**Critical Patterns:**
+
+- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes ASN in background
+- **External JSON Config**: Mapping configuration in separate JSON file (`config/asn-mapping.json`)
+- **Modular Architecture**: Separate services, workflows, config, types folders
+- **Background Processing**: Long-running operations (GraphQL mutations, validation) happen asynchronously
+- **Error Handling**: Comprehensive error handling with duplicate detection
+
+**When to Use This Template:**
+
+- ✅ ASN processing from 3PL/WMS systems
+- ✅ EDI 856 format (XML or JSON)
+- ✅ Need fast webhook response (don't wait for receipt creation)
+- ✅ Container/pallet tracking
+- ✅ Cross-dock scenarios
+
+**When NOT to Use:**
+
+- ❌ Bulk ASN processing (use Batch API or scheduled workflows)
+- ❌ Real-time inventory updates (use Event API)
+- ❌ Need synchronous receipt creation (wait for result before responding)
+
+---
+
+## STEP 2: Implementation Prompt for Claude Code
+
+**Copy this prompt and send to Claude Code to generate the complete implementation:**
+
+```
+Create a Versori webhook workflow for ASN (Advanced Ship Notice) processing to Fluent Commerce.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhook)
+2. Source: ASN data via HTTP POST webhook (XML or JSON, EDI 856 format)
+3. Destination: Fluent Commerce GraphQL API (createInventoryReceipt mutation)
+4. Format: XML or JSON (EDI 856 compatible)
+5. Entity: InventoryReceipt (GraphQL mutation)
+
+KEY FEATURES:
+- Sync + fire-and-forget pattern (fast webhook response, background processing)
+- External JSON mapping configuration (config/asn-mapping.json)
+- Modular architecture (workflows/, services/, config/, types/)
+- XML/JSON parsing with EDI 856 structure support
+- GraphQLMutationMapper for ASN → GraphQL transformation
+- Custom resolvers for address normalization and SKU validation
+- Duplicate ASN detection and prevention
+- Audit trail (save input/output files)
+
+CRITICAL REQUIREMENTS:
+1. Webhook Mode: response: { mode: 'sync' } (fast response)
+2. Background Processing: Fire-and-forget pattern (no await on long operations)
+3. Mapping Config: External JSON file (config/asn-mapping.json)
+4. Modular Structure: Separate services/, config/, types/ folders
+5. Native Logging: Use log from context (no LoggingService)
+6. Error Handling: Duplicate detection, comprehensive error responses
+
+SDK METHODS TO USE:
+- createClient({ ...ctx, log }) - Pass full Versori context
+- new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client }) - Initialize mapper
+- mapper.mapWithNodes(asnData, customResolvers, context) - Map ASN with custom resolvers (REQUIRED for custom resolvers)
+- mapWithNodes() now returns query automatically (no need for buildMutation())
+- client.graphql({ query, variables }) - Execute GraphQL mutation
+
+FORBIDDEN PATTERNS:
+- ❌ Inline mapping config (use external JSON)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ LoggingService (use native log from context)
+- ❌ All code in one file (use modular structure)
+- ❌ async mode webhook (use sync + fire-and-forget)
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. WEBHOOK RECEIVED                                         │
+│    POST https://{workspace}.versori.run/process-asn          │
+│    Content-Type: application/xml or application/json         │
+│    Body: <ShipNotice>...</ShipNotice> or { ... }            │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
+│    - Check fluent_commerce connection exists                 │
+│    - Validate ASN payload present                            │
+│    - Return HTTP 200 OK immediately                         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3a. Initialize Fluent Client                        │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3b. Parse ASN (XML or JSON)                         │  │
+│    │     - XMLParserService or JSONParserService          │  │
+│    │     - Extract ASN identifier                         │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3c. Check for Duplicates                             │  │
+│    │     - Query Fluent for existing receipt              │  │
+│    │     - Return early if duplicate                      │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3d. Map ASN to GraphQL Variables                    │  │
+│    │     - Load mapping config from JSON                 │  │
+│    │     - GraphQLMutationMapper.map()                    │  │
+│    │     - Apply custom resolvers                        │  │
+│    │     - Returns { success, data, query, context }     │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3e. Execute GraphQL Mutation                        │  │
+│    │     - client.graphql({ query: result.query,         │  │
+│    │                        variables: result.variables })│  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3g. Save Audit Trail (Optional)                      │  │
+│    │     - asn-input.json                                │  │
+│    │     - mapped-variables.json                         │  │
+│    │     - graphql-response.json                          │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Background Processing** | ~1000-3000ms | ❌ No (fire-and-forget) |
+| **Total Response Time** | ~10-50ms | ✅ Fast response |
+
+**Key Benefit**: Webhook caller receives immediate acknowledgment (~50ms) while ASN processing happens in background (~2-3s).
+
+---
+
+## STEP 4: Production Modular Structure
+
+> **✅ This section shows the COMPLETE production-ready modular structure.**
+> All files are shown with proper imports/exports and folder organization.
+
+### Complete Project Structure
+
+```
+asn-purchase-order-processing/
+├── package.json                              # Dependencies and Versori config
+├── index.ts                                  # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── asn-receipt.ts               # Webhook: Receive ASN notifications
+    │
+    ├── services/
+    │   └── asn-processing.service.ts        # Shared orchestration logic (reusable)
+    │
+    ├── resolvers/
+    │   └── asn-resolvers.ts                 # Custom resolvers for transformations
+    │
+    ├── config/
+    │   └── asn-mapping.json                 # Mapping configuration (external JSON)
+    │
+    └── types/
+        └── asn.types.ts                     # TypeScript interfaces
+```
+
+**Why This Structure?**
+
+- ✅ **Clear separation**: Webhook handlers vs business logic
+- ✅ **Reusable services**: ASN processing logic can be reused
+- ✅ **External config**: Mapping changes don't require code changes
+- ✅ **Custom resolvers**: Separate file for complex transformations
+- ✅ **Type safety**: TypeScript interfaces for better IDE support
+- ✅ **Scalable**: Easy to add new ASN formats or processing steps
+
+---
+
+## SDK Methods Used
+
+```typescript
+// Core SDK imports
+import {
+  createClient,
+  GraphQLMutationMapper,
+  XMLParserService,
+  JSONParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Versori imports
+import { webhook } from '@versori/run';
+import { Buffer } from 'node:buffer';                     // Required for Versori runtime
+
+// Key methods
+const logger = { info, warn, error, debug };             // Map Versori log to SDK Logger interface
+const client = await createClient({ ...ctx, log: logger }); // Auto-detects Versori context
+new GraphQLMutationMapper(config, logger, { fluentClient: client });       // Map ASN to GraphQL (uses logger adapter)
+new XMLParserService();                                  // Parse ASN XML (EDI 856)
+mapper.mapWithNodes(asnData, resolvers, context);        // Apply mapping with custom logic
+// mapWithNodes() now returns query automatically - use result.query
+client.graphql({ query, variables });                    // Execute mutation
+```
+
+---
+
+## Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+asn-purchase-order-processing/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── asn-receipt.ts           # Webhook: Receive ASN notifications
+    │
+    ├── services/
+    │   └── asn-processing.service.ts     # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── asn-mapping.json             # Mapping configuration
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Scalable (add new workflows without cluttering)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Easy to modify individual workflows without affecting others
+
+---
+
+## Complete Working Code
+
+### 1. Entry Point: `index.ts`
+
+```typescript
+/**
+ * Entry point - Export all workflows for Versori platform
+ *
+ * This file exports all workflows to be registered with Versori.
+ * Each workflow is defined in its own file for better organization.
+ *
+ * MEMORY INTERPRETER PATTERN:
+ * Versori's interpreter reads this file and registers all exported workflows.
+ * Do NOT use dynamic imports or conditional exports.
+ */
+
+// Webhook workflows
+export { processAsnWebhook } from './workflows/webhook/asn-receipt';
+export { manualAsnTest } from './workflows/webhook/asn-receipt';
+export { healthCheck } from './workflows/webhook/asn-receipt';
+```
+
+### 2. Main Webhook Workflow: `workflows/webhook/asn-receipt.ts`
+
+```typescript
+/**
+ * ASN (Advanced Ship Notice) Processing Webhook
+ *
+ * Receives ASN notifications from Acme 3PL/WMS and creates expected inventory
+ * receipts in Fluent Commerce.
+ *
+ * ASN = Advanced Ship Notice (EDI 856) - notification that shipment is on the way
+ *
+ * Flow:
+ * 1. Receive ASN webhook (XML or JSON payload from 3PL)
+ * 2. Parse ASN structure (shipment header, containers, items)
+ * 3. Map to Fluent expected receipt format
+ * 4. Calculate expected arrival date (based on carrier and transit time)
+ * 5. Create inventory receipt mutation (creates expected inventory)
+ * 6. Send confirmation response to 3PL
+ * 7. Optional: Send notification to warehouse ops team
+ */
+import { webhook } from '@versori/run';
+import { Buffer } from 'node:buffer'; // Required for Versori runtime
+import {
+  createClient,
+  GraphQLMutationMapper,
+  XMLParserService,
+  JSONParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+import { asnResolvers } from '../../resolvers/asn-resolvers';
+import asnMappingConfig from '../../mappings/asn-to-fluent-receipt.json' with { type: 'json' };
+
+/**
+ * Main ASN webhook endpoint
+ * Expects POST with XML or JSON ASN payload
+ */
+export const processAsnWebhook = webhook('process-asn', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    }),
+    onError: (ctx, error) => new Response(JSON.stringify({
+      success: false,
+      error: error.message,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check mapping configuration JSON and verify source paths match incoming ASN structure'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : 'Review error details and check ASN payload structure',
+      timestamp: new Date().toISOString()
+    }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  }
+}, async (ctx) => {
+  const { log, fetch, activation, connections, openKv } = ctx;
+  const startTime = Date.now();
+
+  log.info('🚚 [ASN] Processing Advanced Ship Notice');
+
+  // ? Enhanced: Configuration validation
+  if (!connections || !connections.fluent_commerce) {
+    log.error('❌ [ASN] Configuration error: Missing fluent_commerce connection', {
+      recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials'
+    });
+    throw new Error('Missing fluent_commerce connection');
+  }
+
+  try {
+    // =================================================================
+    // STEP 1: EXTRACT AND PARSE ASN PAYLOAD
+    // =================================================================
+    // Get webhook payload
+    // Supports both XML (EDI 856 format) and JSON
+    const rawPayload = activation?.body;
+    const contentType = activation?.headers?.['content-type'] || 'application/json';
+
+    log.info('📦 [ASN] Payload received', {
+      contentType,
+      payloadSize: JSON.stringify(rawPayload).length,
+    });
+
+    // Determine format and parse
+    let asnData: any;
+    if (contentType.includes('xml') || contentType.includes('text')) {
+      // Parse XML ASN (EDI 856 format)
+      log.info('📄 [ASN] Parsing XML payload');
+      const xmlParser = new XMLParserService();
+      asnData = await xmlParser.parse(rawPayload);
+      log.debug('✅ [ASN] XML parsed successfully', { rootKeys: Object.keys(asnData) });
+    } else {
+      // Assume JSON format
+      log.info('📝 [ASN] Processing JSON payload');
+      asnData = rawPayload;
+    }
+
+    // Extract ASN identifier for tracking
+    // Common paths: ASN.shipment_id, ShipNotice.shipment_number, etc.
+    const asnId =
+      asnData?.ShipNotice?.['@shipment_id'] ||
+      asnData?.ASN?.shipment_number ||
+      asnData?.shipmentId ||
+      'UNKNOWN';
+
+    log.info(`🔍 [ASN] Processing ASN: ${asnId}`);
+
+    // =================================================================
+    // STEP 2: CREATE FLUENT CLIENT
+    // =================================================================
+    // Create SDK logger adapter to map Versori log to SDK Logger interface
+    const logger = {
+      info: (msg: string, ...args: any[]) => log.info(msg, ...args),
+      warn: (msg: string, ...args: any[]) => log.warn(msg, ...args),
+      error: (msg: string, ...args: any[]) => log.error(msg, ...args),
+      debug: (msg: string, ...args: any[]) => log.debug?.(msg, ...args) || log.info(msg, ...args)
+    };
+
+    // Create context for SDK client factory
+    const fluentClient = await createClient({ ...ctx, log: logger }); // Auto-detects Versori context
+
+    log.info('✅ [ASN] Fluent client initialized');
+
+    // =================================================================
+    // STEP 3: VALIDATE CONNECTION
+    // =================================================================
+    log.info('🔌 [ASN] Validating Fluent connection');
+    await fluentClient.validateConnection();
+    log.info('✅ [ASN] Connection validated successfully');
+
+    // =================================================================
+    // STEP 4: VALIDATE ASN (PREVENT DUPLICATES)
+    // =================================================================
+    // Query existing receipts to check if ASN already processed
+    // IMPORTANT: Prevents duplicate expected inventory from same ASN
+    log.info('🔍 [ASN] Checking for duplicate ASN');
+    const duplicateCheckQuery = `
+      query CheckExistingReceipt($ref: String!) {
+        inventoryQuantities(ref: $ref, first: 1) {
+          edges {
+            node {
+              id
+              ref
+              status
+            }
+          }
+        }
+      }`;
+
+    const duplicateCheck = await fluentClient.graphql({
+      query: duplicateCheckQuery,
+      variables: {
+        ref: `ASN-${asnId}`,  // Use ASN ID as ref
+      },
+    });
+
+    const existingReceipt = duplicateCheck.data?.inventoryQuantities?.edges?.[0]?.node;
+
+    if (existingReceipt) {
+      log.warn('⚠️ [ASN] Duplicate detected - ASN already processed', {
+        asnId,
+        existingReceiptId: existingReceipt.id,
+        existingStatus: existingReceipt.status,
+      });
+
+      return {
+        success: false,
+        message: 'ASN already processed (duplicate)',
+        asnId,
+        existingReceiptId: existingReceipt.id,
+        timestamp: new Date().toISOString(),
+        duration: `${Date.now() - startTime}ms`,
+      };
+    }
+
+    // =================================================================
+    // STEP 5: SAVE RAW ASN FOR AUDIT TRAIL (KV Storage - Versori-compatible)
+    // =================================================================
+    log.info('Saving raw payload for audit trail');
+    try {
+      const kv = openKv(':project:');
+      const timestamp = new Date().toISOString();
+      const auditKey = ['asn', 'audit', asnId, timestamp];
+      
+      // Save original payload
+      await kv.set([...auditKey, 'asn-raw'], asnData);
+      
+      log.info('Raw ASN saved to KV storage', { asnId, timestamp });
+    } catch (kvError: any) {
+      log.warn('Failed to save ASN to KV storage', { error: kvError.message });
+    }
+
+    // =================================================================
+    // STEP 6: MAP ASN TO FLUENT EXPECTED RECEIPT FORMAT
+    // =================================================================
+    log.info('🗺️ [ASN] Starting ASN mapping');
+    const mappingStartTime = Date.now();
+
+    const mapper = new GraphQLMutationMapper(
+      asnMappingConfig as any,
+      logger,
+      { fluentClient: fluentClient as any }
+    );
+
+    // Apply mapping with custom resolvers
+    // Context includes fluentClient for API calls (SKU validation, etc.)
+    // Returns MapWithNodesResult with query auto-generated!
+    const mappingResult = await mapper.mapWithNodes(asnData, asnResolvers, {
+      fluentClient: fluentClient as any,
+      asnId,
+      config: {
+        retailerId: process.env.RETAILER_ID || '1',
+        defaultLocation: process.env.DEFAULT_RECEIVING_LOCATION || 'DC-RECEIVING',
+      },
+      helpers: {
+        fluentClient: fluentClient as any,
+      },
+    });
+
+    if (!mappingResult.success) {
+      log.error('❌ [ASN] Mapping failed', {
+        errors: mappingResult.errors,
+        recommendation: 'Check mapping configuration JSON and verify source paths match incoming ASN structure'
+      });
+      throw new Error(`ASN mapping failed: ${mappingResult.errors?.join(', ')}`);
+    }
+
+    log.info('✅ [ASN] Mapping successful', {
+      asnId,
+      itemCount: mappingResult.data?.items?.length || 0,
+      duration: `${Date.now() - mappingStartTime}ms`,
+    });
+
+    // Save mapped data to KV storage
+    try {
+      const kv = openKv(':project:');
+      const timestamp = new Date().toISOString();
+      const auditKey = ['asn', 'audit', asnId, timestamp, 'fluent-mapped'];
+      await kv.set(auditKey, mappingResult.data);
+    } catch (kvError: any) {
+      log.warn('Failed to save mapped data to KV', { error: kvError.message });
+    }
+
+    // =================================================================
+    // STEP 7: CREATE EXPECTED RECEIPT IN FLUENT
+    // =================================================================
+    log.info('🚀 [ASN] Creating expected inventory receipt in Fluent');
+    const mutationStartTime = Date.now();
+
+    // mapWithNodes() auto-generates query - no need to call buildMutation()!
+    // Execute mutation (use result.variables for GraphQL execution)
+    const receiptResult = await fluentClient.graphql({
+      query: mappingResult.query,
+      variables: mappingResult.variables  // ✅ Use variables (wrapped if fields pattern)
+    });
+
+    if (receiptResult.errors) {
+      log.error('❌ [ASN] Receipt creation failed', {
+        errors: receiptResult.errors,
+        recommendation: 'Check GraphQL mutation structure and field types',
+      });
+      throw new Error(`Receipt creation failed: ${JSON.stringify(receiptResult.errors)}`);
+    }
+
+    const createdReceipt = receiptResult.data?.createInventoryQuantity;
+
+    log.info('✅ [ASN] Expected receipt created successfully', {
+      receiptId: createdReceipt?.id,
+      asnId,
+      duration: `${Date.now() - mutationStartTime}ms`,
+    });
+
+    // Save Fluent response to KV storage
+    try {
+      const kv = openKv(':project:');
+      const timestamp = new Date().toISOString();
+      const auditKey = ['asn', 'audit', asnId, timestamp, 'fluent-response'];
+      await kv.set(auditKey, receiptResult);
+    } catch (kvError: any) {
+      log.warn('Failed to save Fluent response to KV', { error: kvError.message });
+    }
+
+    // =================================================================
+    // STEP 8: RETURN SUCCESS RESPONSE TO 3PL
+    // =================================================================
+    const totalDuration = Date.now() - startTime;
+    log.info('🎉 [ASN] Processing completed successfully', {
+      asnId,
+      totalDuration: `${totalDuration}ms`,
+    });
+
+    return {
+      success: true,
+      message: 'ASN processed successfully',
+      data: {
+        asnId,
+        receiptId: createdReceipt?.id,
+        receiptRef: createdReceipt?.ref,
+        itemCount: mappingResult.data?.items?.length || 0,
+        expectedDate: mappingResult.data?.expectedOn,
+        timestamp: new Date().toISOString(),
+        duration: `${totalDuration}ms`,
+      },
+    };
+  } catch (error: any) {
+    // ? Enhanced: Error logging with recommendations
+    const totalDuration = Date.now() - startTime;
+    const errorDetails = {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      duration: `${totalDuration}ms`,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check mapping configuration JSON and verify source paths match incoming ASN structure'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : error.message?.includes('validation') || error.message?.includes('required')
+        ? 'Ensure all required fields are present in the ASN webhook payload'
+        : error.message?.includes('duplicate') || error.message?.includes('already processed')
+        ? 'ASN may have been processed already - check existing receipts'
+        : 'Review error details and check ASN payload structure',
+    };
+    log.error('❌ [ASN] Processing failed', errorDetails);
+    throw error; // Let response handler catch it
+  }
+});
+
+/**
+ * Manual test endpoint - Upload ASN file for testing
+ */
+export const manualAsnTest = webhook('manual-asn-test', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    }),
+    onError: (ctx, error) => new Response(JSON.stringify({
+      success: false,
+      error: error.message,
+      recommendation: 'Check that test ASN file exists at expected path'
+    }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  }
+}, async (ctx) => {
+  const { log } = ctx;
+  const startTime = Date.now();
+
+  log.info('🧪 [TEST] Manual ASN test triggered');
+
+  // Load test ASN data
+  const testAsnPath = path.join(__dirname, '../../data/test-asn-sample.json');
+  if (!fs.existsSync(testAsnPath)) {
+    log.error('❌ [TEST] Test ASN file not found', { expectedPath: testAsnPath });
+    return {
+      success: false,
+      error: 'Test ASN file not found',
+      expectedPath: testAsnPath,
+      recommendation: 'Create test-asn-sample.json in the data/ directory',
+    };
+  }
+
+  const testAsnData = JSON.parse(fs.readFileSync(testAsnPath, 'utf-8'));
+
+  log.info('✅ [TEST] Test ASN loaded', {
+    asnId: testAsnData.shipmentId,
+    duration: `${Date.now() - startTime}ms`,
+  });
+
+  // Note: In production, you would trigger the main workflow via HTTP call
+  // This is a simplified test endpoint for development
+  return {
+    success: true,
+    message: 'Test ASN loaded - trigger processAsnWebhook endpoint to process',
+    asnId: testAsnData.shipmentId,
+    testDataPath: testAsnPath,
+    duration: `${Date.now() - startTime}ms`,
+  };
+});
+
+/**
+ * Health check endpoint
+ */
+export const healthCheck = webhook('health-check', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  }
+}, async (ctx) => {
+  const { log } = ctx;
+  log.info('💚 [HEALTH] Health check requested');
+
+  return {
+    success: true,
+    service: 'ASN Processing',
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+  };
+});
+```
+
+### 2. Mapping Configuration: `mappings/asn-to-fluent-receipt.json`
+
+```json
+{
+  "direction": "ingest",
+  "sourceFormat": "json",
+  "mutation": "createInventoryQuantity",
+  "fields": {
+    "ref": {
+      "resolver": "custom.generateReceiptRef",
+      "comment": "Generate unique receipt ref from ASN ID (REQUIRED)"
+    },
+    "locationRef": {
+      "source": "destination.location_code",
+      "resolver": "custom.normalizeLocationRef",
+      "comment": "Receiving location (REQUIRED)"
+    },
+    "type": {
+      "value": "EXPECTED",
+      "comment": "Expected inventory type (REQUIRED)"
+    },
+    "status": {
+      "value": "EXPECTED",
+      "comment": "Status is EXPECTED until physically received (REQUIRED)"
+    },
+    "expectedOn": {
+      "resolver": "custom.calculateExpectedDate",
+      "comment": "Calculate based on ship date + carrier transit time (REQUIRED)"
+    },
+    "carrier": {
+      "source": "shipment.carrier.name",
+      "resolver": "sdk.trim",
+      "comment": "Shipping carrier name"
+    },
+    "trackingNumber": {
+      "source": "shipment.tracking_number",
+      "resolver": "sdk.trim",
+      "comment": "Carrier tracking number"
+    },
+    "retailer.id": {
+      "resolver": "custom.getRetailerId",
+      "comment": "Retailer ID from config (REQUIRED)"
+    },
+    "items": {
+      "source": "shipment.items",
+      "isArray": true,
+      "comment": "Line items in the shipment",
+      "fields": {
+        "skuRef": {
+          "source": "$.sku",
+          "resolver": "custom.validateAndNormalizeSku",
+          "comment": "Product SKU - must exist in Fluent (REQUIRED)"
+        },
+        "qty": {
+          "source": "$.quantity",
+          "resolver": "sdk.parseInt",
+          "comment": "Expected quantity (REQUIRED)"
+        },
+        "lotNumber": {
+          "source": "$.lot_number",
+          "required": false,
+          "comment": "Lot/batch number if applicable"
+        },
+        "serialNumbers": {
+          "source": "$.serial_numbers",
+          "isArray": true,
+          "required": false,
+          "comment": "Serial numbers for serialized items"
+        },
+        "expiryDate": {
+          "source": "$.expiry_date",
+          "resolver": "sdk.formatDate",
+          "required": false,
+          "comment": "Expiration date for perishable goods"
+        },
+        "containerRef": {
+          "source": "$.container_id",
+          "required": false,
+          "comment": "Container/pallet ID for tracking"
+        }
+      }
+    },
+    "containers": {
+      "source": "shipment.containers",
+      "isArray": true,
+      "required": false,
+      "comment": "Container/pallet tracking information",
+      "fields": {
+        "containerRef": {
+          "source": "$.container_id",
+          "resolver": "sdk.toString"
+        },
+        "containerType": {
+          "source": "$.type",
+          "resolver": "sdk.uppercase",
+          "comment": "PALLET, CARTON, TOTE, etc."
+        },
+        "weight": {
+          "source": "$.weight",
+          "resolver": "sdk.parseFloat"
+        },
+        "weightUnit": {
+          "source": "$.weight_unit",
+          "defaultValue": "LBS"
+        },
+        "dimensions": {
+          "resolver": "custom.formatDimensions",
+          "comment": "Format as length x width x height"
+        }
+      }
+    },
+    "attributes": {
+      "resolver": "custom.buildReceiptAttributes",
+      "comment": "Custom attributes for audit trail and tracking"
+    }
+  }
+}
+```
+
+### 3. Custom Resolvers: `src/resolvers/asn-resolvers.ts`
+
+```typescript
+/**
+ * ASN Processing Custom Resolvers
+ */
+import type { ResolverMap } from './types';
+
+export const asnResolvers: ResolverMap = {
+  /**
+   * Generate unique receipt reference from ASN ID
+   */
+  'custom.generateReceiptRef': (value: any, data: any, config: any, helpers: any): string => {
+    const asnId = data.shipmentId || data.shipment_id || data.ASN?.id || 'UNKNOWN';
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
+    return `ASN-${asnId}-${timestamp}`;
+  },
+
+  /**
+   * Normalize location reference
+   * Handles different location code formats from various 3PLs
+   */
+  'custom.normalizeLocationRef': (value: any, data: any, config: any, helpers: any): string => {
+    if (!value) {
+      return config.defaultLocation || 'DC-RECEIVING';
+    }
+
+    // Normalize format: uppercase, replace spaces with hyphens
+    return String(value)
+      .toUpperCase()
+      .trim()
+      .replace(/\s+/g, '-');
+  },
+
+  /**
+   * Calculate expected arrival date
+   * Based on ship date + carrier transit time
+   */
+  'custom.calculateExpectedDate': (value: any, data: any, config: any, helpers: any): string => {
+    const shipDate = data.shipment?.ship_date || data.shipDate;
+    const carrier = data.shipment?.carrier?.name || data.carrier;
+
+    // Default transit times by carrier (in days)
+    const transitTimes: Record<string, number> = {
+      'FEDEX_GROUND': 3,
+      'FEDEX_EXPRESS': 1,
+      'UPS_GROUND': 3,
+      'UPS_NEXT_DAY': 1,
+      'USPS': 5,
+      'DHL': 2,
+      'FREIGHT': 7,
+      'DEFAULT': 3,
+    };
+
+    // Get transit time
+    const carrierKey = String(carrier).toUpperCase().replace(/\s+/g, '_');
+    const transitDays = transitTimes[carrierKey] || transitTimes.DEFAULT;
+
+    // Calculate expected date
+    const shipDateObj = shipDate ? new Date(shipDate) : new Date();
+    shipDateObj.setDate(shipDateObj.getDate() + transitDays);
+
+    return shipDateObj.toISOString();
+  },
+
+  /**
+   * Validate and normalize SKU
+   * Ensures SKU exists in Fluent Commerce (ASYNC)
+   */
+  'custom.validateAndNormalizeSku': async (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Promise<string> => {
+    const sku = String(value).trim().toUpperCase();
+
+    if (!helpers.fluentClient) {
+      // If no client, just return normalized SKU
+      return sku;
+    }
+
+    // Query Fluent to validate SKU exists
+    const query = `
+      query ValidateSku($skuRef: [String!]) {
+        products(ref: $skuRef, first: 1) {
+          edges {
+            node {
+              id
+              ref
+            }
+          }
+        }
+      }`;
+
+    try {
+      const result = await helpers.fluentClient.graphql({
+        query,
+        variables: { skuRef: [sku] },
+      });
+
+      const product = result.data?.products?.edges?.[0]?.node;
+
+      if (!product) {
+        helpers.logger?.warn('SKU not found in Fluent Commerce', { sku });
+        // Option 1: Throw error to halt processing
+        // throw new Error(`SKU not found: ${sku}`);
+
+        // Option 2: Return SKU anyway (let Fluent validation handle it)
+        return sku;
+      }
+
+      helpers.logger?.debug('SKU validated successfully', { sku, productId: product.id });
+      return sku;
+    } catch (error: any) {
+      helpers.logger?.error('SKU validation failed', { sku, error: error.message });
+      return sku;  // Return SKU anyway, let Fluent handle validation
+    }
+  },
+
+  /**
+   * Get retailer ID from configuration
+   */
+  'custom.getRetailerId': (value: any, data: any, config: any, helpers: any): string => {
+    return config.retailerId || process.env.RETAILER_ID || '1';
+  },
+
+  /**
+   * Format dimensions as string
+   */
+  'custom.formatDimensions': (value: any, data: any, config: any, helpers: any): string => {
+    const container = data;  // Current container object
+    const length = container.length || 0;
+    const width = container.width || 0;
+    const height = container.height || 0;
+    const unit = container.dimension_unit || 'IN';
+
+    if (!length && !width && !height) {
+      return '';
+    }
+
+    return `${length} x ${width} x ${height} ${unit}`;
+  },
+
+  /**
+   * Build receipt attributes for audit trail
+   */
+  'custom.buildReceiptAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    // Add ASN metadata
+    attributes.push({
+      name: 'asn_id',
+      type: 'STRING',
+      value: config.asnId || data.shipmentId || 'UNKNOWN',
+    });
+
+    attributes.push({
+      name: 'asn_received_date',
+      type: 'STRING',
+      value: new Date().toISOString(),
+    });
+
+    // Add carrier tracking
+    if (data.shipment?.tracking_number) {
+      attributes.push({
+        name: 'tracking_number',
+        type: 'STRING',
+        value: data.shipment.tracking_number,
+      });
+    }
+
+    // Add origin information
+    if (data.shipment?.origin) {
+      attributes.push({
+        name: 'origin_location',
+        type: 'STRING',
+        value: JSON.stringify(data.shipment.origin),
+      });
+    }
+
+    // Add PO number if present
+    if (data.purchase_order_number) {
+      attributes.push({
+        name: 'po_number',
+        type: 'STRING',
+        value: data.purchase_order_number,
+      });
+    }
+
+    // Cross-dock flag
+    if (data.shipment?.is_crossdock) {
+      attributes.push({
+        name: 'is_crossdock',
+        type: 'BOOLEAN',
+        value: 'true',
+      });
+    }
+
+    return attributes;
+  },
+};
+```
+
+### 4. Sample ASN Test Data: `data/test-asn-sample.json`
+
+```json
+{
+  "shipmentId": "ASN-20250117-001",
+  "purchase_order_number": "PO-12345",
+  "shipment": {
+    "ship_date": "2025-01-17T10:00:00Z",
+    "carrier": {
+      "name": "FEDEX_GROUND",
+      "scac": "FXFE"
+    },
+    "tracking_number": "123456789012",
+    "origin": {
+      "name": "Acme Distribution Center",
+      "address": "123 Warehouse Dr",
+      "city": "Memphis",
+      "state": "TN",
+      "zip": "38101"
+    },
+    "is_crossdock": false,
+    "items": [
+      {
+        "sku": "ACME-WIDGET-100",
+        "quantity": 50,
+        "lot_number": "LOT20250115",
+        "container_id": "PALLET-001"
+      },
+      {
+        "sku": "ACME-GADGET-200",
+        "quantity": 100,
+        "container_id": "PALLET-001"
+      },
+      {
+        "sku": "ACME-TOOL-300",
+        "quantity": 25,
+        "lot_number": "LOT20250110",
+        "expiry_date": "2026-01-10T00:00:00Z",
+        "container_id": "PALLET-002"
+      }
+    ],
+    "containers": [
+      {
+        "container_id": "PALLET-001",
+        "type": "PALLET",
+        "weight": 250.5,
+        "weight_unit": "LBS",
+        "length": 48,
+        "width": 40,
+        "height": 60,
+        "dimension_unit": "IN"
+      },
+      {
+        "container_id": "PALLET-002",
+        "type": "PALLET",
+        "weight": 180.0,
+        "weight_unit": "LBS",
+        "length": 48,
+        "width": 40,
+        "height": 48,
+        "dimension_unit": "IN"
+      }
+    ]
+  },
+  "destination": {
+    "location_code": "DC-01-RECEIVING",
+    "name": "Distribution Center 01",
+    "address": "789 Commerce Pkwy",
+    "city": "Atlanta",
+    "state": "GA",
+    "zip": "30301"
+  }
+}
+```
+
+### 5. Package Configuration: `package.json`
+
+```json
+{
+  "name": "asn-processing-connector",
+  "version": "1.0.0",
+  "description": "ASN/Purchase Order processing connector for Acme 3PL integration",
+  "versori": {
+    "workflows": "./workflows/asn-receipt.ts"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "deploy": "versori deploy",
+    "logs": "versori logs",
+    "test": "node -r ts-node/register workflows/asn-receipt.ts"
+  }
+}
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: ASN Duplicate Prevention
+
+**Check for Existing Receipt Before Creating:**
+
+```typescript
+// Query existing receipts using ASN ID as ref
+const duplicateCheckQuery = `
+  query CheckExistingReceipt($ref: String!) {
+    inventoryQuantities(ref: $ref, first: 1) {
+      edges {
+        node {
+          id
+          ref
+          status
+        }
+      }
+    }
+  }`;
+
+const duplicateCheck = await fluentClient.graphql({
+  query: duplicateCheckQuery,
+  variables: {
+    ref: `ASN-${asnId}`,  // Unique ref from ASN shipment ID
+  },
+});
+
+const existingReceipt = duplicateCheck.data?.inventoryQuantities?.edges?.[0]?.node;
+
+if (existingReceipt) {
+  // ASN already processed - return early
+  return {
+    status: 200,
+    body: {
+      success: false,
+      message: 'ASN already processed (duplicate)',
+      existingReceiptId: existingReceipt.id,
+    },
+  };
+}
+```
+
+**Why this matters**: 3PLs may send duplicate ASN notifications due to:
+- Network retries
+- System glitches
+- Manual re-sends
+- Webhook replay
+
+**Without duplicate prevention**: Creates duplicate expected inventory, causing:
+- Inflated ATP calculations
+- Incorrect stock levels
+- Failed physical receipts (already expected)
+
+**Best practices**:
+- Always use ASN shipment ID as part of receipt ref
+- Query before creating
+- Log duplicate attempts for monitoring
+
+### Pattern 2: Expected Date Calculation
+
+**Calculate Arrival Date Based on Carrier Transit Time:**
+
+```typescript
+'custom.calculateExpectedDate': (value, data, config, helpers) => {
+  const shipDate = data.shipment?.ship_date || data.shipDate;
+  const carrier = data.shipment?.carrier?.name || data.carrier;
+
+  // Transit time lookup by carrier
+  const transitTimes = {
+    'FEDEX_GROUND': 3,
+    'FEDEX_EXPRESS': 1,
+    'UPS_GROUND': 3,
+    'UPS_NEXT_DAY': 1,
+    'USPS': 5,
+    'DHL': 2,
+    'FREIGHT': 7,
+    'DEFAULT': 3,
+  };
+
+  const carrierKey = String(carrier).toUpperCase().replace(/\s+/g, '_');
+  const transitDays = transitTimes[carrierKey] || transitTimes.DEFAULT;
+
+  // Add transit days to ship date
+  const shipDateObj = shipDate ? new Date(shipDate) : new Date();
+  shipDateObj.setDate(shipDateObj.getDate() + transitDays);
+
+  return shipDateObj.toISOString();
+};
+```
+
+**Why this matters**: Expected date drives:
+- ATP calculations (Available To Promise)
+- Allocation timing
+- Customer promise dates
+- Warehouse receiving schedules
+
+**Improvements for production:**
+
+```typescript
+// Add business days logic (skip weekends)
+function addBusinessDays(date: Date, days: number): Date {
+  let result = new Date(date);
+  let addedDays = 0;
+
+  while (addedDays < days) {
+    result.setDate(result.getDate() + 1);
+    // Skip weekends (0 = Sunday, 6 = Saturday)
+    if (result.getDay() !== 0 && result.getDay() !== 6) {
+      addedDays++;
+    }
+  }
+
+  return result;
+}
+
+// Add holiday logic
+const holidays = ['2025-01-01', '2025-07-04', '2025-12-25'];
+
+function isHoliday(date: Date): boolean {
+  const dateStr = date.toISOString().substring(0, 10);
+  return holidays.includes(dateStr);
+}
+```
+
+### Pattern 3: SKU Validation (Async Resolver)
+
+**Validate SKU Exists in Fluent Before Creating Receipt:**
+
+```typescript
+'custom.validateAndNormalizeSku': async (value, data, config, helpers) => {
+  const sku = String(value).trim().toUpperCase();
+
+  // Query Fluent to check if SKU exists
+  const query = `
+    query ValidateSku($skuRef: [String!]) {
+      products(ref: $skuRef, first: 1) {
+        edges {
+          node {
+            id
+            ref
+          }
+        }
+      }
+    }
+  `;
+
+  const result = await helpers.fluentClient.graphql({
+    query,
+    variables: { skuRef: [sku] },
+  });
+
+  const product = result.data?.products?.edges?.[0]?.node;
+
+  if (!product) {
+    // SKU not found - options:
+    // 1. Throw error (halt processing)
+    throw new Error(`SKU not found: ${sku}`);
+
+    // 2. Log warning and continue (let Fluent handle validation)
+    helpers.logger?.warn('SKU not found', { sku });
+    return sku;
+  }
+
+  return sku;
+};
+```
+
+**When to use SKU validation**:
+- ✅ **3PL sends ASN before products are created** (prevents invalid receipts)
+- ✅ **SKU format differs between systems** (can normalize)
+- ✅ **Need early warning** (alert on unknown SKUs)
+
+**When to skip**:
+- ❌ **High volume** (100+ SKUs per ASN = slow)
+- ❌ **Products always exist** (pre-synced)
+- ❌ **Performance critical** (let Fluent validation handle it)
+
+**Performance optimization**:
+
+```typescript
+// Cache SKU validation results in resolver context
+const skuCache = new Map<string, boolean>();
+
+if (skuCache.has(sku)) {
+  return sku;  // Already validated
+}
+
+const isValid = await validateSku(sku);
+skuCache.set(sku, isValid);
+```
+
+### Pattern 4: Container/Pallet Tracking
+
+**Track Containers for Efficient Receiving:**
+
+```json
+{
+  "containers": {
+    "source": "shipment.containers",
+    "isArray": true,
+    "fields": {
+      "containerRef": {
+        "source": "$.container_id"
+      },
+      "containerType": {
+        "source": "$.type",
+        "comment": "PALLET, CARTON, TOTE"
+      },
+      "weight": { "source": "$.weight" },
+      "dimensions": {
+        "resolver": "custom.formatDimensions"
+      }
+    }
+  }
+}
+```
+
+**Why container tracking matters**:
+- **Warehouse efficiency**: Receive entire pallets at once
+- **Put-away optimization**: Route containers to correct zones
+- **Cross-docking**: Direct routing without storage
+- **Audit trail**: Track physical container movement
+
+**Real-world example**:
+
+```
+ASN contains:
+- PALLET-001: 50x WIDGET + 100x GADGET
+- PALLET-002: 25x TOOL (refrigerated)
+
+Warehouse receives PALLET-001 first:
+→ Scan PALLET-001 barcode
+→ System shows all 2 SKUs on pallet
+→ Receive all at once (no item-by-item scan)
+→ PALLET-002 still expected
+```
+
+### Pattern 5: Cross-Dock Scenario Handling
+
+**Handle Direct Fulfillment Without Storage:**
+
+```typescript
+// In ASN data
+{
+  "shipment": {
+    "is_crossdock": true,  // Flag for cross-dock shipment
+    "destination_order_ref": "ORDER-12345"
+  }
+}
+
+// Custom resolver for cross-dock logic
+'custom.buildReceiptAttributes': (value, data, config, helpers) => {
+  const attributes = [];
+
+  if (data.shipment?.is_crossdock) {
+    attributes.push({
+      name: 'is_crossdock',
+      type: 'BOOLEAN',
+      value: 'true',
+    });
+
+    // Link to destination order
+    if (data.shipment.destination_order_ref) {
+      attributes.push({
+        name: 'crossdock_order_ref',
+        type: 'STRING',
+        value: data.shipment.destination_order_ref,
+      });
+    }
+
+    // Mark for expedited processing
+    attributes.push({
+      name: 'receiving_priority',
+      type: 'STRING',
+      value: 'HIGH',
+    });
+  }
+
+  return attributes;
+};
+```
+
+**Cross-dock workflow**:
+1. **ASN received** with `is_crossdock: true`
+2. **Expected receipt created** with crossdock flag
+3. **Physical receipt** → immediately allocated to order
+4. **Skip put-away** → direct to packing station
+5. **Ship within hours** (not days)
+
+**Benefits**:
+- Faster order fulfillment (same-day ship)
+- Reduced warehouse touches
+- Lower storage costs
+- Improved customer satisfaction
+
+### Pattern 6: XML vs JSON Payload Handling
+
+**Support Multiple Payload Formats:**
+
+```typescript
+// Detect content type from header
+const contentType = ctx.activation?.headers?.['content-type'] || 'application/json';
+
+let asnData: any;
+
+if (contentType.includes('xml') || contentType.includes('text')) {
+  // Parse XML (EDI 856 format)
+  const xmlParser = new XMLParserService();
+  asnData = await xmlParser.parse(rawPayload);
+} else {
+  // Assume JSON
+  asnData = rawPayload;
+}
+```
+
+**Why support both**:
+- **Enterprise 3PLs**: Often use EDI 856 XML format
+- **Modern 3PLs**: Use JSON REST APIs
+- **Flexibility**: Handle both without separate connectors
+
+**EDI 856 XML example**:
+
+```xml
+<?xml version="1.0"?>
+<ShipNotice shipment_id="ASN-001">
+  <Shipment>
+    <ShipDate>2025-01-17</ShipDate>
+    <Carrier name="FEDEX_GROUND"/>
+    <Items>
+      <Item>
+        <SKU>WIDGET-100</SKU>
+        <Quantity>50</Quantity>
+      </Item>
+    </Items>
+  </Shipment>
+</ShipNotice>
+```
+
+**JSON equivalent**:
+
+```json
+{
+  "shipmentId": "ASN-001",
+  "shipment": {
+    "ship_date": "2025-01-17",
+    "carrier": { "name": "FEDEX_GROUND" },
+    "items": [
+      { "sku": "WIDGET-100", "quantity": 50 }
+    ]
+  }
+}
+```
+
+---
+
+## Testing the Workflow
+
+### 1. Create Test ASN File
+
+Already provided in `data/test-asn-sample.json` above.
+
+### 2. Deploy to Versori Platform
+
+```bash
+cd asn-processing-connector
+npm install
+
+# Deploy to Versori
+versori deploy
+
+# Or if using Versori CLI v2+
+npx @versori/cli deploy
+```
+
+### 3. Configure Versori Connections
+
+In the Versori console:
+
+1. Add **Fluent Commerce** connection:
+   - Connection name: `fluent_commerce`
+   - Base URL: `https://api.fluentcommerce.com/graphql`
+   - Auth: OAuth2 (Client Credentials or Password Grant)
+   - Client ID, Client Secret, Username, Password
+
+2. Configure activation variables (optional):
+   - `OUTPUT_DIR`: Where to save audit files
+   - `RETAILER_ID`: Fluent retailer ID
+   - `DEFAULT_RECEIVING_LOCATION`: Default location code
+
+### 4. Test via Webhook
+
+```bash
+# Get webhook URL from Versori console (usually https://{workspace}.versori.io/{workflow})
+# Example: https://acme.versori.io/processAsnWebhook
+
+# Send test ASN via HTTP POST
+curl -X POST https://acme.versori.io/processAsnWebhook \
+  -H "Content-Type: application/json" \
+  -d @data/test-asn-sample.json
+```
+
+### 5. Use Manual Test Endpoint
+
+```bash
+# Trigger manual test (loads test-asn-sample.json from filesystem)
+curl https://acme.versori.io/manualAsnTest
+```
+
+### 6. Check Health Endpoint
+
+```bash
+# Verify service is running
+curl https://acme.versori.io/healthCheck
+```
+
+### 7. Verify in Fluent Commerce
+
+1. Log into Fluent Console
+2. Navigate to Inventory → Inventory Quantities
+3. Filter by status: `EXPECTED`
+4. Find receipt with ref `ASN-20250117-001-*`
+5. Verify:
+   - Quantity matches ASN
+   - Expected date calculated correctly
+   - Attributes contain ASN metadata
+
+### 8. Monitor Logs
+
+```bash
+# View real-time logs in Versori console
+# Or use Versori CLI
+versori logs --workflow=processAsnWebhook --tail
+
+# Check for errors
+versori logs --workflow=processAsnWebhook --level=error
+```
+
+---
+
+## Common Issues and Solutions
+
+### Issue 1: "Duplicate entity" Error from Fluent
+
+**Symptoms:**
+- GraphQL error: "Entity with ref already exists"
+- Second ASN attempt fails
+
+**Root Cause:**
+- Receipt ref not unique
+- Missing timestamp in ref generation
+
+**Solution:**
+
+```typescript
+// Ensure unique ref with timestamp
+'custom.generateReceiptRef': (value, data, config, helpers) => {
+  const asnId = data.shipmentId || 'UNKNOWN';
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
+  const randomSuffix = Math.random().toString(36).substring(7);
+
+  // Format: ASN-{asnId}-{timestamp}-{random}
+  return `ASN-${asnId}-${timestamp}-${randomSuffix}`;
+};
+```
+
+### Issue 2: Expected Date in the Past
+
+**Symptoms:**
+- Expected date shows yesterday or earlier
+- ATP calculation incorrect
+
+**Root Cause:**
+- Ship date from ASN is in the past
+- Transit time calculation starts from old date
+
+**Solution:**
+
+```typescript
+'custom.calculateExpectedDate': (value, data, config, helpers) => {
+  const shipDate = data.shipment?.ship_date;
+  const carrier = data.shipment?.carrier?.name;
+
+  // Get transit days
+  const transitDays = getTransitDays(carrier);
+
+  // Use ship date or TODAY (whichever is later)
+  const baseDate = shipDate ? new Date(shipDate) : new Date();
+  const today = new Date();
+
+  // If ship date is in the past, use today instead
+  if (baseDate < today) {
+    baseDate.setTime(today.getTime());
+  }
+
+  // Add transit days
+  baseDate.setDate(baseDate.getDate() + transitDays);
+
+  return baseDate.toISOString();
+};
+```
+
+### Issue 3: SKU Validation Slows Processing
+
+**Symptoms:**
+- Webhook timeouts (>30 seconds)
+- ASN with 100+ SKUs fails
+
+**Root Cause:**
+- Sequential SKU validation queries
+- No caching
+
+**Solution:**
+
+```typescript
+// Batch validate all SKUs in single query
+'custom.validateAllSkus': async (value, data, config, helpers) => {
+  const allSkus = data.shipment?.items?.map((item: any) => item.sku) || [];
+
+  // Single query for all SKUs
+  const query = `
+    query ValidateSkus($skuRefs: [String!]) {
+      products(ref: $skuRefs, first: 200) {
+        edges {
+          node {
+            id
+            ref
+          }
+        }
+      }
+    }
+  `;
+
+  const result = await helpers.fluentClient.graphql({
+    query,
+    variables: { skuRefs: allSkus },
+  });
+
+  const validSkus = new Set(
+    result.data?.products?.edges?.map((e: any) => e.node.ref) || []
+  );
+
+  // Check for missing SKUs
+  const missingSkus = allSkus.filter(sku => !validSkus.has(sku));
+
+  if (missingSkus.length > 0) {
+    helpers.logger?.warn('Invalid SKUs found', { missingSkus });
+    // Option: throw error or continue
+  }
+
+  return validSkus;
+};
+```
+
+### Issue 4: Cross-Dock Flag Not Honored
+
+**Symptoms:**
+- Cross-dock inventory goes to storage
+- Fulfillment delayed
+
+**Root Cause:**
+- Warehouse receiving app doesn't check attributes
+- Missing workflow trigger
+
+**Solution:**
+
+**Option 1: Create Fluent Event**
+
+```typescript
+// After creating receipt, send event if cross-dock
+if (data.shipment?.is_crossdock) {
+  await fluentClient.sendEvent({
+    name: 'InventoryReceiptCrossDock',
+    entityType: 'INVENTORY',
+    entityRef: createdReceipt.ref,
+    data: {
+      destinationOrderRef: data.shipment.destination_order_ref,
+      priority: 'HIGH',
+    },
+  });
+}
+```
+
+**Option 2: Use Different Location**
+
+```typescript
+// Route cross-dock receipts to special location
+'custom.normalizeLocationRef': (value, data, config, helpers) => {
+  if (data.shipment?.is_crossdock) {
+    return 'DC-CROSSDOCK-RECEIVING';  // Special receiving zone
+  }
+  return value || config.defaultLocation;
+};
+```
+
+### Issue 5: Container Data Not Appearing in Fluent
+
+**Symptoms:**
+- Container/pallet info missing in Fluent
+- Can't track containers
+
+**Root Cause:**
+- Fluent schema doesn't support container arrays directly
+- Need to use attributes
+
+**Solution:**
+
+```typescript
+// Store containers in attributes instead of separate field
+'custom.buildReceiptAttributes': (value, data, config, helpers) => {
+  const attributes = [];
+
+  // Serialize containers to JSON attribute
+  if (data.shipment?.containers) {
+    attributes.push({
+      name: 'containers',
+      type: 'STRING',
+      value: JSON.stringify(data.shipment.containers),
+    });
+
+    // Also add container count for quick reference
+    attributes.push({
+      name: 'container_count',
+      type: 'INTEGER',
+      value: String(data.shipment.containers.length),
+    });
+  }
+
+  return attributes;
+};
+```
+
+---
+
+## Related Guides
+
+- **[Connector Platform Scheduled: Cycle Count Reconciliation](../workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md)** - Reconciliation patterns
+- **[Universal Mapping Guide](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Field mapping patterns
+- **[GraphQL Mutation Mapper](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)** - Mutation generation
+- **[XML Parsing Guide](../../../02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md)** - EDI 856 XML handling
+
+---
+
+## Production Checklist
+
+Before deploying to production:
+- [ ] Test with real 3PL ASN payloads (XML and JSON)
+- [ ] Configure carrier transit times based on real data
+- [ ] Set up duplicate ASN monitoring/alerting
+- [ ] Verify SKU validation strategy (batch vs individual)
+- [ ] Test cross-dock scenario if applicable
+- [ ] Configure webhook retry policy in 3PL system
+- [ ] Set up error notifications (email/Slack)
+- [ ] Document ASN format variations by 3PL
+- [ ] Test large ASNs (100+ SKUs, 10+ containers)
+- [ ] Verify expected date business days logic
+
+---
+
+## Performance Considerations
+
+**Large ASNs (100+ SKUs)**:
+
+```typescript
+// Process items in chunks to avoid timeouts
+const CHUNK_SIZE = 50;
+
+for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+  const chunk = items.slice(i, i + CHUNK_SIZE);
+  await processItemChunk(chunk);
+}
+```
+
+**High Volume (1000+ ASNs/day)**:
+
+```typescript
+// Use background processing with queue
+export const processAsnWebhookQueued = webhook('queue-asn', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
+      status: 202, // Accepted
+      headers: { 'Content-Type': 'application/json' }
+    })
+  }
+}, async (ctx) => {
+  const { activation } = ctx;
+
+  // Immediately acknowledge receipt
+  const asnId = activation.body.shipmentId;
+
+  // Queue for async processing (implement queueAsnForProcessing function)
+  await queueAsnForProcessing(asnId, activation.body);
+
+  return {
+    success: true,
+    message: 'ASN queued for processing',
+    asnId,
+  };
+});
+```
+
+---
+
+## Next Steps
+
+1. **Add Receipt Confirmation**: Send confirmation back to 3PL when receipt created
+2. **Implement Discrepancy Handling**: Compare expected vs actual receipt quantities
+3. **Add Serial Number Tracking**: Full serial number lifecycle
+4. **Integrate with WMS**: Push ASN to warehouse management system
+5. **Build Dashboard**: Real-time ASN status monitoring
+6. **Add Carrier Tracking Integration**: Real-time shipment tracking via carrier APIs
+
+---
+
+**Need Help?**
+- Review SDK documentation: `/docs/readme.md`
+- Check example connectors: `/connectors/Sample versori connectors/`
+- Connector platform documentation: Check your platform's docs