@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-06-performance.md

@@ -1,109 +1,109 @@
-# Module 6: Performance Optimization
-
-Optimize integration workflows for throughput, latency, and resource efficiency.
-
-## Table of Contents
-
-- [Parallel Processing](#parallel-processing)
-- [Streaming Optimization](#streaming-optimization)
-- [Batch Size Tuning](#batch-size-tuning)
-- [Connection Pooling](#connection-pooling)
-- [Memory Management](#memory-management)
-
----
-
-## Parallel Processing
-
-### Concurrent File Processing
-
-```typescript
-const CONCURRENCY = 5;
-
-for (let i = 0; i < files.length; i += CONCURRENCY) {
-  const chunk = files.slice(i, i + CONCURRENCY);
-  await Promise.all(chunk.map(processFile));
-}
-```
-
-### Parallel Extractions
-
-```typescript
-await Promise.all([
-  extractInventoryPositions(),
-  extractOrders(),
-  extractProducts()
-]);
-```
-
----
-
-## Streaming Optimization
-
-```typescript
-// Stream large files
-const stream = await s3.readFileStream('large-file.csv');
-
-for await (const record of parser.parseStreaming(stream)) {
-  await processRecord(record);
-  // Memory is released after each iteration
-}
-```
-
----
-
-## Batch Size Tuning
-
-| Use Case | Batch Size | Reasoning |
-|----------|------------|-----------|
-| Real-time updates | 50-100 | Fast response |
-| Bulk ETL | 500-1000 | Maximize throughput |
-| Rate-limited APIs | 100-250 | Balance speed/limits |
-
-```typescript
-await batch.sendBatch(jobId, records, {
-  batchSize: 500  // Tune based on use case
-});
-```
-
----
-
-## Connection Pooling
-
-### SFTP Connection Pool
-
-```typescript
-const sftp = new SftpDataSource({
-  type: 'SFTP_CSV',
-  settings: {
-    host: 'sftp.example.com',
-    maxConnections: 10  // Connection pool size
-  }
-}, log);
-```
-
----
-
-## Memory Management
-
-### Chunk Processing
-
-```typescript
-const CHUNK_SIZE = 1000;
-let batch = [];
-
-for await (const record of stream) {
-  batch.push(record);
-
-  if (batch.length >= CHUNK_SIZE) {
-    await processBatch(batch);
-    batch = [];  // Release memory
-  }
-}
-```
-
----
-
-**Navigation:**
-- [Back to Module List](./readme.md)
-- [Previous: Module 05 - Error Handling](./integration-patterns-05-error-handling.md)
-- [Next: Module 07 - API Reference](./integration-patterns-07-api-reference.md)
+# Module 6: Performance Optimization
+
+Optimize integration workflows for throughput, latency, and resource efficiency.
+
+## Table of Contents
+
+- [Parallel Processing](#parallel-processing)
+- [Streaming Optimization](#streaming-optimization)
+- [Batch Size Tuning](#batch-size-tuning)
+- [Connection Pooling](#connection-pooling)
+- [Memory Management](#memory-management)
+
+---
+
+## Parallel Processing
+
+### Concurrent File Processing
+
+```typescript
+const CONCURRENCY = 5;
+
+for (let i = 0; i < files.length; i += CONCURRENCY) {
+  const chunk = files.slice(i, i + CONCURRENCY);
+  await Promise.all(chunk.map(processFile));
+}
+```
+
+### Parallel Extractions
+
+```typescript
+await Promise.all([
+  extractInventoryPositions(),
+  extractOrders(),
+  extractProducts()
+]);
+```
+
+---
+
+## Streaming Optimization
+
+```typescript
+// Stream large files
+const stream = await s3.readFileStream('large-file.csv');
+
+for await (const record of parser.parseStreaming(stream)) {
+  await processRecord(record);
+  // Memory is released after each iteration
+}
+```
+
+---
+
+## Batch Size Tuning
+
+| Use Case | Batch Size | Reasoning |
+|----------|------------|-----------|
+| Real-time updates | 50-100 | Fast response |
+| Bulk ETL | 500-1000 | Maximize throughput |
+| Rate-limited APIs | 100-250 | Balance speed/limits |
+
+```typescript
+await batch.sendBatch(jobId, records, {
+  batchSize: 500  // Tune based on use case
+});
+```
+
+---
+
+## Connection Pooling
+
+### SFTP Connection Pool
+
+```typescript
+const sftp = new SftpDataSource({
+  type: 'SFTP_CSV',
+  settings: {
+    host: 'sftp.example.com',
+    maxConnections: 10  // Connection pool size
+  }
+}, log);
+```
+
+---
+
+## Memory Management
+
+### Chunk Processing
+
+```typescript
+const CHUNK_SIZE = 1000;
+let batch = [];
+
+for await (const record of stream) {
+  batch.push(record);
+
+  if (batch.length >= CHUNK_SIZE) {
+    await processBatch(batch);
+    batch = [];  // Release memory
+  }
+}
+```
+
+---
+
+**Navigation:**
+- [Back to Module List](./readme.md)
+- [Previous: Module 05 - Error Handling](./integration-patterns-05-error-handling.md)
+- [Next: Module 07 - API Reference](./integration-patterns-07-api-reference.md)

package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-07-api-reference.md

@@ -1,34 +1,34 @@
-# Module 7: API Reference
-
-API reference for integration pattern utilities and services.
-
-## Table of Contents
-
-- [ExtractionOrchestrator](#extractionorchestrator)
-- [PartialBatchRecovery](#partialbatchrecovery)
-- [StateService](#stateservice)
-
----
-
-## ExtractionOrchestrator
-
-See [Extraction API Reference](../../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-07-api-reference.md) for complete documentation.
-
----
-
-## PartialBatchRecovery
-
-See [Error Handling API Reference](../error-handling/modules/error-handling-07-api-reference.md) for complete documentation.
-
----
-
-## StateService
-
-See [File Operations API Reference](../file-operations/modules/file-operations-07-api-reference.md) for complete documentation.
-
----
-
-**Navigation:**
-- [Back to Module List](./readme.md)
-- [Previous: Module 06 - Performance](./integration-patterns-06-performance.md)
-- [Back to Integration Patterns Guide](../integration-patterns-readme.md)
+# Module 7: API Reference
+
+API reference for integration pattern utilities and services.
+
+## Table of Contents
+
+- [ExtractionOrchestrator](#extractionorchestrator)
+- [PartialBatchRecovery](#partialbatchrecovery)
+- [StateService](#stateservice)
+
+---
+
+## ExtractionOrchestrator
+
+See [Extraction API Reference](../../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-07-api-reference.md) for complete documentation.
+
+---
+
+## PartialBatchRecovery
+
+See [Error Handling API Reference](../error-handling/modules/error-handling-07-api-reference.md) for complete documentation.
+
+---
+
+## StateService
+
+See [File Operations API Reference](../file-operations/modules/file-operations-07-api-reference.md) for complete documentation.
+
+---
+
+**Navigation:**
+- [Back to Module List](./readme.md)
+- [Previous: Module 06 - Performance](./integration-patterns-06-performance.md)
+- [Back to Integration Patterns Guide](../integration-patterns-readme.md)

package/docs/03-PATTERN-GUIDES/integration-patterns/readme.md

@@ -1,30 +1,30 @@
-# Integration Patterns
-
-> **Enterprise integration patterns for Fluent Commerce**
-> Real-time, batch, delta sync, and bidirectional patterns
-
-For complete documentation, see [integration-patterns-readme.md](./integration-patterns-readme.md)
-
-## Overview
-
-This guide covers enterprise integration patterns for Fluent Commerce integrations, including real-time processing, batch processing, delta synchronization, webhook patterns, and error handling strategies.
-
-## Navigation
-
-- [Complete Documentation](./integration-patterns-readme.md) - Full guide
-- [Quick Reference](./integration-patterns-quick-reference.md) - Cheat sheet
-- [Modules](./modules/) - Progressive learning modules
-- [Examples](./examples/) - Code examples
-
-## Learning Path
-
-| Module | Topic | Level |
-|--------|-------|-------|
-| [Module 1](./modules/integration-patterns-01-real-time-processing.md) | Real-Time Processing | Intermediate |
-| [Module 2](./modules/integration-patterns-02-batch-processing.md) | Batch Processing | Intermediate |
-| [Module 3](./modules/integration-patterns-03-delta-sync.md) | Delta Sync | Advanced |
-| [Module 4](./modules/integration-patterns-04-webhook-patterns.md) | Webhook Patterns | Intermediate |
-| [Module 5](./modules/integration-patterns-05-error-handling.md) | Error Handling | Advanced |
-| [Module 6](./modules/integration-patterns-06-advanced-integration-services.md) | Advanced Services | Advanced |
-
-See [integration-patterns-readme.md](./integration-patterns-readme.md) for complete details.
+# Integration Patterns
+
+> **Enterprise integration patterns for Fluent Commerce**
+> Real-time, batch, delta sync, and bidirectional patterns
+
+For complete documentation, see [integration-patterns-readme.md](./integration-patterns-readme.md)
+
+## Overview
+
+This guide covers enterprise integration patterns for Fluent Commerce integrations, including real-time processing, batch processing, delta synchronization, webhook patterns, and error handling strategies.
+
+## Navigation
+
+- [Complete Documentation](./integration-patterns-readme.md) - Full guide
+- [Quick Reference](./integration-patterns-quick-reference.md) - Cheat sheet
+- [Modules](./modules/) - Progressive learning modules
+- [Examples](./examples/) - Code examples
+
+## Learning Path
+
+| Module | Topic | Level |
+|--------|-------|-------|
+| [Module 1](./modules/integration-patterns-01-real-time-processing.md) | Real-Time Processing | Intermediate |
+| [Module 2](./modules/integration-patterns-02-batch-processing.md) | Batch Processing | Intermediate |
+| [Module 3](./modules/integration-patterns-03-delta-sync.md) | Delta Sync | Advanced |
+| [Module 4](./modules/integration-patterns-04-webhook-patterns.md) | Webhook Patterns | Intermediate |
+| [Module 5](./modules/integration-patterns-05-error-handling.md) | Error Handling | Advanced |
+| [Module 6](./modules/integration-patterns-06-advanced-integration-services.md) | Advanced Services | Advanced |
+
+See [integration-patterns-readme.md](./integration-patterns-readme.md) for complete details.

package/docs/03-PATTERN-GUIDES/logging-minimal-mode.md

@@ -1,128 +1,128 @@
-# Logging: Functional Approach
-
-Level: Beginner
-
-## TL;DR
-
-- Use the platform/logger you already have (Versori `log`) directly.
-- The SDK provides lightweight functional utilities for standalone environments.
-- Pure functions - no classes, no state, fully extensible.
-
-## Minimal Logger (Versori)
-
-```typescript
-// Minimal Versori logger adapter (no LoggingService required)
-const logger: import('@fluentcommerce/fc-connect-sdk').Logger = {
-  debug: (msg, meta) => log.debug(msg, meta),
-  info: (msg, meta) => log.info(msg, meta),
-  warn: (msg, meta) => log.warn(msg, meta),
-  error: (msg, err, meta) => log.error(msg, { ...(meta ?? {}), error: err?.message }),
-};
-
-// Pass `logger` anywhere an SDK service/orchestrator expects a logger
-```
-
-Notes:
-
-- Works in Versori, Node, and tests (replace `log.*` with your env's logging).
-- The SDK only calls `debug/info/warn/error`. No extra APIs required.
-
-## Structured Logging with Context
-
-Add context management by wrapping any logger:
-
-```typescript
-import { toStructuredLogger, generateCorrelationId } from '@fluentcommerce/fc-connect-sdk';
-
-// Wrap Versori native log
-const logger = toStructuredLogger(log, {
-  service: 'ingestion',
-  correlationId: generateCorrelationId(),
-  logLevel: 'info'
-});
-
-// All logs include context automatically
-logger.info('Processing file', { file: 'data.csv' });
-// Output includes: service, correlationId, file, timestamp
-```
-
-Why this works:
-
-- Pure function - no state, no side effects.
-- No background timers or external I/O.
-- No metrics collection or health tracking.
-- Just context management.
-
-## When to Stay Minimal
-
-- You don't need correlation IDs or automatic per-message context.
-- You want the smallest surface and native platform logs.
-
-## When Structured Helps
-
-- You want a single place to set `correlationId`, `jobId`, `fileKey` and have it appear on every log.
-- You need consistent logs across Versori, Node, and Deno without per-env conditionals.
-- You want logger caching by service name.
-
-## Functional Utilities
-
-**Core Functions:**
-- `createConsoleLogger()` - Basic console logger
-- `toStructuredLogger()` - Wrap any logger with context
-- `generateCorrelationId()` - Generate unique request IDs
-
-**Convenience Functions:**
-- `createWorkflowLogger()` - Pre-configured for workflows (includes correlationId)
-- `createServiceLogger()` - Pre-configured for services
-- `createErrorLogger()` - Pre-configured for error handling
-
-**What It Provides:**
-- Context inheritance (base → message)
-- Level filtering (debug, info, warn, error)
-- Context manipulation (add/set/clear/get)
-
-**What It Doesn't Do:**
-- No classes or state
-- No logger caching (you manage references)
-- No global context (context per logger)
-- No metrics or health tracking
-
-## Extending for New Platforms
-
-**Vercel Edge Functions:**
-```typescript
-function createVercelLogger(): Logger {
-  return {
-    debug: (msg, meta) => console.debug(msg, meta),
-    info: (msg, meta) => console.info(msg, meta),
-    warn: (msg, meta) => console.warn(msg, meta),
-    error: (msg, err, meta) => console.error(msg, err, meta),
-  };
-}
-
-const logger = toStructuredLogger(createVercelLogger(), { edge: 'iad1' });
-```
-
-**Cloudflare Workers:**
-```typescript
-function createCloudflareLogger(): Logger {
-  return {
-    debug: (msg, meta) => console.debug(JSON.stringify({ level: 'debug', msg, ...meta })),
-    info: (msg, meta) => console.info(JSON.stringify({ level: 'info', msg, ...meta })),
-    warn: (msg, meta) => console.warn(JSON.stringify({ level: 'warn', msg, ...meta })),
-    error: (msg, err, meta) => console.error(JSON.stringify({
-      level: 'error', msg, ...meta, error: err?.message
-    })),
-  };
-}
-```
-
-## FAQ
-
-Q: Do I need to use these utilities?
-
-A: No. Any logger implementing `debug/info/warn/error` works. These are helpers for standalone environments.
-
-Q: Can I switch logger implementations later?
-
-A: Yes. Just change the factory function - all call sites remain the same.
+# Logging: Functional Approach
+
+Level: Beginner
+
+## TL;DR
+
+- Use the platform/logger you already have (Versori `log`) directly.
+- The SDK provides lightweight functional utilities for standalone environments.
+- Pure functions - no classes, no state, fully extensible.
+
+## Minimal Logger (Versori)
+
+```typescript
+// Minimal Versori logger adapter (no LoggingService required)
+const logger: import('@fluentcommerce/fc-connect-sdk').Logger = {
+  debug: (msg, meta) => log.debug(msg, meta),
+  info: (msg, meta) => log.info(msg, meta),
+  warn: (msg, meta) => log.warn(msg, meta),
+  error: (msg, err, meta) => log.error(msg, { ...(meta ?? {}), error: err?.message }),
+};
+
+// Pass `logger` anywhere an SDK service/orchestrator expects a logger
+```
+
+Notes:
+
+- Works in Versori, Node, and tests (replace `log.*` with your env's logging).
+- The SDK only calls `debug/info/warn/error`. No extra APIs required.
+
+## Structured Logging with Context
+
+Add context management by wrapping any logger:
+
+```typescript
+import { toStructuredLogger, generateCorrelationId } from '@fluentcommerce/fc-connect-sdk';
+
+// Wrap Versori native log
+const logger = toStructuredLogger(log, {
+  service: 'ingestion',
+  correlationId: generateCorrelationId(),
+  logLevel: 'info'
+});
+
+// All logs include context automatically
+logger.info('Processing file', { file: 'data.csv' });
+// Output includes: service, correlationId, file, timestamp
+```
+
+Why this works:
+
+- Pure function - no state, no side effects.
+- No background timers or external I/O.
+- No metrics collection or health tracking.
+- Just context management.
+
+## When to Stay Minimal
+
+- You don't need correlation IDs or automatic per-message context.
+- You want the smallest surface and native platform logs.
+
+## When Structured Helps
+
+- You want a single place to set `correlationId`, `jobId`, `fileKey` and have it appear on every log.
+- You need consistent logs across Versori, Node, and Deno without per-env conditionals.
+- You want logger caching by service name.
+
+## Functional Utilities
+
+**Core Functions:**
+- `createConsoleLogger()` - Basic console logger
+- `toStructuredLogger()` - Wrap any logger with context
+- `generateCorrelationId()` - Generate unique request IDs
+
+**Convenience Functions:**
+- `createWorkflowLogger()` - Pre-configured for workflows (includes correlationId)
+- `createServiceLogger()` - Pre-configured for services
+- `createErrorLogger()` - Pre-configured for error handling
+
+**What It Provides:**
+- Context inheritance (base → message)
+- Level filtering (debug, info, warn, error)
+- Context manipulation (add/set/clear/get)
+
+**What It Doesn't Do:**
+- No classes or state
+- No logger caching (you manage references)
+- No global context (context per logger)
+- No metrics or health tracking
+
+## Extending for New Platforms
+
+**Vercel Edge Functions:**
+```typescript
+function createVercelLogger(): Logger {
+  return {
+    debug: (msg, meta) => console.debug(msg, meta),
+    info: (msg, meta) => console.info(msg, meta),
+    warn: (msg, meta) => console.warn(msg, meta),
+    error: (msg, err, meta) => console.error(msg, err, meta),
+  };
+}
+
+const logger = toStructuredLogger(createVercelLogger(), { edge: 'iad1' });
+```
+
+**Cloudflare Workers:**
+```typescript
+function createCloudflareLogger(): Logger {
+  return {
+    debug: (msg, meta) => console.debug(JSON.stringify({ level: 'debug', msg, ...meta })),
+    info: (msg, meta) => console.info(JSON.stringify({ level: 'info', msg, ...meta })),
+    warn: (msg, meta) => console.warn(JSON.stringify({ level: 'warn', msg, ...meta })),
+    error: (msg, err, meta) => console.error(JSON.stringify({
+      level: 'error', msg, ...meta, error: err?.message
+    })),
+  };
+}
+```
+
+## FAQ
+
+Q: Do I need to use these utilities?
+
+A: No. Any logger implementing `debug/info/warn/error` works. These are helpers for standalone environments.
+
+Q: Can I switch logger implementations later?
+
+A: Yes. Just change the factory function - all call sites remain the same.