@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/logging-guide.md

@@ -1,585 +1,585 @@
-# Logging Guide
-
-## Overview
-
-The fc-connect-sdk provides minimal logging utilities designed for flexibility and extensibility. The logging approach differs based on your deployment environment:
-
-- **Versori Platform**: Use native `log` from context (recommended)
-- **Standalone (Node.js/Deno)**: Use SDK's lightweight utilities
-- **Other Platforms**: Implement the `Logger` interface for your platform
-
-## Philosophy
-
-**Keep it simple:**
-
-- No global state
-- No logger caching
-- Pure functions over classes
-- Platform-agnostic interface
-- Easy to extend
-
-The SDK provides just two core functions for standalone environments, while Versori users should use the platform's native logger directly.
-
----
-
-## Quick Start
-
-### Versori Platform (Recommended)
-
-**Always use the native `log` from context** - don't wrap it:
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const workflow = schedule('daily-sync', '0 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); // Auto-detects Versori context
-    const sftp = new SftpDataSource(config, log);
-
-    log.info('Processing started', { workflow: 'daily-sync' });
-
-    try {
-      const files = await sftp.listFiles({ directory: '/inbound' });
-      log.info('Files found', { count: files.length });
-
-      // Process files...
-
-      log.info('Processing complete', { filesProcessed: files.length });
-    } catch (error) {
-      log.error('Processing failed', error);
-      throw error;
-    }
-  })
-);
-```
-
-**Why native log?**
-
-- Automatically flows to Versori monitoring dashboard
-- Includes execution context
-- No overhead
-- Simpler code
-
-### Standalone Node.js/Deno
-
-**Use the SDK's minimal utilities:**
-
-```typescript
-import {
-  createClient,
-  createConsoleLogger,
-  toStructuredLogger,
-  generateCorrelationId,
-  SftpDataSource,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// 1. Create a console logger
-const logger = createConsoleLogger();
-logger.info('Application started');
-
-// 2. Or wrap with context for richer logs
-const contextLogger = toStructuredLogger(logger, {
-  service: 'InventorySync',
-  correlationId: generateCorrelationId(),
-  logLevel: 'debug',
-});
-
-contextLogger.info('Processing file', { file: 'data.csv' });
-// Output: [2025-01-27T10:00:00.000Z] [INFO] Processing file
-//         {"service":"InventorySync","correlationId":"...","file":"data.csv"}
-
-// 3. Pass to SDK services
-const client = await createClient({
-  config: config,
-  logger: contextLogger,
-});
-const sftp = new SftpDataSource(sftpConfig, contextLogger);
-```
-
-**Note:** `createClient` automatically logs client creation success/failure when a logger is provided.
-
----
-
-## Core Functions
-
-### `createConsoleLogger()`
-
-Creates a simple console-based logger for standalone environments.
-
-**Signature:**
-
-```typescript
-function createConsoleLogger(): Logger;
-```
-
-**Output format:** `[timestamp] [LEVEL] message metadata`
-
-**Example:**
-
-```typescript
-const logger = createConsoleLogger();
-
-logger.info('Processing started', { file: 'inventory.csv' });
-// [2025-01-27T10:00:00.000Z] [INFO] Processing started {"file":"inventory.csv"}
-
-logger.error('Failed to parse', new Error('Invalid CSV'), { line: 42 });
-// [2025-01-27T10:00:00.000Z] [ERROR] Failed to parse {"line":42}
-// Error: Invalid CSV
-//     at <stack trace>
-```
-
-### `toStructuredLogger()`
-
-Wraps a logger with base context that will be merged into all log calls.
-
-**Signature:**
-
-```typescript
-function toStructuredLogger(rootLogger: Logger, options?: LoggerConfig & LogContext): Logger;
-```
-
-**Parameters:**
-
-- `rootLogger`: The underlying logger implementation
-- `options`: Configuration and context in a single object
-  - Config: `logLevel`, `includeTimestamp`, `debugMode`
-  - Context: `service`, `correlationId`, `workflow`, or any custom keys
-
-**Context hierarchy:** `baseContext` → `per-message metadata`
-
-**Example:**
-
-```typescript
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'S3Ingestion',
-  correlationId: generateCorrelationId(),
-  logLevel: 'debug',
-  environment: 'production',
-});
-
-logger.info('File processed', { file: 'data.csv', size: 1024 });
-// All logs include: service, correlationId, environment + per-message metadata
-```
-
-### `generateCorrelationId()`
-
-Generates a unique correlation ID for tracking requests across logs.
-
-**Signature:**
-
-```typescript
-function generateCorrelationId(): string;
-```
-
-**Format:** `{timestamp}-{random}` (e.g., "1706356800000-k9f3x2p1q")
-
-**Example:**
-
-```typescript
-const correlationId = generateCorrelationId();
-// "1706356800000-k9f3x2p1q"
-
-const logger = toStructuredLogger(createConsoleLogger(), {
-  correlationId,
-  service: 'OrderProcessor',
-});
-```
-
----
-
-## Logger Interface
-
-All loggers implement this simple interface:
-
-```typescript
-interface Logger {
-  debug(message: string, meta?: Record<string, unknown>): void;
-  info(message: string, meta?: Record<string, unknown>): void;
-  warn(message: string, meta?: Record<string, unknown>): void;
-  error(message: string, error?: Error, meta?: Record<string, unknown>): void;
-}
-```
-
-**Key points:**
-
-- `error()` accepts an optional `Error` object as the second parameter
-- Metadata is always optional
-- Platform-agnostic - works everywhere
-
----
-
-## Extending for New Platforms
-
-### Vercel Edge Functions
-
-```typescript
-import { Logger } from '@fluentcommerce/fc-connect-sdk';
-
-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),
-  };
-}
-
-// Usage
-export default async function handler(req: Request) {
-  const logger = toStructuredLogger(createVercelLogger(), {
-    edge: 'iad1',
-    requestId: req.headers.get('x-vercel-id'),
-  });
-
-  logger.info('Request received', { url: req.url });
-  // Process...
-}
-```
-
-### Cloudflare Workers
-
-```typescript
-function createCloudflareLogger(env: Env): 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,
-          stack: err?.stack,
-        })
-      ),
-  };
-}
-
-// Usage
-export default {
-  async fetch(request: Request, env: Env) {
-    const logger = toStructuredLogger(createCloudflareLogger(env), {
-      worker: 'inventory-sync',
-      rayId: request.headers.get('cf-ray'),
-    });
-
-    logger.info('Worker invoked');
-    // Process...
-  },
-};
-```
-
-### Third-party Loggers (Pino, Winston, Bunyan)
-
-#### Pino
-
-```typescript
-import pino from 'pino';
-
-function createPinoLogger(options?: pino.LoggerOptions): Logger {
-  const log = pino(options);
-  return {
-    debug: (msg, meta) => log.debug(meta, msg),
-    info: (msg, meta) => log.info(meta, msg),
-    warn: (msg, meta) => log.warn(meta, msg),
-    error: (msg, err, meta) => log.error({ ...meta, err }, msg),
-  };
-}
-
-// Usage with context
-const logger = toStructuredLogger(createPinoLogger(), {
-  service: 'api-gateway',
-  version: '2.0.0',
-});
-```
-
-#### Winston
-
-```typescript
-import winston from 'winston';
-
-function createWinstonLogger(): Logger {
-  const log = winston.createLogger({
-    format: winston.format.json(),
-    transports: [new winston.transports.Console()],
-  });
-
-  return {
-    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 }),
-  };
-}
-```
-
-#### Bunyan
-
-```typescript
-import bunyan from 'bunyan';
-
-function createBunyanLogger(name: string): Logger {
-  const log = bunyan.createLogger({ name });
-
-  return {
-    debug: (msg, meta) => log.debug(meta, msg),
-    info: (msg, meta) => log.info(meta, msg),
-    warn: (msg, meta) => log.warn(meta, msg),
-    error: (msg, err, meta) => log.error({ ...meta, err }, msg),
-  };
-}
-```
-
----
-
-## Log Levels
-
-Supported log levels (in order of severity):
-
-1. `debug` - Detailed diagnostic information
-2. `info` - Informational messages (default)
-3. `warn` - Warning messages
-4. `error` - Error messages
-
-**Level filtering:**
-
-```typescript
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: 'warn', // Only warn and error will be logged
-});
-
-logger.debug('This will not appear');
-logger.info('This will not appear');
-logger.warn('This will appear');
-logger.error('This will appear');
-```
-
----
-
-## Common Patterns
-
-### Per-Request Logging
-
-```typescript
-app.use((req, res, next) => {
-  const requestLogger = toStructuredLogger(logger, {
-    requestId: req.id,
-    method: req.method,
-    path: req.path,
-  });
-
-  req.logger = requestLogger;
-  next();
-});
-
-// In route handler
-req.logger.info('Processing request'); // Includes requestId, method, path
-```
-
-### Service-Level Logging
-
-```typescript
-class InventoryService {
-  private logger: Logger;
-
-  constructor(logger: Logger) {
-    this.logger = toStructuredLogger(logger, {
-      service: 'InventoryService',
-      correlationId: generateCorrelationId(),
-    });
-  }
-
-  async syncInventory(location: string) {
-    this.logger.info('Starting sync', { location });
-
-    try {
-      // Process...
-      this.logger.info('Sync complete', { location, itemsProcessed: 100 });
-    } catch (error) {
-      this.logger.error('Sync failed', error, { location });
-      throw error;
-    }
-  }
-}
-```
-
-### Error Handling
-
-```typescript
-try {
-  await processFile(file);
-} catch (error) {
-  // ✅ GOOD - Pass Error object
-  logger.error('Failed to process file', error, { file: file.name });
-
-  // Error details (message, stack) are automatically included
-}
-
-// Multiple error contexts
-try {
-  await apiCall();
-} catch (error) {
-  logger.error('API call failed', error, {
-    endpoint: '/api/inventory',
-    retries: 3,
-    timeout: 5000,
-  });
-}
-```
-
-### Debug Mode
-
-```typescript
-const isDevelopment = process.env.NODE_ENV === 'development';
-
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: isDevelopment ? 'debug' : 'info',
-  environment: process.env.NODE_ENV,
-});
-
-logger.debug('Detailed info', { config }); // Only in development
-logger.info('Processing started'); // Always logged
-```
-
----
-
-## Migration from Old LoggingService
-
-### Before (Old Class-Based Approach)
-
-```typescript
-import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
-
-// Old: LoggingService class (removed)
-const logger = new LoggingService({
-  service: 'MyService',
-  debug: true
-});
-
-logger.info('Processing');
-```
-
-### After (New Function-Based Approach)
-
-```typescript
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: 'info',
-  service: 'MyService',
-});
-
-logger.info('Processing');
-```
-
-**Changes:**
-
-- No `LoggingService` class instantiation
-- Single function call instead of two
-- Config and context merged into one parameter
-- Simpler, more functional approach
-
-**Note:** The old `LoggingService` class has been removed. Use minimal utilities in standalone (Node/Deno) and the native `log` on Versori.
-
----
-
-## Best Practices
-
-### ✅ DO
-
-```typescript
-// Use native Versori log on Versori platform
-const { log } = ctx;
-const client = await createClient(ctx); // Auto-detects Versori context - log is included
-
-// Create logger once per service/workflow
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'InventorySync' });
-
-// Pass Error objects to error()
-logger.error('Failed', error, { context: 'value' });
-
-// Include relevant context
-logger.info('Processing file', { file, size, location });
-
-// Use correlation IDs for request tracking
-const correlationId = generateCorrelationId();
-```
-
-### ❌ DON'T
-
-```typescript
-// Versori: use native log
-const { log } = ctx;
-
-// Standalone: use utilities
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'my-workflow',
-  logLevel: 'info',
-});
-```
-
----
-
-## Troubleshooting
-
-### Logs not appearing in Versori
-
-**Problem:** Logs not showing in Versori monitoring dashboard
-
-**Solution:** Use native `log` from context, not wrapped:
-
-```typescript
-// ❌ Wrong
-const logging = ctx.log;
-
-// ✅ Right
-const { log } = ctx;
-const client = await createClient(ctx); // Auto-detects Versori context - log is included
-```
-
-### Missing metadata in logs
-
-**Problem:** Context not appearing in log output
-
-**Solution:** Check you're using `toStructuredLogger` with options:
-
-```typescript
-// ❌ No context
-const logger = createConsoleLogger();
-
-// ✅ With context
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'MyService',
-});
-```
-
-### Log level too verbose
-
-**Problem:** Too many debug logs in production
-
-**Solution:** Set appropriate log level:
-
-```typescript
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
-});
-```
-
----
-
-## Summary
-
-- **Versori:** Use native `log` from context
-- **Standalone:** Use `createConsoleLogger()` and `toStructuredLogger()`
-- **Extension:** Implement `Logger` interface for new platforms
-- **Keep it simple:** Pure functions, no state, easy composition
-- **Future-proof:** Easy to extend without breaking changes
-
-The logging system is intentionally minimal - it provides just enough structure for consistency while staying out of your way.
+# Logging Guide
+
+## Overview
+
+The fc-connect-sdk provides minimal logging utilities designed for flexibility and extensibility. The logging approach differs based on your deployment environment:
+
+- **Versori Platform**: Use native `log` from context (recommended)
+- **Standalone (Node.js/Deno)**: Use SDK's lightweight utilities
+- **Other Platforms**: Implement the `Logger` interface for your platform
+
+## Philosophy
+
+**Keep it simple:**
+
+- No global state
+- No logger caching
+- Pure functions over classes
+- Platform-agnostic interface
+- Easy to extend
+
+The SDK provides just two core functions for standalone environments, while Versori users should use the platform's native logger directly.
+
+---
+
+## Quick Start
+
+### Versori Platform (Recommended)
+
+**Always use the native `log` from context** - don't wrap it:
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const workflow = schedule('daily-sync', '0 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); // Auto-detects Versori context
+    const sftp = new SftpDataSource(config, log);
+
+    log.info('Processing started', { workflow: 'daily-sync' });
+
+    try {
+      const files = await sftp.listFiles({ directory: '/inbound' });
+      log.info('Files found', { count: files.length });
+
+      // Process files...
+
+      log.info('Processing complete', { filesProcessed: files.length });
+    } catch (error) {
+      log.error('Processing failed', error);
+      throw error;
+    }
+  })
+);
+```
+
+**Why native log?**
+
+- Automatically flows to Versori monitoring dashboard
+- Includes execution context
+- No overhead
+- Simpler code
+
+### Standalone Node.js/Deno
+
+**Use the SDK's minimal utilities:**
+
+```typescript
+import {
+  createClient,
+  createConsoleLogger,
+  toStructuredLogger,
+  generateCorrelationId,
+  SftpDataSource,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// 1. Create a console logger
+const logger = createConsoleLogger();
+logger.info('Application started');
+
+// 2. Or wrap with context for richer logs
+const contextLogger = toStructuredLogger(logger, {
+  service: 'InventorySync',
+  correlationId: generateCorrelationId(),
+  logLevel: 'debug',
+});
+
+contextLogger.info('Processing file', { file: 'data.csv' });
+// Output: [2025-01-27T10:00:00.000Z] [INFO] Processing file
+//         {"service":"InventorySync","correlationId":"...","file":"data.csv"}
+
+// 3. Pass to SDK services
+const client = await createClient({
+  config: config,
+  logger: contextLogger,
+});
+const sftp = new SftpDataSource(sftpConfig, contextLogger);
+```
+
+**Note:** `createClient` automatically logs client creation success/failure when a logger is provided.
+
+---
+
+## Core Functions
+
+### `createConsoleLogger()`
+
+Creates a simple console-based logger for standalone environments.
+
+**Signature:**
+
+```typescript
+function createConsoleLogger(): Logger;
+```
+
+**Output format:** `[timestamp] [LEVEL] message metadata`
+
+**Example:**
+
+```typescript
+const logger = createConsoleLogger();
+
+logger.info('Processing started', { file: 'inventory.csv' });
+// [2025-01-27T10:00:00.000Z] [INFO] Processing started {"file":"inventory.csv"}
+
+logger.error('Failed to parse', new Error('Invalid CSV'), { line: 42 });
+// [2025-01-27T10:00:00.000Z] [ERROR] Failed to parse {"line":42}
+// Error: Invalid CSV
+//     at <stack trace>
+```
+
+### `toStructuredLogger()`
+
+Wraps a logger with base context that will be merged into all log calls.
+
+**Signature:**
+
+```typescript
+function toStructuredLogger(rootLogger: Logger, options?: LoggerConfig & LogContext): Logger;
+```
+
+**Parameters:**
+
+- `rootLogger`: The underlying logger implementation
+- `options`: Configuration and context in a single object
+  - Config: `logLevel`, `includeTimestamp`, `debugMode`
+  - Context: `service`, `correlationId`, `workflow`, or any custom keys
+
+**Context hierarchy:** `baseContext` → `per-message metadata`
+
+**Example:**
+
+```typescript
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'S3Ingestion',
+  correlationId: generateCorrelationId(),
+  logLevel: 'debug',
+  environment: 'production',
+});
+
+logger.info('File processed', { file: 'data.csv', size: 1024 });
+// All logs include: service, correlationId, environment + per-message metadata
+```
+
+### `generateCorrelationId()`
+
+Generates a unique correlation ID for tracking requests across logs.
+
+**Signature:**
+
+```typescript
+function generateCorrelationId(): string;
+```
+
+**Format:** `{timestamp}-{random}` (e.g., "1706356800000-k9f3x2p1q")
+
+**Example:**
+
+```typescript
+const correlationId = generateCorrelationId();
+// "1706356800000-k9f3x2p1q"
+
+const logger = toStructuredLogger(createConsoleLogger(), {
+  correlationId,
+  service: 'OrderProcessor',
+});
+```
+
+---
+
+## Logger Interface
+
+All loggers implement this simple interface:
+
+```typescript
+interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+}
+```
+
+**Key points:**
+
+- `error()` accepts an optional `Error` object as the second parameter
+- Metadata is always optional
+- Platform-agnostic - works everywhere
+
+---
+
+## Extending for New Platforms
+
+### Vercel Edge Functions
+
+```typescript
+import { Logger } from '@fluentcommerce/fc-connect-sdk';
+
+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),
+  };
+}
+
+// Usage
+export default async function handler(req: Request) {
+  const logger = toStructuredLogger(createVercelLogger(), {
+    edge: 'iad1',
+    requestId: req.headers.get('x-vercel-id'),
+  });
+
+  logger.info('Request received', { url: req.url });
+  // Process...
+}
+```
+
+### Cloudflare Workers
+
+```typescript
+function createCloudflareLogger(env: Env): 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,
+          stack: err?.stack,
+        })
+      ),
+  };
+}
+
+// Usage
+export default {
+  async fetch(request: Request, env: Env) {
+    const logger = toStructuredLogger(createCloudflareLogger(env), {
+      worker: 'inventory-sync',
+      rayId: request.headers.get('cf-ray'),
+    });
+
+    logger.info('Worker invoked');
+    // Process...
+  },
+};
+```
+
+### Third-party Loggers (Pino, Winston, Bunyan)
+
+#### Pino
+
+```typescript
+import pino from 'pino';
+
+function createPinoLogger(options?: pino.LoggerOptions): Logger {
+  const log = pino(options);
+  return {
+    debug: (msg, meta) => log.debug(meta, msg),
+    info: (msg, meta) => log.info(meta, msg),
+    warn: (msg, meta) => log.warn(meta, msg),
+    error: (msg, err, meta) => log.error({ ...meta, err }, msg),
+  };
+}
+
+// Usage with context
+const logger = toStructuredLogger(createPinoLogger(), {
+  service: 'api-gateway',
+  version: '2.0.0',
+});
+```
+
+#### Winston
+
+```typescript
+import winston from 'winston';
+
+function createWinstonLogger(): Logger {
+  const log = winston.createLogger({
+    format: winston.format.json(),
+    transports: [new winston.transports.Console()],
+  });
+
+  return {
+    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 }),
+  };
+}
+```
+
+#### Bunyan
+
+```typescript
+import bunyan from 'bunyan';
+
+function createBunyanLogger(name: string): Logger {
+  const log = bunyan.createLogger({ name });
+
+  return {
+    debug: (msg, meta) => log.debug(meta, msg),
+    info: (msg, meta) => log.info(meta, msg),
+    warn: (msg, meta) => log.warn(meta, msg),
+    error: (msg, err, meta) => log.error({ ...meta, err }, msg),
+  };
+}
+```
+
+---
+
+## Log Levels
+
+Supported log levels (in order of severity):
+
+1. `debug` - Detailed diagnostic information
+2. `info` - Informational messages (default)
+3. `warn` - Warning messages
+4. `error` - Error messages
+
+**Level filtering:**
+
+```typescript
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: 'warn', // Only warn and error will be logged
+});
+
+logger.debug('This will not appear');
+logger.info('This will not appear');
+logger.warn('This will appear');
+logger.error('This will appear');
+```
+
+---
+
+## Common Patterns
+
+### Per-Request Logging
+
+```typescript
+app.use((req, res, next) => {
+  const requestLogger = toStructuredLogger(logger, {
+    requestId: req.id,
+    method: req.method,
+    path: req.path,
+  });
+
+  req.logger = requestLogger;
+  next();
+});
+
+// In route handler
+req.logger.info('Processing request'); // Includes requestId, method, path
+```
+
+### Service-Level Logging
+
+```typescript
+class InventoryService {
+  private logger: Logger;
+
+  constructor(logger: Logger) {
+    this.logger = toStructuredLogger(logger, {
+      service: 'InventoryService',
+      correlationId: generateCorrelationId(),
+    });
+  }
+
+  async syncInventory(location: string) {
+    this.logger.info('Starting sync', { location });
+
+    try {
+      // Process...
+      this.logger.info('Sync complete', { location, itemsProcessed: 100 });
+    } catch (error) {
+      this.logger.error('Sync failed', error, { location });
+      throw error;
+    }
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  await processFile(file);
+} catch (error) {
+  // ✅ GOOD - Pass Error object
+  logger.error('Failed to process file', error, { file: file.name });
+
+  // Error details (message, stack) are automatically included
+}
+
+// Multiple error contexts
+try {
+  await apiCall();
+} catch (error) {
+  logger.error('API call failed', error, {
+    endpoint: '/api/inventory',
+    retries: 3,
+    timeout: 5000,
+  });
+}
+```
+
+### Debug Mode
+
+```typescript
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: isDevelopment ? 'debug' : 'info',
+  environment: process.env.NODE_ENV,
+});
+
+logger.debug('Detailed info', { config }); // Only in development
+logger.info('Processing started'); // Always logged
+```
+
+---
+
+## Migration from Old LoggingService
+
+### Before (Old Class-Based Approach)
+
+```typescript
+import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
+
+// Old: LoggingService class (removed)
+const logger = new LoggingService({
+  service: 'MyService',
+  debug: true
+});
+
+logger.info('Processing');
+```
+
+### After (New Function-Based Approach)
+
+```typescript
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: 'info',
+  service: 'MyService',
+});
+
+logger.info('Processing');
+```
+
+**Changes:**
+
+- No `LoggingService` class instantiation
+- Single function call instead of two
+- Config and context merged into one parameter
+- Simpler, more functional approach
+
+**Note:** The old `LoggingService` class has been removed. Use minimal utilities in standalone (Node/Deno) and the native `log` on Versori.
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+```typescript
+// Use native Versori log on Versori platform
+const { log } = ctx;
+const client = await createClient(ctx); // Auto-detects Versori context - log is included
+
+// Create logger once per service/workflow
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'InventorySync' });
+
+// Pass Error objects to error()
+logger.error('Failed', error, { context: 'value' });
+
+// Include relevant context
+logger.info('Processing file', { file, size, location });
+
+// Use correlation IDs for request tracking
+const correlationId = generateCorrelationId();
+```
+
+### ❌ DON'T
+
+```typescript
+// Versori: use native log
+const { log } = ctx;
+
+// Standalone: use utilities
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'my-workflow',
+  logLevel: 'info',
+});
+```
+
+---
+
+## Troubleshooting
+
+### Logs not appearing in Versori
+
+**Problem:** Logs not showing in Versori monitoring dashboard
+
+**Solution:** Use native `log` from context, not wrapped:
+
+```typescript
+// ❌ Wrong
+const logging = ctx.log;
+
+// ✅ Right
+const { log } = ctx;
+const client = await createClient(ctx); // Auto-detects Versori context - log is included
+```
+
+### Missing metadata in logs
+
+**Problem:** Context not appearing in log output
+
+**Solution:** Check you're using `toStructuredLogger` with options:
+
+```typescript
+// ❌ No context
+const logger = createConsoleLogger();
+
+// ✅ With context
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'MyService',
+});
+```
+
+### Log level too verbose
+
+**Problem:** Too many debug logs in production
+
+**Solution:** Set appropriate log level:
+
+```typescript
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+});
+```
+
+---
+
+## Summary
+
+- **Versori:** Use native `log` from context
+- **Standalone:** Use `createConsoleLogger()` and `toStructuredLogger()`
+- **Extension:** Implement `Logger` interface for new platforms
+- **Keep it simple:** Pure functions, no state, easy composition
+- **Future-proof:** Easy to extend without breaking changes
+
+The logging system is intentionally minimal - it provides just enough structure for consistency while staying out of your way.