npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (495) hide show

package/docs/00-START-HERE/decision-tree.md CHANGED Viewed

@@ -1,552 +1,552 @@
-# SDK Decision Tree - Which Approach Should I Use?
-**Quick navigation to help you choose the right SDK approach for your use case.**
-> Minimal-first policy: Use native/platform primitives by default. Advanced SDK helpers are optional.
-Minimal logger snippet (copy/paste):
-```typescript
-const logger: import('@fluentcommerce/fc-connect-sdk').Logger = {
-  debug: (m, meta) => log.debug(m, meta),
-  info: (m, meta) => log.info(m, meta),
-  warn: (m, meta) => log.warn(m, meta),
-  error: (m, err, meta) => log.error(m, { ...(meta ?? {}), error: err?.message }),
-};
-```
-See also: [Logging Guide](../02-CORE-GUIDES/logging-guide.md)
-## 🎯 Start Here
-Answer these questions to find your path:
-```
-1. What are you trying to do?
-   ├─ Ingest data INTO Fluent Commerce → [Section A: Ingestion](#a-ingestion-use-cases)
-   ├─ Extract data FROM Fluent Commerce → [Section B: Extraction](#b-extraction-use-cases)
-   ├─ Execute GraphQL queries/mutations → [Section C: GraphQL Operations](#c-graphql-operations)
-   └─ Custom integration workflow → [Section D: Custom Workflows](#d-custom-workflows)
-```
----
-## A: Ingestion Use Cases
-**Goal:** Get data into Fluent Commerce
-### A1: Control CSV to Fluent (Control Groups, Rules)
-**Use:** `UniversalMapper` + Bulk GraphQL queries (optimized pattern)
-**Complexity:** 🟡 Intermediate
-```typescript
-import {
-  createClient,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-} from '@fluentcommerce/fc-connect-sdk';
-const client = await createClient(ctx); // Versori context auto-detected
-const s3 = new S3DataSource(config, logger);
-const csvParser = new CSVParserService();
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers: {
-    'custom.buildControlRef': (value, sourceData) => {
-      // Auto-build controlRef from components
-      return `${sourceData.catalogRef}:${sourceData.controlType}:${sourceData.productRef || sourceData.categoryRef}`;
-    },
-  },
-});
-// Bulk query existing controls (5x faster than individual queries)
-const existingControls = await bulkQueryControls(client, controlRefs);
-// Smart upsert with duplicate detection
-for (const record of csvRecords) {
-  const mapped = await mapper.map(record);
-  const mutation = existingControls.has(mapped.data.ref)
-    ? updateControlMutation
-    : createControlMutation;
-  await client.graphql({ query: mutation, variables: mapped.data });
-}
-```
-**Key Features:**
-- ✅ 3 CSV pattern options (pre-built, component-based, hybrid)
-- ✅ Bulk GraphQL queries with pagination (5x faster)
-- ✅ Schema validation with ControlSchemaValidator
-- ✅ 3-level duplicate detection (file, row, cross-file)
-- ✅ 20+ metrics tracking
-**Documentation:**
-- [S3 Control CSV → GraphQL](../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md)
-- [SFTP Control CSV → GraphQL](../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md)
----
-### A2: XML Orders to Fluent (SFCC, EDI, etc.)
-**Use:** `GraphQLMutationMapper` (transforms XML → GraphQL mutations)
-**Complexity:** 🟡 Intermediate
-```typescript
-import { GraphQLMutationMapper, XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new XMLParserService(logger);
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-// Parse XML
-const xmlData = await parser.parse(xmlString);
-// Transform to GraphQL mutation
-const mutation = await mapper.generateMutation(xmlData);
-// Execute
-await client.graphql({
-  query: mutation.mutation,
-  variables: mutation.variables,
-});
-```
-**Documentation:**
-- [GraphQL Mutation Mapping Guide](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md)
-- [XML Parser](../02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md)
-- [Use Case: SFCC Order Ingestion](../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
----
-### A3: Custom Data Source (API, Database, etc.)
-**Use:** Manual composition (low-level)
-**Complexity:** 🔴 Advanced
-```typescript
-import { UniversalMapper, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-// 1. Fetch data from your source
-const data = await fetchFromCustomAPI();
-// 2. Parse/transform
-const parser = new CSVParserService();
-const records = await parser.parse(data);
-// 3. Map fields
-const mapper = new UniversalMapper(mappingConfig);
-const mappedData = await Promise.all(records.map(r => mapper.map(r)));
-// 4. Create job and send batches
-const job = await client.createJob({
-  name: 'custom-ingestion',
-  retailerId: '1',
-  meta: { source: 'custom-api' },
-});
-await client.sendBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  entities: mappedData.filter(r => r.success).map(r => r.data),
-});
-```
-**Documentation:**
-- [SDK Philosophy](./sdk-philosophy.md) - Understanding composition
-- [Universal Mapping](../02-CORE-GUIDES/mapping/mapping-readme.md)
-- [Client API](../02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md)
----
-## B: Extraction Use Cases
-**Goal:** Get data out of Fluent Commerce
-### B1: Export Inventory to S3 (JSON/Parquet/CSV)
-**Use:** `ExtractionOrchestrator` (high-level, recommended)
-**Complexity:** 🟢 Beginner
-```typescript
-import { ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
-const orchestrator = new ExtractionOrchestrator(client, logger);
-// Extract with auto-pagination and validation
-const result = await orchestrator.extract({
-  query: `query GetInventory($first: Int!, $after: String) {
-    inventoryPositions(first: $first, after: $after) {
-      edges {
-        node { ref productRef locationRef onHand status }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-        # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-      }
-    }
-  }`,
-  variables: { first: 100 },
-  resultPath: 'inventoryPositions.edges.node', // Path to nodes for extraction
-  outputFormat: 'json', // or 'csv', 'parquet'
-  s3Config: {
-    bucket: 'my-exports',
-    key: 'inventory/export.json',
-    region: 'us-east-1',
-  },
-  // Optional: field mapping and transformation
-  fieldMappings: {
-    sku: { source: 'ref' },
-    quantity: { source: 'onHand', resolver: 'sdk.parseInt' },
-  },
-  // Optional: validation
-  validateRecords: true,
-  maxRecords: 10000,
-});
-console.log(`Exported ${result.stats.recordCount} records`);
-```
-**Key Features:**
-- ✅ Auto-pagination (handles cursor-based pagination automatically)
-- ✅ Path-based extraction (extracts data from nested GraphQL responses)
-- ✅ Multiple output formats (JSON, CSV, Parquet)
-- ✅ Built-in validation and error handling
-- ✅ Progress tracking and statistics
-**Documentation:**
-- [Extraction Guide](../02-CORE-GUIDES/extraction/extraction-readme.md)
-- [ExtractionOrchestrator Summary](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md)
-- [Export Formats](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-06-export-formats.md)
----
-### B2: GraphQL Query with Auto-Pagination
-**Use:** `client.graphql()` with pagination
-**Complexity:** 🟡 Intermediate
-```typescript
-const result = await client.graphql({
-  query: `query GetOrders($first: Int, $after: String) {
-    orders(first: $first, after: $after) {
-      edges { node { id ref status } }
-      pageInfo {
-        hasNextPage
-        # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-      }
-    }
-  }`,
-  variables: { first: 100 },
-  pagination: {
-    enabled: true,
-    maxPages: 50,
-    pageSize: 100,
-  },
-});
-// All pages automatically fetched
-console.log(result.data);
-```
-**Documentation:**
-- [Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
-- [GraphQL Operations](../02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md#graphql-operations)
----
-## C: GraphQL Operations
-**Goal:** Execute GraphQL queries or mutations directly
-### C1: Simple Query (Single Page)
-**Use:** `client.graphql()`
-**Complexity:** 🟢 Beginner
-```typescript
-const result = await client.graphql({
-  query: `query GetProduct($ref: String!) {
-    product(ref: $ref) { id name status }
-  }`,
-  variables: { ref: 'PRODUCT-123' },
-});
-console.log(result.data);
-```
----
-### C2: Mutation (Create/Update)
-**Use:** `client.graphql()`
-**Complexity:** 🟢 Beginner
-```typescript
-const result = await client.graphql({
-  query: `mutation CreateInventory($input: CreateInventoryInput!) {
-    createInventory(input: $input) { id ref }
-  }`,
-  variables: {
-    input: {
-      ref: 'INV-001',
-      skuRef: 'SKU-123',
-      locationRef: 'DC-01',
-      qty: 100,
-    },
-  },
-});
-```
----
-## D: Custom Workflows
-**Goal:** Build custom integration logic
-### D1: Multi-Source Data Aggregation
-**Complexity:** 🔴 Advanced
-**Approach:** Compose SDK services manually
-```typescript
-// 1. Fetch from multiple sources in parallel
-const [s3Data, sftpData, apiData] = await Promise.all([
-  s3Source.downloadFile('file1.csv'),
-  sftpSource.downloadFile('file2.csv'),
-  fetchFromAPI(),
-]);
-// 2. Parse each format
-const logger = createConsoleLogger();
-const csvParser = new CSVParserService();
-const parquetParser = new ParquetParserService(logger);
-const [s3Records, sftpRecords] = await Promise.all([
-  csvParser.parse(s3Data),
-  csvParser.parse(sftpData),
-]);
-// 3. Aggregate and deduplicate
-const aggregated = [...s3Records, ...sftpRecords, ...apiData];
-const deduplicated = deduplicateByKey(aggregated, 'sku');
-// 4. Map and send
-const mapper = new UniversalMapper(mappingConfig);
-const mapped = await Promise.all(deduplicated.map(r => mapper.map(r)));
-const job = await client.createJob({ name: 'aggregated-ingestion', retailerId: '1' });
-await client.sendBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  entities: mapped.filter(r => r.success).map(r => r.data),
-});
-```
-**Documentation:**
-- [SDK Philosophy](./sdk-philosophy.md)
-- [Custom Workflows Pattern](../01-TEMPLATES/standalone/multi-source-aggregation.md)
----
-### D2: Real-Time Webhook Processing
-**Complexity:** 🟡 Intermediate
-**Approach:** Manual composition with webhook parsing
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-// Parse incoming webhook (Versori context)
-const payload = typeof request.body === 'string' ? JSON.parse(request.body) : request.body;
-// Map and process
-const mapper = new UniversalMapper(mappingConfig);
-const mapped = await mapper.map(payload);
-// Send to Fluent
-await client.graphql({
-  query: createOrderMutation,
-  variables: { input: mapped.data },
-});
-```
-**Documentation:**
-- [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)
-- [Real-Time Processing Pattern](../03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-01-real-time-processing.md)
----
-## Quick Reference Table
-| Use Case                     | SDK Component                    | Complexity  | Documentation                                                                                                |
-| ---------------------------- | -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
-| Control CSV → Fluent         | `UniversalMapper` + Bulk GraphQL | 🟡 Medium   | [S3 Control CSV](../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md) |
-| XML → Fluent (Orders)        | `GraphQLMutationMapper`          | 🟡 Medium   | [GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md)                     |
-| Fluent → S3/JSON/CSV/Parquet | `ExtractionOrchestrator`         | 🟢 Easy     | [Extraction](../02-CORE-GUIDES/extraction/extraction-readme.md)                                                         |
-| GraphQL Query (single)       | `client.graphql()`               | 🟢 Easy     | [Client API](../02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md)                                       |
-| GraphQL Query (paginated)    | `client.graphql({ pagination })` | 🟡 Medium   | [Auto-Pagination](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)                                               |
-| Webhook Processing           | `parseWebhookRequest` + manual   | 🟡 Medium   | [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)                                         |
-| Custom Data Source           | Manual composition               | 🔴 Advanced | [SDK Philosophy](./sdk-philosophy.md)                                                                        |
-| Multi-Source Aggregation     | Manual composition               | 🔴 Advanced | [Custom Workflows](../01-TEMPLATES/patterns/)                                                                |
----
-## Complexity Legend
-- 🟢 **Beginner** - Use high-level orchestrators/services, minimal code, opinionated
-- 🟡 **Intermediate** - Compose 2-3 SDK services, some configuration needed
-- 🔴 **Advanced** - Full manual composition, custom parsers/resolvers, deep understanding required
----
-## Common Questions
-### Q: Should I compose services manually?
-**Always compose services manually for maximum flexibility:**
-- ✅ Custom data source (API, database, etc.)
-- ✅ Complex multi-step transformations
-- ✅ Non-standard file formats
-- ✅ Full control over job creation/batching
-- ✅ Standard CSV/Parquet → Fluent ingestion (use building blocks)
-- ✅ Better testability and maintainability
-### Q: How do I add custom field transformations?
-**Use Custom Resolvers in UniversalMapper:**
-```typescript
-const mapper = new UniversalMapper(config, {
-  customResolvers: {
-    'custom.calculatePrice': (value, sourceData, helpers) => {
-      return helpers.parseFloatSafe(value, 0) * 1.1; // Add 10%
-    },
-  },
-});
-```
-**Documentation:** [Custom Resolvers](../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md)
-### Q: How do I prevent duplicate file processing?
-**Use State Management:**
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-const stateService = new StateService(new VersoriKVAdapter(kv));
-const processed = await stateService.isFileProcessed(fileKey);
-if (!processed) {
-  await processFile();
-  await stateService.markFileProcessed(fileKey, metadata);
-}
-```
-**Documentation:** [State Management](../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md)
-### Q: Can I use multiple Fluent Commerce accounts/retailers?
-**Yes, create multiple clients:**
-```typescript
-const client1 = await createClient({ config: { retailerId: '1', ... } });
-const client2 = await createClient({ config: { retailerId: '2', ... } });
-// Use in parallel
-await Promise.all([
-  client1.createJob({ ... }),
-  client2.createJob({ ... })
-]);
-```
-**Documentation:** [Multiple Connections](../03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md)
-### Q: What if I need to process 100GB+ files?
-**Use streaming and chunking with building blocks:**
-```typescript
-import {
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-  createClient,
-} from '@fluentcommerce/fc-connect-sdk';
-const s3 = new S3DataSource(config, logger);
-const parser = new CSVParserService({ streaming: true }); // Enable streaming
-const mapper = new UniversalMapper(mappingConfig);
-const client = await createClient({ config });
-// Create job
-const job = await client.createJob({
-  name: 'Large File Processing',
-  retailerId: '1',
-});
-// Stream and process in chunks
-const stream = await s3.streamFile('large-file.csv');
-const recordStream = await parser.parseStream(stream);
-let batch = [];
-for await (const record of recordStream) {
-  const result = await mapper.map(record);
-  if (result.success) {
-    batch.push(result.data);
-    // Send when batch reaches 1000
-    if (batch.length >= 1000) {
-      await client.sendBatch(job.id, {
-        action: 'UPSERT',
-        entityType: 'INVENTORY',
-        entities: batch,
-      });
-      batch = [];
-    }
-  }
-}
-// Send remaining records
-if (batch.length > 0) {
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    entities: batch,
-  });
-}
-```
-**Documentation:** [Performance Optimization](../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-08-performance-optimization.md)
----
-## Still Stuck?
-1. **🔧 Debugging:** [`troubleshooting-quick-reference.md`](./troubleshooting-quick-reference.md) - Fix 90% of issues in 5 steps
-2. **Check Examples:** [`docs/01-TEMPLATES/`](../01-TEMPLATES/) - 30+ real-world scenarios
-3. **Read Philosophy:** [`sdk-philosophy.md`](./sdk-philosophy.md) - Understand the "why"
-4. **API Reference:** [`api-reference/`](../02-CORE-GUIDES/api-reference/) - Complete method documentation
-5. **Common Patterns:** [`patterns/`](../01-TEMPLATES/patterns/) - Reusable solutions
----
-**[← Back to Getting Started](./getting-started.md)** | **[Troubleshooting →](./troubleshooting-quick-reference.md)** | **[API Reference →](../02-CORE-GUIDES/api-reference/api-reference-readme.md)**
+# SDK Decision Tree - Which Approach Should I Use?
+**Quick navigation to help you choose the right SDK approach for your use case.**
+> Minimal-first policy: Use native/platform primitives by default. Advanced SDK helpers are optional.
+Minimal logger snippet (copy/paste):
+```typescript
+const logger: import('@fluentcommerce/fc-connect-sdk').Logger = {
+  debug: (m, meta) => log.debug(m, meta),
+  info: (m, meta) => log.info(m, meta),
+  warn: (m, meta) => log.warn(m, meta),
+  error: (m, err, meta) => log.error(m, { ...(meta ?? {}), error: err?.message }),
+};
+```
+See also: [Logging Guide](../02-CORE-GUIDES/logging-guide.md)
+## 🎯 Start Here
+Answer these questions to find your path:
+```
+1. What are you trying to do?
+   ├─ Ingest data INTO Fluent Commerce → [Section A: Ingestion](#a-ingestion-use-cases)
+   ├─ Extract data FROM Fluent Commerce → [Section B: Extraction](#b-extraction-use-cases)
+   ├─ Execute GraphQL queries/mutations → [Section C: GraphQL Operations](#c-graphql-operations)
+   └─ Custom integration workflow → [Section D: Custom Workflows](#d-custom-workflows)
+```
+---
+## A: Ingestion Use Cases
+**Goal:** Get data into Fluent Commerce
+### A1: Control CSV to Fluent (Control Groups, Rules)
+**Use:** `UniversalMapper` + Bulk GraphQL queries (optimized pattern)
+**Complexity:** 🟡 Intermediate
+```typescript
+import {
+  createClient,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+} from '@fluentcommerce/fc-connect-sdk';
+const client = await createClient(ctx); // Versori context auto-detected
+const s3 = new S3DataSource(config, logger);
+const csvParser = new CSVParserService();
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers: {
+    'custom.buildControlRef': (value, sourceData) => {
+      // Auto-build controlRef from components
+      return `${sourceData.catalogRef}:${sourceData.controlType}:${sourceData.productRef || sourceData.categoryRef}`;
+    },
+  },
+});
+// Bulk query existing controls (5x faster than individual queries)
+const existingControls = await bulkQueryControls(client, controlRefs);
+// Smart upsert with duplicate detection
+for (const record of csvRecords) {
+  const mapped = await mapper.map(record);
+  const mutation = existingControls.has(mapped.data.ref)
+    ? updateControlMutation
+    : createControlMutation;
+  await client.graphql({ query: mutation, variables: mapped.data });
+}
+```
+**Key Features:**
+- ✅ 3 CSV pattern options (pre-built, component-based, hybrid)
+- ✅ Bulk GraphQL queries with pagination (5x faster)
+- ✅ Schema validation with ControlSchemaValidator
+- ✅ 3-level duplicate detection (file, row, cross-file)
+- ✅ 20+ metrics tracking
+**Documentation:**
+- [S3 Control CSV → GraphQL](../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md)
+- [SFTP Control CSV → GraphQL](../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md)
+---
+### A2: XML Orders to Fluent (SFCC, EDI, etc.)
+**Use:** `GraphQLMutationMapper` (transforms XML → GraphQL mutations)
+**Complexity:** 🟡 Intermediate
+```typescript
+import { GraphQLMutationMapper, XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new XMLParserService(logger);
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+// Parse XML
+const xmlData = await parser.parse(xmlString);
+// Transform to GraphQL mutation
+const mutation = await mapper.generateMutation(xmlData);
+// Execute
+await client.graphql({
+  query: mutation.mutation,
+  variables: mutation.variables,
+});
+```
+**Documentation:**
+- [GraphQL Mutation Mapping Guide](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md)
+- [XML Parser](../02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md)
+- [Use Case: SFCC Order Ingestion](../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+---
+### A3: Custom Data Source (API, Database, etc.)
+**Use:** Manual composition (low-level)
+**Complexity:** 🔴 Advanced
+```typescript
+import { UniversalMapper, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+// 1. Fetch data from your source
+const data = await fetchFromCustomAPI();
+// 2. Parse/transform
+const parser = new CSVParserService();
+const records = await parser.parse(data);
+// 3. Map fields
+const mapper = new UniversalMapper(mappingConfig);
+const mappedData = await Promise.all(records.map(r => mapper.map(r)));
+// 4. Create job and send batches
+const job = await client.createJob({
+  name: 'custom-ingestion',
+  retailerId: '1',
+  meta: { source: 'custom-api' },
+});
+await client.sendBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  entities: mappedData.filter(r => r.success).map(r => r.data),
+});
+```
+**Documentation:**
+- [SDK Philosophy](./sdk-philosophy.md) - Understanding composition
+- [Universal Mapping](../02-CORE-GUIDES/mapping/mapping-readme.md)
+- [Client API](../02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md)
+---
+## B: Extraction Use Cases
+**Goal:** Get data out of Fluent Commerce
+### B1: Export Inventory to S3 (JSON/Parquet/CSV)
+**Use:** `ExtractionOrchestrator` (high-level, recommended)
+**Complexity:** 🟢 Beginner
+```typescript
+import { ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
+const orchestrator = new ExtractionOrchestrator(client, logger);
+// Extract with auto-pagination and validation
+const result = await orchestrator.extract({
+  query: `query GetInventory($first: Int!, $after: String) {
+    inventoryPositions(first: $first, after: $after) {
+      edges {
+        node { ref productRef locationRef onHand status }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+      }
+    }
+  }`,
+  variables: { first: 100 },
+  resultPath: 'inventoryPositions.edges.node', // Path to nodes for extraction
+  outputFormat: 'json', // or 'csv', 'parquet'
+  s3Config: {
+    bucket: 'my-exports',
+    key: 'inventory/export.json',
+    region: 'us-east-1',
+  },
+  // Optional: field mapping and transformation
+  fieldMappings: {
+    sku: { source: 'ref' },
+    quantity: { source: 'onHand', resolver: 'sdk.parseInt' },
+  },
+  // Optional: validation
+  validateRecords: true,
+  maxRecords: 10000,
+});
+console.log(`Exported ${result.stats.recordCount} records`);
+```
+**Key Features:**
+- ✅ Auto-pagination (handles cursor-based pagination automatically)
+- ✅ Path-based extraction (extracts data from nested GraphQL responses)
+- ✅ Multiple output formats (JSON, CSV, Parquet)
+- ✅ Built-in validation and error handling
+- ✅ Progress tracking and statistics
+**Documentation:**
+- [Extraction Guide](../02-CORE-GUIDES/extraction/extraction-readme.md)
+- [ExtractionOrchestrator Summary](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md)
+- [Export Formats](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-06-export-formats.md)
+---
+### B2: GraphQL Query with Auto-Pagination
+**Use:** `client.graphql()` with pagination
+**Complexity:** 🟡 Intermediate
+```typescript
+const result = await client.graphql({
+  query: `query GetOrders($first: Int, $after: String) {
+    orders(first: $first, after: $after) {
+      edges { node { id ref status } }
+      pageInfo {
+        hasNextPage
+        # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+      }
+    }
+  }`,
+  variables: { first: 100 },
+  pagination: {
+    enabled: true,
+    maxPages: 50,
+    pageSize: 100,
+  },
+});
+// All pages automatically fetched
+console.log(result.data);
+```
+**Documentation:**
+- [Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
+- [GraphQL Operations](../02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md#graphql-operations)
+---
+## C: GraphQL Operations
+**Goal:** Execute GraphQL queries or mutations directly
+### C1: Simple Query (Single Page)
+**Use:** `client.graphql()`
+**Complexity:** 🟢 Beginner
+```typescript
+const result = await client.graphql({
+  query: `query GetProduct($ref: String!) {
+    product(ref: $ref) { id name status }
+  }`,
+  variables: { ref: 'PRODUCT-123' },
+});
+console.log(result.data);
+```
+---
+### C2: Mutation (Create/Update)
+**Use:** `client.graphql()`
+**Complexity:** 🟢 Beginner
+```typescript
+const result = await client.graphql({
+  query: `mutation CreateInventory($input: CreateInventoryInput!) {
+    createInventory(input: $input) { id ref }
+  }`,
+  variables: {
+    input: {
+      ref: 'INV-001',
+      skuRef: 'SKU-123',
+      locationRef: 'DC-01',
+      qty: 100,
+    },
+  },
+});
+```
+---
+## D: Custom Workflows
+**Goal:** Build custom integration logic
+### D1: Multi-Source Data Aggregation
+**Complexity:** 🔴 Advanced
+**Approach:** Compose SDK services manually
+```typescript
+// 1. Fetch from multiple sources in parallel
+const [s3Data, sftpData, apiData] = await Promise.all([
+  s3Source.downloadFile('file1.csv'),
+  sftpSource.downloadFile('file2.csv'),
+  fetchFromAPI(),
+]);
+// 2. Parse each format
+const logger = createConsoleLogger();
+const csvParser = new CSVParserService();
+const parquetParser = new ParquetParserService(logger);
+const [s3Records, sftpRecords] = await Promise.all([
+  csvParser.parse(s3Data),
+  csvParser.parse(sftpData),
+]);
+// 3. Aggregate and deduplicate
+const aggregated = [...s3Records, ...sftpRecords, ...apiData];
+const deduplicated = deduplicateByKey(aggregated, 'sku');
+// 4. Map and send
+const mapper = new UniversalMapper(mappingConfig);
+const mapped = await Promise.all(deduplicated.map(r => mapper.map(r)));
+const job = await client.createJob({ name: 'aggregated-ingestion', retailerId: '1' });
+await client.sendBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  entities: mapped.filter(r => r.success).map(r => r.data),
+});
+```
+**Documentation:**
+- [SDK Philosophy](./sdk-philosophy.md)
+- [Custom Workflows Pattern](../01-TEMPLATES/standalone/multi-source-aggregation.md)
+---
+### D2: Real-Time Webhook Processing
+**Complexity:** 🟡 Intermediate
+**Approach:** Manual composition with webhook parsing
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+// Parse incoming webhook (Versori context)
+const payload = typeof request.body === 'string' ? JSON.parse(request.body) : request.body;
+// Map and process
+const mapper = new UniversalMapper(mappingConfig);
+const mapped = await mapper.map(payload);
+// Send to Fluent
+await client.graphql({
+  query: createOrderMutation,
+  variables: { input: mapped.data },
+});
+```
+**Documentation:**
+- [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)
+- [Real-Time Processing Pattern](../03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-01-real-time-processing.md)
+---
+## Quick Reference Table
+| Use Case                     | SDK Component                    | Complexity  | Documentation                                                                                                |
+| ---------------------------- | -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
+| Control CSV → Fluent         | `UniversalMapper` + Bulk GraphQL | 🟡 Medium   | [S3 Control CSV](../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md) |
+| XML → Fluent (Orders)        | `GraphQLMutationMapper`          | 🟡 Medium   | [GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md)                     |
+| Fluent → S3/JSON/CSV/Parquet | `ExtractionOrchestrator`         | 🟢 Easy     | [Extraction](../02-CORE-GUIDES/extraction/extraction-readme.md)                                                         |
+| GraphQL Query (single)       | `client.graphql()`               | 🟢 Easy     | [Client API](../02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md)                                       |
+| GraphQL Query (paginated)    | `client.graphql({ pagination })` | 🟡 Medium   | [Auto-Pagination](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)                                               |
+| Webhook Processing           | `parseWebhookRequest` + manual   | 🟡 Medium   | [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)                                         |
+| Custom Data Source           | Manual composition               | 🔴 Advanced | [SDK Philosophy](./sdk-philosophy.md)                                                                        |
+| Multi-Source Aggregation     | Manual composition               | 🔴 Advanced | [Custom Workflows](../01-TEMPLATES/patterns/)                                                                |
+---
+## Complexity Legend
+- 🟢 **Beginner** - Use high-level orchestrators/services, minimal code, opinionated
+- 🟡 **Intermediate** - Compose 2-3 SDK services, some configuration needed
+- 🔴 **Advanced** - Full manual composition, custom parsers/resolvers, deep understanding required
+---
+## Common Questions
+### Q: Should I compose services manually?
+**Always compose services manually for maximum flexibility:**
+- ✅ Custom data source (API, database, etc.)
+- ✅ Complex multi-step transformations
+- ✅ Non-standard file formats
+- ✅ Full control over job creation/batching
+- ✅ Standard CSV/Parquet → Fluent ingestion (use building blocks)
+- ✅ Better testability and maintainability
+### Q: How do I add custom field transformations?
+**Use Custom Resolvers in UniversalMapper:**
+```typescript
+const mapper = new UniversalMapper(config, {
+  customResolvers: {
+    'custom.calculatePrice': (value, sourceData, helpers) => {
+      return helpers.parseFloatSafe(value, 0) * 1.1; // Add 10%
+    },
+  },
+});
+```
+**Documentation:** [Custom Resolvers](../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md)
+### Q: How do I prevent duplicate file processing?
+**Use State Management:**
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+const stateService = new StateService(new VersoriKVAdapter(kv));
+const processed = await stateService.isFileProcessed(fileKey);
+if (!processed) {
+  await processFile();
+  await stateService.markFileProcessed(fileKey, metadata);
+}
+```
+**Documentation:** [State Management](../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md)
+### Q: Can I use multiple Fluent Commerce accounts/retailers?
+**Yes, create multiple clients:**
+```typescript
+const client1 = await createClient({ config: { retailerId: '1', ... } });
+const client2 = await createClient({ config: { retailerId: '2', ... } });
+// Use in parallel
+await Promise.all([
+  client1.createJob({ ... }),
+  client2.createJob({ ... })
+]);
+```
+**Documentation:** [Multiple Connections](../03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md)
+### Q: What if I need to process 100GB+ files?
+**Use streaming and chunking with building blocks:**
+```typescript
+import {
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+  createClient,
+} from '@fluentcommerce/fc-connect-sdk';
+const s3 = new S3DataSource(config, logger);
+const parser = new CSVParserService({ streaming: true }); // Enable streaming
+const mapper = new UniversalMapper(mappingConfig);
+const client = await createClient({ config });
+// Create job
+const job = await client.createJob({
+  name: 'Large File Processing',
+  retailerId: '1',
+});
+// Stream and process in chunks
+const stream = await s3.streamFile('large-file.csv');
+const recordStream = await parser.parseStream(stream);
+let batch = [];
+for await (const record of recordStream) {
+  const result = await mapper.map(record);
+  if (result.success) {
+    batch.push(result.data);
+    // Send when batch reaches 1000
+    if (batch.length >= 1000) {
+      await client.sendBatch(job.id, {
+        action: 'UPSERT',
+        entityType: 'INVENTORY',
+        entities: batch,
+      });
+      batch = [];
+    }
+  }
+}
+// Send remaining records
+if (batch.length > 0) {
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    entities: batch,
+  });
+}
+```
+**Documentation:** [Performance Optimization](../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-08-performance-optimization.md)
+---
+## Still Stuck?
+1. **🔧 Debugging:** [`troubleshooting-quick-reference.md`](./troubleshooting-quick-reference.md) - Fix 90% of issues in 5 steps
+2. **Check Examples:** [`docs/01-TEMPLATES/`](../01-TEMPLATES/) - 30+ real-world scenarios
+3. **Read Philosophy:** [`sdk-philosophy.md`](./sdk-philosophy.md) - Understand the "why"
+4. **API Reference:** [`api-reference/`](../02-CORE-GUIDES/api-reference/) - Complete method documentation
+5. **Common Patterns:** [`patterns/`](../01-TEMPLATES/patterns/) - Reusable solutions
+---
+**[← Back to Getting Started](./getting-started.md)** | **[Troubleshooting →](./troubleshooting-quick-reference.md)** | **[API Reference →](../02-CORE-GUIDES/api-reference/api-reference-readme.md)**