@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/00-START-HERE/getting-started.md

@@ -1,1070 +1,1070 @@
-# Getting Started Guide
-
-Get up and running with the Fluent Commerce Connect SDK quickly and efficiently.
-
-## Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Quick Example](#quick-example)
-- [Common Use Cases](#common-use-cases)
-- [Platform-Specific Setup](#platform-specific-setup)
-- [Error Handling](#error-handling)
-- [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
-
-## Prerequisites
-
-Before installing the Fluent Commerce Connect SDK, ensure you have:
-
-- **Node.js** >= 18.0.0
-- **npm** >= 8.0.0 or **yarn** >= 1.22.0
-- **TypeScript** >= 5.0.0 (for TypeScript projects)
-- **Fluent Commerce Account** with API credentials
-- **AWS Credentials** (if using S3 operations)
-
-## Installation
-
-### Using NPM
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk
-```
-
-### Using Yarn
-
-```bash
-yarn add @fluentcommerce/fc-connect-sdk
-```
-
-### Using PNPM
-
-```bash
-pnpm add @fluentcommerce/fc-connect-sdk
-```
-
-### Version Information
-
-```bash
-# Check latest version
-npm view @fluentcommerce/fc-connect-sdk version
-
-# View all available versions
-npm view @fluentcommerce/fc-connect-sdk versions
-```
-
-### Module Formats
-
-The SDK is distributed in multiple formats:
-
-- **CommonJS** (CJS) - For Node.js applications using `require()`
-- **ES Modules** (ESM) - For modern JavaScript/TypeScript applications using `import`
-- **TypeScript Definitions** - Full type definitions included
-
-### Importing from the SDK
-
-**⚠️ IMPORTANT: Always import from the main entry point**
-
-The SDK exports all public APIs from the main entry point. Do NOT use subpath imports.
-
-```typescript
-// ✅ CORRECT - Import from main entry
-import {
-  createClient,
-  FluentClient,
-  FluentVersoriClient,
-  FluentBatchManager,
-  UniversalMapper,
-  VersoriKVAdapter,
-  S3DataSource,
-  SftpDataSource,
-  CSVParserService,
-  XMLParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// ❌ WRONG - Subpath imports are NOT supported
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk/versori';
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk/data-sources';
-```
-
-**Why main entry only?**
-
-- ✅ Simpler and more maintainable
-- ✅ Standard npm package pattern
-- ✅ Better tree-shaking
-- ✅ Consistent with most npm packages (React, Lodash, etc.)
-- ✅ All public APIs are intentionally exported
-
-**All Available Exports:**
-
-- Clients: `createClient`, `FluentClient`, `FluentVersoriClient`
-- Services: `FluentBatchManager`, `UniversalMapper`, `StateService`
-- Orchestrators: `ExtractionOrchestrator`, `JobTracker`, `PartialBatchRecovery`, `PreflightValidator`
-- Data Sources: `S3DataSource`, `SftpDataSource`, `InventoryDataSource`
-- Parsers: `CSVParserService`, `XMLParserService`, `JSONParserService`, `ParquetParserService`
-- Builders: `XMLBuilder`, `CSVBuilder`, `JSONBuilder`
-- Logging Utilities: `createConsoleLogger`, `toStructuredLogger`, `createWorkflowLogger`, `createServiceLogger`
-- Versori: `VersoriKVAdapter`, `VersoriFileTracker`
-- Testing: `S3SDKTester`, `S3PresignedTester`, `FluentConnectionTester`
-- Utilities: `parseWebhookRequest`, `validateFluentEvent`, `validateGraphQLPayload`, and file naming utilities
-- All TypeScript types and interfaces
-
-See [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) for complete list of exports.
-
-### TypeScript Configuration
-
-Add to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
-
-## Logging Approach
-
-The SDK provides minimal logging utilities for standalone environments. **Versori users should always use native platform logs.**
-
-### Versori Platform (Recommended)
-
-Use native `log` from context - no imports needed:
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const myWorkflow = schedule('my-workflow', '0 * * * *')
-  .then(http('process', { connection: 'fluent' }, async (ctx) => {
-    const { log, openKv, activation } = ctx;
-
-    // Pass native log directly to SDK services
-    const client = await createClient({ ...ctx, log });
-    const sftp = new SftpDataSource(config, log);
-
-    log.info('Processing started');
-  }));
-```
-
-### Standalone Node.js/Deno
-
-Use function-based logging utilities:
-
-```typescript
-import {
-  createConsoleLogger,
-  toStructuredLogger,
-  generateCorrelationId,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Simple console logger
-const logger = createConsoleLogger();
-
-// Or with context (adds metadata to all logs)
-const contextLogger = toStructuredLogger(logger, {
-  service: 'InventorySync',
-  correlationId: generateCorrelationId(),
-  logLevel: 'debug',
-});
-
-const client = await createClient({ config: { ...config, logger: contextLogger } });
-```
-
-**See**: [Logging Guide](../02-CORE-GUIDES/logging-guide.md) for complete logging documentation.
-
-## Configuration
-
-### Environment Variables
-
-Create a `.env` file in your project root:
-
-```bash
-# Fluent Commerce Configuration
-FLUENT_BASE_URL=https://api.fluentcommerce.com
-FLUENT_RETAILER_ID=your-retailer-id
-FLUENT_CLIENT_ID=your-client-id
-FLUENT_CLIENT_SECRET=your-client-secret
-FLUENT_USERNAME=your-username
-FLUENT_PASSWORD=your-password
-
-# AWS Configuration (for S3 operations)
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
-AWS_REGION=us-east-1
-
-# SFTP Configuration (for SFTP operations)
-SFTP_HOST=sftp.yourcompany.com
-SFTP_PORT=22
-SFTP_USERNAME=your-sftp-username
-SFTP_PASSWORD=your-sftp-password
-# Alternative: Use private key authentication
-# SFTP_PRIVATE_KEY=/path/to/private/key
-# SFTP_PASSPHRASE=key-passphrase
-
-# Target AWS Configuration (for extraction)
-TARGET_AWS_ACCESS_KEY_ID=target-access-key
-TARGET_AWS_SECRET_ACCESS_KEY=target-secret-key
-TARGET_AWS_REGION=us-west-2
-
-# Webhook Validation (Fluent Commerce Rubix workflows only)
-FLUENT_WEBHOOK_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-
-# Optional: Processing Configuration
-FLUENT_TIMEOUT=30000
-FLUENT_RETRY_ATTEMPTS=3
-FLUENT_RETRY_DELAY=1000
-```
-
-### Client Configuration Options
-
-```typescript
-interface FluentConfig {
-  // Required
-  baseUrl: string; // Fluent Commerce API endpoint
-
-  // Optional - only required for Job/Event APIs (NOT for GraphQL queries)
-  retailerId?: string; // See retailerid-configuration.md for all options
-
-  // OAuth2 Client Credentials (always required)
-  clientId?: string; // OAuth2 client ID
-  clientSecret?: string; // OAuth2 client secret
-
-  // OAuth2 Password Grant (optional - for user-specific operations)
-  username?: string; // OAuth2 username
-  password?: string; // OAuth2 password
-
-  // Optional Settings
-  timeout?: number; // Request timeout (ms), default: 30000
-  retryAttempts?: number; // Number of retries, default: 3
-  retryDelay?: number; // Delay between retries (ms), default: 1000
-  
-  /**
-   * Retry configuration with sensible defaults
-   * Override specific values as needed for fine-grained control
-   */
-  retryConfig?: {
-    /** Maximum number of retry attempts for general requests (default: 3) */
-    maxRetries?: number;
-    /** Maximum number of retry attempts for authentication failures (default: 3) */
-    maxAuthRetries?: number;
-    /** Base delay in milliseconds before first retry (default: 1000) */
-    baseRetryDelayMs?: number;
-    /** Maximum delay in milliseconds for general retries (default: 10000) */
-    maxRetryDelayMs?: number;
-    /** Maximum delay in milliseconds for authentication retries (default: 5000) */
-    maxAuthRetryDelayMs?: number;
-    /** Token expiry buffer in seconds (default: 60) */
-    tokenExpiryBufferSeconds?: number;
-  };
-
-  // Optional Advanced
-  headers?: Record<string, string>; // Custom headers
-  proxy?: ProxyConfig; // Proxy configuration
-}
-```
-
-### Configuration Methods
-
-#### 1. Direct Configuration
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-    // retailerId optional - only needed for Job/Event APIs
-    // retailerId: 'your-retailer-id',
-    username: 'your-username', // For password grant (optional)
-    password: 'your-password', // For password grant (optional)
-    timeout: 60000,
-    retryAttempts: 5, // Simple retry configuration
-    // Or use retryConfig for fine-grained control:
-    retryConfig: {
-      maxRetries: 5,
-      baseRetryDelayMs: 2000,
-      tokenExpiryBufferSeconds: 120,
-    },
-  },
-});
-```
-
-#### 2. Using Environment Variables
-
-```typescript
-import dotenv from 'dotenv';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-dotenv.config();
-
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    username: process.env.FLUENT_USERNAME!,
-    password: process.env.FLUENT_PASSWORD!,
-    // retailerId optional - only for Job/Event APIs
-    // retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-});
-```
-
-#### 3. Configuration File
-
-Create `config.json`:
-
-```json
-{
-  "fluent": {
-    "baseUrl": "https://api.fluentcommerce.com",
-    "retailerId": "your-retailer-id",
-    "timeout": 30000,
-    "retryAttempts": 3
-  },
-  "aws": {
-    "region": "us-east-1"
-  },
-  "processing": {
-    "batchSize": 1000,
-    "parallelJobs": 5
-  }
-}
-```
-
-Load configuration:
-
-```typescript
-import config from './config.json';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({ config: config.fluent });
-```
-
-## Quick Example
-
-### 1. Initialize the Client
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-  },
-});
-
-// Set retailer ID when needed for Job/Batch operations
-client.setRetailerId('your-retailer-id');
-```
-
-### 2. Execute a GraphQL Query
-
-#### Single Page Query (Without Pagination Variables)
-
-```typescript
-// Query without pagination variables - returns ONE page only
-// Note: InventoryPosition uses 'onHand' field (VirtualPosition uses 'quantity')
-const query = `
-  query GetInventoryPositions {
-    inventoryPositions(first: 10) {
-      edges {
-        node {
-          ref
-          productRef
-          locationRef
-          onHand
-          status
-        }
-      }
-    }
-  }
-`;
-
-const result = await client.graphql({ query });
-console.log('Inventory positions:', result.data.inventoryPositions);
-```
-
-#### Understanding Auto-Pagination
-
-> **Auto-Pagination**: `client.graphql()` automatically fetches all pages when pagination variables are present. Disable with `pagination: { enabled: false }`.
-
-```typescript
-// Auto-pagination when pagination variables are present
-const result = await client.graphql({
-  query: `
-    query GetAllInventory($first: Int!, $after: String) {
-      inventoryPositions(first: $first, after: $after) {
-        edges { cursor node { ref productRef locationRef qty status } }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: { maxPages: 50 },
-});
-const allInventory = result.data?.inventoryPositions?.edges?.map(e => e.node) || [];
-console.log(`Fetched ${allInventory.length} total inventory positions`);
-```
-
-**See**: [Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md) for complete documentation.
-
-### 3. Send a Batch Update
-
-```typescript
-import { BatchAction, EntityType } from '@fluentcommerce/fc-connect-sdk';
-
-// Create a job (retailerId required for Job API)
-const job = await client.createJob({
-  name: 'Inventory Update',
-  retailerId: 'your-retailer-id', // Required for createJob()
-});
-
-// Send batch data
-const batchResult = await client.sendBatch(job.id, {
-  action: BatchAction.UPSERT,
-  entityType: EntityType.INVENTORY,
-  entities: [
-    {
-      ref: 'SKU001',
-      productRef: 'PROD001',
-      locationRef: 'LOC001',
-      qty: 100,
-      status: 'AVAILABLE',
-    },
-    {
-      ref: 'SKU002',
-      productRef: 'PROD002',
-      locationRef: 'LOC001',
-      qty: 50,
-      status: 'AVAILABLE',
-    },
-  ],
-});
-
-console.log('Batch sent:', batchResult);
-```
-
-## Common Use Cases
-
-### Inventory Ingestion from CSV
-
-```typescript
-import {
-  createClient,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-  BatchAction,
-  EntityType,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function ingestInventoryFromCSV() {
-  const logger = toStructuredLogger(createConsoleLogger(), {
-    logLevel: 'info',
-  });
-
-  // Initialize client
-  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!,
-    },
-  });
-
-  // Configure data source
-  const s3Source = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      s3Config: {
-        bucket: 'my-inventory-bucket',
-        region: 'us-east-1',
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      },
-    },
-    logger
-  );
-
-  // Read CSV file
-  const csvData = await s3Source.downloadFile('inventory/products.csv');
-
-  // Parse CSV
-  const parser = new CSVParserService({ delimiter: ',', headers: true });
-  const records = await parser.parse(csvData);
-
-  // Map fields with UniversalMapper
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: { source: 'sku', required: true },
-      productRef: { source: 'product_id', required: true },
-      locationRef: { source: 'location_code', required: true },
-      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-      status: { source: 'status', resolver: 'sdk.uppercase' },
-    },
-  });
-
-  const mappedData: any[] = [];
-  for (const record of records) {
-    const result = await mapper.map(record);
-    if (result.success) {
-      mappedData.push(result.data);
-    } else {
-      logger.warn('Mapping failed', { record, errors: result.errors });
-    }
-  }
-
-  // Send to Fluent
-  const job = await client.createJob({
-    name: 'CSV Inventory Import',
-    retailerId: client.getRetailerId(),
-  });
-
-  await client.sendBatch(job.id, {
-    action: BatchAction.UPSERT,
-    entityType: EntityType.INVENTORY,
-    entities: mappedData,
-  });
-
-  logger.info('Ingestion complete', { count: mappedData.length });
-}
-```
-
-### Data Extraction to S3 (High-Level)
-
-```typescript
-import {
-  createClient,
-  ExtractionOrchestrator,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function extractInventoryToS3() {
-  const logger = toStructuredLogger(createConsoleLogger(), {
-    logLevel: 'info',
-  });
-
-  // Initialize client
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    },
-  });
-
-  // Extract with ExtractionOrchestrator (handles pagination + export)
-  const orchestrator = new ExtractionOrchestrator(client, logger);
-
-  const result = await orchestrator.extract({
-    query: `
-      query GetInventory($first: Int!, $after: String) {
-        inventoryPositions(first: $first, after: $after) {
-          edges {
-            node {
-              ref
-              productRef
-              locationRef
-              onHand
-              status
-              updatedOn
-            }
-            cursor
-          }
-          pageInfo {
-            hasNextPage
-            # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-          }
-        }
-      }
-    `,
-    resultPath: 'inventoryPositions.edges.node', // Path to nodes for extraction
-    pageSize: 100,
-    maxRecords: 10000,
-    maxPages: 100,
-    direction: 'forward',
-    onProgress: (stats) => {
-      logger.info('Extraction progress', {
-        pagesProcessed: stats.pagesProcessed,
-        recordCount: stats.recordCount,
-      });
-    },
-  });
-
-  logger.info('Extraction complete', {
-    recordCount: result.stats.recordCount,
-    pagesProcessed: result.stats.pagesProcessed,
-  });
-}
-```
-
-### Data Extraction to S3 (Manual Composition)
-
-For more control, you can manually compose SDK services:
-
-```typescript
-import {
-  createClient,
-  S3DataSource,
-  UniversalMapper,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function extractInventoryManual() {
-  const logger = toStructuredLogger(createConsoleLogger(), {
-    logLevel: 'info',
-  });
-
-  // Initialize client
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    },
-  });
-
-  // Query inventory with auto-pagination
-  const result = await client.graphql({
-    query: `
-      query GetInventory($first: Int!, $after: String) {
-        inventoryPositions(first: $first, after: $after) {
-          edges {
-            node {
-              ref
-              productRef
-              locationRef
-              onHand
-              status
-              updatedOn
-            }
-            cursor
-          }
-          pageInfo {
-            hasNextPage
-            # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-          }
-        }
-      }
-    `,
-    variables: { first: 100 },
-    pagination: { maxRecords: 10000 },
-  });
-
-  const inventory = result.data?.inventoryPositions?.edges?.map(e => e.node) || [];
-
-  // Transform for export
-  const mapper = new UniversalMapper({
-    fields: {
-      sku: { source: 'ref', resolver: 'sdk.toString' },
-      product_id: { source: 'productRef', resolver: 'sdk.toString' },
-      location: { source: 'locationRef', resolver: 'sdk.toString' },
-      quantity: { source: 'onHand', resolver: 'sdk.parseInt' },
-      status: { source: 'status', resolver: 'sdk.lowercase' },
-      last_updated: { source: 'updatedOn', resolver: 'sdk.formatDate' },
-    },
-  });
-
-  const transformed: any[] = [];
-  for (const item of inventory) {
-    const result = await mapper.map(item);
-    if (result.success) {
-      transformed.push(result.data);
-    }
-  }
-
-  // Upload to S3
-  const s3Target = new S3DataSource(
-    {
-      type: 'S3_JSON',
-      connectionId: 's3-target',
-      name: 'Export S3',
-      s3Config: {
-        bucket: 'my-export-bucket',
-        region: 'us-west-2',
-        accessKeyId: process.env.TARGET_AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.TARGET_AWS_SECRET_ACCESS_KEY!,
-      },
-    },
-    logger
-  );
-
-  await s3Target.uploadFile('exports/inventory-export.json', JSON.stringify(transformed, null, 2), {
-    contentType: 'application/json',
-  });
-
-  logger.info('Extraction complete', { count: transformed.length });
-}
-```
-
-### Backward Pagination (Reverse Order)
-
-Fetch records in reverse chronological order (from end to start):
-
-```typescript
-import { ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
-
-const orchestrator = new ExtractionOrchestrator(client, logger);
-
-const result = await orchestrator.extract({
-  query: `
-    query GetRecentOrders($last: Int!, $before: String) {
-      orders(last: $last, before: $before) {
-        edges {
-          node { id ref status createdOn }
-          cursor
-        }
-        pageInfo { hasPreviousPage }
-      }
-    }
-  `,
-  resultPath: 'orders.edges.node',
-  variables: { last: 100 },
-  direction: 'backward', // Fetch from end to start
-  maxRecords: 1000,
-});
-
-console.log(`Extracted ${result.stats.totalRecords} orders`);
-```
-
-**When to use backward pagination:**
-
-- Fetching most recent records (latest orders, recent events)
-- Reverse chronological feeds
-- "Show last N items" scenarios
-
-### Processing with State Management
-
-```typescript
-import {
-  createClient,
-  S3DataSource,
-  StateService,
-  VersoriKVAdapter,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processFilesWithStateTracking(context) {
-  const logger = toStructuredLogger(createConsoleLogger(), {
-    logLevel: 'info',
-  });
-
-  // Initialize state service (Versori example)
-  const kvAdapter = new VersoriKVAdapter(context.openKv(':project:'));
-  const stateService = new StateService(kvAdapter);
-
-  // Initialize S3
-  const s3 = new S3DataSource(s3Config, logger);
-
-  // List files
-  const files = await s3.listFiles({ prefix: 'inbox/' });
-
-  for (const file of files) {
-    // Check if already processed
-    if (await stateService.isFileProcessed(file.path)) {
-      logger.info('File already processed', { file: file.name });
-      continue;
-    }
-
-    try {
-      // Process file
-      const content = await s3.downloadFile(file.path);
-      await processFileContent(content);
-
-      // Mark as processed
-      await stateService.markFileProcessed(file.path, {
-        processedAt: new Date().toISOString(),
-        size: file.size,
-      });
-
-      logger.info('File processed successfully', { file: file.name });
-    } catch (error) {
-      logger.error('Failed to process file', error as Error, { file: file.name });
-      throw error;
-    }
-  }
-}
-```
-
-## Platform-Specific Setup
-
-### Node.js Applications
-
-No additional configuration needed. The SDK works out of the box with Node.js 18+.
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function main() {
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    },
-  });
-
-  // Use client...
-}
-```
-
-### Versori Platform
-
-For Versori platform applications, the SDK automatically detects and uses the Versori context:
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const handler = http(
-  'handler',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    // Auto-detects Versori context
-    const client = await createClient(ctx);
-
-    // Use the same API
-    const result = await client.graphql({
-      query: `query { locations { edges { node { id ref } } } }`,
-    });
-
-    return {
-      statusCode: 200,
-      body: JSON.stringify(result),
-    };
-  }
-);
-```
-
-**See**: [Versori Platform Guide](../04-REFERENCE/platforms/versori/) for complete Versori documentation.
-
-### Deno Support
-
-The SDK is compatible with Deno runtime. See the [Deno Platform Guide](../04-REFERENCE/platforms/deno/) for details.
-
-## Error Handling
-
-```typescript
-import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await client.sendBatch(jobId, batchData);
-} catch (error) {
-  if (error instanceof IngestionError) {
-    console.error('Ingestion failed:', {
-      code: error.code,
-      message: error.message,
-      context: error.context,
-    });
-
-    // Handle specific errors
-    switch (error.code) {
-      case IngestionErrorCode.VALIDATION_ERROR:
-        // Handle validation errors
-        await logValidationError(error.context);
-        break;
-
-      case IngestionErrorCode.RATE_LIMIT_ERROR:
-        // Retry with exponential backoff
-        await retryWithBackoff(() => client.sendBatch(jobId, batchData));
-        break;
-
-      case IngestionErrorCode.JOB_CREATION_ERROR:
-        // Create new job and retry
-        const newJob = await client.createJob({
-          name: 'Retry Job',
-          retailerId: client.getRetailerId(),
-        });
-        await client.sendBatch(newJob.id, batchData);
-        break;
-
-      case IngestionErrorCode.NETWORK_ERROR:
-        // Check network and retry
-        await checkNetworkConnectivity();
-        break;
-    }
-  } else {
-    // Handle unexpected errors
-    console.error('Unexpected error:', error);
-    throw error;
-  }
-}
-```
-
-**See**: [Error Handling Guide](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) for comprehensive error handling patterns.
-
-## Best Practices
-
-### 1. Security
-
-- **Store credentials securely** using environment variables or secret managers
-- **Never commit credentials** to version control
-- **Validate webhook signatures** (for Fluent Rubix webhooks only)
-- **Use least privilege** AWS IAM policies
-
-### 2. Performance
-
-- **Use streaming parsers** for large files to minimize memory usage
-- **Batch operations** to reduce API calls
-- **Use auto-pagination** for large result sets - See [Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
-- **Configure appropriate timeouts** based on operation types
-
-### 3. Reliability
-
-- **Implement retry logic** with exponential backoff for transient failures
-- **Track processing state** to prevent duplicate processing
-- **Use distributed locking** for concurrent workflows
-- **Monitor job status** and handle failures gracefully
-
-### 4. Data Quality
-
-- **Validate data** before sending to Fluent
-- **Use UniversalMapper** for consistent field transformations
-- **Handle missing data** with default values
-- **Log transformation errors** for debugging
-
-### 5. Monitoring
-
-- **Log all operations** with structured logging
-- **Track metrics** like processing time and record counts
-- **Set up alerts** for failures and anomalies
-- **Monitor API rate limits** and adjust accordingly
-
-## Troubleshooting
-
-### Common Installation Issues
-
-#### Module Resolution Errors
-
-```bash
-npm cache clean --force
-rm -rf node_modules package-lock.json
-npm install
-```
-
-#### TypeScript Errors
-
-- Ensure TypeScript version is >= 5.0.0
-- Add `"skipLibCheck": true` to tsconfig.json
-- Check for type definition conflicts
-
-#### Version Conflicts
-
-```bash
-# Check installed version
-npm ls @fluentcommerce/fc-connect-sdk
-
-# Update to latest
-npm update @fluentcommerce/fc-connect-sdk
-```
-
-### Runtime Issues
-
-#### Authentication Failures
-
-- Verify API credentials are correct
-- Check base URL matches your environment
-- Ensure retailer ID is valid (for Job/Batch operations)
-
-#### Network Timeouts
-
-- Increase timeout configuration
-- Check network connectivity
-- Verify firewall rules
-
-#### Memory Issues
-
-- Use streaming for large files
-- Process data in chunks
-- Monitor memory usage
-
-### Debugging Tips
-
-```typescript
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-
-// Use structured logging
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: 'debug',
-});
-
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    timeout: 60000,
-    retryAttempts: 3,
-  },
-});
-
-// Log GraphQL operations
-const query = `query { products { edges { node { ref } } } }`;
-logger.debug('Executing GraphQL query', { query });
-const result = await client.graphql({ query });
-logger.debug('Query result', {
-  recordCount: result.data?.products?.edges?.length,
-});
-
-// Log batch operations
-logger.info('Sending batch', {
-  jobId,
-  recordCount: batchData.entities.length,
-});
-await client.sendBatch(jobId, batchData);
-logger.info('Batch sent successfully');
-```
-
-## Next Steps
-
-Now that you're set up, explore:
-
-- **[API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete API documentation
-- **[Universal Mapping Guide](../02-CORE-GUIDES/mapping/mapping-readme.md)** - Field mapping and transformations
-- **[Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)** - Automatic GraphQL pagination
-- **[Ingestion Guide](../02-CORE-GUIDES/ingestion/)** - Inventory ingestion workflows
-- **[Extraction Guide](../02-CORE-GUIDES/extraction/)** - Data extraction patterns
-- **[Use Cases](../01-TEMPLATES/readme.md)** - Real-world examples and patterns
-
-## CLI Tools
-
-The SDK provides command-line tools for working with GraphQL schemas and mappings:
-
-```bash
-# Show available commands
-npx fc-connect help
-
-# Check SDK version
-npx fc-connect version
-
-# Generate mutation mapping template
-npx fc-connect generate-mutation-mapping \
-  --file ./mutations/createOrder.graphql \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --output ./mappings/createOrder.json
-
-# Introspect and cache schema
-npx fc-connect introspect-schema \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --output ./schema/fluent-schema.json
-```
-
-**See**: [API Reference - CLI Tools](../02-CORE-GUIDES/api-reference/modules/api-reference-11-cli-tools.md) for complete CLI documentation.
+# Getting Started Guide
+
+Get up and running with the Fluent Commerce Connect SDK quickly and efficiently.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Example](#quick-example)
+- [Common Use Cases](#common-use-cases)
+- [Platform-Specific Setup](#platform-specific-setup)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+Before installing the Fluent Commerce Connect SDK, ensure you have:
+
+- **Node.js** >= 18.0.0
+- **npm** >= 8.0.0 or **yarn** >= 1.22.0
+- **TypeScript** >= 5.0.0 (for TypeScript projects)
+- **Fluent Commerce Account** with API credentials
+- **AWS Credentials** (if using S3 operations)
+
+## Installation
+
+### Using NPM
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk
+```
+
+### Using Yarn
+
+```bash
+yarn add @fluentcommerce/fc-connect-sdk
+```
+
+### Using PNPM
+
+```bash
+pnpm add @fluentcommerce/fc-connect-sdk
+```
+
+### Version Information
+
+```bash
+# Check latest version
+npm view @fluentcommerce/fc-connect-sdk version
+
+# View all available versions
+npm view @fluentcommerce/fc-connect-sdk versions
+```
+
+### Module Formats
+
+The SDK is distributed in multiple formats:
+
+- **CommonJS** (CJS) - For Node.js applications using `require()`
+- **ES Modules** (ESM) - For modern JavaScript/TypeScript applications using `import`
+- **TypeScript Definitions** - Full type definitions included
+
+### Importing from the SDK
+
+**⚠️ IMPORTANT: Always import from the main entry point**
+
+The SDK exports all public APIs from the main entry point. Do NOT use subpath imports.
+
+```typescript
+// ✅ CORRECT - Import from main entry
+import {
+  createClient,
+  FluentClient,
+  FluentVersoriClient,
+  FluentBatchManager,
+  UniversalMapper,
+  VersoriKVAdapter,
+  S3DataSource,
+  SftpDataSource,
+  CSVParserService,
+  XMLParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// ❌ WRONG - Subpath imports are NOT supported
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk/versori';
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk/data-sources';
+```
+
+**Why main entry only?**
+
+- ✅ Simpler and more maintainable
+- ✅ Standard npm package pattern
+- ✅ Better tree-shaking
+- ✅ Consistent with most npm packages (React, Lodash, etc.)
+- ✅ All public APIs are intentionally exported
+
+**All Available Exports:**
+
+- Clients: `createClient`, `FluentClient`, `FluentVersoriClient`
+- Services: `FluentBatchManager`, `UniversalMapper`, `StateService`
+- Orchestrators: `ExtractionOrchestrator`, `JobTracker`, `PartialBatchRecovery`, `PreflightValidator`
+- Data Sources: `S3DataSource`, `SftpDataSource`, `InventoryDataSource`
+- Parsers: `CSVParserService`, `XMLParserService`, `JSONParserService`, `ParquetParserService`
+- Builders: `XMLBuilder`, `CSVBuilder`, `JSONBuilder`
+- Logging Utilities: `createConsoleLogger`, `toStructuredLogger`, `createWorkflowLogger`, `createServiceLogger`
+- Versori: `VersoriKVAdapter`, `VersoriFileTracker`
+- Testing: `S3SDKTester`, `S3PresignedTester`, `FluentConnectionTester`
+- Utilities: `parseWebhookRequest`, `validateFluentEvent`, `validateGraphQLPayload`, and file naming utilities
+- All TypeScript types and interfaces
+
+See [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) for complete list of exports.
+
+### TypeScript Configuration
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Logging Approach
+
+The SDK provides minimal logging utilities for standalone environments. **Versori users should always use native platform logs.**
+
+### Versori Platform (Recommended)
+
+Use native `log` from context - no imports needed:
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const myWorkflow = schedule('my-workflow', '0 * * * *')
+  .then(http('process', { connection: 'fluent' }, async (ctx) => {
+    const { log, openKv, activation } = ctx;
+
+    // Pass native log directly to SDK services
+    const client = await createClient({ ...ctx, log });
+    const sftp = new SftpDataSource(config, log);
+
+    log.info('Processing started');
+  }));
+```
+
+### Standalone Node.js/Deno
+
+Use function-based logging utilities:
+
+```typescript
+import {
+  createConsoleLogger,
+  toStructuredLogger,
+  generateCorrelationId,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Simple console logger
+const logger = createConsoleLogger();
+
+// Or with context (adds metadata to all logs)
+const contextLogger = toStructuredLogger(logger, {
+  service: 'InventorySync',
+  correlationId: generateCorrelationId(),
+  logLevel: 'debug',
+});
+
+const client = await createClient({ config: { ...config, logger: contextLogger } });
+```
+
+**See**: [Logging Guide](../02-CORE-GUIDES/logging-guide.md) for complete logging documentation.
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Fluent Commerce Configuration
+FLUENT_BASE_URL=https://api.fluentcommerce.com
+FLUENT_RETAILER_ID=your-retailer-id
+FLUENT_CLIENT_ID=your-client-id
+FLUENT_CLIENT_SECRET=your-client-secret
+FLUENT_USERNAME=your-username
+FLUENT_PASSWORD=your-password
+
+# AWS Configuration (for S3 operations)
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_REGION=us-east-1
+
+# SFTP Configuration (for SFTP operations)
+SFTP_HOST=sftp.yourcompany.com
+SFTP_PORT=22
+SFTP_USERNAME=your-sftp-username
+SFTP_PASSWORD=your-sftp-password
+# Alternative: Use private key authentication
+# SFTP_PRIVATE_KEY=/path/to/private/key
+# SFTP_PASSPHRASE=key-passphrase
+
+# Target AWS Configuration (for extraction)
+TARGET_AWS_ACCESS_KEY_ID=target-access-key
+TARGET_AWS_SECRET_ACCESS_KEY=target-secret-key
+TARGET_AWS_REGION=us-west-2
+
+# Webhook Validation (Fluent Commerce Rubix workflows only)
+FLUENT_WEBHOOK_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+
+# Optional: Processing Configuration
+FLUENT_TIMEOUT=30000
+FLUENT_RETRY_ATTEMPTS=3
+FLUENT_RETRY_DELAY=1000
+```
+
+### Client Configuration Options
+
+```typescript
+interface FluentConfig {
+  // Required
+  baseUrl: string; // Fluent Commerce API endpoint
+
+  // Optional - only required for Job/Event APIs (NOT for GraphQL queries)
+  retailerId?: string; // See retailerid-configuration.md for all options
+
+  // OAuth2 Client Credentials (always required)
+  clientId?: string; // OAuth2 client ID
+  clientSecret?: string; // OAuth2 client secret
+
+  // OAuth2 Password Grant (optional - for user-specific operations)
+  username?: string; // OAuth2 username
+  password?: string; // OAuth2 password
+
+  // Optional Settings
+  timeout?: number; // Request timeout (ms), default: 30000
+  retryAttempts?: number; // Number of retries, default: 3
+  retryDelay?: number; // Delay between retries (ms), default: 1000
+  
+  /**
+   * Retry configuration with sensible defaults
+   * Override specific values as needed for fine-grained control
+   */
+  retryConfig?: {
+    /** Maximum number of retry attempts for general requests (default: 3) */
+    maxRetries?: number;
+    /** Maximum number of retry attempts for authentication failures (default: 3) */
+    maxAuthRetries?: number;
+    /** Base delay in milliseconds before first retry (default: 1000) */
+    baseRetryDelayMs?: number;
+    /** Maximum delay in milliseconds for general retries (default: 10000) */
+    maxRetryDelayMs?: number;
+    /** Maximum delay in milliseconds for authentication retries (default: 5000) */
+    maxAuthRetryDelayMs?: number;
+    /** Token expiry buffer in seconds (default: 60) */
+    tokenExpiryBufferSeconds?: number;
+  };
+
+  // Optional Advanced
+  headers?: Record<string, string>; // Custom headers
+  proxy?: ProxyConfig; // Proxy configuration
+}
+```
+
+### Configuration Methods
+
+#### 1. Direct Configuration
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    // retailerId optional - only needed for Job/Event APIs
+    // retailerId: 'your-retailer-id',
+    username: 'your-username', // For password grant (optional)
+    password: 'your-password', // For password grant (optional)
+    timeout: 60000,
+    retryAttempts: 5, // Simple retry configuration
+    // Or use retryConfig for fine-grained control:
+    retryConfig: {
+      maxRetries: 5,
+      baseRetryDelayMs: 2000,
+      tokenExpiryBufferSeconds: 120,
+    },
+  },
+});
+```
+
+#### 2. Using Environment Variables
+
+```typescript
+import dotenv from 'dotenv';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+dotenv.config();
+
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    username: process.env.FLUENT_USERNAME!,
+    password: process.env.FLUENT_PASSWORD!,
+    // retailerId optional - only for Job/Event APIs
+    // retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+});
+```
+
+#### 3. Configuration File
+
+Create `config.json`:
+
+```json
+{
+  "fluent": {
+    "baseUrl": "https://api.fluentcommerce.com",
+    "retailerId": "your-retailer-id",
+    "timeout": 30000,
+    "retryAttempts": 3
+  },
+  "aws": {
+    "region": "us-east-1"
+  },
+  "processing": {
+    "batchSize": 1000,
+    "parallelJobs": 5
+  }
+}
+```
+
+Load configuration:
+
+```typescript
+import config from './config.json';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({ config: config.fluent });
+```
+
+## Quick Example
+
+### 1. Initialize the Client
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+  },
+});
+
+// Set retailer ID when needed for Job/Batch operations
+client.setRetailerId('your-retailer-id');
+```
+
+### 2. Execute a GraphQL Query
+
+#### Single Page Query (Without Pagination Variables)
+
+```typescript
+// Query without pagination variables - returns ONE page only
+// Note: InventoryPosition uses 'onHand' field (VirtualPosition uses 'quantity')
+const query = `
+  query GetInventoryPositions {
+    inventoryPositions(first: 10) {
+      edges {
+        node {
+          ref
+          productRef
+          locationRef
+          onHand
+          status
+        }
+      }
+    }
+  }
+`;
+
+const result = await client.graphql({ query });
+console.log('Inventory positions:', result.data.inventoryPositions);
+```
+
+#### Understanding Auto-Pagination
+
+> **Auto-Pagination**: `client.graphql()` automatically fetches all pages when pagination variables are present. Disable with `pagination: { enabled: false }`.
+
+```typescript
+// Auto-pagination when pagination variables are present
+const result = await client.graphql({
+  query: `
+    query GetAllInventory($first: Int!, $after: String) {
+      inventoryPositions(first: $first, after: $after) {
+        edges { cursor node { ref productRef locationRef qty status } }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: { maxPages: 50 },
+});
+const allInventory = result.data?.inventoryPositions?.edges?.map(e => e.node) || [];
+console.log(`Fetched ${allInventory.length} total inventory positions`);
+```
+
+**See**: [Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md) for complete documentation.
+
+### 3. Send a Batch Update
+
+```typescript
+import { BatchAction, EntityType } from '@fluentcommerce/fc-connect-sdk';
+
+// Create a job (retailerId required for Job API)
+const job = await client.createJob({
+  name: 'Inventory Update',
+  retailerId: 'your-retailer-id', // Required for createJob()
+});
+
+// Send batch data
+const batchResult = await client.sendBatch(job.id, {
+  action: BatchAction.UPSERT,
+  entityType: EntityType.INVENTORY,
+  entities: [
+    {
+      ref: 'SKU001',
+      productRef: 'PROD001',
+      locationRef: 'LOC001',
+      qty: 100,
+      status: 'AVAILABLE',
+    },
+    {
+      ref: 'SKU002',
+      productRef: 'PROD002',
+      locationRef: 'LOC001',
+      qty: 50,
+      status: 'AVAILABLE',
+    },
+  ],
+});
+
+console.log('Batch sent:', batchResult);
+```
+
+## Common Use Cases
+
+### Inventory Ingestion from CSV
+
+```typescript
+import {
+  createClient,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+  BatchAction,
+  EntityType,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function ingestInventoryFromCSV() {
+  const logger = toStructuredLogger(createConsoleLogger(), {
+    logLevel: 'info',
+  });
+
+  // Initialize client
+  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!,
+    },
+  });
+
+  // Configure data source
+  const s3Source = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      s3Config: {
+        bucket: 'my-inventory-bucket',
+        region: 'us-east-1',
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      },
+    },
+    logger
+  );
+
+  // Read CSV file
+  const csvData = await s3Source.downloadFile('inventory/products.csv');
+
+  // Parse CSV
+  const parser = new CSVParserService({ delimiter: ',', headers: true });
+  const records = await parser.parse(csvData);
+
+  // Map fields with UniversalMapper
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: { source: 'sku', required: true },
+      productRef: { source: 'product_id', required: true },
+      locationRef: { source: 'location_code', required: true },
+      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+      status: { source: 'status', resolver: 'sdk.uppercase' },
+    },
+  });
+
+  const mappedData: any[] = [];
+  for (const record of records) {
+    const result = await mapper.map(record);
+    if (result.success) {
+      mappedData.push(result.data);
+    } else {
+      logger.warn('Mapping failed', { record, errors: result.errors });
+    }
+  }
+
+  // Send to Fluent
+  const job = await client.createJob({
+    name: 'CSV Inventory Import',
+    retailerId: client.getRetailerId(),
+  });
+
+  await client.sendBatch(job.id, {
+    action: BatchAction.UPSERT,
+    entityType: EntityType.INVENTORY,
+    entities: mappedData,
+  });
+
+  logger.info('Ingestion complete', { count: mappedData.length });
+}
+```
+
+### Data Extraction to S3 (High-Level)
+
+```typescript
+import {
+  createClient,
+  ExtractionOrchestrator,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function extractInventoryToS3() {
+  const logger = toStructuredLogger(createConsoleLogger(), {
+    logLevel: 'info',
+  });
+
+  // Initialize client
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    },
+  });
+
+  // Extract with ExtractionOrchestrator (handles pagination + export)
+  const orchestrator = new ExtractionOrchestrator(client, logger);
+
+  const result = await orchestrator.extract({
+    query: `
+      query GetInventory($first: Int!, $after: String) {
+        inventoryPositions(first: $first, after: $after) {
+          edges {
+            node {
+              ref
+              productRef
+              locationRef
+              onHand
+              status
+              updatedOn
+            }
+            cursor
+          }
+          pageInfo {
+            hasNextPage
+            # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+          }
+        }
+      }
+    `,
+    resultPath: 'inventoryPositions.edges.node', // Path to nodes for extraction
+    pageSize: 100,
+    maxRecords: 10000,
+    maxPages: 100,
+    direction: 'forward',
+    onProgress: (stats) => {
+      logger.info('Extraction progress', {
+        pagesProcessed: stats.pagesProcessed,
+        recordCount: stats.recordCount,
+      });
+    },
+  });
+
+  logger.info('Extraction complete', {
+    recordCount: result.stats.recordCount,
+    pagesProcessed: result.stats.pagesProcessed,
+  });
+}
+```
+
+### Data Extraction to S3 (Manual Composition)
+
+For more control, you can manually compose SDK services:
+
+```typescript
+import {
+  createClient,
+  S3DataSource,
+  UniversalMapper,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function extractInventoryManual() {
+  const logger = toStructuredLogger(createConsoleLogger(), {
+    logLevel: 'info',
+  });
+
+  // Initialize client
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    },
+  });
+
+  // Query inventory with auto-pagination
+  const result = await client.graphql({
+    query: `
+      query GetInventory($first: Int!, $after: String) {
+        inventoryPositions(first: $first, after: $after) {
+          edges {
+            node {
+              ref
+              productRef
+              locationRef
+              onHand
+              status
+              updatedOn
+            }
+            cursor
+          }
+          pageInfo {
+            hasNextPage
+            # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+          }
+        }
+      }
+    `,
+    variables: { first: 100 },
+    pagination: { maxRecords: 10000 },
+  });
+
+  const inventory = result.data?.inventoryPositions?.edges?.map(e => e.node) || [];
+
+  // Transform for export
+  const mapper = new UniversalMapper({
+    fields: {
+      sku: { source: 'ref', resolver: 'sdk.toString' },
+      product_id: { source: 'productRef', resolver: 'sdk.toString' },
+      location: { source: 'locationRef', resolver: 'sdk.toString' },
+      quantity: { source: 'onHand', resolver: 'sdk.parseInt' },
+      status: { source: 'status', resolver: 'sdk.lowercase' },
+      last_updated: { source: 'updatedOn', resolver: 'sdk.formatDate' },
+    },
+  });
+
+  const transformed: any[] = [];
+  for (const item of inventory) {
+    const result = await mapper.map(item);
+    if (result.success) {
+      transformed.push(result.data);
+    }
+  }
+
+  // Upload to S3
+  const s3Target = new S3DataSource(
+    {
+      type: 'S3_JSON',
+      connectionId: 's3-target',
+      name: 'Export S3',
+      s3Config: {
+        bucket: 'my-export-bucket',
+        region: 'us-west-2',
+        accessKeyId: process.env.TARGET_AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.TARGET_AWS_SECRET_ACCESS_KEY!,
+      },
+    },
+    logger
+  );
+
+  await s3Target.uploadFile('exports/inventory-export.json', JSON.stringify(transformed, null, 2), {
+    contentType: 'application/json',
+  });
+
+  logger.info('Extraction complete', { count: transformed.length });
+}
+```
+
+### Backward Pagination (Reverse Order)
+
+Fetch records in reverse chronological order (from end to start):
+
+```typescript
+import { ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
+
+const orchestrator = new ExtractionOrchestrator(client, logger);
+
+const result = await orchestrator.extract({
+  query: `
+    query GetRecentOrders($last: Int!, $before: String) {
+      orders(last: $last, before: $before) {
+        edges {
+          node { id ref status createdOn }
+          cursor
+        }
+        pageInfo { hasPreviousPage }
+      }
+    }
+  `,
+  resultPath: 'orders.edges.node',
+  variables: { last: 100 },
+  direction: 'backward', // Fetch from end to start
+  maxRecords: 1000,
+});
+
+console.log(`Extracted ${result.stats.totalRecords} orders`);
+```
+
+**When to use backward pagination:**
+
+- Fetching most recent records (latest orders, recent events)
+- Reverse chronological feeds
+- "Show last N items" scenarios
+
+### Processing with State Management
+
+```typescript
+import {
+  createClient,
+  S3DataSource,
+  StateService,
+  VersoriKVAdapter,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processFilesWithStateTracking(context) {
+  const logger = toStructuredLogger(createConsoleLogger(), {
+    logLevel: 'info',
+  });
+
+  // Initialize state service (Versori example)
+  const kvAdapter = new VersoriKVAdapter(context.openKv(':project:'));
+  const stateService = new StateService(kvAdapter);
+
+  // Initialize S3
+  const s3 = new S3DataSource(s3Config, logger);
+
+  // List files
+  const files = await s3.listFiles({ prefix: 'inbox/' });
+
+  for (const file of files) {
+    // Check if already processed
+    if (await stateService.isFileProcessed(file.path)) {
+      logger.info('File already processed', { file: file.name });
+      continue;
+    }
+
+    try {
+      // Process file
+      const content = await s3.downloadFile(file.path);
+      await processFileContent(content);
+
+      // Mark as processed
+      await stateService.markFileProcessed(file.path, {
+        processedAt: new Date().toISOString(),
+        size: file.size,
+      });
+
+      logger.info('File processed successfully', { file: file.name });
+    } catch (error) {
+      logger.error('Failed to process file', error as Error, { file: file.name });
+      throw error;
+    }
+  }
+}
+```
+
+## Platform-Specific Setup
+
+### Node.js Applications
+
+No additional configuration needed. The SDK works out of the box with Node.js 18+.
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function main() {
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    },
+  });
+
+  // Use client...
+}
+```
+
+### Versori Platform
+
+For Versori platform applications, the SDK automatically detects and uses the Versori context:
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const handler = http(
+  'handler',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    // Auto-detects Versori context
+    const client = await createClient(ctx);
+
+    // Use the same API
+    const result = await client.graphql({
+      query: `query { locations { edges { node { id ref } } } }`,
+    });
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify(result),
+    };
+  }
+);
+```
+
+**See**: [Versori Platform Guide](../04-REFERENCE/platforms/versori/) for complete Versori documentation.
+
+### Deno Support
+
+The SDK is compatible with Deno runtime. See the [Deno Platform Guide](../04-REFERENCE/platforms/deno/) for details.
+
+## Error Handling
+
+```typescript
+import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await client.sendBatch(jobId, batchData);
+} catch (error) {
+  if (error instanceof IngestionError) {
+    console.error('Ingestion failed:', {
+      code: error.code,
+      message: error.message,
+      context: error.context,
+    });
+
+    // Handle specific errors
+    switch (error.code) {
+      case IngestionErrorCode.VALIDATION_ERROR:
+        // Handle validation errors
+        await logValidationError(error.context);
+        break;
+
+      case IngestionErrorCode.RATE_LIMIT_ERROR:
+        // Retry with exponential backoff
+        await retryWithBackoff(() => client.sendBatch(jobId, batchData));
+        break;
+
+      case IngestionErrorCode.JOB_CREATION_ERROR:
+        // Create new job and retry
+        const newJob = await client.createJob({
+          name: 'Retry Job',
+          retailerId: client.getRetailerId(),
+        });
+        await client.sendBatch(newJob.id, batchData);
+        break;
+
+      case IngestionErrorCode.NETWORK_ERROR:
+        // Check network and retry
+        await checkNetworkConnectivity();
+        break;
+    }
+  } else {
+    // Handle unexpected errors
+    console.error('Unexpected error:', error);
+    throw error;
+  }
+}
+```
+
+**See**: [Error Handling Guide](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) for comprehensive error handling patterns.
+
+## Best Practices
+
+### 1. Security
+
+- **Store credentials securely** using environment variables or secret managers
+- **Never commit credentials** to version control
+- **Validate webhook signatures** (for Fluent Rubix webhooks only)
+- **Use least privilege** AWS IAM policies
+
+### 2. Performance
+
+- **Use streaming parsers** for large files to minimize memory usage
+- **Batch operations** to reduce API calls
+- **Use auto-pagination** for large result sets - See [Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
+- **Configure appropriate timeouts** based on operation types
+
+### 3. Reliability
+
+- **Implement retry logic** with exponential backoff for transient failures
+- **Track processing state** to prevent duplicate processing
+- **Use distributed locking** for concurrent workflows
+- **Monitor job status** and handle failures gracefully
+
+### 4. Data Quality
+
+- **Validate data** before sending to Fluent
+- **Use UniversalMapper** for consistent field transformations
+- **Handle missing data** with default values
+- **Log transformation errors** for debugging
+
+### 5. Monitoring
+
+- **Log all operations** with structured logging
+- **Track metrics** like processing time and record counts
+- **Set up alerts** for failures and anomalies
+- **Monitor API rate limits** and adjust accordingly
+
+## Troubleshooting
+
+### Common Installation Issues
+
+#### Module Resolution Errors
+
+```bash
+npm cache clean --force
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### TypeScript Errors
+
+- Ensure TypeScript version is >= 5.0.0
+- Add `"skipLibCheck": true` to tsconfig.json
+- Check for type definition conflicts
+
+#### Version Conflicts
+
+```bash
+# Check installed version
+npm ls @fluentcommerce/fc-connect-sdk
+
+# Update to latest
+npm update @fluentcommerce/fc-connect-sdk
+```
+
+### Runtime Issues
+
+#### Authentication Failures
+
+- Verify API credentials are correct
+- Check base URL matches your environment
+- Ensure retailer ID is valid (for Job/Batch operations)
+
+#### Network Timeouts
+
+- Increase timeout configuration
+- Check network connectivity
+- Verify firewall rules
+
+#### Memory Issues
+
+- Use streaming for large files
+- Process data in chunks
+- Monitor memory usage
+
+### Debugging Tips
+
+```typescript
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+
+// Use structured logging
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: 'debug',
+});
+
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    timeout: 60000,
+    retryAttempts: 3,
+  },
+});
+
+// Log GraphQL operations
+const query = `query { products { edges { node { ref } } } }`;
+logger.debug('Executing GraphQL query', { query });
+const result = await client.graphql({ query });
+logger.debug('Query result', {
+  recordCount: result.data?.products?.edges?.length,
+});
+
+// Log batch operations
+logger.info('Sending batch', {
+  jobId,
+  recordCount: batchData.entities.length,
+});
+await client.sendBatch(jobId, batchData);
+logger.info('Batch sent successfully');
+```
+
+## Next Steps
+
+Now that you're set up, explore:
+
+- **[API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete API documentation
+- **[Universal Mapping Guide](../02-CORE-GUIDES/mapping/mapping-readme.md)** - Field mapping and transformations
+- **[Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)** - Automatic GraphQL pagination
+- **[Ingestion Guide](../02-CORE-GUIDES/ingestion/)** - Inventory ingestion workflows
+- **[Extraction Guide](../02-CORE-GUIDES/extraction/)** - Data extraction patterns
+- **[Use Cases](../01-TEMPLATES/readme.md)** - Real-world examples and patterns
+
+## CLI Tools
+
+The SDK provides command-line tools for working with GraphQL schemas and mappings:
+
+```bash
+# Show available commands
+npx fc-connect help
+
+# Check SDK version
+npx fc-connect version
+
+# Generate mutation mapping template
+npx fc-connect generate-mutation-mapping \
+  --file ./mutations/createOrder.graphql \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --output ./mappings/createOrder.json
+
+# Introspect and cache schema
+npx fc-connect introspect-schema \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --output ./schema/fluent-schema.json
+```
+
+**See**: [API Reference - CLI Tools](../02-CORE-GUIDES/api-reference/modules/api-reference-11-cli-tools.md) for complete CLI documentation.