npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.56 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (476) hide show

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-03-authentication.md CHANGED Viewed

@@ -1,757 +1,757 @@
-# Module 3: Authentication & Connections
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-**Module 3 of 8** | **Level**: Beginner | **Time**: 35 minutes
----
-## Learning Objectives
-By the end of this module, you will:
-- ✅ Understand OAuth2 authentication in Versori
-- ✅ Configure Fluent Commerce connections in Versori UI
-- ✅ Use `createClient()` with Versori context
-- ✅ Understand FluentVersoriClient vs FluentClient
-- ✅ Access connection credentials and metadata
-- ✅ Handle authentication errors
-- ✅ Implement security best practices
----
-## OAuth2 in Versori Platform
-Versori manages OAuth2 credentials securely through **Connections**. Your code never handles raw credentials.
-### Key Benefits
-- **No credential management** in code - Versori handles token storage and refresh
-- **Automatic token refresh** when expired - transparent to your code
-- **Secure storage** in Versori platform - encrypted at rest
-- **Environment-specific** configs (dev/staging/prod) - separate credentials per environment
-- **Audit logging** of API calls - full traceability
-- **Connection reuse** across workflows - configure once, use everywhere
-### How Authentication Works
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Versori Platform                                            │
-│                                                             │
-│  ┌──────────────┐                 ┌──────────────┐        │
-│  │   Workflow   │──ctx.fetch()──→ │  Connection  │        │
-│  │              │                  │   (OAuth2)   │        │
-│  └──────────────┘                 └──────┬───────┘        │
-│                                           │                 │
-└───────────────────────────────────────────┼─────────────────┘
-                                            │
-                                            │ Managed Auth
-                                            ↓
-                              ┌──────────────────────────┐
-                              │   Fluent Commerce API    │
-                              │  (api.fluentcommerce.com)│
-                              └──────────────────────────┘
-```
-**Key Points**:
-1. Workflows use `ctx.fetch()` - Versori injects authentication automatically
-2. Connection stores OAuth2 credentials - client ID, client secret
-3. Platform handles token lifecycle - fetch, refresh, retry on 401
-4. Your code never sees raw credentials - only uses authenticated fetch
----
-## Configuring Fluent Commerce Connection
-### Step 1: Access Connections in Versori UI
-1. Log in to Versori dashboard
-2. Navigate to **Connections** tab (left sidebar)
-3. Click **"Add Connection"** button
-### Step 2: Connection Configuration
-**Basic Details**:
-```
-Name: fluent_commerce
-Description: Fluent Commerce Production API
-Type: Custom OAuth2
-```
-**OAuth2 Settings**:
-```
-Auth URL: https://api.fluentcommerce.com/oauth/token
-Token URL: https://api.fluentcommerce.com/oauth/token
-Grant Type: client_credentials
-```
-**Client Credentials**:
-```
-Client ID: [Your Fluent OAuth2 Client ID]
-Client Secret: [Your Fluent OAuth2 Client Secret]
-```
-**API Configuration**:
-```
-Base URL: https://api.fluentcommerce.com
-```
-**Custom Parameters** (JSON) - **Optional:**
-```json
-{
-  "retailerId": "1"
-}
-```
-**Note:** `retailerId` is only needed if you're using Job API or Event API. For GraphQL queries only, you can omit it. If your Versori version doesn't support Custom Parameters, use `client.setRetailerId('1')` after creating the client.
-**See complete retailerId guide below or:** [Complete retailerId Configuration Guide](../../../../00-START-HERE/retailerid-configuration.md)
-### Step 3: Test Connection
-Click **"Test Connection"** to verify:
-- OAuth2 token can be fetched
-- Base URL is accessible
-- Credentials are correct
----
-## Using createClient() with Versori
-### Basic Usage
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export const workflow = http('name', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // Create client from Versori context
-  const client = await createClient(ctx);
-  // Use client - authentication is automatic
-  const result = await client.graphql({
-    query: `query { products(first: 10) { edges { node { id ref } } } }`
-  });
-  return result.data;
-});
-```
-### What `createClient()` Does
-```typescript
-// Internally, createClient() detects Versori context:
-export async function createClient(ctx: HttpContext): Promise<FluentVersoriClient> {
-  // 1. Detects runtime (Versori vs Node.js/Deno)
-  // 2. Creates appropriate client type
-  // 3. Extracts retailerId from connection variables or URL
-  // 4. Returns configured client
-  return FluentVersoriClient.fromContext(ctx);
-}
-```
-**Key Detection Logic**:
-- Checks for `ctx.fetch` (Versori-specific)
-- Checks for `ctx.log` (Versori logging)
-- Checks for `ctx.baseUrl` (connection base URL)
-- Falls back to standalone mode if not Versori
----
-## FluentVersoriClient vs FluentClient
-### Architecture Comparison
-| Feature | FluentVersoriClient | FluentClient |
-|---------|---------------------|--------------|
-| **Runtime** | Versori platform only | Node.js, Deno, standalone |
-| **Authentication** | Platform-managed (ctx.fetch) | Manual OAuth2 (clientId/secret) |
-| **Token Management** | Automatic (Versori) | Manual (AuthService) |
-| **Base URL** | From connection config | Passed in constructor |
-| **Fetch Implementation** | `ctx.fetch()` (Versori) | `fetch()` (standard) |
-| **Logging** | `ctx.log` (platform) | Custom logger or console |
-| **KV Storage** | `ctx.openKv()` available | External KV required |
-### When to Use Each
-**Use FluentVersoriClient** (via `createClient(ctx)`):
-- ✅ Running on Versori platform (webhooks, scheduled, HTTP workflows)
-- ✅ Want automatic authentication
-- ✅ Need Versori KV storage integration
-- ✅ Platform logging required
-**Use FluentClient** (standalone):
-- ✅ Running Node.js scripts locally
-- ✅ Running in Deno
-- ✅ Custom environments (Lambda, Docker, etc.)
-- ✅ Testing with mock credentials
-### Code Example: Both Approaches
-```typescript
-// ✅ Versori Platform (FluentVersoriClient via createClient)
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export const versoriWorkflow = http('versori', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const client = await createClient(ctx);  // Auto-detects Versori
-  return await client.graphql({ query: '...' });
-});
-// ✅ Standalone Node.js (FluentClient directly)
-import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-const client = new FluentClient({
-  baseUrl: 'https://api.fluentcommerce.com',
-  clientId: process.env.FLUENT_CLIENT_ID!,
-  clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-  username: process.env.FLUENT_USERNAME,
-  password: process.env.FLUENT_PASSWORD,
-  retailerId: '1'
-});
-const result = await client.graphql({ query: '...' });
-```
----
-## Accessing Connection Credentials
-### Connection Variables
-Versori connections can store custom variables accessible in workflows:
-```typescript
-import { http } from '@versori/run';
-export const accessConnectionVars = http('access-vars', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // Access connection variables
-  const connectionVars = ctx.connectionVariables || {};
-  const retailerId = connectionVars.retailerId || '1';
-  const environment = connectionVars.environment || 'production';
-  ctx.log('info', 'Connection variables', {
-    retailerId,
-    environment
-  });
-  return { retailerId, environment };
-});
-```
-### Base URL Access
-```typescript
-export const accessBaseUrl = http('access-url', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // Base URL may be a Promise
-  const baseUrl = await ctx.baseUrl;
-  ctx.log('info', 'Connection base URL', { baseUrl });
-  return { baseUrl };
-});
-```
-### Retailer ID Extraction
-The SDK automatically extracts retailer ID from:
-1. **Connection variables** (highest priority):
-   ```json
-   { "retailerId": "1" }
-   ```
-2. **URL path** (fallback):
-   ```
-   https://api.fluentcommerce.com/graphql/1
-                                      ↑
-                                  retailerId
-   ```
-3. **Manual override**:
-   ```typescript
-   const client = await createClient(ctx);
-   client.setRetailerId('2');  // Override if needed
-   ```
----
-## retailerId Configuration (v0.1.30+)
-Starting with v0.1.30, `retailerId` is **optional** for GraphQL queries but **required** for Job and Event APIs.
-### When retailerId is Required
-| API Type | retailerId Required? | Validation |
-|----------|---------------------|------------|
-| GraphQL Queries (`client.graphql()`) | ❌ Optional | Not validated |
-| GraphQL Mutations (`client.graphql()`) | ❌ Optional | Not validated |
-| Job API (`createJob()`, `getJob()`) | ✅ Required | Fail-fast at method call |
-| Event API (`sendEvent()`) | ✅ Required | Fail-fast at method call |
-| Batch API (`sendBatch()`) | ✅ Required | Fail-fast at method call |
-### Configuration Patterns
-**Option 1: Set at Client Creation (Recommended)**
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export const inventorySync = http('POST', '/sync', async (ctx) => {
-  // retailerId set once at client creation
-  const client = await createClient({
-    context: ctx,
-    retailerId: ctx.connectionVariables?.RETAILER_ID,
-  });
-  // Works for all APIs
-  await client.createJob({ name: 'inventory-sync' });
-  await client.graphql({ query: '...' });
-  return { success: true };
-});
-```
-**Option 2: Set Dynamically (Multi-Tenant)**
-```typescript
-export const multiTenantSync = http('POST', '/sync/:retailerId', async (ctx) => {
-  const client = await createClient({ context: ctx });
-  // Set retailerId from URL parameter
-  const retailerId = ctx.params?.retailerId;
-  client.setRetailerId(retailerId);
-  await client.createJob({ name: 'inventory-sync' });
-  return { success: true };
-});
-```
-**Option 3: No retailerId (GraphQL Only)**
-```typescript
-export const queryProducts = http('POST', '/query', async (ctx) => {
-  // No retailerId needed for GraphQL queries
-  const client = await createClient({ context: ctx });
-  const result = await client.graphql({
-    query: `query { products { edges { node { id ref } } } }`
-  });
-  return result.data;
-});
-```
-### Error Handling
-```typescript
-export const withRetailerIdValidation = http('POST', '/sync', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  try {
-    const client = await createClient({ context: ctx });
-    // Try to call Job API
-    const job = await client.createJob({ name: 'inventory-sync' });
-    return { success: true, jobId: job.id };
-  } catch (error) {
-    if (error instanceof Error && error.message.includes('retailerId is required')) {
-      // Handle missing retailerId
-      ctx.log('error', 'retailerId not configured', {
-        error: error.message
-      });
-      return {
-        success: false,
-        error: 'retailerId configuration missing',
-        details: 'Configure retailerId in connection variables or use client.setRetailerId()'
-      };
-    }
-    throw error; // Re-throw other errors
-  }
-});
-```
-**See Also:** [Complete retailerId Configuration Guide](../../../../00-START-HERE/retailerid-configuration.md) for all patterns and use cases.
----
-## Authentication Error Handling
-### Common Authentication Errors
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export const errorHandling = http('error-handling', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  try {
-    const client = await createClient(ctx);
-    const result = await client.graphql({
-      query: `query { products(first: 10) { edges { node { id } } } }`
-    });
-    return { success: true, data: result.data };
-  } catch (error) {
-    // Log error details
-    ctx.log('error', 'GraphQL request failed', {
-      error: error instanceof Error ? error.message : String(error),
-      name: error instanceof Error ? error.name : 'Unknown'
-    });
-    // Check error type
-    if (error instanceof Error) {
-      // Authentication errors
-      if (error.message.includes('401') || error.message.includes('Unauthorized')) {
-        return {
-          success: false,
-          error: 'Authentication failed - check connection credentials',
-          retryable: false
-        };
-      }
-      // Token refresh errors
-      if (error.message.includes('token') || error.message.includes('expired')) {
-        return {
-          success: false,
-          error: 'Token expired - Versori will retry automatically',
-          retryable: true
-        };
-      }
-      // Network errors
-      if (error.message.includes('ECONNREFUSED') || error.message.includes('timeout')) {
-        return {
-          success: false,
-          error: 'Network error - Fluent API unreachable',
-          retryable: true
-        };
-      }
-    }
-    // Generic error response
-    return {
-      success: false,
-      error: 'Request failed',
-      details: error instanceof Error ? error.message : String(error)
-    };
-  }
-});
-```
-### Error Response Patterns
-| HTTP Status | Meaning | Versori Behavior | Your Action |
-|-------------|---------|------------------|-------------|
-| **401** | Unauthorized | Refreshes token, retries | Log error if retry fails |
-| **403** | Forbidden | No retry | Check retailerId, permissions |
-| **429** | Rate limited | Retries with backoff | Reduce request rate |
-| **500** | Server error | May retry | Log for investigation |
-| **503** | Service unavailable | Retries | Wait for service recovery |
----
-## Token Management (Versori)
-### Automatic Token Refresh
-Versori handles token lifecycle automatically:
-```typescript
-// You write this:
-const result = await client.graphql({ query: '...' });
-// Versori does this behind the scenes:
-// 1. Check if token exists and is valid
-// 2. If expired, fetch new token from OAuth2 endpoint
-// 3. Retry original request with fresh token
-// 4. Return result to your code
-```
-**No manual token management needed!**
-### Token Debugging
-If authentication fails, check Versori logs:
-```typescript
-export const debugAuth = http('debug-auth', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  ctx.log('info', 'Connection details', {
-    hasBaseUrl: !!ctx.baseUrl,
-    hasFetch: typeof ctx.fetch === 'function',
-    hasLog: typeof ctx.log === 'function',
-    connectionVars: ctx.connectionVariables || {}
-  });
-  // Test authentication
-  try {
-    const client = await createClient(ctx);
-    // Simple query to test auth
-    await client.graphql({
-      query: `query { __typename }`
-    });
-    ctx.log('info', 'Authentication successful');
-    return { authOk: true };
-  } catch (error) {
-    ctx.log('error', 'Authentication failed', {
-      error: error instanceof Error ? error.message : String(error)
-    });
-    return { authOk: false, error: String(error) };
-  }
-});
-```
----
-## Security Best Practices
-### 1. Never Log Credentials
-```typescript
-// ❌ WRONG - Logs sensitive data
-ctx.log('info', 'Client config', {
-  clientId: connectionVars.clientId,
-  clientSecret: connectionVars.clientSecret  // DON'T DO THIS
-});
-// ✅ CORRECT - Log safely
-ctx.log('info', 'Client config', {
-  hasClientId: !!connectionVars.clientId,
-  hasClientSecret: !!connectionVars.clientSecret
-});
-```
-### 2. Use Environment-Specific Connections
-```
-Connections:
-- fluent_commerce_dev      (dev environment)
-- fluent_commerce_staging  (staging environment)
-- fluent_commerce_prod     (production environment)
-```
-```typescript
-// Select connection based on environment
-const connectionName = process.env.ENV === 'production'
-  ? 'fluent_commerce_prod'
-  : 'fluent_commerce_dev';
-export const workflow = http('workflow', {
-  connection: connectionName
-}, async (ctx) => {
-  // ...
-});
-```
-### 3. Validate RetailerID
-```typescript
-export const validateRetailer = http('validate', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const client = await createClient(ctx);
-  const retailerId = client.getRetailerId();
-  // Validate retailer ID
-  if (!retailerId || retailerId === '') {
-    ctx.log('error', 'Retailer ID not configured');
-    throw new Error('Retailer ID missing - check connection configuration');
-  }
-  // Validate format (numeric)
-  if (!/^\d+$/.test(retailerId)) {
-    ctx.log('error', 'Invalid retailer ID format', { retailerId });
-    throw new Error('Retailer ID must be numeric');
-  }
-  return { retailerId, valid: true };
-});
-```
-### 4. Implement Request Timeouts
-```typescript
-export const withTimeout = http('with-timeout', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const client = await createClient(ctx);
-  // Implement timeout for long-running queries
-  const timeoutMs = 30000;  // 30 seconds
-  const result = await Promise.race([
-    client.graphql({ query: '...' }),
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error('Request timeout')), timeoutMs)
-    )
-  ]);
-  return result;
-});
-```
----
-## Advanced Connection Patterns
-### Multi-Retailer Workflows
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export const multiRetailer = http('multi-retailer', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const retailers = ['1', '2', '3'];
-  const results = [];
-  for (const retailerId of retailers) {
-    const client = await createClient(ctx);
-    client.setRetailerId(retailerId);
-    try {
-      const result = await client.graphql({
-        query: `query { products(first: 10) { edges { node { id ref } } } }`
-      });
-      results.push({
-        retailerId,
-        success: true,
-        productCount: result.data.products.edges.length
-      });
-    } catch (error) {
-      ctx.log('error', 'Query failed for retailer', {
-        retailerId,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      results.push({
-        retailerId,
-        success: false,
-        error: String(error)
-      });
-    }
-  }
-  return { results };
-});
-```
-### Connection Health Check
-```typescript
-export const healthCheck = http('health-check', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const startTime = Date.now();
-  try {
-    const client = await createClient(ctx);
-    // Test basic connectivity
-    await client.graphql({
-      query: `query { __typename }`
-    });
-    const duration = Date.now() - startTime;
-    ctx.log('info', 'Health check passed', { durationMs: duration });
-    return {
-      healthy: true,
-      durationMs: duration,
-      timestamp: new Date().toISOString()
-    };
-  } catch (error) {
-    const duration = Date.now() - startTime;
-    ctx.log('error', 'Health check failed', {
-      durationMs: duration,
-      error: error instanceof Error ? error.message : String(error)
-    });
-    return {
-      healthy: false,
-      durationMs: duration,
-      error: String(error),
-      timestamp: new Date().toISOString()
-    };
-  }
-});
-```
----
-## Key Takeaways
-- 🎯 **Versori manages OAuth2** - Your code never handles credentials
-- 🎯 **createClient(ctx)** - Universal factory auto-detects Versori context
-- 🎯 **FluentVersoriClient** - Platform-optimized client using ctx.fetch
-- 🎯 **FluentClient** - Standalone client for Node.js/Deno with manual OAuth2
-- 🎯 **Connection variables** - Store retailerId and custom config
-- 🎯 **Automatic token refresh** - Versori handles token lifecycle
-- 🎯 **Error handling** - Log errors, check status codes, implement retries
-- 🎯 **Security** - Never log credentials, use environment-specific connections
----
-## Practice Exercise
-Create a workflow that:
-1. Uses `createClient()` to create authenticated client
-2. Validates retailer ID is configured
-3. Implements proper error handling for auth failures
-4. Logs connection health metrics
-5. Handles multiple retries on transient errors
-**Hints**:
-- Use `try/catch` for error handling
-- Check `client.getRetailerId()` for validation
-- Use `ctx.log()` for observability
-- Implement exponential backoff for retries
-**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
----
-## Next Steps
-Now that you understand authentication and connections, let's explore different workflow types.
-Continue to [Module 4: Workflows →](./platforms-versori-04-workflows.md) to learn about HTTP, webhooks, and scheduled workflows.
----
-## Related Documentation
-- [Module 2: Quick Start](./platforms-versori-02-quick-start.md) - Your first workflow
-- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Workflow types
-- [Module 5: Connections](./platforms-versori-05-connections.md) - Advanced connection patterns
-- [API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
----
-[← Previous: Module 2](./platforms-versori-02-quick-start.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 4: Workflows →](./platforms-versori-04-workflows.md)
+# Module 3: Authentication & Connections
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+**Module 3 of 8** | **Level**: Beginner | **Time**: 35 minutes
+---
+## Learning Objectives
+By the end of this module, you will:
+- ✅ Understand OAuth2 authentication in Versori
+- ✅ Configure Fluent Commerce connections in Versori UI
+- ✅ Use `createClient()` with Versori context
+- ✅ Understand FluentVersoriClient vs FluentClient
+- ✅ Access connection credentials and metadata
+- ✅ Handle authentication errors
+- ✅ Implement security best practices
+---
+## OAuth2 in Versori Platform
+Versori manages OAuth2 credentials securely through **Connections**. Your code never handles raw credentials.
+### Key Benefits
+- **No credential management** in code - Versori handles token storage and refresh
+- **Automatic token refresh** when expired - transparent to your code
+- **Secure storage** in Versori platform - encrypted at rest
+- **Environment-specific** configs (dev/staging/prod) - separate credentials per environment
+- **Audit logging** of API calls - full traceability
+- **Connection reuse** across workflows - configure once, use everywhere
+### How Authentication Works
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Versori Platform                                            │
+│                                                             │
+│  ┌──────────────┐                 ┌──────────────┐        │
+│  │   Workflow   │──ctx.fetch()──→ │  Connection  │        │
+│  │              │                  │   (OAuth2)   │        │
+│  └──────────────┘                 └──────┬───────┘        │
+│                                           │                 │
+└───────────────────────────────────────────┼─────────────────┘
+                                            │
+                                            │ Managed Auth
+                                            ↓
+                              ┌──────────────────────────┐
+                              │   Fluent Commerce API    │
+                              │  (api.fluentcommerce.com)│
+                              └──────────────────────────┘
+```
+**Key Points**:
+1. Workflows use `ctx.fetch()` - Versori injects authentication automatically
+2. Connection stores OAuth2 credentials - client ID, client secret
+3. Platform handles token lifecycle - fetch, refresh, retry on 401
+4. Your code never sees raw credentials - only uses authenticated fetch
+---
+## Configuring Fluent Commerce Connection
+### Step 1: Access Connections in Versori UI
+1. Log in to Versori dashboard
+2. Navigate to **Connections** tab (left sidebar)
+3. Click **"Add Connection"** button
+### Step 2: Connection Configuration
+**Basic Details**:
+```
+Name: fluent_commerce
+Description: Fluent Commerce Production API
+Type: Custom OAuth2
+```
+**OAuth2 Settings**:
+```
+Auth URL: https://api.fluentcommerce.com/oauth/token
+Token URL: https://api.fluentcommerce.com/oauth/token
+Grant Type: client_credentials
+```
+**Client Credentials**:
+```
+Client ID: [Your Fluent OAuth2 Client ID]
+Client Secret: [Your Fluent OAuth2 Client Secret]
+```
+**API Configuration**:
+```
+Base URL: https://api.fluentcommerce.com
+```
+**Custom Parameters** (JSON) - **Optional:**
+```json
+{
+  "retailerId": "1"
+}
+```
+**Note:** `retailerId` is only needed if you're using Job API or Event API. For GraphQL queries only, you can omit it. If your Versori version doesn't support Custom Parameters, use `client.setRetailerId('1')` after creating the client.
+**See complete retailerId guide below or:** [Complete retailerId Configuration Guide](../../../../00-START-HERE/retailerid-configuration.md)
+### Step 3: Test Connection
+Click **"Test Connection"** to verify:
+- OAuth2 token can be fetched
+- Base URL is accessible
+- Credentials are correct
+---
+## Using createClient() with Versori
+### Basic Usage
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export const workflow = http('name', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // Create client from Versori context
+  const client = await createClient(ctx);
+  // Use client - authentication is automatic
+  const result = await client.graphql({
+    query: `query { products(first: 10) { edges { node { id ref } } } }`
+  });
+  return result.data;
+});
+```
+### What `createClient()` Does
+```typescript
+// Internally, createClient() detects Versori context:
+export async function createClient(ctx: HttpContext): Promise<FluentVersoriClient> {
+  // 1. Detects runtime (Versori vs Node.js/Deno)
+  // 2. Creates appropriate client type
+  // 3. Extracts retailerId from connection variables or URL
+  // 4. Returns configured client
+  return FluentVersoriClient.fromContext(ctx);
+}
+```
+**Key Detection Logic**:
+- Checks for `ctx.fetch` (Versori-specific)
+- Checks for `ctx.log` (Versori logging)
+- Checks for `ctx.baseUrl` (connection base URL)
+- Falls back to standalone mode if not Versori
+---
+## FluentVersoriClient vs FluentClient
+### Architecture Comparison
+| Feature | FluentVersoriClient | FluentClient |
+|---------|---------------------|--------------|
+| **Runtime** | Versori platform only | Node.js, Deno, standalone |
+| **Authentication** | Platform-managed (ctx.fetch) | Manual OAuth2 (clientId/secret) |
+| **Token Management** | Automatic (Versori) | Manual (AuthService) |
+| **Base URL** | From connection config | Passed in constructor |
+| **Fetch Implementation** | `ctx.fetch()` (Versori) | `fetch()` (standard) |
+| **Logging** | `ctx.log` (platform) | Custom logger or console |
+| **KV Storage** | `ctx.openKv()` available | External KV required |
+### When to Use Each
+**Use FluentVersoriClient** (via `createClient(ctx)`):
+- ✅ Running on Versori platform (webhooks, scheduled, HTTP workflows)
+- ✅ Want automatic authentication
+- ✅ Need Versori KV storage integration
+- ✅ Platform logging required
+**Use FluentClient** (standalone):
+- ✅ Running Node.js scripts locally
+- ✅ Running in Deno
+- ✅ Custom environments (Lambda, Docker, etc.)
+- ✅ Testing with mock credentials
+### Code Example: Both Approaches
+```typescript
+// ✅ Versori Platform (FluentVersoriClient via createClient)
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export const versoriWorkflow = http('versori', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const client = await createClient(ctx);  // Auto-detects Versori
+  return await client.graphql({ query: '...' });
+});
+// ✅ Standalone Node.js (FluentClient directly)
+import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+const client = new FluentClient({
+  baseUrl: 'https://api.fluentcommerce.com',
+  clientId: process.env.FLUENT_CLIENT_ID!,
+  clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+  username: process.env.FLUENT_USERNAME,
+  password: process.env.FLUENT_PASSWORD,
+  retailerId: '1'
+});
+const result = await client.graphql({ query: '...' });
+```
+---
+## Accessing Connection Credentials
+### Connection Variables
+Versori connections can store custom variables accessible in workflows:
+```typescript
+import { http } from '@versori/run';
+export const accessConnectionVars = http('access-vars', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // Access connection variables
+  const connectionVars = ctx.connectionVariables || {};
+  const retailerId = connectionVars.retailerId || '1';
+  const environment = connectionVars.environment || 'production';
+  ctx.log('info', 'Connection variables', {
+    retailerId,
+    environment
+  });
+  return { retailerId, environment };
+});
+```
+### Base URL Access
+```typescript
+export const accessBaseUrl = http('access-url', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // Base URL may be a Promise
+  const baseUrl = await ctx.baseUrl;
+  ctx.log('info', 'Connection base URL', { baseUrl });
+  return { baseUrl };
+});
+```
+### Retailer ID Extraction
+The SDK automatically extracts retailer ID from:
+1. **Connection variables** (highest priority):
+   ```json
+   { "retailerId": "1" }
+   ```
+2. **URL path** (fallback):
+   ```
+   https://api.fluentcommerce.com/graphql/1
+                                      ↑
+                                  retailerId
+   ```
+3. **Manual override**:
+   ```typescript
+   const client = await createClient(ctx);
+   client.setRetailerId('2');  // Override if needed
+   ```
+---
+## retailerId Configuration (v0.1.30+)
+Starting with v0.1.30, `retailerId` is **optional** for GraphQL queries but **required** for Job and Event APIs.
+### When retailerId is Required
+| API Type | retailerId Required? | Validation |
+|----------|---------------------|------------|
+| GraphQL Queries (`client.graphql()`) | ❌ Optional | Not validated |
+| GraphQL Mutations (`client.graphql()`) | ❌ Optional | Not validated |
+| Job API (`createJob()`, `getJob()`) | ✅ Required | Fail-fast at method call |
+| Event API (`sendEvent()`) | ✅ Required | Fail-fast at method call |
+| Batch API (`sendBatch()`) | ✅ Required | Fail-fast at method call |
+### Configuration Patterns
+**Option 1: Set at Client Creation (Recommended)**
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export const inventorySync = http('POST', '/sync', async (ctx) => {
+  // retailerId set once at client creation
+  const client = await createClient({
+    context: ctx,
+    retailerId: ctx.connectionVariables?.RETAILER_ID,
+  });
+  // Works for all APIs
+  await client.createJob({ name: 'inventory-sync' });
+  await client.graphql({ query: '...' });
+  return { success: true };
+});
+```
+**Option 2: Set Dynamically (Multi-Tenant)**
+```typescript
+export const multiTenantSync = http('POST', '/sync/:retailerId', async (ctx) => {
+  const client = await createClient({ context: ctx });
+  // Set retailerId from URL parameter
+  const retailerId = ctx.params?.retailerId;
+  client.setRetailerId(retailerId);
+  await client.createJob({ name: 'inventory-sync' });
+  return { success: true };
+});
+```
+**Option 3: No retailerId (GraphQL Only)**
+```typescript
+export const queryProducts = http('POST', '/query', async (ctx) => {
+  // No retailerId needed for GraphQL queries
+  const client = await createClient({ context: ctx });
+  const result = await client.graphql({
+    query: `query { products { edges { node { id ref } } } }`
+  });
+  return result.data;
+});
+```
+### Error Handling
+```typescript
+export const withRetailerIdValidation = http('POST', '/sync', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  try {
+    const client = await createClient({ context: ctx });
+    // Try to call Job API
+    const job = await client.createJob({ name: 'inventory-sync' });
+    return { success: true, jobId: job.id };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('retailerId is required')) {
+      // Handle missing retailerId
+      ctx.log('error', 'retailerId not configured', {
+        error: error.message
+      });
+      return {
+        success: false,
+        error: 'retailerId configuration missing',
+        details: 'Configure retailerId in connection variables or use client.setRetailerId()'
+      };
+    }
+    throw error; // Re-throw other errors
+  }
+});
+```
+**See Also:** [Complete retailerId Configuration Guide](../../../../00-START-HERE/retailerid-configuration.md) for all patterns and use cases.
+---
+## Authentication Error Handling
+### Common Authentication Errors
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export const errorHandling = http('error-handling', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  try {
+    const client = await createClient(ctx);
+    const result = await client.graphql({
+      query: `query { products(first: 10) { edges { node { id } } } }`
+    });
+    return { success: true, data: result.data };
+  } catch (error) {
+    // Log error details
+    ctx.log('error', 'GraphQL request failed', {
+      error: error instanceof Error ? error.message : String(error),
+      name: error instanceof Error ? error.name : 'Unknown'
+    });
+    // Check error type
+    if (error instanceof Error) {
+      // Authentication errors
+      if (error.message.includes('401') || error.message.includes('Unauthorized')) {
+        return {
+          success: false,
+          error: 'Authentication failed - check connection credentials',
+          retryable: false
+        };
+      }
+      // Token refresh errors
+      if (error.message.includes('token') || error.message.includes('expired')) {
+        return {
+          success: false,
+          error: 'Token expired - Versori will retry automatically',
+          retryable: true
+        };
+      }
+      // Network errors
+      if (error.message.includes('ECONNREFUSED') || error.message.includes('timeout')) {
+        return {
+          success: false,
+          error: 'Network error - Fluent API unreachable',
+          retryable: true
+        };
+      }
+    }
+    // Generic error response
+    return {
+      success: false,
+      error: 'Request failed',
+      details: error instanceof Error ? error.message : String(error)
+    };
+  }
+});
+```
+### Error Response Patterns
+| HTTP Status | Meaning | Versori Behavior | Your Action |
+|-------------|---------|------------------|-------------|
+| **401** | Unauthorized | Refreshes token, retries | Log error if retry fails |
+| **403** | Forbidden | No retry | Check retailerId, permissions |
+| **429** | Rate limited | Retries with backoff | Reduce request rate |
+| **500** | Server error | May retry | Log for investigation |
+| **503** | Service unavailable | Retries | Wait for service recovery |
+---
+## Token Management (Versori)
+### Automatic Token Refresh
+Versori handles token lifecycle automatically:
+```typescript
+// You write this:
+const result = await client.graphql({ query: '...' });
+// Versori does this behind the scenes:
+// 1. Check if token exists and is valid
+// 2. If expired, fetch new token from OAuth2 endpoint
+// 3. Retry original request with fresh token
+// 4. Return result to your code
+```
+**No manual token management needed!**
+### Token Debugging
+If authentication fails, check Versori logs:
+```typescript
+export const debugAuth = http('debug-auth', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  ctx.log('info', 'Connection details', {
+    hasBaseUrl: !!ctx.baseUrl,
+    hasFetch: typeof ctx.fetch === 'function',
+    hasLog: typeof ctx.log === 'function',
+    connectionVars: ctx.connectionVariables || {}
+  });
+  // Test authentication
+  try {
+    const client = await createClient(ctx);
+    // Simple query to test auth
+    await client.graphql({
+      query: `query { __typename }`
+    });
+    ctx.log('info', 'Authentication successful');
+    return { authOk: true };
+  } catch (error) {
+    ctx.log('error', 'Authentication failed', {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return { authOk: false, error: String(error) };
+  }
+});
+```
+---
+## Security Best Practices
+### 1. Never Log Credentials
+```typescript
+// ❌ WRONG - Logs sensitive data
+ctx.log('info', 'Client config', {
+  clientId: connectionVars.clientId,
+  clientSecret: connectionVars.clientSecret  // DON'T DO THIS
+});
+// ✅ CORRECT - Log safely
+ctx.log('info', 'Client config', {
+  hasClientId: !!connectionVars.clientId,
+  hasClientSecret: !!connectionVars.clientSecret
+});
+```
+### 2. Use Environment-Specific Connections
+```
+Connections:
+- fluent_commerce_dev      (dev environment)
+- fluent_commerce_staging  (staging environment)
+- fluent_commerce_prod     (production environment)
+```
+```typescript
+// Select connection based on environment
+const connectionName = process.env.ENV === 'production'
+  ? 'fluent_commerce_prod'
+  : 'fluent_commerce_dev';
+export const workflow = http('workflow', {
+  connection: connectionName
+}, async (ctx) => {
+  // ...
+});
+```
+### 3. Validate RetailerID
+```typescript
+export const validateRetailer = http('validate', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const client = await createClient(ctx);
+  const retailerId = client.getRetailerId();
+  // Validate retailer ID
+  if (!retailerId || retailerId === '') {
+    ctx.log('error', 'Retailer ID not configured');
+    throw new Error('Retailer ID missing - check connection configuration');
+  }
+  // Validate format (numeric)
+  if (!/^\d+$/.test(retailerId)) {
+    ctx.log('error', 'Invalid retailer ID format', { retailerId });
+    throw new Error('Retailer ID must be numeric');
+  }
+  return { retailerId, valid: true };
+});
+```
+### 4. Implement Request Timeouts
+```typescript
+export const withTimeout = http('with-timeout', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const client = await createClient(ctx);
+  // Implement timeout for long-running queries
+  const timeoutMs = 30000;  // 30 seconds
+  const result = await Promise.race([
+    client.graphql({ query: '...' }),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Request timeout')), timeoutMs)
+    )
+  ]);
+  return result;
+});
+```
+---
+## Advanced Connection Patterns
+### Multi-Retailer Workflows
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export const multiRetailer = http('multi-retailer', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const retailers = ['1', '2', '3'];
+  const results = [];
+  for (const retailerId of retailers) {
+    const client = await createClient(ctx);
+    client.setRetailerId(retailerId);
+    try {
+      const result = await client.graphql({
+        query: `query { products(first: 10) { edges { node { id ref } } } }`
+      });
+      results.push({
+        retailerId,
+        success: true,
+        productCount: result.data.products.edges.length
+      });
+    } catch (error) {
+      ctx.log('error', 'Query failed for retailer', {
+        retailerId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      results.push({
+        retailerId,
+        success: false,
+        error: String(error)
+      });
+    }
+  }
+  return { results };
+});
+```
+### Connection Health Check
+```typescript
+export const healthCheck = http('health-check', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const startTime = Date.now();
+  try {
+    const client = await createClient(ctx);
+    // Test basic connectivity
+    await client.graphql({
+      query: `query { __typename }`
+    });
+    const duration = Date.now() - startTime;
+    ctx.log('info', 'Health check passed', { durationMs: duration });
+    return {
+      healthy: true,
+      durationMs: duration,
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    ctx.log('error', 'Health check failed', {
+      durationMs: duration,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return {
+      healthy: false,
+      durationMs: duration,
+      error: String(error),
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+```
+---
+## Key Takeaways
+- 🎯 **Versori manages OAuth2** - Your code never handles credentials
+- 🎯 **createClient(ctx)** - Universal factory auto-detects Versori context
+- 🎯 **FluentVersoriClient** - Platform-optimized client using ctx.fetch
+- 🎯 **FluentClient** - Standalone client for Node.js/Deno with manual OAuth2
+- 🎯 **Connection variables** - Store retailerId and custom config
+- 🎯 **Automatic token refresh** - Versori handles token lifecycle
+- 🎯 **Error handling** - Log errors, check status codes, implement retries
+- 🎯 **Security** - Never log credentials, use environment-specific connections
+---
+## Practice Exercise
+Create a workflow that:
+1. Uses `createClient()` to create authenticated client
+2. Validates retailer ID is configured
+3. Implements proper error handling for auth failures
+4. Logs connection health metrics
+5. Handles multiple retries on transient errors
+**Hints**:
+- Use `try/catch` for error handling
+- Check `client.getRetailerId()` for validation
+- Use `ctx.log()` for observability
+- Implement exponential backoff for retries
+**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
+---
+## Next Steps
+Now that you understand authentication and connections, let's explore different workflow types.
+Continue to [Module 4: Workflows →](./platforms-versori-04-workflows.md) to learn about HTTP, webhooks, and scheduled workflows.
+---
+## Related Documentation
+- [Module 2: Quick Start](./platforms-versori-02-quick-start.md) - Your first workflow
+- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Workflow types
+- [Module 5: Connections](./platforms-versori-05-connections.md) - Advanced connection patterns
+- [API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
+---
+[← Previous: Module 2](./platforms-versori-02-quick-start.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 4: Workflows →](./platforms-versori-04-workflows.md)