@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/api-reference/api-reference-quick-reference.md

@@ -1,548 +1,548 @@
-# API Quick Reference
-
-**One-page cheat sheet for FC Connect SDK**
-
-## Import Statements
-
-```typescript
-// Core client and factory
-import { createClient, FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Services
-import {
-  UniversalMapper,
-  StateService,
-  WebhookValidationService,
-  S3Service,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Data Sources & Parsers
-import {
-  S3DataSource,
-  SftpDataSource,
-  CSVParserService,
-  XMLParserService,
-  JSONParserService,
-  ParquetParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// GraphQL Mapping
-import {
-  GraphQLMutationMapper,
-  XMLPathResolver,
-  JSONPathResolver,
-  GraphQLIntrospectionService,
-  classifyError,
-  classifyErrors,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Types
-import {
-  FluentClientConfig,
-  BatchAction,
-  EntityType,
-  JobStrategy,
-  MappingConfig,
-  FieldConfig,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Utilities
-import {
-  parseWebhookRequest,
-  validateFluentEvent,
-  generateFileName,
-  sdkResolvers,
-} from '@fluentcommerce/fc-connect-sdk';
-```
-
-## Client Creation
-
-```typescript
-// Node.js/Standalone
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-    username: 'your-username', // Optional - for password grant
-    password: 'your-password', // Optional - for password grant
-    retailerId: 'your-retailer-id', // Optional - only for Job/Batch ops
-  },
-  logger: toStructuredLogger(createConsoleLogger(), {
-    logLevel: 'info',
-  }), // Optional
-});
-
-// Versori Platform (context already has proper shape)
-const client = await createClient(ctx);
-```
-
-## GraphQL Operations
-
-```typescript
-// Using the main graphql() method
-const result = await client.graphql({
-  query: `
-    query GetProducts($first: Int) {
-      products(first: $first) {
-        edges { node { id ref name } }
-      }
-    }
-  `,
-  variables: { first: 10 },
-});
-
-// Using helper method: prefer graphql
-const queryResult = await client.graphql({ query:
-  `
-  query GetProducts($first: Int) {
-    products(first: $first) {
-      edges { node { id ref name } }
-    }
-  }
-`, variables: { first: 10 } });
-
-const mutationResult = await client.graphql({ query: `
-  mutation UpdateProduct($input: UpdateProductInput!) {
-    updateProduct(input: $input) {
-      id ref name
-    }
-  }
-`, variables: { input: { id: '123', name: 'Updated' } } });
-```
-
-## Job & Batch Operations
-
-```typescript
-// Create job
-const job = await client.createJob({
-  name: 'Inventory Sync',
-  retailerId: 'retailer-123',
-});
-
-// Send batch (UPSERT only) - source and event are REQUIRED fields
-const batch = await client.sendBatch(job.id, {
-  action: BatchAction.UPSERT,
-  entityType: EntityType.INVENTORY,
-  source: 'CSV_IMPORT',      // REQUIRED: Source system identifier
-  event: 'INVENTORY_UPDATE',  // REQUIRED: Event identifier
-  entities: [{ ref: 'SKU-001', qty: 100, locationRef: 'DC-001' }],
-});
-```
-
-## Universal Mapping
-
-```typescript
-const mapper = new UniversalMapper({
-  version: '1.0',
-  fields: {
-    skuRef: { source: 'SKU', required: true },
-    qty: { source: 'QTY', resolver: 'sdk.parseInt' },
-    status: { source: 'STATUS', resolver: 'sdk.uppercase' },
-  },
-});
-
-const result = await mapper.map(record);
-```
-
-## GraphQL Mutation Mapping
-
-```typescript
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-
-const payload = await mapper.map(parsedXmlData, {
-  beforeMapping: async (data, context) => data,
-  afterMapping: async (variables, context) => {
-    variables.input.totalPrice = calculateTotal(variables.input.items);
-    return variables;
-  },
-});
-
-const result = await client.graphql(payload);
-```
-
-## State Management
-
-```typescript
-const stateService = new StateService({
-  kvStore: kvAdapter,
-  namespace: 'inventory-sync',
-});
-
-// Check if processed
-if (!(await stateService.isProcessed('file.csv'))) {
-  // Process file
-  await stateService.markProcessed('file.csv', { records: 1000 });
-}
-
-// Distributed locking
-const lock = await stateService.acquireLock('critical-section', 60000);
-try {
-  // Critical section
-} finally {
-  await stateService.releaseLock('critical-section');
-}
-```
-
-## S3 Operations
-
-```typescript
-const s3Service = new S3Service({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'xxx',
-    secretAccessKey: 'yyy',
-  },
-});
-
-// List objects
-const objects = await s3Service.listObjects('bucket', { prefix: 'path/' });
-
-// Get object
-const data = await s3Service.getObject('bucket', 'key');
-
-// Put object
-await s3Service.putObject('bucket', 'key', data, {
-  contentType: 'application/json',
-});
-
-// Generate presigned URL
-const url = await s3Service.getPresignedUrl('getObject', 'bucket', 'key', 3600);
-```
-
-## Data Sources
-
-```typescript
-// S3 Data Source
-const s3Source = new S3DataSource(
-  {
-    type: 'S3_CSV',
-    connectionId: 'my-s3',
-    name: 'My S3 Source',
-    s3Config: {
-      bucket: 'my-bucket',
-      region: 'us-east-1',
-      accessKeyId: 'xxx',
-      secretAccessKey: 'yyy',
-    },
-  },
-  logger
-);
-
-const files = await s3Source.listFiles({ prefix: 'inventory/' });
-const content = await s3Source.downloadFile('inventory/data.csv');
-
-// SFTP Data Source
-const sftpSource = new SftpDataSource(
-  {
-    type: 'SFTP_CSV',
-    connectionId: 'my-sftp',
-    name: 'My SFTP Source',
-    settings: {
-      host: 'sftp.example.com',
-      port: 22,
-      username: 'user',
-      password: 'secret',
-      remotePath: '/inventory',
-      filePattern: '*.csv',
-    },
-  },
-  logger
-);
-
-const sftpFiles = await sftpSource.listFiles();
-const sftpContent = await sftpSource.downloadFile('/inventory/data.csv');
-```
-
-## Parsers
-
-```typescript
-// CSV Parser
-const csvParser = new CSVParserService();
-// Options go to parse() method
-const records = await csvParser.parse(csvContent, { columns: true });
-
-// XML Parser
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent, {
-  includeAttributes: true,
-  attributePrefix: '@',
-});
-
-// JSON Parser
-const jsonParser = new JSONParserService();
-const parsed = await jsonParser.parse(jsonContent);
-
-// Parquet Parser
-const logger = createConsoleLogger();
-const parquetParser = new ParquetParserService(logger);
-const records = await parquetParser.parse(parquetBuffer);
-```
-
-## Path Resolvers
-
-```typescript
-// XML Path Resolver
-const xmlResolver = new XMLPathResolver();
-const orderNo = xmlResolver.resolve(xmlData, 'order@order-no');
-const items = xmlResolver.resolve(xmlData, 'items.item.*.sku');
-
-// JSON Path Resolver
-const jsonResolver = new JSONPathResolver();
-const orderNo = jsonResolver.resolve(jsonData, 'order.orderNo');
-const items = jsonResolver.resolve(jsonData, 'items.*.sku');
-```
-
-## Webhook Validation
-
-```typescript
-import { WebhookValidationService, SignatureAlgorithm } from '@fluentcommerce/fc-connect-sdk';
-
-// IMPORTANT: Only for Fluent Commerce Rubix workflows
-const validator = new WebhookValidationService(
-  {
-    algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
-    strictValidation: true,
-  },
-  logger
-);
-
-const result = await validator.validateWebhookSignature(
-  JSON.stringify(requestBody),
-  headers['fluent-signature'],
-  publicKey,
-  SignatureAlgorithm.SHA512_WITH_RSA
-);
-
-if (!result.isValid) {
-  throw new Error(`Validation failed: ${result.error}`);
-}
-```
-
-## Building Blocks Composition
-
-```typescript
-// Compose SDK services for custom workflows
-import { S3DataSource, CSVParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const s3 = new S3DataSource(
-  {
-    type: 'S3_CSV',
-    connectionId: 's3-composition',
-    name: 'S3 Composition',
-    s3Config: config.s3Config,
-  },
-  logger
-);
-const parser = new CSVParserService();
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: 'SKU', required: true },
-    qty: { source: 'Quantity', resolver: 'sdk.parseInt' },
-    locationRef: { source: 'Location', required: true },
-  },
-});
-
-// Read and parse
-const content = await s3.downloadFile('inventory.csv');
-const records = await parser.parse(content);
-
-// Map records
-const inventory = [];
-for (const record of records) {
-  const result = await mapper.map(record);
-  if (result.success) inventory.push(result.data);
-}
-
-// Create job and send batches
-const job = await client.createJob({
-  name: 'Daily Inventory',
-  retailerId: '1',
-});
-
-const batches = chunkArray(inventory, 1000);
-for (const batch of batches) {
-  await client.sendBatch(job.id, {
-    action: BatchAction.UPSERT,
-    entityType: EntityType.INVENTORY,
-    source: 'CSV_IMPORT',
-    event: 'INVENTORY_UPDATE',
-    entities: batch,
-  });
-}
-```
-
-## Logging
-
-```typescript
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
-
-logger.info('Processing started', { file: 'inventory.csv' });
-logger.error('Processing failed', { error: error.message });
-logger.debug('Debug info', { records: 100 });
-logger.warn('Warning message', { field: 'qty' });
-```
-
-## Error Handling
-
-```typescript
-import {
-  FluentError,
-  AuthenticationError,
-  ValidationError,
-  MappingError,
-  S3ServiceError,
-  classifyErrors,
-} from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  const result = await client.graphql({ query });
-  
-  // Classify GraphQL errors
-  if (result.errors) {
-    const classification = classifyErrors(result.errors);
-    console.error('GraphQL error:', {
-      errorCode: classification.errorCode,
-      retryable: classification.retryable,
-      action: classification.action,
-    });
-    
-    if (!classification.retryable) {
-      throw new Error(classification.userMessage);
-    }
-  }
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Auth failed:', error.message);
-  } else if (error instanceof ValidationError) {
-    console.error('Validation failed:', error.details);
-  } else if (error instanceof MappingError) {
-    console.error('Mapping failed:', error.field, error.sourcePath);
-  }
-}
-```
-
-## Common Enums
-
-```typescript
-// Batch Actions (only UPSERT is supported)
-enum BatchAction {
-  UPSERT = 'UPSERT',
-}
-
-// Entity Types
-enum EntityType {
-  INVENTORY = 'INVENTORY',
-  PRODUCT = 'PRODUCT',
-  ORDER = 'ORDER',
-  CUSTOMER = 'CUSTOMER',
-  LOCATION = 'LOCATION',
-  FULFILLMENT = 'FULFILLMENT',
-}
-
-// Job Strategies
-enum JobStrategy {
-  PER_FILE = 'PER_FILE',
-  DAILY = 'DAILY',
-  BATCHES_PER_JOB = 'BATCHES_PER_JOB',
-}
-
-// Signature Algorithms
-enum SignatureAlgorithm {
-  SHA512_WITH_RSA = 'SHA512withRSA',
-  MD5_WITH_RSA = 'MD5withRSA',
-}
-```
-
-## SDK Resolvers
-
-Built-in resolvers for Universal Mapper (use with `resolver` field):
-
-```typescript
-// String transformations
-('sdk.uppercase', 'sdk.lowercase', 'sdk.trim', 'sdk.toString');
-
-// Number transformations
-('sdk.parseInt', 'sdk.parseFloat', 'sdk.number');
-
-// Date transformations
-('sdk.formatDate', 'sdk.formatDateShort', 'sdk.parseDate');
-
-// Type transformations
-('sdk.boolean', 'sdk.parseJson', 'sdk.toJson');
-
-// Utility
-('sdk.identity', 'sdk.coalesce');
-```
-
-## Mapping Configuration Pattern
-
-```typescript
-const mappingConfig = {
-  version: '1.0',
-  direction: 'ingest', // or 'extract'
-  sourceFormat: 'xml', // or 'json', 'csv', 'graphql'
-  mutation: 'createOrder', // For ingest
-  fields: {
-    ref: {
-      source: 'order@id',
-      required: true,
-    },
-    items: {
-      source: 'items.item',
-      isArray: true,
-      fields: {
-        productRef: { source: 'sku' },
-        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-      },
-    },
-  },
-};
-```
-
-## Testing Utilities
-
-```typescript
-// S3 Testers
-import {
-  S3SDKTester,
-  S3PresignedTester,
-  FluentConnectionTester,
-} from '@fluentcommerce/fc-connect-sdk';
-
-const s3SdkTester = new S3SDKTester({
-  region: 'us-east-1',
-  credentials: { accessKeyId: 'xxx', secretAccessKey: 'yyy' },
-  bucket: 'my-bucket',
-  testOperations: ['list', 'read', 'write', 'delete'],
-  logger: console,
-});
-await s3SdkTester.runTests();
-
-// Fluent Connection Tester
-const fluentTester = new FluentConnectionTester(client, { logger: console });
-const result = await fluentTester.testConnection();
-```
-
-## CLI Tools
-
-```bash
-# Introspect GraphQL schema
-npx @fluentcommerce/fc-connect-sdk introspect-schema --url https://api.fluentcommerce.com/graphql
-
-# Generate mutation mapping
-npx @fluentcommerce/fc-connect-sdk generate-mutation-mapping --schema schema.json --mutation createOrder
-
-# Validate mapping configuration
-npx @fluentcommerce/fc-connect-sdk validate-schema --mapping config.json --schema schema.json
-
-# Analyze test coverage
-npx @fluentcommerce/fc-connect-sdk analyze-coverage --dir tests/
-```
-
----
-
-For detailed documentation, see the [complete API Reference](./api-reference-readme.md) or browse individual [modules](./modules/).
+# API Quick Reference
+
+**One-page cheat sheet for FC Connect SDK**
+
+## Import Statements
+
+```typescript
+// Core client and factory
+import { createClient, FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Services
+import {
+  UniversalMapper,
+  StateService,
+  WebhookValidationService,
+  S3Service,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Data Sources & Parsers
+import {
+  S3DataSource,
+  SftpDataSource,
+  CSVParserService,
+  XMLParserService,
+  JSONParserService,
+  ParquetParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// GraphQL Mapping
+import {
+  GraphQLMutationMapper,
+  XMLPathResolver,
+  JSONPathResolver,
+  GraphQLIntrospectionService,
+  classifyError,
+  classifyErrors,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Types
+import {
+  FluentClientConfig,
+  BatchAction,
+  EntityType,
+  JobStrategy,
+  MappingConfig,
+  FieldConfig,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Utilities
+import {
+  parseWebhookRequest,
+  validateFluentEvent,
+  generateFileName,
+  sdkResolvers,
+} from '@fluentcommerce/fc-connect-sdk';
+```
+
+## Client Creation
+
+```typescript
+// Node.js/Standalone
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    username: 'your-username', // Optional - for password grant
+    password: 'your-password', // Optional - for password grant
+    retailerId: 'your-retailer-id', // Optional - only for Job/Batch ops
+  },
+  logger: toStructuredLogger(createConsoleLogger(), {
+    logLevel: 'info',
+  }), // Optional
+});
+
+// Versori Platform (context already has proper shape)
+const client = await createClient(ctx);
+```
+
+## GraphQL Operations
+
+```typescript
+// Using the main graphql() method
+const result = await client.graphql({
+  query: `
+    query GetProducts($first: Int) {
+      products(first: $first) {
+        edges { node { id ref name } }
+      }
+    }
+  `,
+  variables: { first: 10 },
+});
+
+// Using helper method: prefer graphql
+const queryResult = await client.graphql({ query:
+  `
+  query GetProducts($first: Int) {
+    products(first: $first) {
+      edges { node { id ref name } }
+    }
+  }
+`, variables: { first: 10 } });
+
+const mutationResult = await client.graphql({ query: `
+  mutation UpdateProduct($input: UpdateProductInput!) {
+    updateProduct(input: $input) {
+      id ref name
+    }
+  }
+`, variables: { input: { id: '123', name: 'Updated' } } });
+```
+
+## Job & Batch Operations
+
+```typescript
+// Create job
+const job = await client.createJob({
+  name: 'Inventory Sync',
+  retailerId: 'retailer-123',
+});
+
+// Send batch (UPSERT only) - source and event are REQUIRED fields
+const batch = await client.sendBatch(job.id, {
+  action: BatchAction.UPSERT,
+  entityType: EntityType.INVENTORY,
+  source: 'CSV_IMPORT',      // REQUIRED: Source system identifier
+  event: 'INVENTORY_UPDATE',  // REQUIRED: Event identifier
+  entities: [{ ref: 'SKU-001', qty: 100, locationRef: 'DC-001' }],
+});
+```
+
+## Universal Mapping
+
+```typescript
+const mapper = new UniversalMapper({
+  version: '1.0',
+  fields: {
+    skuRef: { source: 'SKU', required: true },
+    qty: { source: 'QTY', resolver: 'sdk.parseInt' },
+    status: { source: 'STATUS', resolver: 'sdk.uppercase' },
+  },
+});
+
+const result = await mapper.map(record);
+```
+
+## GraphQL Mutation Mapping
+
+```typescript
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+
+const payload = await mapper.map(parsedXmlData, {
+  beforeMapping: async (data, context) => data,
+  afterMapping: async (variables, context) => {
+    variables.input.totalPrice = calculateTotal(variables.input.items);
+    return variables;
+  },
+});
+
+const result = await client.graphql(payload);
+```
+
+## State Management
+
+```typescript
+const stateService = new StateService({
+  kvStore: kvAdapter,
+  namespace: 'inventory-sync',
+});
+
+// Check if processed
+if (!(await stateService.isProcessed('file.csv'))) {
+  // Process file
+  await stateService.markProcessed('file.csv', { records: 1000 });
+}
+
+// Distributed locking
+const lock = await stateService.acquireLock('critical-section', 60000);
+try {
+  // Critical section
+} finally {
+  await stateService.releaseLock('critical-section');
+}
+```
+
+## S3 Operations
+
+```typescript
+const s3Service = new S3Service({
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: 'xxx',
+    secretAccessKey: 'yyy',
+  },
+});
+
+// List objects
+const objects = await s3Service.listObjects('bucket', { prefix: 'path/' });
+
+// Get object
+const data = await s3Service.getObject('bucket', 'key');
+
+// Put object
+await s3Service.putObject('bucket', 'key', data, {
+  contentType: 'application/json',
+});
+
+// Generate presigned URL
+const url = await s3Service.getPresignedUrl('getObject', 'bucket', 'key', 3600);
+```
+
+## Data Sources
+
+```typescript
+// S3 Data Source
+const s3Source = new S3DataSource(
+  {
+    type: 'S3_CSV',
+    connectionId: 'my-s3',
+    name: 'My S3 Source',
+    s3Config: {
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: 'xxx',
+      secretAccessKey: 'yyy',
+    },
+  },
+  logger
+);
+
+const files = await s3Source.listFiles({ prefix: 'inventory/' });
+const content = await s3Source.downloadFile('inventory/data.csv');
+
+// SFTP Data Source
+const sftpSource = new SftpDataSource(
+  {
+    type: 'SFTP_CSV',
+    connectionId: 'my-sftp',
+    name: 'My SFTP Source',
+    settings: {
+      host: 'sftp.example.com',
+      port: 22,
+      username: 'user',
+      password: 'secret',
+      remotePath: '/inventory',
+      filePattern: '*.csv',
+    },
+  },
+  logger
+);
+
+const sftpFiles = await sftpSource.listFiles();
+const sftpContent = await sftpSource.downloadFile('/inventory/data.csv');
+```
+
+## Parsers
+
+```typescript
+// CSV Parser
+const csvParser = new CSVParserService();
+// Options go to parse() method
+const records = await csvParser.parse(csvContent, { columns: true });
+
+// XML Parser
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent, {
+  includeAttributes: true,
+  attributePrefix: '@',
+});
+
+// JSON Parser
+const jsonParser = new JSONParserService();
+const parsed = await jsonParser.parse(jsonContent);
+
+// Parquet Parser
+const logger = createConsoleLogger();
+const parquetParser = new ParquetParserService(logger);
+const records = await parquetParser.parse(parquetBuffer);
+```
+
+## Path Resolvers
+
+```typescript
+// XML Path Resolver
+const xmlResolver = new XMLPathResolver();
+const orderNo = xmlResolver.resolve(xmlData, 'order@order-no');
+const items = xmlResolver.resolve(xmlData, 'items.item.*.sku');
+
+// JSON Path Resolver
+const jsonResolver = new JSONPathResolver();
+const orderNo = jsonResolver.resolve(jsonData, 'order.orderNo');
+const items = jsonResolver.resolve(jsonData, 'items.*.sku');
+```
+
+## Webhook Validation
+
+```typescript
+import { WebhookValidationService, SignatureAlgorithm } from '@fluentcommerce/fc-connect-sdk';
+
+// IMPORTANT: Only for Fluent Commerce Rubix workflows
+const validator = new WebhookValidationService(
+  {
+    algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
+    strictValidation: true,
+  },
+  logger
+);
+
+const result = await validator.validateWebhookSignature(
+  JSON.stringify(requestBody),
+  headers['fluent-signature'],
+  publicKey,
+  SignatureAlgorithm.SHA512_WITH_RSA
+);
+
+if (!result.isValid) {
+  throw new Error(`Validation failed: ${result.error}`);
+}
+```
+
+## Building Blocks Composition
+
+```typescript
+// Compose SDK services for custom workflows
+import { S3DataSource, CSVParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const s3 = new S3DataSource(
+  {
+    type: 'S3_CSV',
+    connectionId: 's3-composition',
+    name: 'S3 Composition',
+    s3Config: config.s3Config,
+  },
+  logger
+);
+const parser = new CSVParserService();
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: 'SKU', required: true },
+    qty: { source: 'Quantity', resolver: 'sdk.parseInt' },
+    locationRef: { source: 'Location', required: true },
+  },
+});
+
+// Read and parse
+const content = await s3.downloadFile('inventory.csv');
+const records = await parser.parse(content);
+
+// Map records
+const inventory = [];
+for (const record of records) {
+  const result = await mapper.map(record);
+  if (result.success) inventory.push(result.data);
+}
+
+// Create job and send batches
+const job = await client.createJob({
+  name: 'Daily Inventory',
+  retailerId: '1',
+});
+
+const batches = chunkArray(inventory, 1000);
+for (const batch of batches) {
+  await client.sendBatch(job.id, {
+    action: BatchAction.UPSERT,
+    entityType: EntityType.INVENTORY,
+    source: 'CSV_IMPORT',
+    event: 'INVENTORY_UPDATE',
+    entities: batch,
+  });
+}
+```
+
+## Logging
+
+```typescript
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
+
+logger.info('Processing started', { file: 'inventory.csv' });
+logger.error('Processing failed', { error: error.message });
+logger.debug('Debug info', { records: 100 });
+logger.warn('Warning message', { field: 'qty' });
+```
+
+## Error Handling
+
+```typescript
+import {
+  FluentError,
+  AuthenticationError,
+  ValidationError,
+  MappingError,
+  S3ServiceError,
+  classifyErrors,
+} from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  const result = await client.graphql({ query });
+  
+  // Classify GraphQL errors
+  if (result.errors) {
+    const classification = classifyErrors(result.errors);
+    console.error('GraphQL error:', {
+      errorCode: classification.errorCode,
+      retryable: classification.retryable,
+      action: classification.action,
+    });
+    
+    if (!classification.retryable) {
+      throw new Error(classification.userMessage);
+    }
+  }
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Auth failed:', error.message);
+  } else if (error instanceof ValidationError) {
+    console.error('Validation failed:', error.details);
+  } else if (error instanceof MappingError) {
+    console.error('Mapping failed:', error.field, error.sourcePath);
+  }
+}
+```
+
+## Common Enums
+
+```typescript
+// Batch Actions (only UPSERT is supported)
+enum BatchAction {
+  UPSERT = 'UPSERT',
+}
+
+// Entity Types
+enum EntityType {
+  INVENTORY = 'INVENTORY',
+  PRODUCT = 'PRODUCT',
+  ORDER = 'ORDER',
+  CUSTOMER = 'CUSTOMER',
+  LOCATION = 'LOCATION',
+  FULFILLMENT = 'FULFILLMENT',
+}
+
+// Job Strategies
+enum JobStrategy {
+  PER_FILE = 'PER_FILE',
+  DAILY = 'DAILY',
+  BATCHES_PER_JOB = 'BATCHES_PER_JOB',
+}
+
+// Signature Algorithms
+enum SignatureAlgorithm {
+  SHA512_WITH_RSA = 'SHA512withRSA',
+  MD5_WITH_RSA = 'MD5withRSA',
+}
+```
+
+## SDK Resolvers
+
+Built-in resolvers for Universal Mapper (use with `resolver` field):
+
+```typescript
+// String transformations
+('sdk.uppercase', 'sdk.lowercase', 'sdk.trim', 'sdk.toString');
+
+// Number transformations
+('sdk.parseInt', 'sdk.parseFloat', 'sdk.number');
+
+// Date transformations
+('sdk.formatDate', 'sdk.formatDateShort', 'sdk.parseDate');
+
+// Type transformations
+('sdk.boolean', 'sdk.parseJson', 'sdk.toJson');
+
+// Utility
+('sdk.identity', 'sdk.coalesce');
+```
+
+## Mapping Configuration Pattern
+
+```typescript
+const mappingConfig = {
+  version: '1.0',
+  direction: 'ingest', // or 'extract'
+  sourceFormat: 'xml', // or 'json', 'csv', 'graphql'
+  mutation: 'createOrder', // For ingest
+  fields: {
+    ref: {
+      source: 'order@id',
+      required: true,
+    },
+    items: {
+      source: 'items.item',
+      isArray: true,
+      fields: {
+        productRef: { source: 'sku' },
+        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+      },
+    },
+  },
+};
+```
+
+## Testing Utilities
+
+```typescript
+// S3 Testers
+import {
+  S3SDKTester,
+  S3PresignedTester,
+  FluentConnectionTester,
+} from '@fluentcommerce/fc-connect-sdk';
+
+const s3SdkTester = new S3SDKTester({
+  region: 'us-east-1',
+  credentials: { accessKeyId: 'xxx', secretAccessKey: 'yyy' },
+  bucket: 'my-bucket',
+  testOperations: ['list', 'read', 'write', 'delete'],
+  logger: console,
+});
+await s3SdkTester.runTests();
+
+// Fluent Connection Tester
+const fluentTester = new FluentConnectionTester(client, { logger: console });
+const result = await fluentTester.testConnection();
+```
+
+## CLI Tools
+
+```bash
+# Introspect GraphQL schema
+npx @fluentcommerce/fc-connect-sdk introspect-schema --url https://api.fluentcommerce.com/graphql
+
+# Generate mutation mapping
+npx @fluentcommerce/fc-connect-sdk generate-mutation-mapping --schema schema.json --mutation createOrder
+
+# Validate mapping configuration
+npx @fluentcommerce/fc-connect-sdk validate-schema --mapping config.json --schema schema.json
+
+# Analyze test coverage
+npx @fluentcommerce/fc-connect-sdk analyze-coverage --dir tests/
+```
+
+---
+
+For detailed documentation, see the [complete API Reference](./api-reference-readme.md) or browse individual [modules](./modules/).