@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-06-integration-patterns.md

@@ -1,702 +1,702 @@
-# Module 6: Integration Patterns
-
-**Level:** Advanced
-**Estimated Time:** 25 minutes
-
-## Overview
-
-This module shows how to combine parsers with other SDK services to build complete integration workflows. You'll learn patterns for ingestion, extraction, transformation, and multi-format ETL pipelines.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Combine parsers with UniversalMapper for transformations
-- ✅ Integrate with Batch API for inventory ingestion
-- ✅ Build extraction pipelines with S3 and Parquet
-- ✅ Create multi-format ETL workflows
-- ✅ Implement Versori webhook handlers
-- ✅ Build complete end-to-end integrations
-
-## Common Integration Patterns
-
-### Pattern 1: CSV Ingestion Pipeline
-
-**Use Case:** Daily inventory feed from warehouse (CSV → Fluent)
-
-```typescript
-import {
-  createClient,
-  CSVParserService,
-  UniversalMapper,
-  S3DataSource,
-  StateService,
-  VersoriKVAdapter
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function csvIngestionPipeline(s3Key: string, kvAdapter: VersoriKVAdapter) {
-  // 1. Initialize services
-  const client = await createClient({ config });
-  const csvParser = new CSVParserService();
-  const s3DataSource = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 's3-csv-pipeline',
-      name: 'S3 CSV Pipeline',
-      s3Config: {
-        ...s3Config,
-        bucket: 'inventory-feeds',
-      },
-    },
-    console
-  );
-  const stateService = new StateService(kvAdapter);
-
-  // 2. Check if already processed
-  const fileKey = `processed:${s3Key}`;
-  const alreadyProcessed = await stateService.isFileProcessed(fileKey);
-
-  if (alreadyProcessed) {
-    console.log(`File ${s3Key} already processed, skipping`);
-    return;
-  }
-
-  // 3. Download CSV from S3
-  const csvContent = await s3DataSource.downloadFile(s3Key);
-
-  // 4. Parse CSV
-  const records = await csvParser.parse(csvContent);
-  console.log(`Parsed ${records.length} records`);
-
-  // 5. Transform with UniversalMapper
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: { source: 'sku', required: true },
-      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-      locationRef: { source: 'warehouse' },
-      type: { value: 'LAST' }
-    }
-  });
-
-  const result = await mapper.map(records);
-
-  if (!result.success) {
-    throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
-  }
-
-  // 6. Send to Fluent Batch API (INVENTORY only)
-  const job = await client.createJob({
-    name: `csv-ingestion-${Date.now()}`,
-    type: 'INVENTORY',
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  });
-
-  await client.sendBatch(job.id, {
-    entities: result.data
-  });
-
-  // 7. Mark as processed
-  await stateService.markFileProcessed(fileKey, {
-    recordCount: records.length,
-    processedAt: new Date().toISOString()
-  });
-
-  console.log(`✅ Processed ${records.length} inventory records`);
-}
-```
-
-### Pattern 2: JSON Webhook Processing
-
-**Use Case:** Process incoming webhooks from e-commerce platform
-
-```typescript
-import {
-  createClient,
-  JSONParserService,
-  UniversalMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processOrderWebhook(webhookPayload: string) {
-  // 1. Parse JSON webhook
-  const jsonParser = new JSONParserService();
-  const order = await jsonParser.parse(webhookPayload, {
-    parseDates: true,
-    validateSchema: true,
-    schema: orderSchema
-  });
-
-  // 2. Transform to Fluent format
-  const fluentOrder = {
-    ref: `WEB-${order.id}`,
-    type: 'HD',
-    retailerId: '1',
-    customer: {
-      email: order.customer.email,
-      firstName: order.customer.first_name,
-      lastName: order.customer.last_name
-    },
-    items: order.items.map(item => ({
-      ref: item.sku,
-      quantity: item.quantity,
-      price: parseFloat(item.price)
-    }))
-  };
-
-  // 3. Send to Fluent (using GraphQL mutation, NOT Batch API)
-  const client = await createClient({ config });
-  const result = await client.graphql({
-    query: `
-      mutation CreateOrder($input: CreateOrderInput!) {
-        createOrder(input: $input) {
-          id
-          ref
-          status
-        }
-      }
-    `,
-    variables: {
-      input: fluentOrder
-    }
-  });
-
-  console.log(`✅ Order created: ${result.data.createOrder.ref}`);
-  return result.data.createOrder;
-}
-```
-
-### Pattern 3: XML to GraphQL Mutation (SFCC Orders)
-
-**Use Case:** SFCC order XML → Fluent GraphQL mutation
-
-```typescript
-import {
-  createClient,
-  XMLParserService,
-  GraphQLMutationMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processSFCCOrder(xmlContent: string) {
-  // 1. Parse XML
-  const xmlParser = new XMLParserService();
-  const parsed = await xmlParser.parse(xmlContent);
-
-  // 2. Transform with GraphQLMutationMapper
-  const mapper = new GraphQLMutationMapper({
-    mutation: 'createOrder',
-    rootPath: 'Order',
-    fields: {
-      ref: { xmlPath: '@customerOrderId', required: true },
-      type: { value: 'HD' },
-      retailerId: { value: '1' },
-      customer: {
-        email: { xmlPath: 'Customer.EmailAddress' },
-        firstName: { xmlPath: 'Customer.Name.FirstName' },
-        lastName: { xmlPath: 'Customer.Name.LastName' }
-      },
-      items: {
-        arrayPath: 'OrderItems.OrderItem',
-        fields: {
-          ref: { xmlPath: 'ItemId' },
-          quantity: { xmlPath: 'Quantity', resolver: 'sdk.parseInt' },
-          price: { xmlPath: 'Price', resolver: 'sdk.parseFloat' }
-        }
-      }
-    }
-  });
-
-  const mutation = await mapper.map(parsed);
-
-  // 3. Send to Fluent
-  const client = await createClient({ config });
-  const result = await client.graphql({
-    query: mutation.query,
-    variables: mutation.variables
-  });
-
-  console.log(`✅ SFCC order created: ${result.data.createOrder.ref}`);
-  return result.data.createOrder;
-}
-```
-
-### Pattern 4: Parquet Extraction Pipeline
-
-**Use Case:** Extract Fluent data to analytics warehouse
-
-```typescript
-import {
-  createClient,
-  ParquetParserService,
-  S3DataSource,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function extractToParquet(entityType: string) {
-  const logger = createConsoleLogger();
-  const client = await createClient({ config });
-  const s3DataSource = new S3DataSource({
-    type: 'S3_PARQUET',
-    connectionId: 's3-parquet-extract',
-    name: 'S3 Parquet Extract',
-    s3Config: s3Config
-  }, logger);
-
-  // 1. Fetch data from Fluent with auto-pagination
-  const result = await client.graphql({
-    query: `
-      query GetVirtualPositions($first: Int!, $after: String) {
-        virtualPositions(first: $first, after: $after) {
-          edges {
-            node {
-              id
-              productRef
-              quantity
-              groupRef
-              createdOn
-              updatedOn
-            }
-            cursor
-          }
-          pageInfo {
-            hasNextPage
-          }
-        }
-      }
-    `,
-    variables: { first: 1000 },
-    pagination: { maxRecords: 1000000 }
-  });
-
-  // 2. Transform to flat structure
-  const records = result.data.virtualPositions.edges.map(edge => ({
-    id: edge.node.id,
-    productRef: edge.node.productRef,
-    quantity: edge.node.quantity,
-    groupRef: edge.node.groupRef,
-    createdOn: edge.node.createdOn,
-    updatedOn: edge.node.updatedOn
-  }));
-
-  console.log(`Extracted ${records.length} virtual positions`);
-
-  // 3. Convert to Parquet
-  const parquetBuffer = await convertToParquet(records);
-
-  // 4. Upload to S3 with date partition
-  const date = new Date().toISOString().split('T')[0];
-  await s3DataSource.uploadFile(
-    `virtual-positions/date=${date}/data.parquet`,
-    parquetBuffer,
-    { contentType: 'application/octet-stream' }
-  );
-
-  console.log(`✅ Extracted ${records.length} records to S3`);
-}
-```
-
-### Pattern 5: Multi-Format ETL Pipeline
-
-**Use Case:** Accept multiple formats, detect and route appropriately
-
-```typescript
-import {
-  CSVParserService,
-  JSONParserService,
-  XMLParserService,
-  ParquetParserService,
-  UniversalMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function multiFormatETL(fileContent: string | Buffer, fileType: string) {
-  let records: any[];
-
-  // 1. Parse based on format
-  switch (fileType) {
-    case 'csv':
-      const csvParser = new CSVParserService();
-      records = await csvParser.parse(fileContent as string);
-      break;
-
-    case 'json':
-      const jsonParser = new JSONParserService();
-      records = await jsonParser.parse(fileContent as string);
-      break;
-
-    case 'xml':
-      const xmlParser = new XMLParserService();
-      const parsed = await xmlParser.parse(fileContent as string);
-      records = extractRecordsFromXML(parsed);
-      break;
-
-    case 'parquet':
-      const logger = createConsoleLogger();
-      const parquetParser = new ParquetParserService(logger);
-      records = await parquetParser.parse(fileContent as Buffer);
-      break;
-
-    default:
-      throw new Error(`Unsupported file type: ${fileType}`);
-  }
-
-  console.log(`Parsed ${records.length} records from ${fileType}`);
-
-  // 2. Transform with UniversalMapper (works for all formats!)
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: { source: 'sku', required: true },
-      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-      locationRef: { source: 'location' }
-    }
-  });
-
-  const result = await mapper.map(records);
-
-  if (!result.success) {
-    throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
-  }
-
-  // 3. Send to Fluent
-  const client = await createClient({ config });
-  const job = await client.createJob({
-    name: 'inventory-ingestion',
-    retailerId: config.config.retailerId
-  });
-
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    source: 'csv-import',
-    event: 'inventory.update',
-    entities: result.data
-  });
-
-  console.log(`✅ Processed ${records.length} records`);
-}
-
-function extractRecordsFromXML(parsed: any): any[] {
-  // Extract array from XML structure
-  return parsed.products?.product || [];
-}
-```
-
-## Versori Platform Patterns
-
-### Pattern 6: Versori Scheduled Workflow
-
-**Use Case:** Daily S3 CSV ingestion on Versori platform
-
-```typescript
-import { fn, schedule } from '@versori/run';
-import {
-  createClient,
-  CSVParserService,
-  UniversalMapper,
-  S3DataSource
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const dailyInventorySync = schedule('daily-inventory')
-  .cron('0 2 * * *') // 2 AM daily
-  .do(async (ctx) => {
-    // Auto-detects Versori context
-    const client = await createClient(ctx);
-    const csvParser = new CSVParserService();
-
-    // Use S3DataSource for Versori S3 connection
-    const s3Source = new S3DataSource(ctx.connections.s3);
-
-    // Download CSV
-    const csvContent = await s3Source.downloadFile({
-      bucket: 'inventory-feeds',
-      key: 'daily/inventory.csv'
-    });
-
-    // Parse and transform
-    const records = await csvParser.parse(csvContent);
-    const mapper = new UniversalMapper(mappingConfig);
-    const result = await mapper.map(records);
-
-    // Send to Fluent
-    const job = await client.createJob({
-    name: 'inventory-ingestion',
-    retailerId: config.config.retailerId
-  });
-
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    source: 'csv-import',
-    event: 'inventory.update',
-    entities: result.data
-  });
-
-    ctx.log.info(`✅ Processed ${records.length} records`);
-  });
-```
-
-### Pattern 7: Versori Webhook Handler
-
-**Use Case:** Process incoming JSON webhooks on Versori
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import {
-  createClient,
-  JSONParserService,
-  UniversalMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const processWebhook = webhook('order-webhook')
-  .then(fn('parse', async (ctx) => {
-    const jsonParser = new JSONParserService();
-
-    // Parse webhook payload
-    const order = await jsonParser.parse(ctx.trigger.body, {
-      parseDates: true
-    });
-
-    return { order };
-  }))
-  .then(fn('transform', async (ctx) => {
-    const mapper = new UniversalMapper(orderMappingConfig);
-    const result = await mapper.map(ctx.data.order);
-
-    if (!result.success) {
-      throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
-    }
-
-    return { fluentOrder: result.data };
-  }))
-  .then(fn('send-to-fluent', async (ctx) => {
-    const client = await createClient(ctx);
-
-    const result = await client.graphql({
-      query: createOrderMutation,
-      variables: { input: ctx.data.fluentOrder }
-    });
-
-    return result.data.createOrder;
-  }))
-  .catch((ctx) => {
-    ctx.log.error('Webhook processing failed:', ctx.error);
-    throw ctx.error;
-  });
-```
-
-## Complete Real-World Examples
-
-### Example 1: S3 CSV Inventory Ingestion (Node.js)
-
-```typescript
-import {
-  createClient,
-  CSVParserService,
-  UniversalMapper,
-  S3DataSource,
-  StateService,
-  VersoriKVAdapter
-} from '@fluentcommerce/fc-connect-sdk';
-import * as fs from 'fs/promises';
-
-async function s3CsvIngestion() {
-  // Initialize services
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  }
-});
-
-  const s3DataSource = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 's3-parsers-integration',
-      name: 'S3 Parsers Integration',
-      s3Config: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-        region: process.env.AWS_REGION!,
-        bucket: 'inventory-feeds',
-      },
-    },
-    console
-  );
-
-  // List files in S3
-  const files = await s3DataSource.listFiles({
-    prefix: 'daily/'
-  });
-
-  for (const file of files) {
-    console.log(`Processing ${file.path}`);
-
-    // Download CSV
-    const csvContent = await s3DataSource.downloadFile(file.path);
-
-    // Parse CSV
-    const csvParser = new CSVParserService();
-    const records = await csvParser.parse(csvContent);
-
-    // Transform
-    const mapper = new UniversalMapper({
-      fields: {
-        ref: { source: 'sku', required: true },
-        qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-        locationRef: { source: 'warehouse' },
-        type: { value: 'LAST' }
-      }
-    });
-
-    const result = await mapper.map(records);
-
-    // Send to Fluent
-    const job = await client.createJob({
-    name: 'inventory-ingestion',
-    retailerId: config.config.retailerId
-  });
-
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    source: 'csv-import',
-    event: 'inventory.update',
-    entities: result.data
-  });
-
-    console.log(`✅ Processed ${records.length} records from ${file.path}`);
-  }
-}
-```
-
-### Example 2: Extraction to Parquet (Node.js)
-
-```typescript
-import {
-  createClient,
-  ParquetParserService,
-  S3DataSource,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function extractToParquet() {
-  const logger = createConsoleLogger();
-  const client = await createClient({ config });
-  const s3DataSource = new S3DataSource({
-    type: 'S3_PARQUET',
-    connectionId: 's3-parquet-extract',
-    name: 'S3 Parquet Extract',
-    s3Config: s3Config
-  }, logger);
-
-  // Fetch data with auto-pagination
-  const result = await client.graphql({
-    query: virtualPositionsQuery,
-    variables: { first: 1000 },
-    pagination: { maxRecords: 1000000 }
-  });
-
-  const records = result.data.virtualPositions.edges.map(e => e.node);
-
-  // Convert to Parquet
-  const parquetBuffer = await convertToParquet(records);
-
-  // Upload to S3
-  const date = new Date().toISOString().split('T')[0];
-  await s3DataSource.uploadFile(
-    `virtual-positions/date=${date}/data.parquet`,
-    parquetBuffer
-  );
-
-  console.log(`✅ Extracted ${records.length} records`);
-}
-```
-
-## Error Handling Patterns
-
-### Comprehensive Error Handling
-
-```typescript
-async function robustIntegration(fileContent: string) {
-  try {
-    // 1. Parse
-    const csvParser = new CSVParserService();
-    const records = await csvParser.parse(fileContent);
-
-    // 2. Validate
-    if (records.length === 0) {
-      throw new Error('No records found in file');
-    }
-
-    // 3. Transform
-    const mapper = new UniversalMapper(mappingConfig);
-    const result = await mapper.map(records);
-
-    if (!result.success) {
-      // Log mapping errors but continue with successful records
-      console.error('Mapping errors:', result.errors);
-
-      if (result.data.length === 0) {
-        throw new Error('All records failed mapping');
-      }
-
-      console.warn(`Proceeding with ${result.data.length}/${records.length} successful records`);
-    }
-
-    // 4. Send to Fluent
-    const client = await createClient({ config });
-    const job = await client.createJob({
-    name: 'inventory-ingestion',
-    retailerId: config.config.retailerId
-  });
-
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    source: 'csv-import',
-    event: 'inventory.update',
-    entities: result.data
-  });
-
-    console.log(`✅ Processed ${result.data.length} records`);
-
-  } catch (error) {
-    console.error('Integration failed:', error);
-
-    // Send alert/notification
-    await sendAlert(`Integration failed: ${error.message}`);
-
-    throw error;
-  }
-}
-```
-
-## Key Takeaways
-
-- 🎯 Combine parsers with UniversalMapper for standard transformation pattern
-- 🎯 Use GraphQLMutationMapper for complex XML→GraphQL transformations
-- 🎯 Integrate with S3DataSource for file operations
-- 🎯 Use StateService to prevent duplicate processing
-- 🎯 Auto-pagination works seamlessly for large extractions
-- 🎯 Versori patterns auto-detect platform context
-- 🎯 Always handle errors and log processing metrics
-
-## Practice Exercise
-
-**Challenge:** Build complete ingestion pipeline:
-
-**Requirements:**
-1. Download CSV from S3: `s3://feeds/inventory-2025-01-15.csv`
-2. Parse CSV with validation
-3. Transform with UniversalMapper (sku→ref, quantity→qty)
-4. Send to Fluent Batch API
-5. Track state to prevent duplicate processing
-6. Handle errors gracefully
-
-**Solution:** See [Parser Examples](../examples/)
-
-## Next Steps
-
-Continue to [Module 7: Troubleshooting →](./02-core-guides-parsers-07-troubleshooting.md) for error handling and optimization.
-
----
-
-**Module 6 Complete!** ✅
+# Module 6: Integration Patterns
+
+**Level:** Advanced
+**Estimated Time:** 25 minutes
+
+## Overview
+
+This module shows how to combine parsers with other SDK services to build complete integration workflows. You'll learn patterns for ingestion, extraction, transformation, and multi-format ETL pipelines.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Combine parsers with UniversalMapper for transformations
+- ✅ Integrate with Batch API for inventory ingestion
+- ✅ Build extraction pipelines with S3 and Parquet
+- ✅ Create multi-format ETL workflows
+- ✅ Implement Versori webhook handlers
+- ✅ Build complete end-to-end integrations
+
+## Common Integration Patterns
+
+### Pattern 1: CSV Ingestion Pipeline
+
+**Use Case:** Daily inventory feed from warehouse (CSV → Fluent)
+
+```typescript
+import {
+  createClient,
+  CSVParserService,
+  UniversalMapper,
+  S3DataSource,
+  StateService,
+  VersoriKVAdapter
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function csvIngestionPipeline(s3Key: string, kvAdapter: VersoriKVAdapter) {
+  // 1. Initialize services
+  const client = await createClient({ config });
+  const csvParser = new CSVParserService();
+  const s3DataSource = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 's3-csv-pipeline',
+      name: 'S3 CSV Pipeline',
+      s3Config: {
+        ...s3Config,
+        bucket: 'inventory-feeds',
+      },
+    },
+    console
+  );
+  const stateService = new StateService(kvAdapter);
+
+  // 2. Check if already processed
+  const fileKey = `processed:${s3Key}`;
+  const alreadyProcessed = await stateService.isFileProcessed(fileKey);
+
+  if (alreadyProcessed) {
+    console.log(`File ${s3Key} already processed, skipping`);
+    return;
+  }
+
+  // 3. Download CSV from S3
+  const csvContent = await s3DataSource.downloadFile(s3Key);
+
+  // 4. Parse CSV
+  const records = await csvParser.parse(csvContent);
+  console.log(`Parsed ${records.length} records`);
+
+  // 5. Transform with UniversalMapper
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: { source: 'sku', required: true },
+      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+      locationRef: { source: 'warehouse' },
+      type: { value: 'LAST' }
+    }
+  });
+
+  const result = await mapper.map(records);
+
+  if (!result.success) {
+    throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
+  }
+
+  // 6. Send to Fluent Batch API (INVENTORY only)
+  const job = await client.createJob({
+    name: `csv-ingestion-${Date.now()}`,
+    type: 'INVENTORY',
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  });
+
+  await client.sendBatch(job.id, {
+    entities: result.data
+  });
+
+  // 7. Mark as processed
+  await stateService.markFileProcessed(fileKey, {
+    recordCount: records.length,
+    processedAt: new Date().toISOString()
+  });
+
+  console.log(`✅ Processed ${records.length} inventory records`);
+}
+```
+
+### Pattern 2: JSON Webhook Processing
+
+**Use Case:** Process incoming webhooks from e-commerce platform
+
+```typescript
+import {
+  createClient,
+  JSONParserService,
+  UniversalMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processOrderWebhook(webhookPayload: string) {
+  // 1. Parse JSON webhook
+  const jsonParser = new JSONParserService();
+  const order = await jsonParser.parse(webhookPayload, {
+    parseDates: true,
+    validateSchema: true,
+    schema: orderSchema
+  });
+
+  // 2. Transform to Fluent format
+  const fluentOrder = {
+    ref: `WEB-${order.id}`,
+    type: 'HD',
+    retailerId: '1',
+    customer: {
+      email: order.customer.email,
+      firstName: order.customer.first_name,
+      lastName: order.customer.last_name
+    },
+    items: order.items.map(item => ({
+      ref: item.sku,
+      quantity: item.quantity,
+      price: parseFloat(item.price)
+    }))
+  };
+
+  // 3. Send to Fluent (using GraphQL mutation, NOT Batch API)
+  const client = await createClient({ config });
+  const result = await client.graphql({
+    query: `
+      mutation CreateOrder($input: CreateOrderInput!) {
+        createOrder(input: $input) {
+          id
+          ref
+          status
+        }
+      }
+    `,
+    variables: {
+      input: fluentOrder
+    }
+  });
+
+  console.log(`✅ Order created: ${result.data.createOrder.ref}`);
+  return result.data.createOrder;
+}
+```
+
+### Pattern 3: XML to GraphQL Mutation (SFCC Orders)
+
+**Use Case:** SFCC order XML → Fluent GraphQL mutation
+
+```typescript
+import {
+  createClient,
+  XMLParserService,
+  GraphQLMutationMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processSFCCOrder(xmlContent: string) {
+  // 1. Parse XML
+  const xmlParser = new XMLParserService();
+  const parsed = await xmlParser.parse(xmlContent);
+
+  // 2. Transform with GraphQLMutationMapper
+  const mapper = new GraphQLMutationMapper({
+    mutation: 'createOrder',
+    rootPath: 'Order',
+    fields: {
+      ref: { xmlPath: '@customerOrderId', required: true },
+      type: { value: 'HD' },
+      retailerId: { value: '1' },
+      customer: {
+        email: { xmlPath: 'Customer.EmailAddress' },
+        firstName: { xmlPath: 'Customer.Name.FirstName' },
+        lastName: { xmlPath: 'Customer.Name.LastName' }
+      },
+      items: {
+        arrayPath: 'OrderItems.OrderItem',
+        fields: {
+          ref: { xmlPath: 'ItemId' },
+          quantity: { xmlPath: 'Quantity', resolver: 'sdk.parseInt' },
+          price: { xmlPath: 'Price', resolver: 'sdk.parseFloat' }
+        }
+      }
+    }
+  });
+
+  const mutation = await mapper.map(parsed);
+
+  // 3. Send to Fluent
+  const client = await createClient({ config });
+  const result = await client.graphql({
+    query: mutation.query,
+    variables: mutation.variables
+  });
+
+  console.log(`✅ SFCC order created: ${result.data.createOrder.ref}`);
+  return result.data.createOrder;
+}
+```
+
+### Pattern 4: Parquet Extraction Pipeline
+
+**Use Case:** Extract Fluent data to analytics warehouse
+
+```typescript
+import {
+  createClient,
+  ParquetParserService,
+  S3DataSource,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function extractToParquet(entityType: string) {
+  const logger = createConsoleLogger();
+  const client = await createClient({ config });
+  const s3DataSource = new S3DataSource({
+    type: 'S3_PARQUET',
+    connectionId: 's3-parquet-extract',
+    name: 'S3 Parquet Extract',
+    s3Config: s3Config
+  }, logger);
+
+  // 1. Fetch data from Fluent with auto-pagination
+  const result = await client.graphql({
+    query: `
+      query GetVirtualPositions($first: Int!, $after: String) {
+        virtualPositions(first: $first, after: $after) {
+          edges {
+            node {
+              id
+              productRef
+              quantity
+              groupRef
+              createdOn
+              updatedOn
+            }
+            cursor
+          }
+          pageInfo {
+            hasNextPage
+          }
+        }
+      }
+    `,
+    variables: { first: 1000 },
+    pagination: { maxRecords: 1000000 }
+  });
+
+  // 2. Transform to flat structure
+  const records = result.data.virtualPositions.edges.map(edge => ({
+    id: edge.node.id,
+    productRef: edge.node.productRef,
+    quantity: edge.node.quantity,
+    groupRef: edge.node.groupRef,
+    createdOn: edge.node.createdOn,
+    updatedOn: edge.node.updatedOn
+  }));
+
+  console.log(`Extracted ${records.length} virtual positions`);
+
+  // 3. Convert to Parquet
+  const parquetBuffer = await convertToParquet(records);
+
+  // 4. Upload to S3 with date partition
+  const date = new Date().toISOString().split('T')[0];
+  await s3DataSource.uploadFile(
+    `virtual-positions/date=${date}/data.parquet`,
+    parquetBuffer,
+    { contentType: 'application/octet-stream' }
+  );
+
+  console.log(`✅ Extracted ${records.length} records to S3`);
+}
+```
+
+### Pattern 5: Multi-Format ETL Pipeline
+
+**Use Case:** Accept multiple formats, detect and route appropriately
+
+```typescript
+import {
+  CSVParserService,
+  JSONParserService,
+  XMLParserService,
+  ParquetParserService,
+  UniversalMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function multiFormatETL(fileContent: string | Buffer, fileType: string) {
+  let records: any[];
+
+  // 1. Parse based on format
+  switch (fileType) {
+    case 'csv':
+      const csvParser = new CSVParserService();
+      records = await csvParser.parse(fileContent as string);
+      break;
+
+    case 'json':
+      const jsonParser = new JSONParserService();
+      records = await jsonParser.parse(fileContent as string);
+      break;
+
+    case 'xml':
+      const xmlParser = new XMLParserService();
+      const parsed = await xmlParser.parse(fileContent as string);
+      records = extractRecordsFromXML(parsed);
+      break;
+
+    case 'parquet':
+      const logger = createConsoleLogger();
+      const parquetParser = new ParquetParserService(logger);
+      records = await parquetParser.parse(fileContent as Buffer);
+      break;
+
+    default:
+      throw new Error(`Unsupported file type: ${fileType}`);
+  }
+
+  console.log(`Parsed ${records.length} records from ${fileType}`);
+
+  // 2. Transform with UniversalMapper (works for all formats!)
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: { source: 'sku', required: true },
+      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+      locationRef: { source: 'location' }
+    }
+  });
+
+  const result = await mapper.map(records);
+
+  if (!result.success) {
+    throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
+  }
+
+  // 3. Send to Fluent
+  const client = await createClient({ config });
+  const job = await client.createJob({
+    name: 'inventory-ingestion',
+    retailerId: config.config.retailerId
+  });
+
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    source: 'csv-import',
+    event: 'inventory.update',
+    entities: result.data
+  });
+
+  console.log(`✅ Processed ${records.length} records`);
+}
+
+function extractRecordsFromXML(parsed: any): any[] {
+  // Extract array from XML structure
+  return parsed.products?.product || [];
+}
+```
+
+## Versori Platform Patterns
+
+### Pattern 6: Versori Scheduled Workflow
+
+**Use Case:** Daily S3 CSV ingestion on Versori platform
+
+```typescript
+import { fn, schedule } from '@versori/run';
+import {
+  createClient,
+  CSVParserService,
+  UniversalMapper,
+  S3DataSource
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const dailyInventorySync = schedule('daily-inventory')
+  .cron('0 2 * * *') // 2 AM daily
+  .do(async (ctx) => {
+    // Auto-detects Versori context
+    const client = await createClient(ctx);
+    const csvParser = new CSVParserService();
+
+    // Use S3DataSource for Versori S3 connection
+    const s3Source = new S3DataSource(ctx.connections.s3);
+
+    // Download CSV
+    const csvContent = await s3Source.downloadFile({
+      bucket: 'inventory-feeds',
+      key: 'daily/inventory.csv'
+    });
+
+    // Parse and transform
+    const records = await csvParser.parse(csvContent);
+    const mapper = new UniversalMapper(mappingConfig);
+    const result = await mapper.map(records);
+
+    // Send to Fluent
+    const job = await client.createJob({
+    name: 'inventory-ingestion',
+    retailerId: config.config.retailerId
+  });
+
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    source: 'csv-import',
+    event: 'inventory.update',
+    entities: result.data
+  });
+
+    ctx.log.info(`✅ Processed ${records.length} records`);
+  });
+```
+
+### Pattern 7: Versori Webhook Handler
+
+**Use Case:** Process incoming JSON webhooks on Versori
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import {
+  createClient,
+  JSONParserService,
+  UniversalMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const processWebhook = webhook('order-webhook')
+  .then(fn('parse', async (ctx) => {
+    const jsonParser = new JSONParserService();
+
+    // Parse webhook payload
+    const order = await jsonParser.parse(ctx.trigger.body, {
+      parseDates: true
+    });
+
+    return { order };
+  }))
+  .then(fn('transform', async (ctx) => {
+    const mapper = new UniversalMapper(orderMappingConfig);
+    const result = await mapper.map(ctx.data.order);
+
+    if (!result.success) {
+      throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
+    }
+
+    return { fluentOrder: result.data };
+  }))
+  .then(fn('send-to-fluent', async (ctx) => {
+    const client = await createClient(ctx);
+
+    const result = await client.graphql({
+      query: createOrderMutation,
+      variables: { input: ctx.data.fluentOrder }
+    });
+
+    return result.data.createOrder;
+  }))
+  .catch((ctx) => {
+    ctx.log.error('Webhook processing failed:', ctx.error);
+    throw ctx.error;
+  });
+```
+
+## Complete Real-World Examples
+
+### Example 1: S3 CSV Inventory Ingestion (Node.js)
+
+```typescript
+import {
+  createClient,
+  CSVParserService,
+  UniversalMapper,
+  S3DataSource,
+  StateService,
+  VersoriKVAdapter
+} from '@fluentcommerce/fc-connect-sdk';
+import * as fs from 'fs/promises';
+
+async function s3CsvIngestion() {
+  // Initialize services
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  }
+});
+
+  const s3DataSource = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 's3-parsers-integration',
+      name: 'S3 Parsers Integration',
+      s3Config: {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+        region: process.env.AWS_REGION!,
+        bucket: 'inventory-feeds',
+      },
+    },
+    console
+  );
+
+  // List files in S3
+  const files = await s3DataSource.listFiles({
+    prefix: 'daily/'
+  });
+
+  for (const file of files) {
+    console.log(`Processing ${file.path}`);
+
+    // Download CSV
+    const csvContent = await s3DataSource.downloadFile(file.path);
+
+    // Parse CSV
+    const csvParser = new CSVParserService();
+    const records = await csvParser.parse(csvContent);
+
+    // Transform
+    const mapper = new UniversalMapper({
+      fields: {
+        ref: { source: 'sku', required: true },
+        qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+        locationRef: { source: 'warehouse' },
+        type: { value: 'LAST' }
+      }
+    });
+
+    const result = await mapper.map(records);
+
+    // Send to Fluent
+    const job = await client.createJob({
+    name: 'inventory-ingestion',
+    retailerId: config.config.retailerId
+  });
+
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    source: 'csv-import',
+    event: 'inventory.update',
+    entities: result.data
+  });
+
+    console.log(`✅ Processed ${records.length} records from ${file.path}`);
+  }
+}
+```
+
+### Example 2: Extraction to Parquet (Node.js)
+
+```typescript
+import {
+  createClient,
+  ParquetParserService,
+  S3DataSource,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function extractToParquet() {
+  const logger = createConsoleLogger();
+  const client = await createClient({ config });
+  const s3DataSource = new S3DataSource({
+    type: 'S3_PARQUET',
+    connectionId: 's3-parquet-extract',
+    name: 'S3 Parquet Extract',
+    s3Config: s3Config
+  }, logger);
+
+  // Fetch data with auto-pagination
+  const result = await client.graphql({
+    query: virtualPositionsQuery,
+    variables: { first: 1000 },
+    pagination: { maxRecords: 1000000 }
+  });
+
+  const records = result.data.virtualPositions.edges.map(e => e.node);
+
+  // Convert to Parquet
+  const parquetBuffer = await convertToParquet(records);
+
+  // Upload to S3
+  const date = new Date().toISOString().split('T')[0];
+  await s3DataSource.uploadFile(
+    `virtual-positions/date=${date}/data.parquet`,
+    parquetBuffer
+  );
+
+  console.log(`✅ Extracted ${records.length} records`);
+}
+```
+
+## Error Handling Patterns
+
+### Comprehensive Error Handling
+
+```typescript
+async function robustIntegration(fileContent: string) {
+  try {
+    // 1. Parse
+    const csvParser = new CSVParserService();
+    const records = await csvParser.parse(fileContent);
+
+    // 2. Validate
+    if (records.length === 0) {
+      throw new Error('No records found in file');
+    }
+
+    // 3. Transform
+    const mapper = new UniversalMapper(mappingConfig);
+    const result = await mapper.map(records);
+
+    if (!result.success) {
+      // Log mapping errors but continue with successful records
+      console.error('Mapping errors:', result.errors);
+
+      if (result.data.length === 0) {
+        throw new Error('All records failed mapping');
+      }
+
+      console.warn(`Proceeding with ${result.data.length}/${records.length} successful records`);
+    }
+
+    // 4. Send to Fluent
+    const client = await createClient({ config });
+    const job = await client.createJob({
+    name: 'inventory-ingestion',
+    retailerId: config.config.retailerId
+  });
+
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    source: 'csv-import',
+    event: 'inventory.update',
+    entities: result.data
+  });
+
+    console.log(`✅ Processed ${result.data.length} records`);
+
+  } catch (error) {
+    console.error('Integration failed:', error);
+
+    // Send alert/notification
+    await sendAlert(`Integration failed: ${error.message}`);
+
+    throw error;
+  }
+}
+```
+
+## Key Takeaways
+
+- 🎯 Combine parsers with UniversalMapper for standard transformation pattern
+- 🎯 Use GraphQLMutationMapper for complex XML→GraphQL transformations
+- 🎯 Integrate with S3DataSource for file operations
+- 🎯 Use StateService to prevent duplicate processing
+- 🎯 Auto-pagination works seamlessly for large extractions
+- 🎯 Versori patterns auto-detect platform context
+- 🎯 Always handle errors and log processing metrics
+
+## Practice Exercise
+
+**Challenge:** Build complete ingestion pipeline:
+
+**Requirements:**
+1. Download CSV from S3: `s3://feeds/inventory-2025-01-15.csv`
+2. Parse CSV with validation
+3. Transform with UniversalMapper (sku→ref, quantity→qty)
+4. Send to Fluent Batch API
+5. Track state to prevent duplicate processing
+6. Handle errors gracefully
+
+**Solution:** See [Parser Examples](../examples/)
+
+## Next Steps
+
+Continue to [Module 7: Troubleshooting →](./02-core-guides-parsers-07-troubleshooting.md) for error handling and optimization.
+
+---
+
+**Module 6 Complete!** ✅