@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/architecture/architecture-02-client-architecture.md

@@ -1,424 +1,424 @@
-# Client Architecture
-
-This document explains how the FC Connect SDK handles client creation, authentication, and runtime detection.
-
-## Overview
-
-The SDK provides a **universal client factory** that automatically detects your runtime environment and creates the appropriate client with the correct authentication mechanism.
-
-**Key Features:**
-
-- Versori client parity: GraphQL auto-pagination, pagination-field stripping, aligned endpoints (sendBatch POST, status endpoints), retry/backoff for 5xx, and `validateWebhook()`.
-- Logging: Use function-based utilities for Node/Deno; use native logs on Versori. Pass the platform log directly to SDK services.
-
-## Client Creation Flow
-
-```mermaid
-flowchart TD
-    START[Your Code Calls createClient] --> DETECT{Detect Runtime Context}
-
-    DETECT -->|Versori Platform| VERSORI[Create FluentVersoriClient]
-    DETECT -->|Node.js/Deno| STANDALONE[Create FluentClient]
-
-    VERSORI --> VERSORI_AUTH[Use Platform Connection Auth]
-    STANDALONE --> OAUTH[Use OAuth2 Authentication]
-
-    VERSORI_AUTH --> CLIENT1[FluentVersoriClient Instance]
-    OAUTH --> CLIENT2[FluentClient Instance]
-
-    CLIENT1 --> SHARED[Shared Service Layer]
-    CLIENT2 --> SHARED
-
-    SHARED --> API[Fluent Commerce API]
-
-    style START fill:#e3f2fd
-    style DETECT fill:#fff4e6
-    style VERSORI fill:#f3e5f5
-    style STANDALONE fill:#e8f5e9
-    style SHARED fill:#e1f5ff
-    style API fill:#ffebee
-```
-
-## Context Detection
-
-The SDK detects **2 context patterns**:
-
-```mermaid
-graph TB
-    FACTORY[createClient Factory]
-
-    subgraph "Context Types"
-        VERSORI_HTTP[Versori HTTP Context<br/>Has: fetch, log, activation<br/>Optional: baseUrl, data<br/>No: config]
-        DIRECT_CONFIG[Direct Config<br/>Has: config, logger<br/>No: fetch]
-    end
-
-    FACTORY --> CHECK{Has fetch?<br/>No config?}
-    
-    CHECK -->|Yes| VERSORI_HTTP
-    CHECK -->|No| DIRECT_CONFIG
-
-    VERSORI_HTTP --> FVC[FluentVersoriClient<br/>Platform Auth]
-    DIRECT_CONFIG --> FC[FluentClient<br/>OAuth2]
-
-    style FACTORY fill:#fff4e6
-    style FVC fill:#f3e5f5
-    style FC fill:#e8f5e9
-```
-
-**Detection Logic:**
-- **Versori Platform**: `'fetch' in context && !('config' in context)` → `FluentVersoriClient`
-- **Standalone (Node.js/Deno)**: `'config' in context` → `FluentClient`
-
-**Note:** The factory doesn't distinguish between Node.js and Deno environments - both use the same `{ config }` context pattern. The distinction is that Deno uses `Deno.env` instead of `process.env`, but the factory doesn't check this directly.
-
-## Client Types
-
-### FluentClient (OAuth2)
-
-Used for standalone Node.js and Deno applications.
-
-```mermaid
-sequenceDiagram
-    participant App
-    participant FluentClient
-    participant AuthService
-    participant FluentAPI
-
-    App->>FluentClient: createClient(config)
-    FluentClient->>AuthService: Initialize OAuth2
-    App->>FluentClient: getBatchStatus(jobId)
-    FluentClient->>AuthService: Get access token
-    AuthService->>FluentAPI: POST /oauth/token
-    FluentAPI-->>AuthService: Access token
-    AuthService-->>FluentClient: Token
-    FluentClient->>FluentAPI: GET /batch/status
-    FluentAPI-->>FluentClient: Batch data
-    FluentClient-->>App: Batch status
-```
-
-**Key Features:**
-
-- OAuth2 client credentials flow
-- Automatic token refresh
-- Retry logic with exponential backoff
-- Environment variable configuration
-
-**Configuration:**
-
-```typescript
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-});
-```
-
-### FluentVersoriClient (Platform Auth)
-
-Used within the Versori platform with connection-based authentication.
-
-```mermaid
-sequenceDiagram
-    participant Versori
-    participant FluentVersoriClient
-    participant Connection
-    participant FluentAPI
-
-    Versori->>FluentVersoriClient: createClient(ctx)
-    FluentVersoriClient->>Connection: Use platform connection
-    Versori->>FluentVersoriClient: getBatchStatus(jobId)
-    FluentVersoriClient->>Connection: Get authenticated fetch
-    Connection-->>FluentVersoriClient: ctx.fetch (pre-authenticated)
-    FluentVersoriClient->>FluentAPI: GET /batch/status
-    FluentAPI-->>FluentVersoriClient: Batch data
-    FluentVersoriClient-->>Versori: Batch status
-```
-
-**Key Features:**
-
-- Platform-managed authentication (no manual OAuth2)
-- Automatic logging integration
-- KV storage support for state management
-- Connection-based configuration
-
-**Configuration:**
-
-```typescript
-// Prefer the universal factory on Versori
-const client = await createClient(context);
-```
-
-## Authentication Flow
-
-### OAuth2 Flow (FluentClient)
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant AuthService
-    participant TokenCache
-    participant FluentAPI
-
-    Client->>AuthService: getAccessToken()
-    AuthService->>TokenCache: Check cached token
-
-    alt Token Valid
-        TokenCache-->>AuthService: Return cached token
-    else Token Expired or Missing
-        AuthService->>FluentAPI: POST /oauth/token
-        FluentAPI-->>AuthService: New access token
-        AuthService->>TokenCache: Cache token
-    end
-
-    AuthService-->>Client: Access token
-    Client->>FluentAPI: API request with Bearer token
-    FluentAPI-->>Client: Response
-```
-
-**Token Management:**
-
-- Tokens cached in memory
-- Automatic refresh before expiration
-- Thread-safe token renewal
-- Configurable token endpoint
-
-### Platform Auth Flow (FluentVersoriClient)
-
-```mermaid
-sequenceDiagram
-    participant Workflow
-    participant FluentVersoriClient
-    participant VersoriPlatform
-    participant FluentAPI
-
-    VersoriPlatform->>Workflow: Trigger workflow
-    Workflow->>FluentVersoriClient: Create client from connection
-    FluentVersoriClient->>VersoriPlatform: Get authenticated fetch
-    VersoriPlatform-->>FluentVersoriClient: ctx.fetch (pre-authenticated)
-    FluentVersoriClient->>FluentAPI: API request (platform handles auth)
-    FluentAPI-->>FluentVersoriClient: Response
-```
-
-**Platform Benefits:**
-
-- No manual credential management
-- Automatic token rotation
-- Centralized connection configuration
-- Built-in security compliance
-
-## Shared Service Layer
-
-Both client types use the same underlying service implementations:
-
-```mermaid
-graph TB
-    subgraph "Client Layer"
-        FC[FluentClient]
-        FVC[FluentVersoriClient]
-    end
-
-    subgraph "Shared Services"
-        BATCH[FluentBatchManager]
-        MAPPER[UniversalMapper]
-        STATE[StateService]
-        S3[S3Service]
-    end
-
-    FC --> BATCH
-    FC --> MAPPER
-    FVC --> BATCH
-    FVC --> MAPPER
-
-    BATCH --> STATE
-    MAPPER --> STATE
-
-    style FC fill:#e8f5e9
-    style FVC fill:#f3e5f5
-    style BATCH fill:#e3f2fd
-    style MAPPER fill:#fff3e0
-    style STATE fill:#e8f5e9
-    style S3 fill:#ffebee
-```
-
-**Why This Matters:**
-
-- Write code once, run anywhere (Node.js, Deno, Versori)
-- Consistent behavior across environments
-- Shared testing and validation
-- Easier maintenance
-
-## Runtime Compatibility
-
-```mermaid
-graph LR
-    SDK[FC Connect SDK]
-
-    subgraph "Node.js Runtime"
-        NODE_FC[FluentClient]
-        NODE_SERVICES[All Services]
-        NODE_AUTH[OAuth2 Auth]
-    end
-
-    subgraph "Deno Runtime"
-        DENO_FC[FluentClient]
-        DENO_SERVICES[All Services]
-        DENO_AUTH[OAuth2 Auth]
-    end
-
-    subgraph "Versori Platform"
-        VERSORI_FVC[FluentVersoriClient]
-        VERSORI_SERVICES[All Services]
-        VERSORI_AUTH[Platform Auth]
-        VERSORI_KV[KV Storage]
-    end
-
-    SDK --> NODE_FC
-    SDK --> DENO_FC
-    SDK --> VERSORI_FVC
-
-    NODE_FC --> NODE_SERVICES
-    NODE_SERVICES --> NODE_AUTH
-
-    DENO_FC --> DENO_SERVICES
-    DENO_SERVICES --> DENO_AUTH
-
-    VERSORI_FVC --> VERSORI_SERVICES
-    VERSORI_SERVICES --> VERSORI_AUTH
-    VERSORI_SERVICES --> VERSORI_KV
-
-    style SDK fill:#e3f2fd
-    style NODE_FC fill:#e8f5e9
-    style DENO_FC fill:#fff3e0
-    style VERSORI_FVC fill:#f3e5f5
-```
-
-**Compatibility Matrix:**
-
-| Feature       | Node.js     | Deno        | Versori                 |
-| ------------- | ----------- | ----------- | ----------------------- |
-| OAuth2 Auth   | ✅          | ✅          | ❌ (uses platform auth) |
-| Platform Auth | ❌          | ❌          | ✅                      |
-| All Services  | ✅          | ✅          | ✅                      |
-| KV Storage    | ⚠️ (custom) | ⚠️ (custom) | ✅ (built-in)           |
-| Logging       | Console     | Console     | Platform                |
-| Build Output  | CJS/ESM     | ESM         | ESM                     |
-
-## Best Practices
-
-### 1. Always Use the Factory
-
-```typescript
-// ✅ CORRECT - Auto-detects context
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-const client = await createClient(ctx); // Pass Versori context directly
-
-// ❌ WRONG - Bypasses context detection (do not use)
-// import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-// const client = new FluentClient(config);
-
-// ✅ CORRECT - Use universal factory
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-const client = await createClient({ config });
-```
-
-### 2. Environment-Specific Configuration
-
-```typescript
-// Node.js/Deno - Use environment variables
-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,
-  },
-});
-
-// Versori - Use platform context
-const client = await createClient(ctx);
-```
-
-### 3. Error Handling
-
-```typescript
-try {
-  const client = await createClient({ config });
-  const job = await client.createJob({ name: 'inventory-sync' });
-} catch (error) {
-  if ((error as Error).message.includes('authentication')) {
-    // Handle auth errors
-  } else if ((error as Error).message.includes('network')) {
-    // Handle network errors
-  }
-}
-```
-
-**Note:** `createClient` automatically logs success/failure when a logger is provided (uses `ctx.log` on Versori, `logger` property for standalone apps).
-
-**Connection Validation:** Use `{ validateConnection: true }` option to validate authentication immediately:
-```typescript
-// Fail fast - validates credentials on creation
-const client = await createClient({ config }, { validateConnection: true });
-```
-When enabled, executes `query { me { ref } }` to verify authentication. Default: `false` (fast creation, validation on first API call).
-
-## Client Method Categories
-
-### Core Client Methods
-
-- `graphql(payload)` - Execute query or mutation (auto-pagination for queries)
-- `query(queryOrPayload, variables?)` - Convenience query helper
-- `mutate(mutationOrPayload, variables?)` - Convenience mutation helper
-- `sendEvent(event, mode?)` - Send Fluent event (sync/async)
-
-### Retailer Management
-
-- `setRetailerId(retailerId)` - Set retailer ID for API requests
-- `getRetailerId()` - Get current retailer ID
-
-### Job & Batch
-
-- `createJob(payload)` - Create batch job
-- `sendBatch(jobId, payload)` - Submit batch to job
-- `getJobStatus(jobId)` - Poll job status
-- `getBatchStatus(jobId, batchId)` - Poll batch status
-- `getJobResults(jobId)` - Fetch job results
-
-### Webhook Validation
-
-- `validateWebhook(payload, signature?, rawPayload?)` - Validate Fluent webhook signatures with HMAC-SHA256. Returns `Promise<boolean>`.
-
-**Example:**
-
-```typescript
-// Basic validation (no signature)
-const isValid = await client.validateWebhook(payload);
-
-// With signature validation
-const isValid = await client.validateWebhook(
-  payload,
-  request.headers['x-fluent-signature'],
-  rawRequestBody
-);
-
-if (!isValid) {
-  throw new Error('Invalid webhook signature');
-}
-
-// Process validated webhook
-console.log('Event type:', payload.name);
-```
-
-### Static Factory Methods
-
-- `FluentClient.fromVersoriConnection(connection, logger, context?)` - Create FluentClient from Versori connection object (useful when you have explicit connection references)
-- `FluentVersoriClient.fromContext(context)` - Create Versori client from Versori HTTP context
-
-## Next Steps
-
-- [Data Flow Architecture](./architecture-03-data-flow.md) - Understand data processing flows
-- [Service Layer](./architecture-04-service-layer.md) - Explore service organization
-- [Getting Started Guide](../../00-START-HERE/getting-started.md) - Start building
+# Client Architecture
+
+This document explains how the FC Connect SDK handles client creation, authentication, and runtime detection.
+
+## Overview
+
+The SDK provides a **universal client factory** that automatically detects your runtime environment and creates the appropriate client with the correct authentication mechanism.
+
+**Key Features:**
+
+- Versori client parity: GraphQL auto-pagination, pagination-field stripping, aligned endpoints (sendBatch POST, status endpoints), retry/backoff for 5xx, and `validateWebhook()`.
+- Logging: Use function-based utilities for Node/Deno; use native logs on Versori. Pass the platform log directly to SDK services.
+
+## Client Creation Flow
+
+```mermaid
+flowchart TD
+    START[Your Code Calls createClient] --> DETECT{Detect Runtime Context}
+
+    DETECT -->|Versori Platform| VERSORI[Create FluentVersoriClient]
+    DETECT -->|Node.js/Deno| STANDALONE[Create FluentClient]
+
+    VERSORI --> VERSORI_AUTH[Use Platform Connection Auth]
+    STANDALONE --> OAUTH[Use OAuth2 Authentication]
+
+    VERSORI_AUTH --> CLIENT1[FluentVersoriClient Instance]
+    OAUTH --> CLIENT2[FluentClient Instance]
+
+    CLIENT1 --> SHARED[Shared Service Layer]
+    CLIENT2 --> SHARED
+
+    SHARED --> API[Fluent Commerce API]
+
+    style START fill:#e3f2fd
+    style DETECT fill:#fff4e6
+    style VERSORI fill:#f3e5f5
+    style STANDALONE fill:#e8f5e9
+    style SHARED fill:#e1f5ff
+    style API fill:#ffebee
+```
+
+## Context Detection
+
+The SDK detects **2 context patterns**:
+
+```mermaid
+graph TB
+    FACTORY[createClient Factory]
+
+    subgraph "Context Types"
+        VERSORI_HTTP[Versori HTTP Context<br/>Has: fetch, log, activation<br/>Optional: baseUrl, data<br/>No: config]
+        DIRECT_CONFIG[Direct Config<br/>Has: config, logger<br/>No: fetch]
+    end
+
+    FACTORY --> CHECK{Has fetch?<br/>No config?}
+    
+    CHECK -->|Yes| VERSORI_HTTP
+    CHECK -->|No| DIRECT_CONFIG
+
+    VERSORI_HTTP --> FVC[FluentVersoriClient<br/>Platform Auth]
+    DIRECT_CONFIG --> FC[FluentClient<br/>OAuth2]
+
+    style FACTORY fill:#fff4e6
+    style FVC fill:#f3e5f5
+    style FC fill:#e8f5e9
+```
+
+**Detection Logic:**
+- **Versori Platform**: `'fetch' in context && !('config' in context)` → `FluentVersoriClient`
+- **Standalone (Node.js/Deno)**: `'config' in context` → `FluentClient`
+
+**Note:** The factory doesn't distinguish between Node.js and Deno environments - both use the same `{ config }` context pattern. The distinction is that Deno uses `Deno.env` instead of `process.env`, but the factory doesn't check this directly.
+
+## Client Types
+
+### FluentClient (OAuth2)
+
+Used for standalone Node.js and Deno applications.
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant FluentClient
+    participant AuthService
+    participant FluentAPI
+
+    App->>FluentClient: createClient(config)
+    FluentClient->>AuthService: Initialize OAuth2
+    App->>FluentClient: getBatchStatus(jobId)
+    FluentClient->>AuthService: Get access token
+    AuthService->>FluentAPI: POST /oauth/token
+    FluentAPI-->>AuthService: Access token
+    AuthService-->>FluentClient: Token
+    FluentClient->>FluentAPI: GET /batch/status
+    FluentAPI-->>FluentClient: Batch data
+    FluentClient-->>App: Batch status
+```
+
+**Key Features:**
+
+- OAuth2 client credentials flow
+- Automatic token refresh
+- Retry logic with exponential backoff
+- Environment variable configuration
+
+**Configuration:**
+
+```typescript
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+});
+```
+
+### FluentVersoriClient (Platform Auth)
+
+Used within the Versori platform with connection-based authentication.
+
+```mermaid
+sequenceDiagram
+    participant Versori
+    participant FluentVersoriClient
+    participant Connection
+    participant FluentAPI
+
+    Versori->>FluentVersoriClient: createClient(ctx)
+    FluentVersoriClient->>Connection: Use platform connection
+    Versori->>FluentVersoriClient: getBatchStatus(jobId)
+    FluentVersoriClient->>Connection: Get authenticated fetch
+    Connection-->>FluentVersoriClient: ctx.fetch (pre-authenticated)
+    FluentVersoriClient->>FluentAPI: GET /batch/status
+    FluentAPI-->>FluentVersoriClient: Batch data
+    FluentVersoriClient-->>Versori: Batch status
+```
+
+**Key Features:**
+
+- Platform-managed authentication (no manual OAuth2)
+- Automatic logging integration
+- KV storage support for state management
+- Connection-based configuration
+
+**Configuration:**
+
+```typescript
+// Prefer the universal factory on Versori
+const client = await createClient(context);
+```
+
+## Authentication Flow
+
+### OAuth2 Flow (FluentClient)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant AuthService
+    participant TokenCache
+    participant FluentAPI
+
+    Client->>AuthService: getAccessToken()
+    AuthService->>TokenCache: Check cached token
+
+    alt Token Valid
+        TokenCache-->>AuthService: Return cached token
+    else Token Expired or Missing
+        AuthService->>FluentAPI: POST /oauth/token
+        FluentAPI-->>AuthService: New access token
+        AuthService->>TokenCache: Cache token
+    end
+
+    AuthService-->>Client: Access token
+    Client->>FluentAPI: API request with Bearer token
+    FluentAPI-->>Client: Response
+```
+
+**Token Management:**
+
+- Tokens cached in memory
+- Automatic refresh before expiration
+- Thread-safe token renewal
+- Configurable token endpoint
+
+### Platform Auth Flow (FluentVersoriClient)
+
+```mermaid
+sequenceDiagram
+    participant Workflow
+    participant FluentVersoriClient
+    participant VersoriPlatform
+    participant FluentAPI
+
+    VersoriPlatform->>Workflow: Trigger workflow
+    Workflow->>FluentVersoriClient: Create client from connection
+    FluentVersoriClient->>VersoriPlatform: Get authenticated fetch
+    VersoriPlatform-->>FluentVersoriClient: ctx.fetch (pre-authenticated)
+    FluentVersoriClient->>FluentAPI: API request (platform handles auth)
+    FluentAPI-->>FluentVersoriClient: Response
+```
+
+**Platform Benefits:**
+
+- No manual credential management
+- Automatic token rotation
+- Centralized connection configuration
+- Built-in security compliance
+
+## Shared Service Layer
+
+Both client types use the same underlying service implementations:
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        FC[FluentClient]
+        FVC[FluentVersoriClient]
+    end
+
+    subgraph "Shared Services"
+        BATCH[FluentBatchManager]
+        MAPPER[UniversalMapper]
+        STATE[StateService]
+        S3[S3Service]
+    end
+
+    FC --> BATCH
+    FC --> MAPPER
+    FVC --> BATCH
+    FVC --> MAPPER
+
+    BATCH --> STATE
+    MAPPER --> STATE
+
+    style FC fill:#e8f5e9
+    style FVC fill:#f3e5f5
+    style BATCH fill:#e3f2fd
+    style MAPPER fill:#fff3e0
+    style STATE fill:#e8f5e9
+    style S3 fill:#ffebee
+```
+
+**Why This Matters:**
+
+- Write code once, run anywhere (Node.js, Deno, Versori)
+- Consistent behavior across environments
+- Shared testing and validation
+- Easier maintenance
+
+## Runtime Compatibility
+
+```mermaid
+graph LR
+    SDK[FC Connect SDK]
+
+    subgraph "Node.js Runtime"
+        NODE_FC[FluentClient]
+        NODE_SERVICES[All Services]
+        NODE_AUTH[OAuth2 Auth]
+    end
+
+    subgraph "Deno Runtime"
+        DENO_FC[FluentClient]
+        DENO_SERVICES[All Services]
+        DENO_AUTH[OAuth2 Auth]
+    end
+
+    subgraph "Versori Platform"
+        VERSORI_FVC[FluentVersoriClient]
+        VERSORI_SERVICES[All Services]
+        VERSORI_AUTH[Platform Auth]
+        VERSORI_KV[KV Storage]
+    end
+
+    SDK --> NODE_FC
+    SDK --> DENO_FC
+    SDK --> VERSORI_FVC
+
+    NODE_FC --> NODE_SERVICES
+    NODE_SERVICES --> NODE_AUTH
+
+    DENO_FC --> DENO_SERVICES
+    DENO_SERVICES --> DENO_AUTH
+
+    VERSORI_FVC --> VERSORI_SERVICES
+    VERSORI_SERVICES --> VERSORI_AUTH
+    VERSORI_SERVICES --> VERSORI_KV
+
+    style SDK fill:#e3f2fd
+    style NODE_FC fill:#e8f5e9
+    style DENO_FC fill:#fff3e0
+    style VERSORI_FVC fill:#f3e5f5
+```
+
+**Compatibility Matrix:**
+
+| Feature       | Node.js     | Deno        | Versori                 |
+| ------------- | ----------- | ----------- | ----------------------- |
+| OAuth2 Auth   | ✅          | ✅          | ❌ (uses platform auth) |
+| Platform Auth | ❌          | ❌          | ✅                      |
+| All Services  | ✅          | ✅          | ✅                      |
+| KV Storage    | ⚠️ (custom) | ⚠️ (custom) | ✅ (built-in)           |
+| Logging       | Console     | Console     | Platform                |
+| Build Output  | CJS/ESM     | ESM         | ESM                     |
+
+## Best Practices
+
+### 1. Always Use the Factory
+
+```typescript
+// ✅ CORRECT - Auto-detects context
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+const client = await createClient(ctx); // Pass Versori context directly
+
+// ❌ WRONG - Bypasses context detection (do not use)
+// import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+// const client = new FluentClient(config);
+
+// ✅ CORRECT - Use universal factory
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+const client = await createClient({ config });
+```
+
+### 2. Environment-Specific Configuration
+
+```typescript
+// Node.js/Deno - Use environment variables
+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,
+  },
+});
+
+// Versori - Use platform context
+const client = await createClient(ctx);
+```
+
+### 3. Error Handling
+
+```typescript
+try {
+  const client = await createClient({ config });
+  const job = await client.createJob({ name: 'inventory-sync' });
+} catch (error) {
+  if ((error as Error).message.includes('authentication')) {
+    // Handle auth errors
+  } else if ((error as Error).message.includes('network')) {
+    // Handle network errors
+  }
+}
+```
+
+**Note:** `createClient` automatically logs success/failure when a logger is provided (uses `ctx.log` on Versori, `logger` property for standalone apps).
+
+**Connection Validation:** Use `{ validateConnection: true }` option to validate authentication immediately:
+```typescript
+// Fail fast - validates credentials on creation
+const client = await createClient({ config }, { validateConnection: true });
+```
+When enabled, executes `query { me { ref } }` to verify authentication. Default: `false` (fast creation, validation on first API call).
+
+## Client Method Categories
+
+### Core Client Methods
+
+- `graphql(payload)` - Execute query or mutation (auto-pagination for queries)
+- `query(queryOrPayload, variables?)` - Convenience query helper
+- `mutate(mutationOrPayload, variables?)` - Convenience mutation helper
+- `sendEvent(event, mode?)` - Send Fluent event (sync/async)
+
+### Retailer Management
+
+- `setRetailerId(retailerId)` - Set retailer ID for API requests
+- `getRetailerId()` - Get current retailer ID
+
+### Job & Batch
+
+- `createJob(payload)` - Create batch job
+- `sendBatch(jobId, payload)` - Submit batch to job
+- `getJobStatus(jobId)` - Poll job status
+- `getBatchStatus(jobId, batchId)` - Poll batch status
+- `getJobResults(jobId)` - Fetch job results
+
+### Webhook Validation
+
+- `validateWebhook(payload, signature?, rawPayload?)` - Validate Fluent webhook signatures with HMAC-SHA256. Returns `Promise<boolean>`.
+
+**Example:**
+
+```typescript
+// Basic validation (no signature)
+const isValid = await client.validateWebhook(payload);
+
+// With signature validation
+const isValid = await client.validateWebhook(
+  payload,
+  request.headers['x-fluent-signature'],
+  rawRequestBody
+);
+
+if (!isValid) {
+  throw new Error('Invalid webhook signature');
+}
+
+// Process validated webhook
+console.log('Event type:', payload.name);
+```
+
+### Static Factory Methods
+
+- `FluentClient.fromVersoriConnection(connection, logger, context?)` - Create FluentClient from Versori connection object (useful when you have explicit connection references)
+- `FluentVersoriClient.fromContext(context)` - Create Versori client from Versori HTTP context
+
+## Next Steps
+
+- [Data Flow Architecture](./architecture-03-data-flow.md) - Understand data processing flows
+- [Service Layer](./architecture-04-service-layer.md) - Explore service organization
+- [Getting Started Guide](../../00-START-HERE/getting-started.md) - Start building