@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md

@@ -1,682 +1,682 @@
-# Mapper Comparison Guide: Real-World Scenario
-
-> **📚 Quick Decision First?** See [Mapper Quick Decision Guide](../../00-START-HERE/mapper-quick-decision-guide.md) (2-minute read) for a simple decision table.
-
-**SCENARIO:** You have 100 locations in a CSV file. You need to create new locations or update existing ones in Fluent Commerce.
-
-**CSV Input:**
-```csv
-ref,name,status,type,address1,city,state,country,latitude,longitude
-DC-01,Distribution Center NYC,ACTIVE,DC,123 Main St,New York,NY,US,40.7128,-74.0060
-STORE-001,Manhattan Store,ACTIVE,STORE,456 Broadway,New York,NY,US,40.7580,-73.9855
-STORE-002,Brooklyn Store,ACTIVE,STORE,789 Atlantic Ave,Brooklyn,NY,US,40.6782,-73.9442
-... (97 more rows)
-```
-
-**Goal:** Create or update each location using Fluent Commerce API.
-
----
-
-## Overview: 4 Working Approaches
-
-| Approach | Field Mapping | API | GraphQL Query | Use Case |
-|----------|--------------|-----|---------------|----------|
-| **1. GraphQLMutationMapper** | ✅ Auto | GraphQL Mutations | ✅ Auto-generated | Complex XML/JSON, want schema validation |
-| **2. UniversalMapper + Manual GraphQL** | ✅ Auto | GraphQL Mutations | ❌ You write | CSV with transformations, control over queries |
-| **3. UniversalMapper + Event API** | ✅ Auto | Event API | ❌ N/A | Trigger Rubix workflows, bulk operations |
-| **4. Fully Manual** | ❌ Manual | GraphQL Mutations | ❌ You write | Simple operations, maximum control |
-
-**Key Insight:** UniversalMapper is NOT just for Batch API - it works with GraphQL mutations AND Event API!
-
----
-
-## Approach 1: GraphQLMutationMapper
-
-### When to Use
-✅ Complex XML/JSON structures (SFCC orders, EDI)
-✅ Want auto-generated GraphQL mutation queries
-✅ Need schema validation against GraphQL types
-✅ Prefer declarative configuration
-
-### Code
-
-```typescript
-import {
-  GraphQLMutationMapper,
-  CSVParserService,
-  createClient,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// 1. Parse CSV
-const parser = new CSVParserService();
-const locations = await parser.parse(csvContent, { columns: true });
-
-// 2. Configure mapping (CSV columns → GraphQL fields)
-const createConfig = {
-  mutation: 'createLocation',
-  operationName: 'CreateLocation',
-  sourceFormat: 'json' as const,
-  arguments: {
-    input: {
-      _type: 'CreateLocationInput!',
-      ref: { source: 'ref', required: true, resolver: 'sdk.trim' },
-      name: { source: 'name', required: true, resolver: 'sdk.trim' },
-      type: { source: 'type', required: true, resolver: 'sdk.uppercase' },
-      status: { source: 'status', defaultValue: 'ACTIVE' },
-      supportPhoneNumber: { value: '+1-800-555-0100' },
-      retailer: {
-        id: { value: '1', resolver: 'sdk.parseInt' },
-      },
-      primaryAddress: {
-        ref: { source: 'ref' },
-        street: { source: 'address1' },
-        city: { source: 'city' },
-        state: { source: 'state' },
-        country: { source: 'country' },
-        latitude: { source: 'latitude', resolver: 'sdk.parseFloat' },
-        longitude: { source: 'longitude', resolver: 'sdk.parseFloat' },
-      },
-      openingSchedule: {
-        allHours: { value: true },
-      },
-    },
-  },
-  returnFields: ['id', 'ref', 'type', 'status'],
-};
-
-// 3. Setup client and mapper
-const client = await createClient({ /* config */ });
-const createMapper = new GraphQLMutationMapper(createConfig, client);
-
-// 4. Process each location
-for (const location of locations) {
-  // Option A: Use map() - throws on error (use try/catch)
-  try {
-    const payload = await createMapper.map(location);
-    const result = await client.graphql(payload);
-    console.log(`✅ Created: ${location.ref}`);
-  } catch (error) {
-    console.error(`❌ Failed: ${location.ref}`, error);
-  }
-
-  // Option B: Use mapSafe() - returns result object (recommended for production)
-  const result = await createMapper.mapSafe(location);
-  if (!result.success) {
-    console.error(`❌ Failed: ${location.ref}`, result.errors);
-    continue;
-  }
-  await client.graphql({ query: result.query, variables: result.variables });
-  console.log(`✅ Created: ${location.ref}`);
-}
-```
-
-### What It Does
-1. **Auto-builds GraphQL mutation query** from mapping config
-2. **Validates** against GraphQL schema (catches type errors before sending)
-3. **Applies** SDK resolvers (`sdk.trim`, `sdk.parseFloat`, etc.)
-4. **Handles** nested structures automatically
-5. **Returns** `{ query, variables }` ready for execution
-
-### Pros
-✅ **Auto-generates mutation query** - Don't write GraphQL strings
-✅ **Schema validation** - Catches errors before sending to API
-✅ **Declarative config** - Easy to read and maintain
-✅ **Handles nested structures** - Automatic handling of `primaryAddress`
-✅ **Type safety** - GraphQL types validated
-
-### Cons
-❌ **Learning curve** - Need to understand mapping config syntax
-❌ **Verbose config** - More setup for simple mappings
-❌ **One-at-a-time** - 100 locations = 100 API calls
-
-### Performance
-- **100 locations** = 100 mutations = **100 API calls**
-- **Time**: ~30-60 seconds
-
----
-
-## Approach 2: UniversalMapper + Manual GraphQL
-
-### When to Use
-✅ Want field mapping/transformation (SDK resolvers)
-✅ Prefer writing your own GraphQL query strings
-✅ Need flexibility in GraphQL query structure
-✅ CSV/JSON with transformations
-
-### Code
-
-```typescript
-import {
-  UniversalMapper,
-  CSVParserService,
-  createClient,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// 1. Parse CSV
-const parser = new CSVParserService();
-const locations = await parser.parse(csvContent, { columns: true });
-
-// 2. Configure field mapping (UniversalMapper)
-const locationMapping = {
-  fields: {
-    ref: { source: 'ref', required: true, resolver: 'sdk.trim' },
-    name: { source: 'name', required: true, resolver: 'sdk.trim' },
-    type: { source: 'type', required: true, resolver: 'sdk.uppercase' },
-    status: { source: 'status', defaultValue: 'ACTIVE' },
-    supportPhoneNumber: { value: '+1-800-555-0100' },
-
-    // Nested address fields - UniversalMapper handles this!
-    'primaryAddress.ref': { source: 'ref' },
-    'primaryAddress.street': { source: 'address1' },
-    'primaryAddress.city': { source: 'city' },
-    'primaryAddress.state': { source: 'state' },
-    'primaryAddress.country': { source: 'country' },
-    'primaryAddress.latitude': { source: 'latitude', resolver: 'sdk.parseFloat' },
-    'primaryAddress.longitude': { source: 'longitude', resolver: 'sdk.parseFloat' },
-  },
-};
-
-// 3. Map all CSV records
-const mapper = new UniversalMapper(locationMapping);
-const mappedLocations = [];
-
-for (const location of locations) {
-  const mapped = await mapper.map(location);
-  if (mapped.success) {
-    mappedLocations.push(mapped.data);
-  } else {
-    console.error(`Mapping failed: ${mapped.errors?.join(', ')}`);
-  }
-}
-
-// 4. Write GraphQL mutation manually
-const createMutation = `
-  mutation CreateLocation($input: CreateLocationInput!) {
-    createLocation(input: $input) {
-      id
-      ref
-      name
-      type
-    }
-  }
-`;
-
-// 5. Setup client
-const client = await createClient({ /* config */ });
-
-// 6. Execute mutations using mapped data as variables
-for (const location of mappedLocations) {
-  // Use mapped plain object as GraphQL variables
-  const result = await client.graphql({
-    query: createMutation,
-    variables: { input: location }, // ✅ Mapped data from UniversalMapper!
-  });
-
-  console.log(`✅ Created: ${location.ref}`);
-}
-```
-
-### What It Does
-1. **UniversalMapper** handles field mapping and transformations
-2. **Returns plain objects** with nested structures properly formatted
-3. **YOU write** the GraphQL mutation strings
-4. **Use mapped objects** as GraphQL `variables`
-
-### Pros
-✅ **Field mapping with SDK resolvers** - Get transformations (`sdk.parseInt`, `sdk.trim`, etc.)
-✅ **Handles nested structures** - `primaryAddress.street` → proper nested object
-✅ **Full control over GraphQL** - Write exact queries you need
-✅ **Easier to debug** - See exactly what's happening
-✅ **Less learning curve** - Just mapping config + standard GraphQL
-
-### Cons
-❌ **Manual GraphQL queries** - Must write mutation strings yourself
-❌ **No schema validation** - Errors only at runtime
-❌ **More boilerplate** - Mapping config + GraphQL query strings
-❌ **One-at-a-time** - 100 locations = 100 API calls
-
-### Performance
-- **Same as GraphQLMutationMapper**: 100 locations = 100 API calls
-- **Time**: ~30-60 seconds
-
----
-
-## Approach 3: UniversalMapper + Event API
-
-### When to Use
-✅ Want to trigger Rubix workflows
-✅ Need asynchronous processing
-✅ Bulk operations that trigger business logic
-✅ Products, locations, or any entity with Rubix workflow
-
-### Code
-
-```typescript
-import {
-  UniversalMapper,
-  CSVParserService,
-  createClient,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// 1. Parse CSV
-const parser = new CSVParserService();
-const locations = await parser.parse(csvContent, { columns: true });
-
-// 2. Configure field mapping (same UniversalMapper config)
-const locationMapping = {
-  fields: {
-    ref: { source: 'ref', required: true, resolver: 'sdk.trim' },
-    name: { source: 'name', required: true, resolver: 'sdk.trim' },
-    type: { source: 'type', required: true, resolver: 'sdk.uppercase' },
-    status: { source: 'status', defaultValue: 'ACTIVE' },
-
-    // Nested address fields
-    'primaryAddress.ref': { source: 'ref' },
-    'primaryAddress.street': { source: 'address1' },
-    'primaryAddress.city': { source: 'city' },
-    'primaryAddress.state': { source: 'state' },
-    'primaryAddress.country': { source: 'country' },
-    'primaryAddress.latitude': { source: 'latitude', resolver: 'sdk.parseFloat' },
-    'primaryAddress.longitude': { source: 'longitude', resolver: 'sdk.parseFloat' },
-  },
-};
-
-// 3. Map all CSV records
-const mapper = new UniversalMapper(locationMapping);
-const mappedLocations = [];
-
-for (const location of locations) {
-  const mapped = await mapper.map(location);
-  if (mapped.success) {
-    mappedLocations.push(mapped.data);
-  }
-}
-
-// 4. Setup client
-const client = await createClient({ /* config */ });
-
-// 5. Send each record as an event (triggers Rubix workflow)
-const eventName = 'UPSERT_LOCATION';
-const entityRef = 'LOCATION_CATALOGUE:MASTER:1'; // Your catalogue reference
-
-for (const location of mappedLocations) {
-  await client.sendEvent(
-    {
-      name: eventName,
-      entityRef: entityRef,
-      entityType: 'LOCATION_CATALOGUE',
-      entitySubtype: 'MASTER',
-      rootEntityRef: entityRef,
-      rootEntityType: 'LOCATION_CATALOGUE',
-      retailerId: '1',
-      attributes: location, // ✅ Mapped data from UniversalMapper!
-    },
-    'async' // or 'sync' for synchronous processing
-  );
-
-  console.log(`✅ Event sent: ${location.ref}`);
-}
-```
-
-### What It Does
-1. **UniversalMapper** handles field mapping and transformations
-2. **Returns plain objects** ready for Event API
-3. **Send to Event API** which triggers Rubix workflows
-4. **Workflows** handle the actual GraphQL mutations
-
-### Pros
-✅ **Field mapping with SDK resolvers** - Same as approach 2
-✅ **Triggers Rubix workflows** - Business logic execution
-✅ **Asynchronous processing** - Don't wait for completion
-✅ **Error recovery** - Workflows can retry
-✅ **Business logic** - Workflows can add custom validation, enrichment
-
-### Cons
-❌ **Requires Rubix workflows** - Need workflow setup
-❌ **No immediate feedback** - Async processing
-❌ **More complexity** - Workflow management
-❌ **One-at-a-time** - 100 locations = 100 events
-
-### Performance
-- **100 locations** = 100 event API calls
-- **Time**: ~30-60 seconds (event submission), plus async workflow processing
-
----
-
-## Approach 4: Fully Manual (No Mapper)
-
-### When to Use
-✅ Simple, one-off operations
-✅ Maximum control over everything
-✅ Prototyping/testing
-✅ Don't need field transformations
-
-### Code
-
-```typescript
-import { CSVParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// 1. Parse CSV manually
-const parser = new CSVParserService();
-const locations = await parser.parse(csvContent, { columns: true });
-
-// 2. Write GraphQL mutation manually
-const createMutation = `
-  mutation CreateLocation($input: CreateLocationInput!) {
-    createLocation(input: $input) {
-      id
-      ref
-      name
-      type
-    }
-  }
-`;
-
-// 3. Setup client
-const client = await createClient({ /* config */ });
-
-// 4. Process each location manually (build variables yourself)
-for (const location of locations) {
-  // Manually build variables object
-  const variables = {
-    input: {
-      ref: location.ref?.trim(),
-      name: location.name?.trim(),
-      type: location.type?.toUpperCase(),
-      status: location.status || 'ACTIVE',
-      supportPhoneNumber: '+1-800-555-0100',
-      primaryAddress: {
-        ref: location.ref,
-        street: location.address1,
-        city: location.city,
-        state: location.state,
-        country: location.country,
-        latitude: parseFloat(location.latitude),
-        longitude: parseFloat(location.longitude),
-      },
-    },
-  };
-
-  const result = await client.graphql({ query: createMutation, variables });
-  console.log(`✅ Created: ${location.ref}`);
-}
-```
-
-### What It Does
-1. **You parse** CSV data
-2. **You write** GraphQL mutation strings
-3. **You build** variables object manually
-4. **You handle** transformations (`trim()`, `parseFloat()`, `toUpperCase()`)
-
-### Pros
-✅ **Full control** - No abstraction overhead
-✅ **Simple to understand** - No mapper configuration
-✅ **Easy to debug** - See exactly what's happening
-✅ **No learning curve** - Just TypeScript + GraphQL
-
-### Cons
-❌ **Boilerplate** - Repetitive code for transformations
-❌ **No validation** - Errors only at runtime
-❌ **Manual transforms** - Write `trim()`, `parseFloat()`, etc. yourself
-❌ **Error handling** - You implement all error logic
-❌ **Maintenance** - Schema changes need code updates
-❌ **One-at-a-time** - 100 locations = 100 API calls
-
-### Performance
-- **Same as other approaches**: 100 locations = 100 API calls
-- **Time**: ~30-60 seconds
-
----
-
-## Decision Matrix
-
-| Factor | GraphQLMutationMapper | UniversalMapper + GraphQL | UniversalMapper + Event API | Fully Manual |
-|--------|----------------------|--------------------------|----------------------------|--------------|
-| **Field Mapping** | ✅ Built-in | ✅ Built-in | ✅ Built-in | ❌ Manual |
-| **SDK Resolvers** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
-| **GraphQL Generation** | ✅ Auto | ❌ You write | ❌ N/A | ❌ You write |
-| **Schema Validation** | ✅ Yes | ❌ No | ❌ No | ❌ No |
-| **Nested Structures** | ✅ Auto | ✅ Auto | ✅ Auto | ❌ Manual |
-| **Triggers Workflows** | ❌ No | ❌ No | ✅ Yes | ❌ No |
-| **Immediate Feedback** | ✅ Yes | ✅ Yes | ❌ Async | ✅ Yes |
-| **Learning Curve** | 🟡 Medium | 🟢 Easy | 🟢 Easy | 🟢 Easy |
-| **Best For** | Complex XML/JSON | CSV + control | Workflow triggers | Simple tasks |
-
----
-
-## API Comparison: GraphQL Mutations vs Event API vs Batch API
-
-### GraphQL Mutations (Approaches 1, 2, 4)
-```typescript
-await client.graphql({
-  query: mutation,
-  variables: { input: data },
-});
-```
-- **Immediate feedback**: Response includes created/updated entity
-- **All entities**: Locations, products, orders, customers
-- **One-at-a-time**: N records = N API calls
-- **Use when**: Need immediate response, <100 records
-
-### Event API (Approach 3)
-```typescript
-await client.sendEvent({
-  name: 'UPSERT_LOCATION',
-  attributes: data,
-}, 'async');
-```
-- **Triggers workflows**: Rubix workflows process events
-- **Asynchronous**: Don't wait for completion
-- **All entities**: Locations, products, orders (NOT inventory)
-- **One-at-a-time**: N records = N events
-- **Use when**: Need workflow execution, complex business logic
-
-### Batch API (Inventory ONLY)
-```typescript
-await client.sendBatch(jobId, {
-  entityType: 'INVENTORY',
-  action: 'UPSERT',
-  entities: data,
-});
-```
-- **Bulk optimized**: 1 API call for thousands of records
-- **Change detection**: BPP filters unchanged records
-- **INVENTORY ONLY**: No other entities supported
-- **Use when**: Bulk inventory updates (>100 records)
-
----
-
-## Key Insights
-
-### 1. UniversalMapper Works With ALL APIs!
-
-**Pattern:**
-```typescript
-// Step 1: Map data using UniversalMapper
-const mapper = new UniversalMapper(mappingConfig);
-const mapped = await mapper.map(csvRow);
-
-// Step 2: Use mapped data with ANY API
-// Option A: GraphQL Mutations
-await client.graphql({
-  query: mutation,
-  variables: { input: mapped.data },
-});
-
-// Option B: Event API
-await client.sendEvent({
-  name: 'UPSERT_ENTITY',
-  attributes: mapped.data,
-}, 'async');
-
-// Option C: Batch API (inventory only)
-await client.sendBatch(jobId, {
-  entityType: 'INVENTORY',
-  entities: [mapped.data],
-});
-```
-
-### 2. Four Approaches Comparison
-
-| Approach | Mapping | API | GraphQL Query | Control |
-|----------|---------|-----|---------------|---------|
-| **GraphQLMutationMapper** | Auto | GraphQL | Auto | Low |
-| **UniversalMapper + GraphQL** | Auto | GraphQL | Manual | Medium |
-| **UniversalMapper + Event API** | Auto | Event API | N/A | Medium |
-| **Fully Manual** | Manual | GraphQL | Manual | Maximum |
-
-### 3. When to Use Each Approach
-
-**GraphQLMutationMapper:**
-- Complex XML/JSON (SFCC orders, EDI)
-- Need schema validation
-- Want auto-generated queries
-
-**UniversalMapper + Manual GraphQL:**
-- CSV with transformations
-- Want control over GraphQL queries
-- Comfortable writing queries
-
-**UniversalMapper + Event API:**
-- Need to trigger Rubix workflows
-- Complex business logic
-- Asynchronous processing
-
-**Fully Manual:**
-- Simple CSV → GraphQL
-- Prototyping
-- Maximum flexibility
-
-### 4. Batch API is Special
-
-**Batch API ONLY supports inventory:**
-
-```typescript
-// ✅ CORRECT - Inventory via Batch API
-await client.sendBatch(jobId, {
-  entityType: 'INVENTORY',  // Only option!
-  action: 'UPSERT',
-  entities: inventoryData,
-});
-
-// ❌ WRONG - No Batch API for these
-entityType: 'LOCATION'   // Use GraphQL or Event API
-entityType: 'PRODUCT'    // Use GraphQL or Event API
-entityType: 'ORDER'      // Use GraphQL or Event API
-```
-
-**For inventory with UniversalMapper:**
-```typescript
-// Map inventory records
-const mapper = new UniversalMapper({
-  fields: {
-    skuRef: { source: 'sku', required: true },
-    locationRef: { source: 'location', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-  },
-});
-
-const mapped = await Promise.all(csvRows.map(row => mapper.map(row)));
-
-// Send to Batch API (1 API call for thousands of records!)
-const job = await client.createJob({ name: 'inventory', retailerId: '1' });
-await client.sendBatch(job.id, {
-  entityType: 'INVENTORY',
-  action: 'UPSERT',
-  entities: mapped.filter(r => r.success).map(r => r.data),
-});
-```
-
----
-
-## Performance Comparison
-
-| Scenario | Approach | API Calls | Time | Best For |
-|----------|----------|-----------|------|----------|
-| **100 locations** | GraphQLMutationMapper | 100 | ~30-60 sec | Schema validation |
-| **100 locations** | UniversalMapper + GraphQL | 100 | ~30-60 sec | Query control |
-| **100 locations** | UniversalMapper + Event API | 100 | ~30-60 sec | Workflow triggers |
-| **100 locations** | Fully Manual | 100 | ~30-60 sec | Simplicity |
-| **1,000 inventory** | Any approach + GraphQL | 1,000 | ~5-10 min ❌ | Don't use |
-| **1,000 inventory** | UniversalMapper + Batch API | 2 | ~30 sec ✅ | BEST choice |
-
-**Key Takeaway**: All four approaches have same performance for locations (no Batch API). Only inventory benefits from Batch API.
-
----
-
-## Summary
-
-**All 4 approaches work for locations:**
-
-1. **GraphQLMutationMapper** = Auto mapping + auto GraphQL query
-2. **UniversalMapper + Manual GraphQL** = Auto mapping + manual GraphQL query
-3. **UniversalMapper + Event API** = Auto mapping + workflow triggers
-4. **Fully Manual** = Everything manual
-
-**Choose based on:**
-
-1. **Need schema validation?** → GraphQLMutationMapper
-2. **Want query control?** → UniversalMapper + Manual GraphQL
-3. **Need workflows?** → UniversalMapper + Event API
-4. **Simple operation?** → Fully Manual
-
-**For inventory specifically:**
-- Use UniversalMapper + Batch API (20x faster for bulk!)
-
----
-
----
-
-## Testing All Approaches
-
-A comprehensive test script is available to validate all 4 approaches with the same input:
-
-**Location**: `fc-connect-sdk/tests/manual/mapper-comparison-test.ts`
-
-### Run in Dry Run Mode (No API Calls)
-
-```bash
-npx tsx tests/manual/mapper-comparison-test.ts
-```
-
-This will:
-- Parse the same CSV data in all 4 approaches
-- Show the mapped data structure for each approach
-- Demonstrate that all approaches produce consistent output
-- No actual API calls are made
-
-### Run with Live Credentials
-
-```bash
-FLUENT_BASE_URL=https://your-instance.api.fluentretail.com/graphql \
-FLUENT_CLIENT_ID=your-client-id \
-FLUENT_CLIENT_SECRET=your-secret \
-FLUENT_USERNAME=your-username \
-FLUENT_PASSWORD=your-password \
-FLUENT_RETAILER_ID=1 \
-npx tsx tests/manual/mapper-comparison-test.ts
-```
-
-This will actually execute all 4 approaches against your Fluent Commerce instance.
-
-**⚠️ Warning**: This will create 3 locations (DC-01, STORE-001, STORE-002) in your Fluent instance. Use a sandbox/test environment.
-
-### Output Example
-
-Each approach shows:
-- Parsed CSV data
-- Mapped/transformed data structure
-- GraphQL query (Approach 1 only)
-- Execution result (if using live credentials)
-
----
-
-## Related Docs
-
-- GraphQLMutationMapper Guide: `docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
-- UniversalMapper Guide: `docs/02-CORE-GUIDES/mapping/modules/`
-- Event API Guide: `docs/02-CORE-GUIDES/ingestion/modules/08-event-api.md`
-- Batch API Guide: `docs/02-CORE-GUIDES/ingestion/modules/06-batch-api.md`
-- Real Templates:
-  - UniversalMapper + GraphQL: `docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-location-graphql.md`
-  - UniversalMapper + Event API: `docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md`
+# Mapper Comparison Guide: Real-World Scenario
+
+> **📚 Quick Decision First?** See [Mapper Quick Decision Guide](../../00-START-HERE/mapper-quick-decision-guide.md) (2-minute read) for a simple decision table.
+
+**SCENARIO:** You have 100 locations in a CSV file. You need to create new locations or update existing ones in Fluent Commerce.
+
+**CSV Input:**
+```csv
+ref,name,status,type,address1,city,state,country,latitude,longitude
+DC-01,Distribution Center NYC,ACTIVE,DC,123 Main St,New York,NY,US,40.7128,-74.0060
+STORE-001,Manhattan Store,ACTIVE,STORE,456 Broadway,New York,NY,US,40.7580,-73.9855
+STORE-002,Brooklyn Store,ACTIVE,STORE,789 Atlantic Ave,Brooklyn,NY,US,40.6782,-73.9442
+... (97 more rows)
+```
+
+**Goal:** Create or update each location using Fluent Commerce API.
+
+---
+
+## Overview: 4 Working Approaches
+
+| Approach | Field Mapping | API | GraphQL Query | Use Case |
+|----------|--------------|-----|---------------|----------|
+| **1. GraphQLMutationMapper** | ✅ Auto | GraphQL Mutations | ✅ Auto-generated | Complex XML/JSON, want schema validation |
+| **2. UniversalMapper + Manual GraphQL** | ✅ Auto | GraphQL Mutations | ❌ You write | CSV with transformations, control over queries |
+| **3. UniversalMapper + Event API** | ✅ Auto | Event API | ❌ N/A | Trigger Rubix workflows, bulk operations |
+| **4. Fully Manual** | ❌ Manual | GraphQL Mutations | ❌ You write | Simple operations, maximum control |
+
+**Key Insight:** UniversalMapper is NOT just for Batch API - it works with GraphQL mutations AND Event API!
+
+---
+
+## Approach 1: GraphQLMutationMapper
+
+### When to Use
+✅ Complex XML/JSON structures (SFCC orders, EDI)
+✅ Want auto-generated GraphQL mutation queries
+✅ Need schema validation against GraphQL types
+✅ Prefer declarative configuration
+
+### Code
+
+```typescript
+import {
+  GraphQLMutationMapper,
+  CSVParserService,
+  createClient,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// 1. Parse CSV
+const parser = new CSVParserService();
+const locations = await parser.parse(csvContent, { columns: true });
+
+// 2. Configure mapping (CSV columns → GraphQL fields)
+const createConfig = {
+  mutation: 'createLocation',
+  operationName: 'CreateLocation',
+  sourceFormat: 'json' as const,
+  arguments: {
+    input: {
+      _type: 'CreateLocationInput!',
+      ref: { source: 'ref', required: true, resolver: 'sdk.trim' },
+      name: { source: 'name', required: true, resolver: 'sdk.trim' },
+      type: { source: 'type', required: true, resolver: 'sdk.uppercase' },
+      status: { source: 'status', defaultValue: 'ACTIVE' },
+      supportPhoneNumber: { value: '+1-800-555-0100' },
+      retailer: {
+        id: { value: '1', resolver: 'sdk.parseInt' },
+      },
+      primaryAddress: {
+        ref: { source: 'ref' },
+        street: { source: 'address1' },
+        city: { source: 'city' },
+        state: { source: 'state' },
+        country: { source: 'country' },
+        latitude: { source: 'latitude', resolver: 'sdk.parseFloat' },
+        longitude: { source: 'longitude', resolver: 'sdk.parseFloat' },
+      },
+      openingSchedule: {
+        allHours: { value: true },
+      },
+    },
+  },
+  returnFields: ['id', 'ref', 'type', 'status'],
+};
+
+// 3. Setup client and mapper
+const client = await createClient({ /* config */ });
+const createMapper = new GraphQLMutationMapper(createConfig, client);
+
+// 4. Process each location
+for (const location of locations) {
+  // Option A: Use map() - throws on error (use try/catch)
+  try {
+    const payload = await createMapper.map(location);
+    const result = await client.graphql(payload);
+    console.log(`✅ Created: ${location.ref}`);
+  } catch (error) {
+    console.error(`❌ Failed: ${location.ref}`, error);
+  }
+
+  // Option B: Use mapSafe() - returns result object (recommended for production)
+  const result = await createMapper.mapSafe(location);
+  if (!result.success) {
+    console.error(`❌ Failed: ${location.ref}`, result.errors);
+    continue;
+  }
+  await client.graphql({ query: result.query, variables: result.variables });
+  console.log(`✅ Created: ${location.ref}`);
+}
+```
+
+### What It Does
+1. **Auto-builds GraphQL mutation query** from mapping config
+2. **Validates** against GraphQL schema (catches type errors before sending)
+3. **Applies** SDK resolvers (`sdk.trim`, `sdk.parseFloat`, etc.)
+4. **Handles** nested structures automatically
+5. **Returns** `{ query, variables }` ready for execution
+
+### Pros
+✅ **Auto-generates mutation query** - Don't write GraphQL strings
+✅ **Schema validation** - Catches errors before sending to API
+✅ **Declarative config** - Easy to read and maintain
+✅ **Handles nested structures** - Automatic handling of `primaryAddress`
+✅ **Type safety** - GraphQL types validated
+
+### Cons
+❌ **Learning curve** - Need to understand mapping config syntax
+❌ **Verbose config** - More setup for simple mappings
+❌ **One-at-a-time** - 100 locations = 100 API calls
+
+### Performance
+- **100 locations** = 100 mutations = **100 API calls**
+- **Time**: ~30-60 seconds
+
+---
+
+## Approach 2: UniversalMapper + Manual GraphQL
+
+### When to Use
+✅ Want field mapping/transformation (SDK resolvers)
+✅ Prefer writing your own GraphQL query strings
+✅ Need flexibility in GraphQL query structure
+✅ CSV/JSON with transformations
+
+### Code
+
+```typescript
+import {
+  UniversalMapper,
+  CSVParserService,
+  createClient,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// 1. Parse CSV
+const parser = new CSVParserService();
+const locations = await parser.parse(csvContent, { columns: true });
+
+// 2. Configure field mapping (UniversalMapper)
+const locationMapping = {
+  fields: {
+    ref: { source: 'ref', required: true, resolver: 'sdk.trim' },
+    name: { source: 'name', required: true, resolver: 'sdk.trim' },
+    type: { source: 'type', required: true, resolver: 'sdk.uppercase' },
+    status: { source: 'status', defaultValue: 'ACTIVE' },
+    supportPhoneNumber: { value: '+1-800-555-0100' },
+
+    // Nested address fields - UniversalMapper handles this!
+    'primaryAddress.ref': { source: 'ref' },
+    'primaryAddress.street': { source: 'address1' },
+    'primaryAddress.city': { source: 'city' },
+    'primaryAddress.state': { source: 'state' },
+    'primaryAddress.country': { source: 'country' },
+    'primaryAddress.latitude': { source: 'latitude', resolver: 'sdk.parseFloat' },
+    'primaryAddress.longitude': { source: 'longitude', resolver: 'sdk.parseFloat' },
+  },
+};
+
+// 3. Map all CSV records
+const mapper = new UniversalMapper(locationMapping);
+const mappedLocations = [];
+
+for (const location of locations) {
+  const mapped = await mapper.map(location);
+  if (mapped.success) {
+    mappedLocations.push(mapped.data);
+  } else {
+    console.error(`Mapping failed: ${mapped.errors?.join(', ')}`);
+  }
+}
+
+// 4. Write GraphQL mutation manually
+const createMutation = `
+  mutation CreateLocation($input: CreateLocationInput!) {
+    createLocation(input: $input) {
+      id
+      ref
+      name
+      type
+    }
+  }
+`;
+
+// 5. Setup client
+const client = await createClient({ /* config */ });
+
+// 6. Execute mutations using mapped data as variables
+for (const location of mappedLocations) {
+  // Use mapped plain object as GraphQL variables
+  const result = await client.graphql({
+    query: createMutation,
+    variables: { input: location }, // ✅ Mapped data from UniversalMapper!
+  });
+
+  console.log(`✅ Created: ${location.ref}`);
+}
+```
+
+### What It Does
+1. **UniversalMapper** handles field mapping and transformations
+2. **Returns plain objects** with nested structures properly formatted
+3. **YOU write** the GraphQL mutation strings
+4. **Use mapped objects** as GraphQL `variables`
+
+### Pros
+✅ **Field mapping with SDK resolvers** - Get transformations (`sdk.parseInt`, `sdk.trim`, etc.)
+✅ **Handles nested structures** - `primaryAddress.street` → proper nested object
+✅ **Full control over GraphQL** - Write exact queries you need
+✅ **Easier to debug** - See exactly what's happening
+✅ **Less learning curve** - Just mapping config + standard GraphQL
+
+### Cons
+❌ **Manual GraphQL queries** - Must write mutation strings yourself
+❌ **No schema validation** - Errors only at runtime
+❌ **More boilerplate** - Mapping config + GraphQL query strings
+❌ **One-at-a-time** - 100 locations = 100 API calls
+
+### Performance
+- **Same as GraphQLMutationMapper**: 100 locations = 100 API calls
+- **Time**: ~30-60 seconds
+
+---
+
+## Approach 3: UniversalMapper + Event API
+
+### When to Use
+✅ Want to trigger Rubix workflows
+✅ Need asynchronous processing
+✅ Bulk operations that trigger business logic
+✅ Products, locations, or any entity with Rubix workflow
+
+### Code
+
+```typescript
+import {
+  UniversalMapper,
+  CSVParserService,
+  createClient,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// 1. Parse CSV
+const parser = new CSVParserService();
+const locations = await parser.parse(csvContent, { columns: true });
+
+// 2. Configure field mapping (same UniversalMapper config)
+const locationMapping = {
+  fields: {
+    ref: { source: 'ref', required: true, resolver: 'sdk.trim' },
+    name: { source: 'name', required: true, resolver: 'sdk.trim' },
+    type: { source: 'type', required: true, resolver: 'sdk.uppercase' },
+    status: { source: 'status', defaultValue: 'ACTIVE' },
+
+    // Nested address fields
+    'primaryAddress.ref': { source: 'ref' },
+    'primaryAddress.street': { source: 'address1' },
+    'primaryAddress.city': { source: 'city' },
+    'primaryAddress.state': { source: 'state' },
+    'primaryAddress.country': { source: 'country' },
+    'primaryAddress.latitude': { source: 'latitude', resolver: 'sdk.parseFloat' },
+    'primaryAddress.longitude': { source: 'longitude', resolver: 'sdk.parseFloat' },
+  },
+};
+
+// 3. Map all CSV records
+const mapper = new UniversalMapper(locationMapping);
+const mappedLocations = [];
+
+for (const location of locations) {
+  const mapped = await mapper.map(location);
+  if (mapped.success) {
+    mappedLocations.push(mapped.data);
+  }
+}
+
+// 4. Setup client
+const client = await createClient({ /* config */ });
+
+// 5. Send each record as an event (triggers Rubix workflow)
+const eventName = 'UPSERT_LOCATION';
+const entityRef = 'LOCATION_CATALOGUE:MASTER:1'; // Your catalogue reference
+
+for (const location of mappedLocations) {
+  await client.sendEvent(
+    {
+      name: eventName,
+      entityRef: entityRef,
+      entityType: 'LOCATION_CATALOGUE',
+      entitySubtype: 'MASTER',
+      rootEntityRef: entityRef,
+      rootEntityType: 'LOCATION_CATALOGUE',
+      retailerId: '1',
+      attributes: location, // ✅ Mapped data from UniversalMapper!
+    },
+    'async' // or 'sync' for synchronous processing
+  );
+
+  console.log(`✅ Event sent: ${location.ref}`);
+}
+```
+
+### What It Does
+1. **UniversalMapper** handles field mapping and transformations
+2. **Returns plain objects** ready for Event API
+3. **Send to Event API** which triggers Rubix workflows
+4. **Workflows** handle the actual GraphQL mutations
+
+### Pros
+✅ **Field mapping with SDK resolvers** - Same as approach 2
+✅ **Triggers Rubix workflows** - Business logic execution
+✅ **Asynchronous processing** - Don't wait for completion
+✅ **Error recovery** - Workflows can retry
+✅ **Business logic** - Workflows can add custom validation, enrichment
+
+### Cons
+❌ **Requires Rubix workflows** - Need workflow setup
+❌ **No immediate feedback** - Async processing
+❌ **More complexity** - Workflow management
+❌ **One-at-a-time** - 100 locations = 100 events
+
+### Performance
+- **100 locations** = 100 event API calls
+- **Time**: ~30-60 seconds (event submission), plus async workflow processing
+
+---
+
+## Approach 4: Fully Manual (No Mapper)
+
+### When to Use
+✅ Simple, one-off operations
+✅ Maximum control over everything
+✅ Prototyping/testing
+✅ Don't need field transformations
+
+### Code
+
+```typescript
+import { CSVParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// 1. Parse CSV manually
+const parser = new CSVParserService();
+const locations = await parser.parse(csvContent, { columns: true });
+
+// 2. Write GraphQL mutation manually
+const createMutation = `
+  mutation CreateLocation($input: CreateLocationInput!) {
+    createLocation(input: $input) {
+      id
+      ref
+      name
+      type
+    }
+  }
+`;
+
+// 3. Setup client
+const client = await createClient({ /* config */ });
+
+// 4. Process each location manually (build variables yourself)
+for (const location of locations) {
+  // Manually build variables object
+  const variables = {
+    input: {
+      ref: location.ref?.trim(),
+      name: location.name?.trim(),
+      type: location.type?.toUpperCase(),
+      status: location.status || 'ACTIVE',
+      supportPhoneNumber: '+1-800-555-0100',
+      primaryAddress: {
+        ref: location.ref,
+        street: location.address1,
+        city: location.city,
+        state: location.state,
+        country: location.country,
+        latitude: parseFloat(location.latitude),
+        longitude: parseFloat(location.longitude),
+      },
+    },
+  };
+
+  const result = await client.graphql({ query: createMutation, variables });
+  console.log(`✅ Created: ${location.ref}`);
+}
+```
+
+### What It Does
+1. **You parse** CSV data
+2. **You write** GraphQL mutation strings
+3. **You build** variables object manually
+4. **You handle** transformations (`trim()`, `parseFloat()`, `toUpperCase()`)
+
+### Pros
+✅ **Full control** - No abstraction overhead
+✅ **Simple to understand** - No mapper configuration
+✅ **Easy to debug** - See exactly what's happening
+✅ **No learning curve** - Just TypeScript + GraphQL
+
+### Cons
+❌ **Boilerplate** - Repetitive code for transformations
+❌ **No validation** - Errors only at runtime
+❌ **Manual transforms** - Write `trim()`, `parseFloat()`, etc. yourself
+❌ **Error handling** - You implement all error logic
+❌ **Maintenance** - Schema changes need code updates
+❌ **One-at-a-time** - 100 locations = 100 API calls
+
+### Performance
+- **Same as other approaches**: 100 locations = 100 API calls
+- **Time**: ~30-60 seconds
+
+---
+
+## Decision Matrix
+
+| Factor | GraphQLMutationMapper | UniversalMapper + GraphQL | UniversalMapper + Event API | Fully Manual |
+|--------|----------------------|--------------------------|----------------------------|--------------|
+| **Field Mapping** | ✅ Built-in | ✅ Built-in | ✅ Built-in | ❌ Manual |
+| **SDK Resolvers** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
+| **GraphQL Generation** | ✅ Auto | ❌ You write | ❌ N/A | ❌ You write |
+| **Schema Validation** | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| **Nested Structures** | ✅ Auto | ✅ Auto | ✅ Auto | ❌ Manual |
+| **Triggers Workflows** | ❌ No | ❌ No | ✅ Yes | ❌ No |
+| **Immediate Feedback** | ✅ Yes | ✅ Yes | ❌ Async | ✅ Yes |
+| **Learning Curve** | 🟡 Medium | 🟢 Easy | 🟢 Easy | 🟢 Easy |
+| **Best For** | Complex XML/JSON | CSV + control | Workflow triggers | Simple tasks |
+
+---
+
+## API Comparison: GraphQL Mutations vs Event API vs Batch API
+
+### GraphQL Mutations (Approaches 1, 2, 4)
+```typescript
+await client.graphql({
+  query: mutation,
+  variables: { input: data },
+});
+```
+- **Immediate feedback**: Response includes created/updated entity
+- **All entities**: Locations, products, orders, customers
+- **One-at-a-time**: N records = N API calls
+- **Use when**: Need immediate response, <100 records
+
+### Event API (Approach 3)
+```typescript
+await client.sendEvent({
+  name: 'UPSERT_LOCATION',
+  attributes: data,
+}, 'async');
+```
+- **Triggers workflows**: Rubix workflows process events
+- **Asynchronous**: Don't wait for completion
+- **All entities**: Locations, products, orders (NOT inventory)
+- **One-at-a-time**: N records = N events
+- **Use when**: Need workflow execution, complex business logic
+
+### Batch API (Inventory ONLY)
+```typescript
+await client.sendBatch(jobId, {
+  entityType: 'INVENTORY',
+  action: 'UPSERT',
+  entities: data,
+});
+```
+- **Bulk optimized**: 1 API call for thousands of records
+- **Change detection**: BPP filters unchanged records
+- **INVENTORY ONLY**: No other entities supported
+- **Use when**: Bulk inventory updates (>100 records)
+
+---
+
+## Key Insights
+
+### 1. UniversalMapper Works With ALL APIs!
+
+**Pattern:**
+```typescript
+// Step 1: Map data using UniversalMapper
+const mapper = new UniversalMapper(mappingConfig);
+const mapped = await mapper.map(csvRow);
+
+// Step 2: Use mapped data with ANY API
+// Option A: GraphQL Mutations
+await client.graphql({
+  query: mutation,
+  variables: { input: mapped.data },
+});
+
+// Option B: Event API
+await client.sendEvent({
+  name: 'UPSERT_ENTITY',
+  attributes: mapped.data,
+}, 'async');
+
+// Option C: Batch API (inventory only)
+await client.sendBatch(jobId, {
+  entityType: 'INVENTORY',
+  entities: [mapped.data],
+});
+```
+
+### 2. Four Approaches Comparison
+
+| Approach | Mapping | API | GraphQL Query | Control |
+|----------|---------|-----|---------------|---------|
+| **GraphQLMutationMapper** | Auto | GraphQL | Auto | Low |
+| **UniversalMapper + GraphQL** | Auto | GraphQL | Manual | Medium |
+| **UniversalMapper + Event API** | Auto | Event API | N/A | Medium |
+| **Fully Manual** | Manual | GraphQL | Manual | Maximum |
+
+### 3. When to Use Each Approach
+
+**GraphQLMutationMapper:**
+- Complex XML/JSON (SFCC orders, EDI)
+- Need schema validation
+- Want auto-generated queries
+
+**UniversalMapper + Manual GraphQL:**
+- CSV with transformations
+- Want control over GraphQL queries
+- Comfortable writing queries
+
+**UniversalMapper + Event API:**
+- Need to trigger Rubix workflows
+- Complex business logic
+- Asynchronous processing
+
+**Fully Manual:**
+- Simple CSV → GraphQL
+- Prototyping
+- Maximum flexibility
+
+### 4. Batch API is Special
+
+**Batch API ONLY supports inventory:**
+
+```typescript
+// ✅ CORRECT - Inventory via Batch API
+await client.sendBatch(jobId, {
+  entityType: 'INVENTORY',  // Only option!
+  action: 'UPSERT',
+  entities: inventoryData,
+});
+
+// ❌ WRONG - No Batch API for these
+entityType: 'LOCATION'   // Use GraphQL or Event API
+entityType: 'PRODUCT'    // Use GraphQL or Event API
+entityType: 'ORDER'      // Use GraphQL or Event API
+```
+
+**For inventory with UniversalMapper:**
+```typescript
+// Map inventory records
+const mapper = new UniversalMapper({
+  fields: {
+    skuRef: { source: 'sku', required: true },
+    locationRef: { source: 'location', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+  },
+});
+
+const mapped = await Promise.all(csvRows.map(row => mapper.map(row)));
+
+// Send to Batch API (1 API call for thousands of records!)
+const job = await client.createJob({ name: 'inventory', retailerId: '1' });
+await client.sendBatch(job.id, {
+  entityType: 'INVENTORY',
+  action: 'UPSERT',
+  entities: mapped.filter(r => r.success).map(r => r.data),
+});
+```
+
+---
+
+## Performance Comparison
+
+| Scenario | Approach | API Calls | Time | Best For |
+|----------|----------|-----------|------|----------|
+| **100 locations** | GraphQLMutationMapper | 100 | ~30-60 sec | Schema validation |
+| **100 locations** | UniversalMapper + GraphQL | 100 | ~30-60 sec | Query control |
+| **100 locations** | UniversalMapper + Event API | 100 | ~30-60 sec | Workflow triggers |
+| **100 locations** | Fully Manual | 100 | ~30-60 sec | Simplicity |
+| **1,000 inventory** | Any approach + GraphQL | 1,000 | ~5-10 min ❌ | Don't use |
+| **1,000 inventory** | UniversalMapper + Batch API | 2 | ~30 sec ✅ | BEST choice |
+
+**Key Takeaway**: All four approaches have same performance for locations (no Batch API). Only inventory benefits from Batch API.
+
+---
+
+## Summary
+
+**All 4 approaches work for locations:**
+
+1. **GraphQLMutationMapper** = Auto mapping + auto GraphQL query
+2. **UniversalMapper + Manual GraphQL** = Auto mapping + manual GraphQL query
+3. **UniversalMapper + Event API** = Auto mapping + workflow triggers
+4. **Fully Manual** = Everything manual
+
+**Choose based on:**
+
+1. **Need schema validation?** → GraphQLMutationMapper
+2. **Want query control?** → UniversalMapper + Manual GraphQL
+3. **Need workflows?** → UniversalMapper + Event API
+4. **Simple operation?** → Fully Manual
+
+**For inventory specifically:**
+- Use UniversalMapper + Batch API (20x faster for bulk!)
+
+---
+
+---
+
+## Testing All Approaches
+
+A comprehensive test script is available to validate all 4 approaches with the same input:
+
+**Location**: `fc-connect-sdk/tests/manual/mapper-comparison-test.ts`
+
+### Run in Dry Run Mode (No API Calls)
+
+```bash
+npx tsx tests/manual/mapper-comparison-test.ts
+```
+
+This will:
+- Parse the same CSV data in all 4 approaches
+- Show the mapped data structure for each approach
+- Demonstrate that all approaches produce consistent output
+- No actual API calls are made
+
+### Run with Live Credentials
+
+```bash
+FLUENT_BASE_URL=https://your-instance.api.fluentretail.com/graphql \
+FLUENT_CLIENT_ID=your-client-id \
+FLUENT_CLIENT_SECRET=your-secret \
+FLUENT_USERNAME=your-username \
+FLUENT_PASSWORD=your-password \
+FLUENT_RETAILER_ID=1 \
+npx tsx tests/manual/mapper-comparison-test.ts
+```
+
+This will actually execute all 4 approaches against your Fluent Commerce instance.
+
+**⚠️ Warning**: This will create 3 locations (DC-01, STORE-001, STORE-002) in your Fluent instance. Use a sandbox/test environment.
+
+### Output Example
+
+Each approach shows:
+- Parsed CSV data
+- Mapped/transformed data structure
+- GraphQL query (Approach 1 only)
+- Execution result (if using live credentials)
+
+---
+
+## Related Docs
+
+- GraphQLMutationMapper Guide: `docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
+- UniversalMapper Guide: `docs/02-CORE-GUIDES/mapping/modules/`
+- Event API Guide: `docs/02-CORE-GUIDES/ingestion/modules/08-event-api.md`
+- Batch API Guide: `docs/02-CORE-GUIDES/ingestion/modules/06-batch-api.md`
+- Real Templates:
+  - UniversalMapper + GraphQL: `docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-location-graphql.md`
+  - UniversalMapper + Event API: `docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md`