@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/webhooks/template-webhook-rma-returns-comprehensive.md

@@ -1,2240 +1,2240 @@
----
-template_id: tpl-webhook-rma-returns-comprehensive
-canonical_filename: template-webhook-rma-returns-comprehensive.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: webhook-json-xml-return
-destination: fluent-graphql
-entity: rma
-format: json-xml
-logging: versori
-status: stable
-features:
-  - webhook-signature-validation
-  - batched-events
-  - attribute-transformation
-  - memory-management
-  - enhanced-logging
----
-
-# Template: Webhook - RMA Returns 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**: Handle customer returns end-to-end from initiation through refund/exchange
-
-**Complexity**: Medium-High
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~950 lines (modular structure)
-
----
-
-## STEP 1: Understand This Template
-
-**What This Template Does:**
-
-- Versori HTTP webhook for return requests
-- Parse return payload from e-commerce (Shopify/SFCC)
-- Create RMA in Fluent Commerce (custom mutation)
-- Generate return shipping label (ShipStation/EasyPost)
-- Track return shipment status
-- Quality inspection workflow (receive → inspect → approve/reject)
-- Process refund or exchange
-- Inventory adjustment (return to stock vs damaged/scrap)
-- Email notifications at each stage
-- VersoriKV state tracking for RMA lifecycle
-- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
-
-**Key SDK Components:**
-
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `UniversalMapper` - Transform return payload with custom resolvers
-- `GraphQLMutationMapper` - Map return data to GraphQL mutations
-- `VersoriKVAdapter` - RMA state tracking (KV storage)
-- Native Versori `log` - Use `log` from context
-
-**Entity Type:**
-
-- **RMA** - Fluent entity for return merchandise authorization
-- **GraphQL Mutations** - Create RMA, update RMA status, process refunds
-
-**Critical Patterns:**
-
-- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes RMA in background
-- **External JSON Config**: Return mapping configuration in separate JSON file (`config/return-mapping.json`)
-- **Modular Architecture**: Separate services, workflows, config, types folders
-- **Background Processing**: Long-running operations (RMA creation, label generation, refunds) happen asynchronously
-- **State Management**: KV storage for RMA lifecycle tracking across multiple webhooks
-- **Multi-Webhook Flow**: Multiple webhooks work together (create → track → inspect → refund)
-
-**When to Use This Template:**
-
-- ✅ End-to-end returns processing
-- ✅ Multiple return sources (Shopify, SFCC, custom)
-- ✅ Need fast webhook response (don't wait for RMA creation)
-- ✅ Multi-stage returns workflow (create → track → inspect → refund)
-- ✅ State tracking across multiple webhooks
-
-**When NOT to Use:**
-
-- ❌ Simple return processing (use single webhook)
-- ❌ Bulk return processing (use Batch API or scheduled workflows)
-- ❌ Need synchronous RMA 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 Versori webhook workflows for comprehensive RMA returns processing to Fluent Commerce.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhooks)
-2. Source: Return data via HTTP POST webhooks (JSON or XML, Shopify/SFCC format)
-3. Destination: Fluent Commerce GraphQL API (RMA mutations)
-4. Format: JSON or XML (Shopify/SFCC compatible)
-5. Entity: RMA (GraphQL mutations for lifecycle management)
-
-KEY FEATURES:
-- Sync + fire-and-forget pattern (fast webhook response, background processing)
-- External JSON mapping configuration (config/return-mapping.json)
-- Modular architecture (workflows/, services/, config/, types/)
-- Multiple webhooks for RMA lifecycle (create → track → inspect → refund)
-- UniversalMapper for return payload transformation
-- KV storage for cross-webhook state tracking
-- Comprehensive error handling
-
-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/return-mapping.json)
-4. Modular Structure: Separate services/, config/, types/ folders
-5. Native Logging: Use log from context (no LoggingService)
-6. State Management: VersoriKVAdapter for RMA lifecycle tracking
-
-SDK METHODS TO USE:
-- createClient({ ...ctx, log }) - Pass full Versori context
-- new UniversalMapper(mappingConfig) - Transform return payload
-- new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client }) - Map to GraphQL
-- new VersoriKVAdapter(openKv(':project:')) - RMA state storage
-- client.graphql({ query, variables }) - Execute GraphQL mutations
-
-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 (Create RMA)                           │
-│    POST https://{workspace}.versori.run/create-rma          │
-│    Content-Type: application/json                           │
-│    Body: { order_id: "...", return_line_items: [...] }      │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
-│    - Check fluent_commerce connection exists                 │
-│    - Validate return payload present                        │
-│    - Return HTTP 200 OK immediately                         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3a. Initialize Fluent Client                        │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3b. Transform Return Payload                        │  │
-│    │     - UniversalMapper with custom resolvers          │  │
-│    │     - Map return reasons, calculate fees            │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3c. Create RMA in Fluent                            │  │
-│    │     - GraphQL mutation to create RMA                │  │
-│    │     - Store RMA state in KV                         │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3d. Generate Return Shipping Label                 │  │
-│    │     - Call shipping provider API                     │  │
-│    │     - Update RMA with label URL                      │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Background Processing** | ~2000-5000ms | ❌ No (fire-and-forget) |
-| **Total Response Time** | ~10-50ms | ✅ Fast response |
-
-**Key Benefit**: Webhook caller receives immediate acknowledgment (~50ms) while RMA creation happens in background (~2-5s).
-
----
-
-## 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
-
-```
-rma-returns-processing/
-├── package.json                              # Dependencies and Versori config
-├── index.ts                                  # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       ├── create-rma.ts                 # Webhook: Create RMA from return
-    │       ├── track-shipment.ts             # Webhook: Track return shipment
-    │       ├── quality-inspection.ts         # Webhook: Quality inspection
-    │       └── process-refund-exchange.ts    # Webhook: Process refund/exchange
-    │
-    ├── services/
-    │   └── return-processing.service.ts      # Shared orchestration logic (reusable)
-    │
-    ├── resolvers/
-    │   └── return-resolvers.ts               # Custom resolvers for transformations
-    │
-    ├── config/
-    │   ├── return-mapping.json               # Mapping configuration (external JSON)
-    │   └── inspection-mapping.json           # Inspection mapping (external JSON)
-    │
-    └── types/
-        └── rma.types.ts                      # TypeScript interfaces
-```
-
-**Why This Structure?**
-
-- ✅ **Clear separation**: Multiple webhook handlers vs business logic
-- ✅ **Reusable services**: Return 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 return sources or processing steps
-
----
-
-## SDK Methods Used
-
-- `webhook(name, handler)` - HTTP webhook endpoint (from `@versori/run`)
-- `fn(name, handler)` - Function handler (from `@versori/run`)
-- `createClient(ctx)` - Auto-detects Versori context, creates FluentClient
-- `UniversalMapper(config, { customResolvers })` - Transform return payload with custom resolvers
-- `client.graphql({ query, variables })` - Execute GraphQL queries/mutations
-- `VersoriKVAdapter(ctx.openKv(':project:'))` - Versori KV storage adapter (:project: scope for cross-webhook state)
-- `kvAdapter.get(key)` - Retrieve state from KV (returns JSON string)
-- `kvAdapter.set(key, value)` - Store state in KV (stores JSON string)
-- Custom resolvers for return reason mapping, restocking fees, eligibility checks
-
----
-
-## 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
-
-```
-rma-returns-processing/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── return-processing.ts     # Webhook: Process return requests
-    │
-    ├── services/
-    │   └── return-processing.service.ts  # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── return-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. Main Workflow File: `index.ts`
-
-```typescript
-/**
- * RMA Returns Processing Workflow
- *
- * Complete returns management from customer initiation through refund/exchange.
- * Supports Shopify and SFCC webhook payloads.
- *
- * Flow:
- * 1. Receive return request webhook
- * 2. Create RMA in Fluent
- * 3. Generate return shipping label
- * 4. Track shipment
- * 5. Quality inspection
- * 6. Process refund/exchange
- * 7. Adjust inventory
- */
-
-import { webhook, http, fn } from '@versori/run';
-import {
-  createClient,
-  GraphQLMutationMapper,
-  UniversalMapper,
-  VersoriKVAdapter,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Import mapping configurations
-import rmaCreationMapping from './mappings/shopify-return-to-rma.json' with { type: 'json' };
-import inspectionMapping from './mappings/inspection-update.json' with { type: 'json' };
-
-/**
- * WEBHOOK 1: Create RMA from Return Request
- *
- * Receives return request from e-commerce platform, creates RMA in Fluent,
- * and generates return shipping label.
- */
-/**
- * Background processing function for RMA creation
- * Handles all long-running operations (transformation, RMA creation, label generation)
- */
-async function processRmaCreation(ctx: any, startTime: number): Promise<void> {
-  const { log, activation } = ctx;
-  const payload = activation?.body || ctx.data;
-
-  try {
-    log.info('🔄 [BACKGROUND] Starting background RMA creation processing', {
-      orderId: payload?.order_id || payload?.orderId,
-    });
-
-    // =================================================================
-    // STEP 1: PARSE AND VALIDATE RETURN REQUEST
-    // =================================================================
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-
-    if (!ctx.connections || !ctx.connections.fluent_commerce) {
-      log.error('❌ [BACKGROUND] Missing fluent_commerce connection');
-      return;
-    }
-
-    // Use :project: scope for cross-webhook RMA state sharing
-    // - createRmaFromReturn stores initial state
-    // - trackReturnShipment updates shipping status
-    // - qualityInspection adds inspection results
-    // - processRefundOrExchange marks completion
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-    // Detect payload format (Shopify JSON vs SFCC XML)
-    const isShopify = payload.order_id && payload.return_line_items;
-    const isSFCC = payload.ReturnRequest || payload.return;
-
-    if (!isShopify && !isSFCC) {
-      log.error('❌ [BACKGROUND] Invalid payload format');
-      return;
-    }
-
-    log.info(`🔍 [BACKGROUND] Detected source: ${isShopify ? 'Shopify' : 'SFCC'}`);
-
-    // =================================================================
-    // STEP 2: TRANSFORM TO FLUENT RMA FORMAT
-    // =================================================================
-        // Custom resolvers for return reason mapping
-        const customResolvers = {
-          // Map e-commerce return reasons to Fluent reason codes
-          'custom.mapReturnReason': (reason: string) => {
-            const reasonMap: Record<string, string> = {
-              'changed_mind': 'CUSTOMER_REMORSE',
-              'defective': 'DEFECTIVE',
-              'wrong_item': 'WRONG_ITEM_SHIPPED',
-              'damaged': 'DAMAGED_IN_TRANSIT',
-              'not_as_described': 'NOT_AS_DESCRIBED',
-              'sizing_issues': 'SIZE_FIT_ISSUE',
-              'late_delivery': 'LATE_DELIVERY',
-              'other': 'OTHER',
-            };
-            return reasonMap[reason?.toLowerCase()] || 'OTHER';
-          },
-
-          // Calculate restocking fee based on reason
-          // Resolver-only field: receives (value, sourceData, helpers)
-          // value = undefined (no source), sourceData = current array item
-          'custom.calculateRestockingFee': (value: any, sourceData: any, helpers: any) => {
-            const feeMap: Record<string, number> = {
-              'CUSTOMER_REMORSE': 0.15,    // 15% restocking fee
-              'SIZE_FIT_ISSUE': 0.10,      // 10% restocking fee
-              'OTHER': 0.10,
-              'DEFECTIVE': 0,              // No fee for defective items
-              'WRONG_ITEM_SHIPPED': 0,     // No fee for our errors
-              'DAMAGED_IN_TRANSIT': 0,
-            };
-
-            // Extract fields from sourceData (the current item)
-            const reason = sourceData?.reason || 'OTHER';
-            const price = helpers.parseFloatSafe(sourceData?.price, 0);
-
-            const feePercentage = feeMap[reason] || 0;
-            return price * feePercentage;
-          },
-
-          // Generate RMA reference
-          'custom.generateRmaRef': (orderId: string) => {
-            const timestamp = Date.now().toString().slice(-6);
-            return `RMA-${orderId}-${timestamp}`;
-          },
-
-          // Determine if return is eligible (30-day window)
-          'custom.isReturnEligible': (orderDate: string) => {
-            const orderTime = new Date(orderDate).getTime();
-            const now = Date.now();
-            const daysSinceOrder = (now - orderTime) / (1000 * 60 * 60 * 24);
-            return daysSinceOrder <= 30; // 30-day return window
-          },
-        };
-
-        // Transform return request to RMA format
-        const mapper = new UniversalMapper(rmaCreationMapping, {
-          customResolvers,
-        });
-
-        const transformResult = await mapper.map(payload);
-
-        if (!transformResult.success) {
-          log.error('❌ [BACKGROUND] Transformation failed', {
-            errors: transformResult.errors,
-          });
-          return;
-        }
-
-        const rmaData = transformResult.data;
-
-        log.info('✅ [RMA] Return request transformed', {
-          rmaRef: rmaData.ref,
-          itemCount: rmaData.items?.length || 0,
-        });
-
-        // =================================================================
-        // STEP 3: CHECK RETURN ELIGIBILITY
-        // =================================================================
-        if (!rmaData.eligible) {
-          log.warn('⚠️ [BACKGROUND] Return request ineligible', {
-            orderId: rmaData.orderRef,
-            reason: 'Outside return window',
-          });
-          return;
-        }
-
-        // =================================================================
-        // STEP 4: CHECK FOR DUPLICATE RMA
-        // =================================================================
-        const existingRmaJson = await kvAdapter.get(`rma-creation:${payload.order_id}`);
-
-        if (existingRmaJson) {
-          const existingRma = JSON.parse(existingRmaJson);
-          log.info('🔍 [BACKGROUND] RMA already exists for this order', {
-            orderId: payload.order_id,
-            existingRmaRef: existingRma.rmaRef,
-          });
-          return; // Already exists, exit early
-        }
-
-        // =================================================================
-        // STEP 5: CREATE RMA IN FLUENT COMMERCE
-        // =================================================================
-        log.info('📝 [RMA] Creating RMA in Fluent', {
-          rmaRef: rmaData.ref,
-          orderRef: rmaData.orderRef,
-        });
-
-        // Create RMA using custom mutation
-        const rmaResult = await fluentClient.graphql({
-          query: `mutation CreateRMA($input: CreateRMAInput!) {
-              createRMA(input: $input) {
-                id
-                ref
-                status
-                orderRef
-                items {
-                  id
-                  productRef
-                  quantity
-                  returnReason
-                  restockingFee
-                }
-                customer {
-                  id
-                  firstName
-                  lastName
-                  email
-                }
-                createdOn
-                attributes {
-                  name
-                  value
-                }
-              }
-            }`,
-          variables: {
-            input: {
-              ref: rmaData.ref,
-              orderRef: rmaData.orderRef,
-              customerId: rmaData.customerId,
-              items: rmaData.items,
-              status: 'PENDING_APPROVAL',
-              returnMethod: rmaData.returnMethod || 'SHIP_BACK',
-              attributes: [
-                { name: 'source', type: 'STRING', value: isShopify ? 'Shopify' : 'SFCC' },
-                { name: 'returnReason', type: 'STRING', value: rmaData.primaryReason },
-                { name: 'customerNotes', type: 'STRING', value: rmaData.notes || '' },
-              ],
-            },
-          },
-        });
-
-        if (!rmaResult.data?.createRMA) {
-          log.error('❌ [BACKGROUND] RMA creation failed', {
-            errors: rmaResult.errors,
-          });
-          return;
-        }
-
-        const rma = rmaResult.data.createRMA;
-
-        log.info('✅ [RMA] RMA created successfully', {
-          rmaId: rma.id,
-          rmaRef: rma.ref,
-          status: rma.status,
-        });
-
-        // =================================================================
-        // STEP 6: STORE RMA STATE IN VERSORI KV
-        // =================================================================
-        const rmaState = {
-          rmaId: rma.id,
-          rmaRef: rma.ref,
-          orderRef: rma.orderRef,
-          status: rma.status,
-          customerId: rma.customer.id,
-          customerEmail: rma.customer.email,
-          itemCount: rma.items.length,
-          createdOn: rma.createdOn,
-          source: isShopify ? 'Shopify' : 'SFCC',
-          stage: 'RMA_CREATED',
-        };
-
-        await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(rmaState));
-
-        // Store creation timestamp to prevent duplicates
-        const creationState = {
-          rmaRef: rma.ref,
-          createdAt: new Date().toISOString(),
-        };
-        await kvAdapter.set(`rma-creation:${payload.order_id}`, JSON.stringify(creationState));
-
-        log.info('[RMA] State stored in KV', { rmaRef: rma.ref });
-
-        // =================================================================
-        // STEP 7: GENERATE RETURN SHIPPING LABEL (MOCK)
-        // =================================================================
-        log.info('[RMA] Generating return shipping label', {
-          rmaRef: rma.ref,
-          customerEmail: rma.customer.email,
-        });
-
-        // In production, integrate with ShipStation, EasyPost, or carrier API
-        const shippingLabel = {
-          trackingNumber: `TRK-${Date.now()}`,
-          labelUrl: `https://labels.example.com/${rma.ref}.pdf`,
-          carrier: 'USPS',
-          service: 'Priority Mail',
-          estimatedDelivery: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000).toISOString(),
-        };
-
-        // Update RMA with shipping label info
-        await fluentClient.graphql({
-          query: `mutation UpdateRMA($id: ID!, $input: UpdateRMAInput!) {
-              updateRMA(id: $id, input: $input) {
-                id
-                ref
-                attributes {
-                  name
-                  value
-                }
-              }
-            }`,
-          variables: {
-            id: rma.id,
-            input: {
-              attributes: [
-                { name: 'returnTrackingNumber', type: 'STRING', value: shippingLabel.trackingNumber },
-                { name: 'returnLabelUrl', type: 'STRING', value: shippingLabel.labelUrl },
-                { name: 'returnCarrier', type: 'STRING', value: shippingLabel.carrier },
-              ],
-            },
-          },
-        });
-
-        log.info('[RMA] Shipping label generated', {
-          trackingNumber: shippingLabel.trackingNumber,
-        });
-
-        // =================================================================
-        // STEP 8: SEND EMAIL NOTIFICATION
-        // =================================================================
-        // In production, integrate with SendGrid, AWS SES, etc.
-        log.info('[RMA] Sending email notification', {
-          to: rma.customer.email,
-          rmaRef: rma.ref,
-          trackingNumber: shippingLabel.trackingNumber,
-        });
-
-        // =================================================================
-        // STEP 9: LOG SUCCESS
-        // =================================================================
-        const duration = Date.now() - startTime;
-        log.info('✅ [BACKGROUND] RMA creation completed successfully', {
-          rmaRef: rma.ref,
-          rmaId: rma.id,
-          duration: `${duration}ms`,
-        });
-      } catch (error: any) {
-        // ? Enhanced: Error logging with recommendations
-        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',
-          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 return request structure'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : error.message?.includes('duplicate') || error.message?.includes('already exists')
-            ? 'RMA may already exist for this order - check existing RMAs'
-            : error.message?.includes('eligible') || error.message?.includes('return window')
-            ? 'Return request is outside the return window - verify order date'
-            : 'Review error details and check return request payload structure',
-        };
-        log.error('❌ [BACKGROUND] RMA creation failed', errorDetails);
-      }
-}
-
-/**
- * RMA Creation Webhook Handler
- * Uses sync + fire-and-forget pattern for fast response
- */
-export const createRmaFromReturn = webhook('create-rma', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-}, async (ctx) => {
-  const { log, activation } = ctx;
-  const startTime = Date.now();
-  const payload = activation?.body || ctx.data;
-
-  log.info('🚀 [WEBHOOK] Received RMA creation webhook', {
-    source: payload?.source || 'unknown',
-    orderId: payload?.order_id || payload?.orderId,
-    timestamp: new Date().toISOString(),
-  });
-
-  // Quick validation
-  if (!ctx.connections || !ctx.connections.fluent_commerce) {
-    log.error('❌ [WEBHOOK] Missing fluent_commerce connection');
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Missing fluent_commerce connection',
-        recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials',
-        timestamp: new Date().toISOString(),
-      },
-    };
-  }
-
-  // Detect payload format (Shopify JSON vs SFCC XML)
-  const isShopify = payload.order_id && payload.return_line_items;
-  const isSFCC = payload.ReturnRequest || payload.return;
-
-  if (!isShopify && !isSFCC) {
-    log.error('❌ [WEBHOOK] Invalid payload format');
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'INVALID_FORMAT',
-        message: 'Unsupported return request format',
-        timestamp: new Date().toISOString(),
-      },
-    };
-  }
-
-  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
-    source: isShopify ? 'Shopify' : 'SFCC',
-  });
-
-  // ✅ Fire-and-forget: Start background processing WITHOUT await
-  // The promise continues execution after we return the response
-  processRmaCreation(ctx, startTime)
-    .then(() => {
-      log.info('✅ [BACKGROUND] RMA creation processing completed successfully', {
-        orderId: payload?.order_id || payload?.orderId,
-      });
-    })
-    .catch((error: unknown) => {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      log.error('❌ [BACKGROUND] RMA creation processing failed', {
-        orderId: payload?.order_id || payload?.orderId,
-        error: errorMessage,
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : typeof error,
-      });
-    });
-
-  // Return immediately (response sent with this return value)
-  return {
-    status: 200,
-    body: {
-      success: true,
-      message: 'RMA creation started in background',
-      timestamp: new Date().toISOString(),
-    },
-  };
-});
-
-/**
- * WEBHOOK 2: Track Return Shipment
- *
- * Receives shipment tracking updates (from carrier or ShipStation)
- * and updates RMA status in Fluent.
- */
-export const trackReturnShipment = webhook('track-return-shipment', async (ctx) => {
-  const { log, activation } = ctx;
-  const payload = activation?.body || ctx.data;
-  const startTime = Date.now();
-
-  log.info('🚀 [RMA] Received shipment tracking update', {
-    trackingNumber: payload.tracking_number,
-    status: payload.status,
-  });
-
-  try {
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-        // Find RMA by tracking number
-        const trackingNumber = payload.tracking_number || payload.trackingNumber;
-
-        // Query Fluent for RMA with this tracking number
-        const rmaResult = await fluentClient.graphql({
-          query: `query FindRMAByTracking($trackingNumber: String!) {
-              rmas(
-                first: 1
-                attributes: [
-                  { name: "returnTrackingNumber", value: $trackingNumber }
-                ]
-              ) {
-                edges {
-                  node {
-                    id
-                    ref
-                    status
-                    orderRef
-                  }
-                }
-              }
-            }`,
-          variables: { trackingNumber },
-        });
-
-        const rma = rmaResult.data?.rmas?.edges[0]?.node;
-
-        if (!rma) {
-          log.warn('⚠️ [RMA] No RMA found for tracking number', { trackingNumber });
-          return {
-            status: 404,
-            body: {
-              success: false,
-              error: 'RMA_NOT_FOUND',
-              message: `No RMA found with tracking number ${trackingNumber}`,
-              timestamp: new Date().toISOString(),
-            },
-          };
-        }
-
-        log.info('✅ [RMA] Found RMA for tracking update', {
-          rmaId: rma.id,
-          rmaRef: rma.ref,
-        });
-
-        // Map carrier status to RMA status
-        const carrierStatus = payload.status?.toUpperCase();
-        let rmaStatus = rma.status;
-        let eventType = 'TRACKING_UPDATE';
-
-        switch (carrierStatus) {
-          case 'IN_TRANSIT':
-            rmaStatus = 'IN_TRANSIT';
-            eventType = 'SHIPMENT_IN_TRANSIT';
-            break;
-          case 'OUT_FOR_DELIVERY':
-            rmaStatus = 'OUT_FOR_DELIVERY';
-            eventType = 'SHIPMENT_OUT_FOR_DELIVERY';
-            break;
-          case 'DELIVERED':
-            rmaStatus = 'RECEIVED';
-            eventType = 'SHIPMENT_DELIVERED';
-            break;
-          case 'EXCEPTION':
-          case 'FAILED':
-            rmaStatus = 'SHIPMENT_EXCEPTION';
-            eventType = 'SHIPMENT_EXCEPTION';
-            break;
-        }
-
-        // Update RMA status in Fluent
-        await fluentClient.graphql({
-          query: `mutation UpdateRMAStatus($id: ID!, $input: UpdateRMAInput!) {
-              updateRMA(id: $id, input: $input) {
-                id
-                ref
-                status
-              }
-            }`,
-          variables: {
-            id: rma.id,
-            input: {
-              status: rmaStatus,
-              attributes: [
-                { name: 'lastTrackingUpdate', type: 'STRING', value: new Date().toISOString() },
-                { name: 'carrierStatus', type: 'STRING', value: carrierStatus },
-              ],
-            },
-          },
-        });
-
-        // Update KV state
-        const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
-        if (existingStateJson) {
-          const existingState = JSON.parse(existingStateJson);
-          const updatedState = {
-            ...existingState,
-            status: rmaStatus,
-            lastTrackingUpdate: new Date().toISOString(),
-            carrierStatus,
-            stage: eventType,
-          };
-          await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
-        }
-
-        const duration = Date.now() - startTime;
-        log.info('✅ [RMA] RMA status updated', {
-          rmaRef: rma.ref,
-          oldStatus: rma.status,
-          newStatus: rmaStatus,
-          duration: `${duration}ms`,
-        });
-
-        return {
-          status: 200,
-          body: {
-            success: true,
-            rmaRef: rma.ref,
-            status: rmaStatus,
-            eventType,
-            message: 'RMA status updated successfully',
-            duration: `${duration}ms`,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      } catch (error: any) {
-        // ? Enhanced: Error logging with recommendations
-        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',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('not found') || error.message?.includes('missing')
-            ? 'RMA not found - verify tracking number and RMA reference'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details and check tracking update payload structure',
-        };
-        log.error('[RMA] Failed to process tracking update', errorDetails);
-        return {
-          status: 500,
-          body: {
-            success: false,
-            error: error.message,
-            recommendation: errorDetails.recommendation,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      }
-    });
-
-/**
- * WEBHOOK 3: Quality Inspection
- *
- * Warehouse receives return, inspects items, and updates RMA with inspection results.
- * Determines if items can be restocked, need repair, or should be scrapped.
- */
-export const qualityInspection = webhook('quality-inspection', async (ctx) => {
-  const { log, activation } = ctx;
-  const payload = activation?.body || ctx.data;
-  const startTime = Date.now();
-
-  log.info('🚀 [RMA] Processing quality inspection', {
-    rmaRef: payload.rmaRef,
-    itemCount: payload.items?.length || 0,
-  });
-
-  try {
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-    // Validate payload
-    if (!payload.rmaRef || !payload.items || payload.items.length === 0) {
-      return {
-        status: 400,
-        body: {
-          success: false,
-          error: 'INVALID_PAYLOAD',
-          message: 'Invalid inspection payload: missing rmaRef or items',
-          timestamp: new Date().toISOString(),
-        },
-      };
-    }
-
-        // =================================================================
-        // STEP 1: RETRIEVE RMA FROM FLUENT
-        // =================================================================
-        const rmaResult = await fluentClient.graphql({
-          query: `query GetRMA($ref: String!) {
-              rma(ref: $ref) {
-                id
-                ref
-                status
-                orderRef
-                items {
-                  id
-                  productRef
-                  quantity
-                  returnReason
-                  restockingFee
-                }
-                customer {
-                  id
-                  email
-                }
-              }
-            }`,
-          variables: { ref: payload.rmaRef },
-        });
-
-        const rma = rmaResult.data?.rma;
-
-        if (!rma) {
-          return {
-            status: 404,
-            body: {
-              success: false,
-              error: 'RMA_NOT_FOUND',
-              message: `RMA not found: ${payload.rmaRef}`,
-              timestamp: new Date().toISOString(),
-            },
-          };
-        }
-
-        log.info('✅ [RMA] RMA retrieved', {
-          rmaId: rma.id,
-          rmaRef: rma.ref,
-          currentStatus: rma.status,
-        });
-
-        // =================================================================
-        // STEP 2: PROCESS INSPECTION RESULTS
-        // =================================================================
-        const inspectionResults = payload.items.map((item: any) => {
-          const condition = item.condition?.toUpperCase();
-          let disposition = 'RESTOCK';
-          let restockable = true;
-
-          switch (condition) {
-            case 'NEW':
-            case 'LIKE_NEW':
-              disposition = 'RESTOCK';
-              restockable = true;
-              break;
-            case 'DAMAGED':
-            case 'DEFECTIVE':
-              disposition = 'SCRAP';
-              restockable = false;
-              break;
-            case 'OPENED':
-            case 'USED':
-              disposition = 'OPEN_BOX';
-              restockable = true;
-              break;
-            case 'MISSING_PARTS':
-              disposition = 'REPAIR';
-              restockable = false;
-              break;
-            default:
-              disposition = 'MANUAL_REVIEW';
-              restockable = false;
-          }
-
-          return {
-            itemId: item.itemId,
-            productRef: item.productRef || item.sku,
-            condition,
-            disposition,
-            restockable,
-            notes: item.notes || '',
-            photoUrls: item.photoUrls || [],
-          };
-        });
-
-        log.info('✅ [RMA] Inspection results processed', {
-          total: inspectionResults.length,
-          restockable: inspectionResults.filter(r => r.restockable).length,
-          scrap: inspectionResults.filter(r => r.disposition === 'SCRAP').length,
-        });
-
-        // =================================================================
-        // STEP 3: UPDATE RMA WITH INSPECTION RESULTS
-        // =================================================================
-        await fluentClient.graphql({
-          query: `mutation UpdateRMAInspection($id: ID!, $input: UpdateRMAInput!) {
-              updateRMA(id: $id, input: $input) {
-                id
-                ref
-                status
-              }
-            }`,
-          variables: {
-            id: rma.id,
-            input: {
-              status: 'INSPECTED',
-              attributes: [
-                { name: 'inspectionDate', type: 'STRING', value: new Date().toISOString() },
-                { name: 'inspectionResults', type: 'JSON', value: JSON.stringify(inspectionResults) },
-                { name: 'inspector', type: 'STRING', value: payload.inspector || 'SYSTEM' },
-              ],
-            },
-          },
-        });
-
-        log.info('[RMA] RMA updated with inspection results', {
-          rmaRef: rma.ref,
-          status: 'INSPECTED',
-        });
-
-        // =================================================================
-        // STEP 4: UPDATE INVENTORY FOR RESTOCKABLE ITEMS
-        // =================================================================
-        const restockableItems = inspectionResults.filter(r => r.restockable);
-
-        if (restockableItems.length > 0) {
-          log.info('[RMA] Restocking items', {
-            count: restockableItems.length,
-          });
-
-          for (const item of restockableItems) {
-            // Increment inventory for restockable items
-            await fluentClient.graphql({
-              query: `mutation AdjustInventory($input: AdjustInventoryInput!) {
-                  adjustInventory(input: $input) {
-                    id
-                    ref
-                    quantity
-                  }
-                }`,
-              variables: {
-                input: {
-                  productRef: item.productRef,
-                  locationRef: payload.locationRef || 'RETURNS_WAREHOUSE',
-                  adjustment: 1, // Increment by quantity returned
-                  reason: 'RMA_RESTOCK',
-                  ref: `${rma.ref}-${item.productRef}`,
-                },
-              },
-            });
-
-            log.info('[RMA] Inventory adjusted', {
-              productRef: item.productRef,
-              disposition: item.disposition,
-            });
-          }
-        }
-
-        // =================================================================
-        // STEP 5: UPDATE KV STATE
-        // =================================================================
-        const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
-        if (existingStateJson) {
-          const existingState = JSON.parse(existingStateJson);
-          const updatedState = {
-            ...existingState,
-            status: 'INSPECTED',
-            stage: 'INSPECTION_COMPLETE',
-            inspectionResults,
-            inspectionDate: new Date().toISOString(),
-          };
-          await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
-        }
-
-        // =================================================================
-        // STEP 6: DETERMINE NEXT ACTION (REFUND OR EXCHANGE)
-        // =================================================================
-        const refundApproved = inspectionResults.every(r =>
-          r.disposition === 'RESTOCK' || r.disposition === 'OPEN_BOX'
-        );
-
-        const duration = Date.now() - startTime;
-        log.info('✅ [RMA] Inspection complete', {
-          rmaRef: rma.ref,
-          refundApproved,
-          nextAction: payload.returnType === 'exchange' ? 'CREATE_EXCHANGE_ORDER' : 'PROCESS_REFUND',
-          duration: `${duration}ms`,
-        });
-
-        return {
-          status: 200,
-          body: {
-            success: true,
-            rmaRef: rma.ref,
-            status: 'INSPECTED',
-            inspectionResults,
-            refundApproved,
-            nextAction: payload.returnType === 'exchange' ? 'CREATE_EXCHANGE_ORDER' : 'PROCESS_REFUND',
-            message: 'Quality inspection completed successfully',
-            duration: `${duration}ms`,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      } catch (error: any) {
-        // ? Enhanced: Error logging with recommendations
-        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',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('not found') || error.message?.includes('missing')
-            ? 'RMA not found - verify RMA reference and inspection payload structure'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details and check inspection payload structure',
-        };
-        log.error('[RMA] Failed to process inspection', errorDetails);
-        return {
-          status: 500,
-          body: {
-            success: false,
-            error: error.message,
-            recommendation: errorDetails.recommendation,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      }
-    });
-
-/**
- * WEBHOOK 4: Process Refund or Exchange
- *
- * After inspection approval, processes refund via payment gateway
- * or creates exchange order.
- */
-export const processRefundOrExchange = webhook('process-refund-exchange', async (ctx) => {
-  const { log, activation } = ctx;
-  const payload = activation?.body || ctx.data;
-  const startTime = Date.now();
-
-  log.info('🚀 [RMA] Processing refund/exchange', {
-    rmaRef: payload.rmaRef,
-    actionType: payload.actionType, // 'refund' or 'exchange'
-  });
-
-  try {
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-        // Retrieve RMA
-        const rmaResult = await fluentClient.graphql({
-          query: `query GetRMA($ref: String!) {
-              rma(ref: $ref) {
-                id
-                ref
-                status
-                orderRef
-                items {
-                  id
-                  productRef
-                  quantity
-                  price
-                  restockingFee
-                }
-                customer {
-                  id
-                  email
-                }
-                attributes {
-                  name
-                  value
-                }
-              }
-            }`,
-          variables: { ref: payload.rmaRef },
-        });
-
-        const rma = rmaResult.data?.rma;
-
-        if (!rma) {
-          return {
-            status: 404,
-            body: {
-              success: false,
-              error: 'RMA_NOT_FOUND',
-              message: `RMA not found: ${payload.rmaRef}`,
-              timestamp: new Date().toISOString(),
-            },
-          };
-        }
-
-        const actionType = payload.actionType?.toLowerCase();
-
-        // =================================================================
-        // OPTION 1: PROCESS REFUND
-        // =================================================================
-        if (actionType === 'refund') {
-          log.info('💰 [RMA] Processing refund', { rmaRef: rma.ref });
-
-          // Calculate refund amount (subtract restocking fees)
-          const totalRefund = rma.items.reduce((sum: number, item: any) => {
-            const itemTotal = item.price * item.quantity;
-            const restockingFee = item.restockingFee || 0;
-            return sum + (itemTotal - restockingFee);
-          }, 0);
-
-          log.info('[RMA] Refund calculated', {
-            totalRefund,
-            itemCount: rma.items.length,
-          });
-
-          // In production, integrate with payment gateway (Stripe, Adyen, etc.)
-          const refundResponse = {
-            refundId: `REF-${Date.now()}`,
-            amount: totalRefund,
-            currency: 'USD',
-            status: 'PROCESSED',
-            transactionId: `TXN-${Date.now()}`,
-          };
-
-          // Update RMA status
-          await fluentClient.graphql({
-            query: `mutation UpdateRMARefund($id: ID!, $input: UpdateRMAInput!) {
-                updateRMA(id: $id, input: $input) {
-                  id
-                  ref
-                  status
-                }
-              }`,
-            variables: {
-              id: rma.id,
-              input: {
-                status: 'REFUNDED',
-                attributes: [
-                  { name: 'refundId', type: 'STRING', value: refundResponse.refundId },
-                  { name: 'refundAmount', type: 'STRING', value: totalRefund.toString() },
-                  { name: 'refundDate', type: 'STRING', value: new Date().toISOString() },
-                ],
-              },
-            },
-          });
-
-          // Update KV state
-          const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
-          if (existingStateJson) {
-            const existingState = JSON.parse(existingStateJson);
-            const updatedState = {
-              ...existingState,
-              status: 'REFUNDED',
-              stage: 'REFUND_COMPLETE',
-              refundAmount: totalRefund,
-              refundId: refundResponse.refundId,
-              refundDate: new Date().toISOString(),
-            };
-            await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
-          }
-
-          const duration = Date.now() - startTime;
-          log.info('✅ [RMA] Refund processed successfully', {
-            rmaRef: rma.ref,
-            refundId: refundResponse.refundId,
-            amount: totalRefund,
-            duration: `${duration}ms`,
-          });
-
-          return {
-            status: 200,
-            body: {
-              success: true,
-              rmaRef: rma.ref,
-              actionType: 'refund',
-              refund: refundResponse,
-              message: `Refund of $${totalRefund} processed successfully`,
-              duration: `${duration}ms`,
-              timestamp: new Date().toISOString(),
-            },
-          };
-        }
-
-        // =================================================================
-        // OPTION 2: CREATE EXCHANGE ORDER
-        // =================================================================
-        if (actionType === 'exchange') {
-          log.info('🔄 [RMA] Creating exchange order', { rmaRef: rma.ref });
-
-          // Exchange items (from payload)
-          const exchangeItems = payload.exchangeItems || [];
-
-          if (exchangeItems.length === 0) {
-            return {
-              status: 400,
-              body: {
-                success: false,
-                error: 'INVALID_PAYLOAD',
-                message: 'No exchange items provided',
-                timestamp: new Date().toISOString(),
-              },
-            };
-          }
-
-          // Create new order in Fluent
-          const exchangeOrderResult = await fluentClient.graphql({
-            query: `mutation CreateExchangeOrder($input: CreateOrderInput!) {
-                createOrder(input: $input) {
-                  id
-                  ref
-                  status
-                  items {
-                    id
-                    productRef
-                    quantity
-                  }
-                }
-              }`,
-            variables: {
-              input: {
-                ref: `EXCH-${rma.ref}`,
-                type: 'EXCHANGE',
-                customerId: rma.customer.id,
-                items: exchangeItems.map((item: any) => ({
-                  productRef: item.productRef,
-                  quantity: item.quantity,
-                })),
-                attributes: [
-                  { name: 'originalRMA', type: 'STRING', value: rma.ref },
-                  { name: 'originalOrder', type: 'STRING', value: rma.orderRef },
-                  { name: 'source', type: 'STRING', value: 'RMA_EXCHANGE' },
-                ],
-              },
-            },
-          });
-
-          const exchangeOrder = exchangeOrderResult.data?.createOrder;
-
-          if (!exchangeOrder) {
-            return {
-              status: 502,
-              body: {
-                success: false,
-                error: 'API_ERROR',
-                message: 'Failed to create exchange order',
-                timestamp: new Date().toISOString(),
-              },
-            };
-          }
-
-          // Update RMA with exchange order reference
-          await fluentClient.graphql({
-            query: `mutation UpdateRMAExchange($id: ID!, $input: UpdateRMAInput!) {
-                updateRMA(id: $id, input: $input) {
-                  id
-                  ref
-                  status
-                }
-              }`,
-            variables: {
-              id: rma.id,
-              input: {
-                status: 'EXCHANGED',
-                attributes: [
-                  { name: 'exchangeOrderRef', type: 'STRING', value: exchangeOrder.ref },
-                  { name: 'exchangeDate', type: 'STRING', value: new Date().toISOString() },
-                ],
-              },
-            },
-          });
-
-          // Update KV state
-          const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
-          if (existingStateJson) {
-            const existingState = JSON.parse(existingStateJson);
-            const updatedState = {
-              ...existingState,
-              status: 'EXCHANGED',
-              stage: 'EXCHANGE_COMPLETE',
-              exchangeOrderRef: exchangeOrder.ref,
-              exchangeDate: new Date().toISOString(),
-            };
-            await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
-          }
-
-          const duration = Date.now() - startTime;
-          log.info('✅ [RMA] Exchange order created', {
-            rmaRef: rma.ref,
-            exchangeOrderRef: exchangeOrder.ref,
-            duration: `${duration}ms`,
-          });
-
-          return {
-            status: 200,
-            body: {
-              success: true,
-              rmaRef: rma.ref,
-              actionType: 'exchange',
-              exchangeOrder: {
-                ref: exchangeOrder.ref,
-                id: exchangeOrder.id,
-                status: exchangeOrder.status,
-              },
-              message: `Exchange order ${exchangeOrder.ref} created successfully`,
-              duration: `${duration}ms`,
-              timestamp: new Date().toISOString(),
-            },
-          };
-        }
-
-        return {
-          status: 400,
-          body: {
-            success: false,
-            error: 'INVALID_ACTION_TYPE',
-            message: `Invalid action type: ${actionType}`,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      } catch (error: any) {
-        // ? Enhanced: Error logging with recommendations
-        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',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('payment') || error.message?.includes('gateway')
-            ? 'Check payment gateway configuration and refund processing credentials'
-            : error.message?.includes('exchange') || error.message?.includes('order')
-            ? 'Check exchange order creation payload and product availability'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details and check refund/exchange payload structure',
-        };
-        log.error('[RMA] Failed to process refund/exchange', errorDetails);
-        return {
-          status: 500,
-          body: {
-            success: false,
-            error: error.message,
-            recommendation: errorDetails.recommendation,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      }
-    });
-
-/**
- * WEBHOOK 5: Get RMA Status
- *
- * Query endpoint to retrieve RMA status and history
- */
-export const getRmaStatus = webhook('get-rma-status', async (ctx) => {
-  const { log, activation } = ctx;
-  const payload = activation?.body || ctx.data;
-  const rmaRef = payload?.rmaRef || ctx.query?.rmaRef;
-  const startTime = Date.now();
-
-  log.info('🚀 [RMA] Querying RMA status', { rmaRef });
-
-  if (!rmaRef) {
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'MISSING_PARAMETER',
-        message: 'Missing rmaRef parameter',
-        timestamp: new Date().toISOString(),
-      },
-    };
-  }
-
-  try {
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-        // Get RMA from Fluent
-        const rmaResult = await fluentClient.graphql({
-          query: `query GetRMA($ref: String!) {
-              rma(ref: $ref) {
-                id
-                ref
-                status
-                orderRef
-                items {
-                  id
-                  productRef
-                  quantity
-                  returnReason
-                  price
-                  restockingFee
-                }
-                customer {
-                  id
-                  firstName
-                  lastName
-                  email
-                }
-                createdOn
-                updatedOn
-                attributes {
-                  name
-                  value
-                }
-              }
-            }`,
-          variables: { ref: rmaRef },
-        });
-
-        const rma = rmaResult.data?.rma;
-
-        if (!rma) {
-          return {
-            status: 404,
-            body: {
-              success: false,
-              error: 'RMA_NOT_FOUND',
-              message: `RMA not found: ${rmaRef}`,
-              timestamp: new Date().toISOString(),
-            },
-          };
-        }
-
-        // Get state from KV
-        const rmaStateJson = await kvAdapter.get(`rma:${rmaRef}`);
-        const rmaState = rmaStateJson ? JSON.parse(rmaStateJson) : null;
-
-        const duration = Date.now() - startTime;
-        log.info('✅ [RMA] Status query complete', {
-          rmaRef: rma.ref,
-          status: rma.status,
-          duration: `${duration}ms`,
-        });
-
-        return {
-          status: 200,
-          body: {
-            success: true,
-            rma: {
-              id: rma.id,
-              ref: rma.ref,
-              status: rma.status,
-              orderRef: rma.orderRef,
-              itemCount: rma.items.length,
-              customer: rma.customer,
-              createdOn: rma.createdOn,
-              updatedOn: rma.updatedOn,
-            },
-            state: rmaState,
-            attributes: rma.attributes,
-            duration: `${duration}ms`,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      } catch (error: any) {
-        // ? Enhanced: Error logging with recommendations
-        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',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('not found') || error.message?.includes('missing')
-            ? 'RMA not found - verify RMA reference and query parameters'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details and check RMA status query parameters',
-        };
-        log.error('[RMA] Failed to query RMA', errorDetails);
-        return {
-          status: 500,
-          body: {
-            success: false,
-            error: error.message,
-            recommendation: errorDetails.recommendation,
-            timestamp: new Date().toISOString(),
-          },
-        };
-      }
-    });
-```
-
----
-
-## 2. RMA Mapping Configuration: `mappings/shopify-return-to-rma.json`
-
-```json
-{
-  "version": "1.0.0",
-  "description": "Shopify return request to Fluent RMA mapping",
-  "direction": "ingest",
-  "sourceFormat": "json",
-  "fields": {
-    "ref": {
-      "source": "order_id",
-      "resolver": "custom.generateRmaRef",
-      "required": true
-    },
-    "orderRef": {
-      "source": "order_id",
-      "required": true
-    },
-    "customerId": {
-      "source": "customer.id",
-      "required": true
-    },
-    "customerEmail": {
-      "source": "customer.email",
-      "resolver": "sdk.lowercase",
-      "required": true
-    },
-    "eligible": {
-      "source": "order.created_at",
-      "resolver": "custom.isReturnEligible"
-    },
-    "returnMethod": {
-      "source": "return_method",
-      "defaultValue": "SHIP_BACK"
-    },
-    "primaryReason": {
-      "source": "return_line_items[0].reason",
-      "resolver": "custom.mapReturnReason"
-    },
-    "notes": {
-      "source": "note",
-      "required": false
-    },
-    "items": {
-      "source": "return_line_items",
-      "isArray": true,
-      "fields": {
-        "lineItemId": {
-          "source": "line_item_id",
-          "resolver": "sdk.toString"
-        },
-        "productRef": {
-          "source": "sku",
-          "required": true
-        },
-        "quantity": {
-          "source": "quantity",
-          "resolver": "sdk.parseInt",
-          "required": true
-        },
-        "returnReason": {
-          "source": "reason",
-          "resolver": "custom.mapReturnReason",
-          "required": true
-        },
-        "customerNotes": {
-          "source": "customer_note",
-          "required": false
-        },
-        "price": {
-          "source": "price",
-          "resolver": "sdk.parseFloat"
-        },
-        "restockingFee": {
-          "resolver": "custom.calculateRestockingFee",
-          "comment": "Resolver-only field - receives full item as sourceData"
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: Return Reason Mapping
-
-Map e-commerce return reasons to Fluent reason codes:
-
-```typescript
-'custom.mapReturnReason': (reason: string) => {
-  const reasonMap: Record<string, string> = {
-    'changed_mind': 'CUSTOMER_REMORSE',
-    'defective': 'DEFECTIVE',
-    'wrong_item': 'WRONG_ITEM_SHIPPED',
-    'damaged': 'DAMAGED_IN_TRANSIT',
-    'not_as_described': 'NOT_AS_DESCRIBED',
-    'sizing_issues': 'SIZE_FIT_ISSUE',
-    'late_delivery': 'LATE_DELIVERY',
-    'other': 'OTHER',
-  };
-  return reasonMap[reason?.toLowerCase()] || 'OTHER';
-}
-```
-
-### Pattern 2: Restocking Fee Calculation
-
-Calculate restocking fees based on return reason using resolver-only field:
-
-```typescript
-// Resolver-only field pattern: receives (value, sourceData, helpers)
-// value = undefined (no source specified)
-// sourceData = current array item containing all fields
-'custom.calculateRestockingFee': (value: any, sourceData: any, helpers: any) => {
-  const feeMap: Record<string, number> = {
-    'CUSTOMER_REMORSE': 0.15,    // 15% restocking fee
-    'SIZE_FIT_ISSUE': 0.10,      // 10% restocking fee
-    'OTHER': 0.10,
-    'DEFECTIVE': 0,              // No fee for defective items
-    'WRONG_ITEM_SHIPPED': 0,     // No fee for our errors
-    'DAMAGED_IN_TRANSIT': 0,
-  };
-
-  // Extract fields from sourceData (the current array item)
-  const reason = sourceData?.reason || 'OTHER';
-  const price = helpers.parseFloatSafe(sourceData?.price, 0);
-
-  const feePercentage = feeMap[reason] || 0;
-  return price * feePercentage;
-}
-```
-
-**Mapping Configuration:**
-```json
-{
-  "restockingFee": {
-    "resolver": "custom.calculateRestockingFee",
-    "comment": "Resolver-only field - no source, extracts from sourceData"
-  }
-}
-```
-
-### Pattern 3: Return Eligibility Check
-
-Validate returns are within policy window (e.g., 30 days):
-
-```typescript
-'custom.isReturnEligible': (orderDate: string) => {
-  const orderTime = new Date(orderDate).getTime();
-  const now = Date.now();
-  const daysSinceOrder = (now - orderTime) / (1000 * 60 * 60 * 24);
-  return daysSinceOrder <= 30; // 30-day return window
-}
-```
-
-### Pattern 4: Quality Inspection States
-
-Map inspection condition to disposition:
-
-```typescript
-const condition = item.condition?.toUpperCase();
-let disposition = 'RESTOCK';
-let restockable = true;
-
-switch (condition) {
-  case 'NEW':
-  case 'LIKE_NEW':
-    disposition = 'RESTOCK';
-    restockable = true;
-    break;
-  case 'DAMAGED':
-  case 'DEFECTIVE':
-    disposition = 'SCRAP';
-    restockable = false;
-    break;
-  case 'OPENED':
-  case 'USED':
-    disposition = 'OPEN_BOX';
-    restockable = true;
-    break;
-  case 'MISSING_PARTS':
-    disposition = 'REPAIR';
-    restockable = false;
-    break;
-  default:
-    disposition = 'MANUAL_REVIEW';
-    restockable = false;
-}
-```
-
-### Pattern 5: Refund vs Exchange Decision Tree
-
-Determine next action based on inspection results:
-
-```typescript
-// Check if all items passed inspection
-const refundApproved = inspectionResults.every(r =>
-  r.disposition === 'RESTOCK' || r.disposition === 'OPEN_BOX'
-);
-
-// Determine next action
-const nextAction = payload.returnType === 'exchange'
-  ? 'CREATE_EXCHANGE_ORDER'
-  : 'PROCESS_REFUND';
-
-log.info('[RMA] Inspection complete', {
-  rmaRef: rma.ref,
-  refundApproved,
-  nextAction,
-});
-```
-
-### Pattern 6: Partial Returns
-
-Handle returns of some items from an order:
-
-```json
-{
-  "items": {
-    "source": "return_line_items",
-    "isArray": true,
-    "fields": {
-      "lineItemId": { "source": "line_item_id" },
-      "productRef": { "source": "sku" },
-      "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
-    }
-  }
-}
-```
-
-**Key**: Use `isArray: true` to map each line item individually.
-
-### Pattern 7: VersoriKV RMA Lifecycle Tracking
-
-Track RMA state across all stages:
-
-```typescript
-// Store initial RMA state
-const rmaState = {
-  rmaId: rma.id,
-  rmaRef: rma.ref,
-  orderRef: rma.orderRef,
-  status: rma.status,
-  stage: 'RMA_CREATED',
-  createdOn: rma.createdOn,
-};
-await kvAdapter.set(`rma:${rma.ref}`, rmaState);
-
-// Update state at each stage
-const existingState = await kvAdapter.get(`rma:${rma.ref}`);
-if (existingState) {
-  const updatedState = {
-    ...existingState,
-    status: 'INSPECTED',
-    stage: 'INSPECTION_COMPLETE',
-    inspectionDate: new Date().toISOString(),
-  };
-  await kvAdapter.set(`rma:${rma.ref}`, updatedState);
-}
-
-// Query state
-const rmaStateJson = await kvAdapter.get(`rma:${rma.ref}`);
-const rmaState = rmaStateJson ? JSON.parse(rmaStateJson) : null;
-```
-
----
-
-## Testing
-
-### 1. Test RMA Creation (Shopify Format)
-
-```bash
-curl -X POST https://your-workspace.versori.run/create-rma \
-  -H "Content-Type: application/json" \
-  -d '{
-    "order_id": "ORD-12345",
-    "customer": {
-      "id": "CUST-789",
-      "email": "customer@example.com"
-    },
-    "order": {
-      "created_at": "2025-01-15T10:00:00Z"
-    },
-    "return_line_items": [
-      {
-        "line_item_id": "LI-001",
-        "sku": "PROD-ABC123",
-        "quantity": 1,
-        "reason": "wrong_item",
-        "customer_note": "Received wrong size",
-        "price": 99.99
-      }
-    ],
-    "return_method": "SHIP_BACK",
-    "note": "Customer wants exchange for correct size"
-  }'
-
-# Expected Response:
-{
-  "status": 200,
-  "body": {
-    "success": true,
-    "rmaId": "RMA-123",
-    "rmaRef": "RMA-ORD-12345-456789",
-    "status": "PENDING_APPROVAL",
-    "shippingLabel": {
-      "trackingNumber": "TRK-1234567890",
-      "labelUrl": "https://labels.example.com/RMA-ORD-12345-456789.pdf",
-      "carrier": "USPS",
-      "service": "Priority Mail"
-    },
-    "message": "RMA created successfully. Return label sent to customer.",
-    "timestamp": "2025-10-30T12:00:00.000Z"
-  }
-}
-```
-
-### 2. Test Shipment Tracking Update
-
-```bash
-curl -X POST https://your-workspace.versori.run/track-return-shipment \
-  -H "Content-Type: application/json" \
-  -d '{
-    "tracking_number": "TRK-1234567890",
-    "status": "DELIVERED",
-    "carrier": "USPS",
-    "timestamp": "2025-01-20T14:30:00Z"
-  }'
-```
-
-### 3. Test Quality Inspection
-
-```bash
-curl -X POST https://your-workspace.versori.run/quality-inspection \
-  -H "Content-Type: application/json" \
-  -d '{
-    "rmaRef": "RMA-ORD-12345-456789",
-    "inspector": "John Doe",
-    "locationRef": "RETURNS_WAREHOUSE",
-    "returnType": "refund",
-    "items": [
-      {
-        "itemId": "RMA-ITEM-001",
-        "productRef": "PROD-ABC123",
-        "condition": "NEW",
-        "notes": "Item in original packaging, tags attached",
-        "photoUrls": ["https://photos.example.com/item1.jpg"]
-      }
-    ]
-  }'
-```
-
-### 4. Test Refund Processing
-
-```bash
-curl -X POST https://your-workspace.versori.run/process-refund-exchange \
-  -H "Content-Type: application/json" \
-  -d '{
-    "rmaRef": "RMA-ORD-12345-456789",
-    "actionType": "refund"
-  }'
-```
-
-### 5. Test Exchange Order Creation
-
-```bash
-curl -X POST https://your-workspace.versori.run/process-refund-exchange \
-  -H "Content-Type: application/json" \
-  -d '{
-    "rmaRef": "RMA-ORD-12345-456789",
-    "actionType": "exchange",
-    "exchangeItems": [
-      {
-        "productRef": "PROD-ABC124",
-        "quantity": 1
-      }
-    ]
-  }'
-```
-
-### 6. Query RMA Status
-
-```bash
-curl https://your-workspace.versori.run/get-rma-status?rmaRef=RMA-ORD-12345-456789
-```
-
----
-
-## Common Issues and Solutions
-
-### Issue 1: Return Request Rejected (Ineligible)
-
-**Symptoms:**
-- RMA creation fails with "INELIGIBLE" error
-- Returns outside policy window
-
-**Root Cause:**
-- Order is older than return window (30 days)
-
-**Solution:**
-
-```typescript
-// Adjust return window in custom resolver
-'custom.isReturnEligible': (orderDate: string) => {
-  const orderTime = new Date(orderDate).getTime();
-  const now = Date.now();
-  const daysSinceOrder = (now - orderTime) / (1000 * 60 * 60 * 24);
-
-  // Change to 60 days or make configurable via activation variable
-  return daysSinceOrder <= 60;
-}
-```
-
-### Issue 2: Restocking Fee Not Calculated
-
-**Symptoms:**
-- Restocking fee is 0 for all items
-- Refund amount is incorrect
-
-**Root Cause:**
-- Custom resolver not receiving price parameter
-- Mapping configuration missing price field
-
-**Solution:**
-
-```json
-{
-  "items": {
-    "source": "return_line_items",
-    "isArray": true,
-    "fields": {
-      "price": {
-        "source": "price",
-        "resolver": "sdk.parseFloat"
-      },
-      "restockingFee": {
-        "resolver": "custom.calculateRestockingFee",
-        "comment": "Resolver-only field - receives full item as sourceData parameter"
-      }
-    }
-  }
-}
-```
-
-### Issue 3: Inventory Not Restocked
-
-**Symptoms:**
-- Quality inspection completes but inventory doesn't increase
-- Restockable items not showing in inventory
-
-**Root Cause:**
-- Location reference incorrect
-- Inventory adjustment mutation failed
-
-**Solution:**
-
-```typescript
-// Verify location exists in Fluent
-const locationResult = await fluentClient.graphql({
-  query: `query { location(ref: "${payload.locationRef}") { id ref } }`
-});
-
-if (!locationResult.data?.location) {
-  log.warn('Location not found, using default', {
-    requestedLocation: payload.locationRef,
-    defaultLocation: 'RETURNS_WAREHOUSE',
-  });
-}
-
-// Use validated location
-const locationRef = locationResult.data?.location?.ref || 'RETURNS_WAREHOUSE';
-```
-
-### Issue 4: Duplicate RMA Creation
-
-**Symptoms:**
-- Multiple RMAs created for same return request
-- Duplicate tracking numbers
-
-**Root Cause:**
-- No duplicate detection
-- Webhook retries creating duplicates
-
-**Solution:**
-
-```typescript
-// Check if RMA already exists before creating
-const existingRma = await kvAdapter.get(`rma-creation:${payload.order_id}`);
-
-if (existingRma) {
-  log.info('[RMA] RMA already exists for this order', {
-    orderId: payload.order_id,
-    existingRmaRef: existingRma.rmaRef,
-  });
-
-  return {
-    success: true,
-    rmaRef: existingRma.rmaRef,
-    duplicate: true,
-    message: 'RMA already exists for this order',
-  };
-}
-
-// Create RMA...
-
-// Store creation state
-const creationState = {
-  rmaRef: rma.ref,
-  createdAt: new Date().toISOString(),
-};
-await kvAdapter.set(`rma-creation:${payload.order_id}`, JSON.stringify(creationState));
-```
-
-### Issue 5: Refund Amount Incorrect
-
-**Symptoms:**
-- Refund amount doesn't match expected value
-- Restocking fees not deducted
-
-**Root Cause:**
-- Calculation logic incorrect
-- Items missing price data
-
-**Solution:**
-
-```typescript
-// Detailed refund calculation with logging
-const refundDetails = rma.items.map((item: any) => {
-  const itemTotal = item.price * item.quantity;
-  const restockingFee = item.restockingFee || 0;
-  const itemRefund = itemTotal - restockingFee;
-
-  log.debug('[RMA] Item refund calculated', {
-    productRef: item.productRef,
-    quantity: item.quantity,
-    price: item.price,
-    itemTotal,
-    restockingFee,
-    itemRefund,
-  });
-
-  return {
-    productRef: item.productRef,
-    itemTotal,
-    restockingFee,
-    itemRefund,
-  };
-});
-
-const totalRefund = refundDetails.reduce((sum, detail) => sum + detail.itemRefund, 0);
-
-log.info('[RMA] Total refund calculated', {
-  totalRefund,
-  itemCount: refundDetails.length,
-  details: refundDetails,
-});
-```
-
----
-
-## Related Guides
-
-- **[Versori Webhook: XML Order Processing](./xml-order-ingestion.md)** - Similar webhook patterns
-- **[Versori Scheduled: CSV Inventory Sync](../workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - State management patterns
-- **[KV State Management](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-06-kv-storage.md)** - VersoriKV usage
-- **[Universal Mapping Guide](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Field mapping patterns
-- **[Custom Resolvers](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Advanced resolver patterns
-- **[Error Handling](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Error handling and retry logic
-
----
-
-## Summary
-
-**Volume:** Medium (5-10% of order volume, 50-500 returns/day)
-
-**Latency:** Real-time (< 2 seconds per webhook)
-
-**Complexity:** Medium (multiple stages, state tracking, conditional logic)
-
-**Key Features:**
-- End-to-end return processing (initiation → refund/exchange)
-- Quality inspection workflow with condition tracking
-- Restocking fee calculation based on return reason
-- Inventory adjustments for restockable items
-- Exchange order creation
-- VersoriKV state management across RMA lifecycle
-- Email notifications at each stage
-- Support for partial returns
-- 30-day return policy enforcement
-
-**Real-World Considerations:**
-- Integrate with actual payment gateway (Stripe, Adyen) for refunds
-- Integrate with shipping provider (ShipStation, EasyPost) for return labels
-- Add email/SMS notifications via SendGrid or Twilio
-- Implement return fraud detection
-- Add approval workflow for high-value returns
-- Track return trends and analytics
-- Support international returns with customs
-- Handle restocking for serialized/batch-tracked items
+---
+template_id: tpl-webhook-rma-returns-comprehensive
+canonical_filename: template-webhook-rma-returns-comprehensive.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: webhook-json-xml-return
+destination: fluent-graphql
+entity: rma
+format: json-xml
+logging: versori
+status: stable
+features:
+  - webhook-signature-validation
+  - batched-events
+  - attribute-transformation
+  - memory-management
+  - enhanced-logging
+---
+
+# Template: Webhook - RMA Returns 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**: Handle customer returns end-to-end from initiation through refund/exchange
+
+**Complexity**: Medium-High
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~950 lines (modular structure)
+
+---
+
+## STEP 1: Understand This Template
+
+**What This Template Does:**
+
+- Versori HTTP webhook for return requests
+- Parse return payload from e-commerce (Shopify/SFCC)
+- Create RMA in Fluent Commerce (custom mutation)
+- Generate return shipping label (ShipStation/EasyPost)
+- Track return shipment status
+- Quality inspection workflow (receive → inspect → approve/reject)
+- Process refund or exchange
+- Inventory adjustment (return to stock vs damaged/scrap)
+- Email notifications at each stage
+- VersoriKV state tracking for RMA lifecycle
+- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
+
+**Key SDK Components:**
+
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `UniversalMapper` - Transform return payload with custom resolvers
+- `GraphQLMutationMapper` - Map return data to GraphQL mutations
+- `VersoriKVAdapter` - RMA state tracking (KV storage)
+- Native Versori `log` - Use `log` from context
+
+**Entity Type:**
+
+- **RMA** - Fluent entity for return merchandise authorization
+- **GraphQL Mutations** - Create RMA, update RMA status, process refunds
+
+**Critical Patterns:**
+
+- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes RMA in background
+- **External JSON Config**: Return mapping configuration in separate JSON file (`config/return-mapping.json`)
+- **Modular Architecture**: Separate services, workflows, config, types folders
+- **Background Processing**: Long-running operations (RMA creation, label generation, refunds) happen asynchronously
+- **State Management**: KV storage for RMA lifecycle tracking across multiple webhooks
+- **Multi-Webhook Flow**: Multiple webhooks work together (create → track → inspect → refund)
+
+**When to Use This Template:**
+
+- ✅ End-to-end returns processing
+- ✅ Multiple return sources (Shopify, SFCC, custom)
+- ✅ Need fast webhook response (don't wait for RMA creation)
+- ✅ Multi-stage returns workflow (create → track → inspect → refund)
+- ✅ State tracking across multiple webhooks
+
+**When NOT to Use:**
+
+- ❌ Simple return processing (use single webhook)
+- ❌ Bulk return processing (use Batch API or scheduled workflows)
+- ❌ Need synchronous RMA 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 Versori webhook workflows for comprehensive RMA returns processing to Fluent Commerce.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhooks)
+2. Source: Return data via HTTP POST webhooks (JSON or XML, Shopify/SFCC format)
+3. Destination: Fluent Commerce GraphQL API (RMA mutations)
+4. Format: JSON or XML (Shopify/SFCC compatible)
+5. Entity: RMA (GraphQL mutations for lifecycle management)
+
+KEY FEATURES:
+- Sync + fire-and-forget pattern (fast webhook response, background processing)
+- External JSON mapping configuration (config/return-mapping.json)
+- Modular architecture (workflows/, services/, config/, types/)
+- Multiple webhooks for RMA lifecycle (create → track → inspect → refund)
+- UniversalMapper for return payload transformation
+- KV storage for cross-webhook state tracking
+- Comprehensive error handling
+
+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/return-mapping.json)
+4. Modular Structure: Separate services/, config/, types/ folders
+5. Native Logging: Use log from context (no LoggingService)
+6. State Management: VersoriKVAdapter for RMA lifecycle tracking
+
+SDK METHODS TO USE:
+- createClient({ ...ctx, log }) - Pass full Versori context
+- new UniversalMapper(mappingConfig) - Transform return payload
+- new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client }) - Map to GraphQL
+- new VersoriKVAdapter(openKv(':project:')) - RMA state storage
+- client.graphql({ query, variables }) - Execute GraphQL mutations
+
+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 (Create RMA)                           │
+│    POST https://{workspace}.versori.run/create-rma          │
+│    Content-Type: application/json                           │
+│    Body: { order_id: "...", return_line_items: [...] }      │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
+│    - Check fluent_commerce connection exists                 │
+│    - Validate return payload present                        │
+│    - Return HTTP 200 OK immediately                         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3a. Initialize Fluent Client                        │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3b. Transform Return Payload                        │  │
+│    │     - UniversalMapper with custom resolvers          │  │
+│    │     - Map return reasons, calculate fees            │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3c. Create RMA in Fluent                            │  │
+│    │     - GraphQL mutation to create RMA                │  │
+│    │     - Store RMA state in KV                         │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3d. Generate Return Shipping Label                 │  │
+│    │     - Call shipping provider API                     │  │
+│    │     - Update RMA with label URL                      │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Background Processing** | ~2000-5000ms | ❌ No (fire-and-forget) |
+| **Total Response Time** | ~10-50ms | ✅ Fast response |
+
+**Key Benefit**: Webhook caller receives immediate acknowledgment (~50ms) while RMA creation happens in background (~2-5s).
+
+---
+
+## 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
+
+```
+rma-returns-processing/
+├── package.json                              # Dependencies and Versori config
+├── index.ts                                  # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       ├── create-rma.ts                 # Webhook: Create RMA from return
+    │       ├── track-shipment.ts             # Webhook: Track return shipment
+    │       ├── quality-inspection.ts         # Webhook: Quality inspection
+    │       └── process-refund-exchange.ts    # Webhook: Process refund/exchange
+    │
+    ├── services/
+    │   └── return-processing.service.ts      # Shared orchestration logic (reusable)
+    │
+    ├── resolvers/
+    │   └── return-resolvers.ts               # Custom resolvers for transformations
+    │
+    ├── config/
+    │   ├── return-mapping.json               # Mapping configuration (external JSON)
+    │   └── inspection-mapping.json           # Inspection mapping (external JSON)
+    │
+    └── types/
+        └── rma.types.ts                      # TypeScript interfaces
+```
+
+**Why This Structure?**
+
+- ✅ **Clear separation**: Multiple webhook handlers vs business logic
+- ✅ **Reusable services**: Return 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 return sources or processing steps
+
+---
+
+## SDK Methods Used
+
+- `webhook(name, handler)` - HTTP webhook endpoint (from `@versori/run`)
+- `fn(name, handler)` - Function handler (from `@versori/run`)
+- `createClient(ctx)` - Auto-detects Versori context, creates FluentClient
+- `UniversalMapper(config, { customResolvers })` - Transform return payload with custom resolvers
+- `client.graphql({ query, variables })` - Execute GraphQL queries/mutations
+- `VersoriKVAdapter(ctx.openKv(':project:'))` - Versori KV storage adapter (:project: scope for cross-webhook state)
+- `kvAdapter.get(key)` - Retrieve state from KV (returns JSON string)
+- `kvAdapter.set(key, value)` - Store state in KV (stores JSON string)
+- Custom resolvers for return reason mapping, restocking fees, eligibility checks
+
+---
+
+## 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
+
+```
+rma-returns-processing/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── return-processing.ts     # Webhook: Process return requests
+    │
+    ├── services/
+    │   └── return-processing.service.ts  # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── return-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. Main Workflow File: `index.ts`
+
+```typescript
+/**
+ * RMA Returns Processing Workflow
+ *
+ * Complete returns management from customer initiation through refund/exchange.
+ * Supports Shopify and SFCC webhook payloads.
+ *
+ * Flow:
+ * 1. Receive return request webhook
+ * 2. Create RMA in Fluent
+ * 3. Generate return shipping label
+ * 4. Track shipment
+ * 5. Quality inspection
+ * 6. Process refund/exchange
+ * 7. Adjust inventory
+ */
+
+import { webhook, http, fn } from '@versori/run';
+import {
+  createClient,
+  GraphQLMutationMapper,
+  UniversalMapper,
+  VersoriKVAdapter,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Import mapping configurations
+import rmaCreationMapping from './mappings/shopify-return-to-rma.json' with { type: 'json' };
+import inspectionMapping from './mappings/inspection-update.json' with { type: 'json' };
+
+/**
+ * WEBHOOK 1: Create RMA from Return Request
+ *
+ * Receives return request from e-commerce platform, creates RMA in Fluent,
+ * and generates return shipping label.
+ */
+/**
+ * Background processing function for RMA creation
+ * Handles all long-running operations (transformation, RMA creation, label generation)
+ */
+async function processRmaCreation(ctx: any, startTime: number): Promise<void> {
+  const { log, activation } = ctx;
+  const payload = activation?.body || ctx.data;
+
+  try {
+    log.info('🔄 [BACKGROUND] Starting background RMA creation processing', {
+      orderId: payload?.order_id || payload?.orderId,
+    });
+
+    // =================================================================
+    // STEP 1: PARSE AND VALIDATE RETURN REQUEST
+    // =================================================================
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+
+    if (!ctx.connections || !ctx.connections.fluent_commerce) {
+      log.error('❌ [BACKGROUND] Missing fluent_commerce connection');
+      return;
+    }
+
+    // Use :project: scope for cross-webhook RMA state sharing
+    // - createRmaFromReturn stores initial state
+    // - trackReturnShipment updates shipping status
+    // - qualityInspection adds inspection results
+    // - processRefundOrExchange marks completion
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+    // Detect payload format (Shopify JSON vs SFCC XML)
+    const isShopify = payload.order_id && payload.return_line_items;
+    const isSFCC = payload.ReturnRequest || payload.return;
+
+    if (!isShopify && !isSFCC) {
+      log.error('❌ [BACKGROUND] Invalid payload format');
+      return;
+    }
+
+    log.info(`🔍 [BACKGROUND] Detected source: ${isShopify ? 'Shopify' : 'SFCC'}`);
+
+    // =================================================================
+    // STEP 2: TRANSFORM TO FLUENT RMA FORMAT
+    // =================================================================
+        // Custom resolvers for return reason mapping
+        const customResolvers = {
+          // Map e-commerce return reasons to Fluent reason codes
+          'custom.mapReturnReason': (reason: string) => {
+            const reasonMap: Record<string, string> = {
+              'changed_mind': 'CUSTOMER_REMORSE',
+              'defective': 'DEFECTIVE',
+              'wrong_item': 'WRONG_ITEM_SHIPPED',
+              'damaged': 'DAMAGED_IN_TRANSIT',
+              'not_as_described': 'NOT_AS_DESCRIBED',
+              'sizing_issues': 'SIZE_FIT_ISSUE',
+              'late_delivery': 'LATE_DELIVERY',
+              'other': 'OTHER',
+            };
+            return reasonMap[reason?.toLowerCase()] || 'OTHER';
+          },
+
+          // Calculate restocking fee based on reason
+          // Resolver-only field: receives (value, sourceData, helpers)
+          // value = undefined (no source), sourceData = current array item
+          'custom.calculateRestockingFee': (value: any, sourceData: any, helpers: any) => {
+            const feeMap: Record<string, number> = {
+              'CUSTOMER_REMORSE': 0.15,    // 15% restocking fee
+              'SIZE_FIT_ISSUE': 0.10,      // 10% restocking fee
+              'OTHER': 0.10,
+              'DEFECTIVE': 0,              // No fee for defective items
+              'WRONG_ITEM_SHIPPED': 0,     // No fee for our errors
+              'DAMAGED_IN_TRANSIT': 0,
+            };
+
+            // Extract fields from sourceData (the current item)
+            const reason = sourceData?.reason || 'OTHER';
+            const price = helpers.parseFloatSafe(sourceData?.price, 0);
+
+            const feePercentage = feeMap[reason] || 0;
+            return price * feePercentage;
+          },
+
+          // Generate RMA reference
+          'custom.generateRmaRef': (orderId: string) => {
+            const timestamp = Date.now().toString().slice(-6);
+            return `RMA-${orderId}-${timestamp}`;
+          },
+
+          // Determine if return is eligible (30-day window)
+          'custom.isReturnEligible': (orderDate: string) => {
+            const orderTime = new Date(orderDate).getTime();
+            const now = Date.now();
+            const daysSinceOrder = (now - orderTime) / (1000 * 60 * 60 * 24);
+            return daysSinceOrder <= 30; // 30-day return window
+          },
+        };
+
+        // Transform return request to RMA format
+        const mapper = new UniversalMapper(rmaCreationMapping, {
+          customResolvers,
+        });
+
+        const transformResult = await mapper.map(payload);
+
+        if (!transformResult.success) {
+          log.error('❌ [BACKGROUND] Transformation failed', {
+            errors: transformResult.errors,
+          });
+          return;
+        }
+
+        const rmaData = transformResult.data;
+
+        log.info('✅ [RMA] Return request transformed', {
+          rmaRef: rmaData.ref,
+          itemCount: rmaData.items?.length || 0,
+        });
+
+        // =================================================================
+        // STEP 3: CHECK RETURN ELIGIBILITY
+        // =================================================================
+        if (!rmaData.eligible) {
+          log.warn('⚠️ [BACKGROUND] Return request ineligible', {
+            orderId: rmaData.orderRef,
+            reason: 'Outside return window',
+          });
+          return;
+        }
+
+        // =================================================================
+        // STEP 4: CHECK FOR DUPLICATE RMA
+        // =================================================================
+        const existingRmaJson = await kvAdapter.get(`rma-creation:${payload.order_id}`);
+
+        if (existingRmaJson) {
+          const existingRma = JSON.parse(existingRmaJson);
+          log.info('🔍 [BACKGROUND] RMA already exists for this order', {
+            orderId: payload.order_id,
+            existingRmaRef: existingRma.rmaRef,
+          });
+          return; // Already exists, exit early
+        }
+
+        // =================================================================
+        // STEP 5: CREATE RMA IN FLUENT COMMERCE
+        // =================================================================
+        log.info('📝 [RMA] Creating RMA in Fluent', {
+          rmaRef: rmaData.ref,
+          orderRef: rmaData.orderRef,
+        });
+
+        // Create RMA using custom mutation
+        const rmaResult = await fluentClient.graphql({
+          query: `mutation CreateRMA($input: CreateRMAInput!) {
+              createRMA(input: $input) {
+                id
+                ref
+                status
+                orderRef
+                items {
+                  id
+                  productRef
+                  quantity
+                  returnReason
+                  restockingFee
+                }
+                customer {
+                  id
+                  firstName
+                  lastName
+                  email
+                }
+                createdOn
+                attributes {
+                  name
+                  value
+                }
+              }
+            }`,
+          variables: {
+            input: {
+              ref: rmaData.ref,
+              orderRef: rmaData.orderRef,
+              customerId: rmaData.customerId,
+              items: rmaData.items,
+              status: 'PENDING_APPROVAL',
+              returnMethod: rmaData.returnMethod || 'SHIP_BACK',
+              attributes: [
+                { name: 'source', type: 'STRING', value: isShopify ? 'Shopify' : 'SFCC' },
+                { name: 'returnReason', type: 'STRING', value: rmaData.primaryReason },
+                { name: 'customerNotes', type: 'STRING', value: rmaData.notes || '' },
+              ],
+            },
+          },
+        });
+
+        if (!rmaResult.data?.createRMA) {
+          log.error('❌ [BACKGROUND] RMA creation failed', {
+            errors: rmaResult.errors,
+          });
+          return;
+        }
+
+        const rma = rmaResult.data.createRMA;
+
+        log.info('✅ [RMA] RMA created successfully', {
+          rmaId: rma.id,
+          rmaRef: rma.ref,
+          status: rma.status,
+        });
+
+        // =================================================================
+        // STEP 6: STORE RMA STATE IN VERSORI KV
+        // =================================================================
+        const rmaState = {
+          rmaId: rma.id,
+          rmaRef: rma.ref,
+          orderRef: rma.orderRef,
+          status: rma.status,
+          customerId: rma.customer.id,
+          customerEmail: rma.customer.email,
+          itemCount: rma.items.length,
+          createdOn: rma.createdOn,
+          source: isShopify ? 'Shopify' : 'SFCC',
+          stage: 'RMA_CREATED',
+        };
+
+        await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(rmaState));
+
+        // Store creation timestamp to prevent duplicates
+        const creationState = {
+          rmaRef: rma.ref,
+          createdAt: new Date().toISOString(),
+        };
+        await kvAdapter.set(`rma-creation:${payload.order_id}`, JSON.stringify(creationState));
+
+        log.info('[RMA] State stored in KV', { rmaRef: rma.ref });
+
+        // =================================================================
+        // STEP 7: GENERATE RETURN SHIPPING LABEL (MOCK)
+        // =================================================================
+        log.info('[RMA] Generating return shipping label', {
+          rmaRef: rma.ref,
+          customerEmail: rma.customer.email,
+        });
+
+        // In production, integrate with ShipStation, EasyPost, or carrier API
+        const shippingLabel = {
+          trackingNumber: `TRK-${Date.now()}`,
+          labelUrl: `https://labels.example.com/${rma.ref}.pdf`,
+          carrier: 'USPS',
+          service: 'Priority Mail',
+          estimatedDelivery: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000).toISOString(),
+        };
+
+        // Update RMA with shipping label info
+        await fluentClient.graphql({
+          query: `mutation UpdateRMA($id: ID!, $input: UpdateRMAInput!) {
+              updateRMA(id: $id, input: $input) {
+                id
+                ref
+                attributes {
+                  name
+                  value
+                }
+              }
+            }`,
+          variables: {
+            id: rma.id,
+            input: {
+              attributes: [
+                { name: 'returnTrackingNumber', type: 'STRING', value: shippingLabel.trackingNumber },
+                { name: 'returnLabelUrl', type: 'STRING', value: shippingLabel.labelUrl },
+                { name: 'returnCarrier', type: 'STRING', value: shippingLabel.carrier },
+              ],
+            },
+          },
+        });
+
+        log.info('[RMA] Shipping label generated', {
+          trackingNumber: shippingLabel.trackingNumber,
+        });
+
+        // =================================================================
+        // STEP 8: SEND EMAIL NOTIFICATION
+        // =================================================================
+        // In production, integrate with SendGrid, AWS SES, etc.
+        log.info('[RMA] Sending email notification', {
+          to: rma.customer.email,
+          rmaRef: rma.ref,
+          trackingNumber: shippingLabel.trackingNumber,
+        });
+
+        // =================================================================
+        // STEP 9: LOG SUCCESS
+        // =================================================================
+        const duration = Date.now() - startTime;
+        log.info('✅ [BACKGROUND] RMA creation completed successfully', {
+          rmaRef: rma.ref,
+          rmaId: rma.id,
+          duration: `${duration}ms`,
+        });
+      } catch (error: any) {
+        // ? Enhanced: Error logging with recommendations
+        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',
+          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 return request structure'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : error.message?.includes('duplicate') || error.message?.includes('already exists')
+            ? 'RMA may already exist for this order - check existing RMAs'
+            : error.message?.includes('eligible') || error.message?.includes('return window')
+            ? 'Return request is outside the return window - verify order date'
+            : 'Review error details and check return request payload structure',
+        };
+        log.error('❌ [BACKGROUND] RMA creation failed', errorDetails);
+      }
+}
+
+/**
+ * RMA Creation Webhook Handler
+ * Uses sync + fire-and-forget pattern for fast response
+ */
+export const createRmaFromReturn = webhook('create-rma', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+}, async (ctx) => {
+  const { log, activation } = ctx;
+  const startTime = Date.now();
+  const payload = activation?.body || ctx.data;
+
+  log.info('🚀 [WEBHOOK] Received RMA creation webhook', {
+    source: payload?.source || 'unknown',
+    orderId: payload?.order_id || payload?.orderId,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Quick validation
+  if (!ctx.connections || !ctx.connections.fluent_commerce) {
+    log.error('❌ [WEBHOOK] Missing fluent_commerce connection');
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Missing fluent_commerce connection',
+        recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials',
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+
+  // Detect payload format (Shopify JSON vs SFCC XML)
+  const isShopify = payload.order_id && payload.return_line_items;
+  const isSFCC = payload.ReturnRequest || payload.return;
+
+  if (!isShopify && !isSFCC) {
+    log.error('❌ [WEBHOOK] Invalid payload format');
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'INVALID_FORMAT',
+        message: 'Unsupported return request format',
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+
+  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
+    source: isShopify ? 'Shopify' : 'SFCC',
+  });
+
+  // ✅ Fire-and-forget: Start background processing WITHOUT await
+  // The promise continues execution after we return the response
+  processRmaCreation(ctx, startTime)
+    .then(() => {
+      log.info('✅ [BACKGROUND] RMA creation processing completed successfully', {
+        orderId: payload?.order_id || payload?.orderId,
+      });
+    })
+    .catch((error: unknown) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      log.error('❌ [BACKGROUND] RMA creation processing failed', {
+        orderId: payload?.order_id || payload?.orderId,
+        error: errorMessage,
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : typeof error,
+      });
+    });
+
+  // Return immediately (response sent with this return value)
+  return {
+    status: 200,
+    body: {
+      success: true,
+      message: 'RMA creation started in background',
+      timestamp: new Date().toISOString(),
+    },
+  };
+});
+
+/**
+ * WEBHOOK 2: Track Return Shipment
+ *
+ * Receives shipment tracking updates (from carrier or ShipStation)
+ * and updates RMA status in Fluent.
+ */
+export const trackReturnShipment = webhook('track-return-shipment', async (ctx) => {
+  const { log, activation } = ctx;
+  const payload = activation?.body || ctx.data;
+  const startTime = Date.now();
+
+  log.info('🚀 [RMA] Received shipment tracking update', {
+    trackingNumber: payload.tracking_number,
+    status: payload.status,
+  });
+
+  try {
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+        // Find RMA by tracking number
+        const trackingNumber = payload.tracking_number || payload.trackingNumber;
+
+        // Query Fluent for RMA with this tracking number
+        const rmaResult = await fluentClient.graphql({
+          query: `query FindRMAByTracking($trackingNumber: String!) {
+              rmas(
+                first: 1
+                attributes: [
+                  { name: "returnTrackingNumber", value: $trackingNumber }
+                ]
+              ) {
+                edges {
+                  node {
+                    id
+                    ref
+                    status
+                    orderRef
+                  }
+                }
+              }
+            }`,
+          variables: { trackingNumber },
+        });
+
+        const rma = rmaResult.data?.rmas?.edges[0]?.node;
+
+        if (!rma) {
+          log.warn('⚠️ [RMA] No RMA found for tracking number', { trackingNumber });
+          return {
+            status: 404,
+            body: {
+              success: false,
+              error: 'RMA_NOT_FOUND',
+              message: `No RMA found with tracking number ${trackingNumber}`,
+              timestamp: new Date().toISOString(),
+            },
+          };
+        }
+
+        log.info('✅ [RMA] Found RMA for tracking update', {
+          rmaId: rma.id,
+          rmaRef: rma.ref,
+        });
+
+        // Map carrier status to RMA status
+        const carrierStatus = payload.status?.toUpperCase();
+        let rmaStatus = rma.status;
+        let eventType = 'TRACKING_UPDATE';
+
+        switch (carrierStatus) {
+          case 'IN_TRANSIT':
+            rmaStatus = 'IN_TRANSIT';
+            eventType = 'SHIPMENT_IN_TRANSIT';
+            break;
+          case 'OUT_FOR_DELIVERY':
+            rmaStatus = 'OUT_FOR_DELIVERY';
+            eventType = 'SHIPMENT_OUT_FOR_DELIVERY';
+            break;
+          case 'DELIVERED':
+            rmaStatus = 'RECEIVED';
+            eventType = 'SHIPMENT_DELIVERED';
+            break;
+          case 'EXCEPTION':
+          case 'FAILED':
+            rmaStatus = 'SHIPMENT_EXCEPTION';
+            eventType = 'SHIPMENT_EXCEPTION';
+            break;
+        }
+
+        // Update RMA status in Fluent
+        await fluentClient.graphql({
+          query: `mutation UpdateRMAStatus($id: ID!, $input: UpdateRMAInput!) {
+              updateRMA(id: $id, input: $input) {
+                id
+                ref
+                status
+              }
+            }`,
+          variables: {
+            id: rma.id,
+            input: {
+              status: rmaStatus,
+              attributes: [
+                { name: 'lastTrackingUpdate', type: 'STRING', value: new Date().toISOString() },
+                { name: 'carrierStatus', type: 'STRING', value: carrierStatus },
+              ],
+            },
+          },
+        });
+
+        // Update KV state
+        const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
+        if (existingStateJson) {
+          const existingState = JSON.parse(existingStateJson);
+          const updatedState = {
+            ...existingState,
+            status: rmaStatus,
+            lastTrackingUpdate: new Date().toISOString(),
+            carrierStatus,
+            stage: eventType,
+          };
+          await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
+        }
+
+        const duration = Date.now() - startTime;
+        log.info('✅ [RMA] RMA status updated', {
+          rmaRef: rma.ref,
+          oldStatus: rma.status,
+          newStatus: rmaStatus,
+          duration: `${duration}ms`,
+        });
+
+        return {
+          status: 200,
+          body: {
+            success: true,
+            rmaRef: rma.ref,
+            status: rmaStatus,
+            eventType,
+            message: 'RMA status updated successfully',
+            duration: `${duration}ms`,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      } catch (error: any) {
+        // ? Enhanced: Error logging with recommendations
+        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',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('not found') || error.message?.includes('missing')
+            ? 'RMA not found - verify tracking number and RMA reference'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details and check tracking update payload structure',
+        };
+        log.error('[RMA] Failed to process tracking update', errorDetails);
+        return {
+          status: 500,
+          body: {
+            success: false,
+            error: error.message,
+            recommendation: errorDetails.recommendation,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      }
+    });
+
+/**
+ * WEBHOOK 3: Quality Inspection
+ *
+ * Warehouse receives return, inspects items, and updates RMA with inspection results.
+ * Determines if items can be restocked, need repair, or should be scrapped.
+ */
+export const qualityInspection = webhook('quality-inspection', async (ctx) => {
+  const { log, activation } = ctx;
+  const payload = activation?.body || ctx.data;
+  const startTime = Date.now();
+
+  log.info('🚀 [RMA] Processing quality inspection', {
+    rmaRef: payload.rmaRef,
+    itemCount: payload.items?.length || 0,
+  });
+
+  try {
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+    // Validate payload
+    if (!payload.rmaRef || !payload.items || payload.items.length === 0) {
+      return {
+        status: 400,
+        body: {
+          success: false,
+          error: 'INVALID_PAYLOAD',
+          message: 'Invalid inspection payload: missing rmaRef or items',
+          timestamp: new Date().toISOString(),
+        },
+      };
+    }
+
+        // =================================================================
+        // STEP 1: RETRIEVE RMA FROM FLUENT
+        // =================================================================
+        const rmaResult = await fluentClient.graphql({
+          query: `query GetRMA($ref: String!) {
+              rma(ref: $ref) {
+                id
+                ref
+                status
+                orderRef
+                items {
+                  id
+                  productRef
+                  quantity
+                  returnReason
+                  restockingFee
+                }
+                customer {
+                  id
+                  email
+                }
+              }
+            }`,
+          variables: { ref: payload.rmaRef },
+        });
+
+        const rma = rmaResult.data?.rma;
+
+        if (!rma) {
+          return {
+            status: 404,
+            body: {
+              success: false,
+              error: 'RMA_NOT_FOUND',
+              message: `RMA not found: ${payload.rmaRef}`,
+              timestamp: new Date().toISOString(),
+            },
+          };
+        }
+
+        log.info('✅ [RMA] RMA retrieved', {
+          rmaId: rma.id,
+          rmaRef: rma.ref,
+          currentStatus: rma.status,
+        });
+
+        // =================================================================
+        // STEP 2: PROCESS INSPECTION RESULTS
+        // =================================================================
+        const inspectionResults = payload.items.map((item: any) => {
+          const condition = item.condition?.toUpperCase();
+          let disposition = 'RESTOCK';
+          let restockable = true;
+
+          switch (condition) {
+            case 'NEW':
+            case 'LIKE_NEW':
+              disposition = 'RESTOCK';
+              restockable = true;
+              break;
+            case 'DAMAGED':
+            case 'DEFECTIVE':
+              disposition = 'SCRAP';
+              restockable = false;
+              break;
+            case 'OPENED':
+            case 'USED':
+              disposition = 'OPEN_BOX';
+              restockable = true;
+              break;
+            case 'MISSING_PARTS':
+              disposition = 'REPAIR';
+              restockable = false;
+              break;
+            default:
+              disposition = 'MANUAL_REVIEW';
+              restockable = false;
+          }
+
+          return {
+            itemId: item.itemId,
+            productRef: item.productRef || item.sku,
+            condition,
+            disposition,
+            restockable,
+            notes: item.notes || '',
+            photoUrls: item.photoUrls || [],
+          };
+        });
+
+        log.info('✅ [RMA] Inspection results processed', {
+          total: inspectionResults.length,
+          restockable: inspectionResults.filter(r => r.restockable).length,
+          scrap: inspectionResults.filter(r => r.disposition === 'SCRAP').length,
+        });
+
+        // =================================================================
+        // STEP 3: UPDATE RMA WITH INSPECTION RESULTS
+        // =================================================================
+        await fluentClient.graphql({
+          query: `mutation UpdateRMAInspection($id: ID!, $input: UpdateRMAInput!) {
+              updateRMA(id: $id, input: $input) {
+                id
+                ref
+                status
+              }
+            }`,
+          variables: {
+            id: rma.id,
+            input: {
+              status: 'INSPECTED',
+              attributes: [
+                { name: 'inspectionDate', type: 'STRING', value: new Date().toISOString() },
+                { name: 'inspectionResults', type: 'JSON', value: JSON.stringify(inspectionResults) },
+                { name: 'inspector', type: 'STRING', value: payload.inspector || 'SYSTEM' },
+              ],
+            },
+          },
+        });
+
+        log.info('[RMA] RMA updated with inspection results', {
+          rmaRef: rma.ref,
+          status: 'INSPECTED',
+        });
+
+        // =================================================================
+        // STEP 4: UPDATE INVENTORY FOR RESTOCKABLE ITEMS
+        // =================================================================
+        const restockableItems = inspectionResults.filter(r => r.restockable);
+
+        if (restockableItems.length > 0) {
+          log.info('[RMA] Restocking items', {
+            count: restockableItems.length,
+          });
+
+          for (const item of restockableItems) {
+            // Increment inventory for restockable items
+            await fluentClient.graphql({
+              query: `mutation AdjustInventory($input: AdjustInventoryInput!) {
+                  adjustInventory(input: $input) {
+                    id
+                    ref
+                    quantity
+                  }
+                }`,
+              variables: {
+                input: {
+                  productRef: item.productRef,
+                  locationRef: payload.locationRef || 'RETURNS_WAREHOUSE',
+                  adjustment: 1, // Increment by quantity returned
+                  reason: 'RMA_RESTOCK',
+                  ref: `${rma.ref}-${item.productRef}`,
+                },
+              },
+            });
+
+            log.info('[RMA] Inventory adjusted', {
+              productRef: item.productRef,
+              disposition: item.disposition,
+            });
+          }
+        }
+
+        // =================================================================
+        // STEP 5: UPDATE KV STATE
+        // =================================================================
+        const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
+        if (existingStateJson) {
+          const existingState = JSON.parse(existingStateJson);
+          const updatedState = {
+            ...existingState,
+            status: 'INSPECTED',
+            stage: 'INSPECTION_COMPLETE',
+            inspectionResults,
+            inspectionDate: new Date().toISOString(),
+          };
+          await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
+        }
+
+        // =================================================================
+        // STEP 6: DETERMINE NEXT ACTION (REFUND OR EXCHANGE)
+        // =================================================================
+        const refundApproved = inspectionResults.every(r =>
+          r.disposition === 'RESTOCK' || r.disposition === 'OPEN_BOX'
+        );
+
+        const duration = Date.now() - startTime;
+        log.info('✅ [RMA] Inspection complete', {
+          rmaRef: rma.ref,
+          refundApproved,
+          nextAction: payload.returnType === 'exchange' ? 'CREATE_EXCHANGE_ORDER' : 'PROCESS_REFUND',
+          duration: `${duration}ms`,
+        });
+
+        return {
+          status: 200,
+          body: {
+            success: true,
+            rmaRef: rma.ref,
+            status: 'INSPECTED',
+            inspectionResults,
+            refundApproved,
+            nextAction: payload.returnType === 'exchange' ? 'CREATE_EXCHANGE_ORDER' : 'PROCESS_REFUND',
+            message: 'Quality inspection completed successfully',
+            duration: `${duration}ms`,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      } catch (error: any) {
+        // ? Enhanced: Error logging with recommendations
+        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',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('not found') || error.message?.includes('missing')
+            ? 'RMA not found - verify RMA reference and inspection payload structure'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details and check inspection payload structure',
+        };
+        log.error('[RMA] Failed to process inspection', errorDetails);
+        return {
+          status: 500,
+          body: {
+            success: false,
+            error: error.message,
+            recommendation: errorDetails.recommendation,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      }
+    });
+
+/**
+ * WEBHOOK 4: Process Refund or Exchange
+ *
+ * After inspection approval, processes refund via payment gateway
+ * or creates exchange order.
+ */
+export const processRefundOrExchange = webhook('process-refund-exchange', async (ctx) => {
+  const { log, activation } = ctx;
+  const payload = activation?.body || ctx.data;
+  const startTime = Date.now();
+
+  log.info('🚀 [RMA] Processing refund/exchange', {
+    rmaRef: payload.rmaRef,
+    actionType: payload.actionType, // 'refund' or 'exchange'
+  });
+
+  try {
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+        // Retrieve RMA
+        const rmaResult = await fluentClient.graphql({
+          query: `query GetRMA($ref: String!) {
+              rma(ref: $ref) {
+                id
+                ref
+                status
+                orderRef
+                items {
+                  id
+                  productRef
+                  quantity
+                  price
+                  restockingFee
+                }
+                customer {
+                  id
+                  email
+                }
+                attributes {
+                  name
+                  value
+                }
+              }
+            }`,
+          variables: { ref: payload.rmaRef },
+        });
+
+        const rma = rmaResult.data?.rma;
+
+        if (!rma) {
+          return {
+            status: 404,
+            body: {
+              success: false,
+              error: 'RMA_NOT_FOUND',
+              message: `RMA not found: ${payload.rmaRef}`,
+              timestamp: new Date().toISOString(),
+            },
+          };
+        }
+
+        const actionType = payload.actionType?.toLowerCase();
+
+        // =================================================================
+        // OPTION 1: PROCESS REFUND
+        // =================================================================
+        if (actionType === 'refund') {
+          log.info('💰 [RMA] Processing refund', { rmaRef: rma.ref });
+
+          // Calculate refund amount (subtract restocking fees)
+          const totalRefund = rma.items.reduce((sum: number, item: any) => {
+            const itemTotal = item.price * item.quantity;
+            const restockingFee = item.restockingFee || 0;
+            return sum + (itemTotal - restockingFee);
+          }, 0);
+
+          log.info('[RMA] Refund calculated', {
+            totalRefund,
+            itemCount: rma.items.length,
+          });
+
+          // In production, integrate with payment gateway (Stripe, Adyen, etc.)
+          const refundResponse = {
+            refundId: `REF-${Date.now()}`,
+            amount: totalRefund,
+            currency: 'USD',
+            status: 'PROCESSED',
+            transactionId: `TXN-${Date.now()}`,
+          };
+
+          // Update RMA status
+          await fluentClient.graphql({
+            query: `mutation UpdateRMARefund($id: ID!, $input: UpdateRMAInput!) {
+                updateRMA(id: $id, input: $input) {
+                  id
+                  ref
+                  status
+                }
+              }`,
+            variables: {
+              id: rma.id,
+              input: {
+                status: 'REFUNDED',
+                attributes: [
+                  { name: 'refundId', type: 'STRING', value: refundResponse.refundId },
+                  { name: 'refundAmount', type: 'STRING', value: totalRefund.toString() },
+                  { name: 'refundDate', type: 'STRING', value: new Date().toISOString() },
+                ],
+              },
+            },
+          });
+
+          // Update KV state
+          const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
+          if (existingStateJson) {
+            const existingState = JSON.parse(existingStateJson);
+            const updatedState = {
+              ...existingState,
+              status: 'REFUNDED',
+              stage: 'REFUND_COMPLETE',
+              refundAmount: totalRefund,
+              refundId: refundResponse.refundId,
+              refundDate: new Date().toISOString(),
+            };
+            await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
+          }
+
+          const duration = Date.now() - startTime;
+          log.info('✅ [RMA] Refund processed successfully', {
+            rmaRef: rma.ref,
+            refundId: refundResponse.refundId,
+            amount: totalRefund,
+            duration: `${duration}ms`,
+          });
+
+          return {
+            status: 200,
+            body: {
+              success: true,
+              rmaRef: rma.ref,
+              actionType: 'refund',
+              refund: refundResponse,
+              message: `Refund of $${totalRefund} processed successfully`,
+              duration: `${duration}ms`,
+              timestamp: new Date().toISOString(),
+            },
+          };
+        }
+
+        // =================================================================
+        // OPTION 2: CREATE EXCHANGE ORDER
+        // =================================================================
+        if (actionType === 'exchange') {
+          log.info('🔄 [RMA] Creating exchange order', { rmaRef: rma.ref });
+
+          // Exchange items (from payload)
+          const exchangeItems = payload.exchangeItems || [];
+
+          if (exchangeItems.length === 0) {
+            return {
+              status: 400,
+              body: {
+                success: false,
+                error: 'INVALID_PAYLOAD',
+                message: 'No exchange items provided',
+                timestamp: new Date().toISOString(),
+              },
+            };
+          }
+
+          // Create new order in Fluent
+          const exchangeOrderResult = await fluentClient.graphql({
+            query: `mutation CreateExchangeOrder($input: CreateOrderInput!) {
+                createOrder(input: $input) {
+                  id
+                  ref
+                  status
+                  items {
+                    id
+                    productRef
+                    quantity
+                  }
+                }
+              }`,
+            variables: {
+              input: {
+                ref: `EXCH-${rma.ref}`,
+                type: 'EXCHANGE',
+                customerId: rma.customer.id,
+                items: exchangeItems.map((item: any) => ({
+                  productRef: item.productRef,
+                  quantity: item.quantity,
+                })),
+                attributes: [
+                  { name: 'originalRMA', type: 'STRING', value: rma.ref },
+                  { name: 'originalOrder', type: 'STRING', value: rma.orderRef },
+                  { name: 'source', type: 'STRING', value: 'RMA_EXCHANGE' },
+                ],
+              },
+            },
+          });
+
+          const exchangeOrder = exchangeOrderResult.data?.createOrder;
+
+          if (!exchangeOrder) {
+            return {
+              status: 502,
+              body: {
+                success: false,
+                error: 'API_ERROR',
+                message: 'Failed to create exchange order',
+                timestamp: new Date().toISOString(),
+              },
+            };
+          }
+
+          // Update RMA with exchange order reference
+          await fluentClient.graphql({
+            query: `mutation UpdateRMAExchange($id: ID!, $input: UpdateRMAInput!) {
+                updateRMA(id: $id, input: $input) {
+                  id
+                  ref
+                  status
+                }
+              }`,
+            variables: {
+              id: rma.id,
+              input: {
+                status: 'EXCHANGED',
+                attributes: [
+                  { name: 'exchangeOrderRef', type: 'STRING', value: exchangeOrder.ref },
+                  { name: 'exchangeDate', type: 'STRING', value: new Date().toISOString() },
+                ],
+              },
+            },
+          });
+
+          // Update KV state
+          const existingStateJson = await kvAdapter.get(`rma:${rma.ref}`);
+          if (existingStateJson) {
+            const existingState = JSON.parse(existingStateJson);
+            const updatedState = {
+              ...existingState,
+              status: 'EXCHANGED',
+              stage: 'EXCHANGE_COMPLETE',
+              exchangeOrderRef: exchangeOrder.ref,
+              exchangeDate: new Date().toISOString(),
+            };
+            await kvAdapter.set(`rma:${rma.ref}`, JSON.stringify(updatedState));
+          }
+
+          const duration = Date.now() - startTime;
+          log.info('✅ [RMA] Exchange order created', {
+            rmaRef: rma.ref,
+            exchangeOrderRef: exchangeOrder.ref,
+            duration: `${duration}ms`,
+          });
+
+          return {
+            status: 200,
+            body: {
+              success: true,
+              rmaRef: rma.ref,
+              actionType: 'exchange',
+              exchangeOrder: {
+                ref: exchangeOrder.ref,
+                id: exchangeOrder.id,
+                status: exchangeOrder.status,
+              },
+              message: `Exchange order ${exchangeOrder.ref} created successfully`,
+              duration: `${duration}ms`,
+              timestamp: new Date().toISOString(),
+            },
+          };
+        }
+
+        return {
+          status: 400,
+          body: {
+            success: false,
+            error: 'INVALID_ACTION_TYPE',
+            message: `Invalid action type: ${actionType}`,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      } catch (error: any) {
+        // ? Enhanced: Error logging with recommendations
+        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',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('payment') || error.message?.includes('gateway')
+            ? 'Check payment gateway configuration and refund processing credentials'
+            : error.message?.includes('exchange') || error.message?.includes('order')
+            ? 'Check exchange order creation payload and product availability'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details and check refund/exchange payload structure',
+        };
+        log.error('[RMA] Failed to process refund/exchange', errorDetails);
+        return {
+          status: 500,
+          body: {
+            success: false,
+            error: error.message,
+            recommendation: errorDetails.recommendation,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      }
+    });
+
+/**
+ * WEBHOOK 5: Get RMA Status
+ *
+ * Query endpoint to retrieve RMA status and history
+ */
+export const getRmaStatus = webhook('get-rma-status', async (ctx) => {
+  const { log, activation } = ctx;
+  const payload = activation?.body || ctx.data;
+  const rmaRef = payload?.rmaRef || ctx.query?.rmaRef;
+  const startTime = Date.now();
+
+  log.info('🚀 [RMA] Querying RMA status', { rmaRef });
+
+  if (!rmaRef) {
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'MISSING_PARAMETER',
+        message: 'Missing rmaRef parameter',
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+
+  try {
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+        // Get RMA from Fluent
+        const rmaResult = await fluentClient.graphql({
+          query: `query GetRMA($ref: String!) {
+              rma(ref: $ref) {
+                id
+                ref
+                status
+                orderRef
+                items {
+                  id
+                  productRef
+                  quantity
+                  returnReason
+                  price
+                  restockingFee
+                }
+                customer {
+                  id
+                  firstName
+                  lastName
+                  email
+                }
+                createdOn
+                updatedOn
+                attributes {
+                  name
+                  value
+                }
+              }
+            }`,
+          variables: { ref: rmaRef },
+        });
+
+        const rma = rmaResult.data?.rma;
+
+        if (!rma) {
+          return {
+            status: 404,
+            body: {
+              success: false,
+              error: 'RMA_NOT_FOUND',
+              message: `RMA not found: ${rmaRef}`,
+              timestamp: new Date().toISOString(),
+            },
+          };
+        }
+
+        // Get state from KV
+        const rmaStateJson = await kvAdapter.get(`rma:${rmaRef}`);
+        const rmaState = rmaStateJson ? JSON.parse(rmaStateJson) : null;
+
+        const duration = Date.now() - startTime;
+        log.info('✅ [RMA] Status query complete', {
+          rmaRef: rma.ref,
+          status: rma.status,
+          duration: `${duration}ms`,
+        });
+
+        return {
+          status: 200,
+          body: {
+            success: true,
+            rma: {
+              id: rma.id,
+              ref: rma.ref,
+              status: rma.status,
+              orderRef: rma.orderRef,
+              itemCount: rma.items.length,
+              customer: rma.customer,
+              createdOn: rma.createdOn,
+              updatedOn: rma.updatedOn,
+            },
+            state: rmaState,
+            attributes: rma.attributes,
+            duration: `${duration}ms`,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      } catch (error: any) {
+        // ? Enhanced: Error logging with recommendations
+        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',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('not found') || error.message?.includes('missing')
+            ? 'RMA not found - verify RMA reference and query parameters'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details and check RMA status query parameters',
+        };
+        log.error('[RMA] Failed to query RMA', errorDetails);
+        return {
+          status: 500,
+          body: {
+            success: false,
+            error: error.message,
+            recommendation: errorDetails.recommendation,
+            timestamp: new Date().toISOString(),
+          },
+        };
+      }
+    });
+```
+
+---
+
+## 2. RMA Mapping Configuration: `mappings/shopify-return-to-rma.json`
+
+```json
+{
+  "version": "1.0.0",
+  "description": "Shopify return request to Fluent RMA mapping",
+  "direction": "ingest",
+  "sourceFormat": "json",
+  "fields": {
+    "ref": {
+      "source": "order_id",
+      "resolver": "custom.generateRmaRef",
+      "required": true
+    },
+    "orderRef": {
+      "source": "order_id",
+      "required": true
+    },
+    "customerId": {
+      "source": "customer.id",
+      "required": true
+    },
+    "customerEmail": {
+      "source": "customer.email",
+      "resolver": "sdk.lowercase",
+      "required": true
+    },
+    "eligible": {
+      "source": "order.created_at",
+      "resolver": "custom.isReturnEligible"
+    },
+    "returnMethod": {
+      "source": "return_method",
+      "defaultValue": "SHIP_BACK"
+    },
+    "primaryReason": {
+      "source": "return_line_items[0].reason",
+      "resolver": "custom.mapReturnReason"
+    },
+    "notes": {
+      "source": "note",
+      "required": false
+    },
+    "items": {
+      "source": "return_line_items",
+      "isArray": true,
+      "fields": {
+        "lineItemId": {
+          "source": "line_item_id",
+          "resolver": "sdk.toString"
+        },
+        "productRef": {
+          "source": "sku",
+          "required": true
+        },
+        "quantity": {
+          "source": "quantity",
+          "resolver": "sdk.parseInt",
+          "required": true
+        },
+        "returnReason": {
+          "source": "reason",
+          "resolver": "custom.mapReturnReason",
+          "required": true
+        },
+        "customerNotes": {
+          "source": "customer_note",
+          "required": false
+        },
+        "price": {
+          "source": "price",
+          "resolver": "sdk.parseFloat"
+        },
+        "restockingFee": {
+          "resolver": "custom.calculateRestockingFee",
+          "comment": "Resolver-only field - receives full item as sourceData"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: Return Reason Mapping
+
+Map e-commerce return reasons to Fluent reason codes:
+
+```typescript
+'custom.mapReturnReason': (reason: string) => {
+  const reasonMap: Record<string, string> = {
+    'changed_mind': 'CUSTOMER_REMORSE',
+    'defective': 'DEFECTIVE',
+    'wrong_item': 'WRONG_ITEM_SHIPPED',
+    'damaged': 'DAMAGED_IN_TRANSIT',
+    'not_as_described': 'NOT_AS_DESCRIBED',
+    'sizing_issues': 'SIZE_FIT_ISSUE',
+    'late_delivery': 'LATE_DELIVERY',
+    'other': 'OTHER',
+  };
+  return reasonMap[reason?.toLowerCase()] || 'OTHER';
+}
+```
+
+### Pattern 2: Restocking Fee Calculation
+
+Calculate restocking fees based on return reason using resolver-only field:
+
+```typescript
+// Resolver-only field pattern: receives (value, sourceData, helpers)
+// value = undefined (no source specified)
+// sourceData = current array item containing all fields
+'custom.calculateRestockingFee': (value: any, sourceData: any, helpers: any) => {
+  const feeMap: Record<string, number> = {
+    'CUSTOMER_REMORSE': 0.15,    // 15% restocking fee
+    'SIZE_FIT_ISSUE': 0.10,      // 10% restocking fee
+    'OTHER': 0.10,
+    'DEFECTIVE': 0,              // No fee for defective items
+    'WRONG_ITEM_SHIPPED': 0,     // No fee for our errors
+    'DAMAGED_IN_TRANSIT': 0,
+  };
+
+  // Extract fields from sourceData (the current array item)
+  const reason = sourceData?.reason || 'OTHER';
+  const price = helpers.parseFloatSafe(sourceData?.price, 0);
+
+  const feePercentage = feeMap[reason] || 0;
+  return price * feePercentage;
+}
+```
+
+**Mapping Configuration:**
+```json
+{
+  "restockingFee": {
+    "resolver": "custom.calculateRestockingFee",
+    "comment": "Resolver-only field - no source, extracts from sourceData"
+  }
+}
+```
+
+### Pattern 3: Return Eligibility Check
+
+Validate returns are within policy window (e.g., 30 days):
+
+```typescript
+'custom.isReturnEligible': (orderDate: string) => {
+  const orderTime = new Date(orderDate).getTime();
+  const now = Date.now();
+  const daysSinceOrder = (now - orderTime) / (1000 * 60 * 60 * 24);
+  return daysSinceOrder <= 30; // 30-day return window
+}
+```
+
+### Pattern 4: Quality Inspection States
+
+Map inspection condition to disposition:
+
+```typescript
+const condition = item.condition?.toUpperCase();
+let disposition = 'RESTOCK';
+let restockable = true;
+
+switch (condition) {
+  case 'NEW':
+  case 'LIKE_NEW':
+    disposition = 'RESTOCK';
+    restockable = true;
+    break;
+  case 'DAMAGED':
+  case 'DEFECTIVE':
+    disposition = 'SCRAP';
+    restockable = false;
+    break;
+  case 'OPENED':
+  case 'USED':
+    disposition = 'OPEN_BOX';
+    restockable = true;
+    break;
+  case 'MISSING_PARTS':
+    disposition = 'REPAIR';
+    restockable = false;
+    break;
+  default:
+    disposition = 'MANUAL_REVIEW';
+    restockable = false;
+}
+```
+
+### Pattern 5: Refund vs Exchange Decision Tree
+
+Determine next action based on inspection results:
+
+```typescript
+// Check if all items passed inspection
+const refundApproved = inspectionResults.every(r =>
+  r.disposition === 'RESTOCK' || r.disposition === 'OPEN_BOX'
+);
+
+// Determine next action
+const nextAction = payload.returnType === 'exchange'
+  ? 'CREATE_EXCHANGE_ORDER'
+  : 'PROCESS_REFUND';
+
+log.info('[RMA] Inspection complete', {
+  rmaRef: rma.ref,
+  refundApproved,
+  nextAction,
+});
+```
+
+### Pattern 6: Partial Returns
+
+Handle returns of some items from an order:
+
+```json
+{
+  "items": {
+    "source": "return_line_items",
+    "isArray": true,
+    "fields": {
+      "lineItemId": { "source": "line_item_id" },
+      "productRef": { "source": "sku" },
+      "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
+    }
+  }
+}
+```
+
+**Key**: Use `isArray: true` to map each line item individually.
+
+### Pattern 7: VersoriKV RMA Lifecycle Tracking
+
+Track RMA state across all stages:
+
+```typescript
+// Store initial RMA state
+const rmaState = {
+  rmaId: rma.id,
+  rmaRef: rma.ref,
+  orderRef: rma.orderRef,
+  status: rma.status,
+  stage: 'RMA_CREATED',
+  createdOn: rma.createdOn,
+};
+await kvAdapter.set(`rma:${rma.ref}`, rmaState);
+
+// Update state at each stage
+const existingState = await kvAdapter.get(`rma:${rma.ref}`);
+if (existingState) {
+  const updatedState = {
+    ...existingState,
+    status: 'INSPECTED',
+    stage: 'INSPECTION_COMPLETE',
+    inspectionDate: new Date().toISOString(),
+  };
+  await kvAdapter.set(`rma:${rma.ref}`, updatedState);
+}
+
+// Query state
+const rmaStateJson = await kvAdapter.get(`rma:${rma.ref}`);
+const rmaState = rmaStateJson ? JSON.parse(rmaStateJson) : null;
+```
+
+---
+
+## Testing
+
+### 1. Test RMA Creation (Shopify Format)
+
+```bash
+curl -X POST https://your-workspace.versori.run/create-rma \
+  -H "Content-Type: application/json" \
+  -d '{
+    "order_id": "ORD-12345",
+    "customer": {
+      "id": "CUST-789",
+      "email": "customer@example.com"
+    },
+    "order": {
+      "created_at": "2025-01-15T10:00:00Z"
+    },
+    "return_line_items": [
+      {
+        "line_item_id": "LI-001",
+        "sku": "PROD-ABC123",
+        "quantity": 1,
+        "reason": "wrong_item",
+        "customer_note": "Received wrong size",
+        "price": 99.99
+      }
+    ],
+    "return_method": "SHIP_BACK",
+    "note": "Customer wants exchange for correct size"
+  }'
+
+# Expected Response:
+{
+  "status": 200,
+  "body": {
+    "success": true,
+    "rmaId": "RMA-123",
+    "rmaRef": "RMA-ORD-12345-456789",
+    "status": "PENDING_APPROVAL",
+    "shippingLabel": {
+      "trackingNumber": "TRK-1234567890",
+      "labelUrl": "https://labels.example.com/RMA-ORD-12345-456789.pdf",
+      "carrier": "USPS",
+      "service": "Priority Mail"
+    },
+    "message": "RMA created successfully. Return label sent to customer.",
+    "timestamp": "2025-10-30T12:00:00.000Z"
+  }
+}
+```
+
+### 2. Test Shipment Tracking Update
+
+```bash
+curl -X POST https://your-workspace.versori.run/track-return-shipment \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tracking_number": "TRK-1234567890",
+    "status": "DELIVERED",
+    "carrier": "USPS",
+    "timestamp": "2025-01-20T14:30:00Z"
+  }'
+```
+
+### 3. Test Quality Inspection
+
+```bash
+curl -X POST https://your-workspace.versori.run/quality-inspection \
+  -H "Content-Type: application/json" \
+  -d '{
+    "rmaRef": "RMA-ORD-12345-456789",
+    "inspector": "John Doe",
+    "locationRef": "RETURNS_WAREHOUSE",
+    "returnType": "refund",
+    "items": [
+      {
+        "itemId": "RMA-ITEM-001",
+        "productRef": "PROD-ABC123",
+        "condition": "NEW",
+        "notes": "Item in original packaging, tags attached",
+        "photoUrls": ["https://photos.example.com/item1.jpg"]
+      }
+    ]
+  }'
+```
+
+### 4. Test Refund Processing
+
+```bash
+curl -X POST https://your-workspace.versori.run/process-refund-exchange \
+  -H "Content-Type: application/json" \
+  -d '{
+    "rmaRef": "RMA-ORD-12345-456789",
+    "actionType": "refund"
+  }'
+```
+
+### 5. Test Exchange Order Creation
+
+```bash
+curl -X POST https://your-workspace.versori.run/process-refund-exchange \
+  -H "Content-Type: application/json" \
+  -d '{
+    "rmaRef": "RMA-ORD-12345-456789",
+    "actionType": "exchange",
+    "exchangeItems": [
+      {
+        "productRef": "PROD-ABC124",
+        "quantity": 1
+      }
+    ]
+  }'
+```
+
+### 6. Query RMA Status
+
+```bash
+curl https://your-workspace.versori.run/get-rma-status?rmaRef=RMA-ORD-12345-456789
+```
+
+---
+
+## Common Issues and Solutions
+
+### Issue 1: Return Request Rejected (Ineligible)
+
+**Symptoms:**
+- RMA creation fails with "INELIGIBLE" error
+- Returns outside policy window
+
+**Root Cause:**
+- Order is older than return window (30 days)
+
+**Solution:**
+
+```typescript
+// Adjust return window in custom resolver
+'custom.isReturnEligible': (orderDate: string) => {
+  const orderTime = new Date(orderDate).getTime();
+  const now = Date.now();
+  const daysSinceOrder = (now - orderTime) / (1000 * 60 * 60 * 24);
+
+  // Change to 60 days or make configurable via activation variable
+  return daysSinceOrder <= 60;
+}
+```
+
+### Issue 2: Restocking Fee Not Calculated
+
+**Symptoms:**
+- Restocking fee is 0 for all items
+- Refund amount is incorrect
+
+**Root Cause:**
+- Custom resolver not receiving price parameter
+- Mapping configuration missing price field
+
+**Solution:**
+
+```json
+{
+  "items": {
+    "source": "return_line_items",
+    "isArray": true,
+    "fields": {
+      "price": {
+        "source": "price",
+        "resolver": "sdk.parseFloat"
+      },
+      "restockingFee": {
+        "resolver": "custom.calculateRestockingFee",
+        "comment": "Resolver-only field - receives full item as sourceData parameter"
+      }
+    }
+  }
+}
+```
+
+### Issue 3: Inventory Not Restocked
+
+**Symptoms:**
+- Quality inspection completes but inventory doesn't increase
+- Restockable items not showing in inventory
+
+**Root Cause:**
+- Location reference incorrect
+- Inventory adjustment mutation failed
+
+**Solution:**
+
+```typescript
+// Verify location exists in Fluent
+const locationResult = await fluentClient.graphql({
+  query: `query { location(ref: "${payload.locationRef}") { id ref } }`
+});
+
+if (!locationResult.data?.location) {
+  log.warn('Location not found, using default', {
+    requestedLocation: payload.locationRef,
+    defaultLocation: 'RETURNS_WAREHOUSE',
+  });
+}
+
+// Use validated location
+const locationRef = locationResult.data?.location?.ref || 'RETURNS_WAREHOUSE';
+```
+
+### Issue 4: Duplicate RMA Creation
+
+**Symptoms:**
+- Multiple RMAs created for same return request
+- Duplicate tracking numbers
+
+**Root Cause:**
+- No duplicate detection
+- Webhook retries creating duplicates
+
+**Solution:**
+
+```typescript
+// Check if RMA already exists before creating
+const existingRma = await kvAdapter.get(`rma-creation:${payload.order_id}`);
+
+if (existingRma) {
+  log.info('[RMA] RMA already exists for this order', {
+    orderId: payload.order_id,
+    existingRmaRef: existingRma.rmaRef,
+  });
+
+  return {
+    success: true,
+    rmaRef: existingRma.rmaRef,
+    duplicate: true,
+    message: 'RMA already exists for this order',
+  };
+}
+
+// Create RMA...
+
+// Store creation state
+const creationState = {
+  rmaRef: rma.ref,
+  createdAt: new Date().toISOString(),
+};
+await kvAdapter.set(`rma-creation:${payload.order_id}`, JSON.stringify(creationState));
+```
+
+### Issue 5: Refund Amount Incorrect
+
+**Symptoms:**
+- Refund amount doesn't match expected value
+- Restocking fees not deducted
+
+**Root Cause:**
+- Calculation logic incorrect
+- Items missing price data
+
+**Solution:**
+
+```typescript
+// Detailed refund calculation with logging
+const refundDetails = rma.items.map((item: any) => {
+  const itemTotal = item.price * item.quantity;
+  const restockingFee = item.restockingFee || 0;
+  const itemRefund = itemTotal - restockingFee;
+
+  log.debug('[RMA] Item refund calculated', {
+    productRef: item.productRef,
+    quantity: item.quantity,
+    price: item.price,
+    itemTotal,
+    restockingFee,
+    itemRefund,
+  });
+
+  return {
+    productRef: item.productRef,
+    itemTotal,
+    restockingFee,
+    itemRefund,
+  };
+});
+
+const totalRefund = refundDetails.reduce((sum, detail) => sum + detail.itemRefund, 0);
+
+log.info('[RMA] Total refund calculated', {
+  totalRefund,
+  itemCount: refundDetails.length,
+  details: refundDetails,
+});
+```
+
+---
+
+## Related Guides
+
+- **[Versori Webhook: XML Order Processing](./xml-order-ingestion.md)** - Similar webhook patterns
+- **[Versori Scheduled: CSV Inventory Sync](../workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - State management patterns
+- **[KV State Management](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-06-kv-storage.md)** - VersoriKV usage
+- **[Universal Mapping Guide](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Field mapping patterns
+- **[Custom Resolvers](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Advanced resolver patterns
+- **[Error Handling](../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Error handling and retry logic
+
+---
+
+## Summary
+
+**Volume:** Medium (5-10% of order volume, 50-500 returns/day)
+
+**Latency:** Real-time (< 2 seconds per webhook)
+
+**Complexity:** Medium (multiple stages, state tracking, conditional logic)
+
+**Key Features:**
+- End-to-end return processing (initiation → refund/exchange)
+- Quality inspection workflow with condition tracking
+- Restocking fee calculation based on return reason
+- Inventory adjustments for restockable items
+- Exchange order creation
+- VersoriKV state management across RMA lifecycle
+- Email notifications at each stage
+- Support for partial returns
+- 30-day return policy enforcement
+
+**Real-World Considerations:**
+- Integrate with actual payment gateway (Stripe, Adyen) for refunds
+- Integrate with shipping provider (ShipStation, EasyPost) for return labels
+- Add email/SMS notifications via SendGrid or Twilio
+- Implement return fraud detection
+- Add approval workflow for high-value returns
+- Track return trends and analytics
+- Support international returns with customs
+- Handle restocking for serialized/batch-tracked items