npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

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 (495) hide show

package/docs/01-TEMPLATES/versori/patterns/versori-patterns-connection-validation-pattern.md CHANGED Viewed

@@ -1,656 +1,656 @@
-# Connection Validation Pattern
-**Pattern**: Optional connection validation for `createClient()` with fail-fast authentication checking
-**Version**: SDK ^0.1.34+
----
-## Overview
-The `createClient()` function supports optional connection validation via the `validateConnection` option. When enabled, it executes a minimal GraphQL query (`query { me { ref } }`) to verify authentication immediately, providing fail-fast error detection.
----
-## Pattern: Make It Configurable
-**Recommended Approach**: Use activation variable to enable/disable validation
-```typescript
-// ✅ OPTIONAL: Validate connection immediately (fail-fast mode)
-// Set activation variable 'validateConnectionOnStart' = 'true' to enable
-// When enabled: Executes query { me { ref } } to verify authentication
-// When disabled: Fast creation, validation happens on first API call (default)
-const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
-const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-if (validateConnection) {
-  log.info('✅ Connection validated successfully - authentication confirmed', { jobId });
-}
-```
----
-## When to Use
-### ✅ **Enable Validation** (`validateConnection: true`)
-- **Webhook workflows** - Quick error responses to callers
-- **Critical production workflows** - Fail-fast on auth errors
-- **Long-running workflows** - Catch auth issues before processing
-- **Debugging scenarios** - Verify credentials immediately
-### ❌ **Disable Validation** (default)
-- **High-frequency scheduled workflows** - Avoid extra API call overhead
-- **Development/testing** - Speed matters more than early validation
-- **Workflows that handle errors gracefully** - Errors surface on first API call anyway
-- **Batch processing** - Multiple client creations per workflow
----
-## Complete Examples
-### Example 1: Webhook Workflow (Fail-Fast Recommended)
-```typescript
-export const orderIngestion = webhook('order-ingestion')
-.then(
-  http('process-order', { connection: 'fluent_commerce' }, async (ctx) => {
-    const { log, activation } = ctx;
-    try {
-      // ✅ Fail-fast: Validate connection immediately for webhooks
-      const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
-      const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-      if (validateConnection) {
-        log.info('✅ Connection validated successfully - authentication confirmed');
-      }
-      // Process order...
-      return { success: true };
-    } catch (error: any) {
-      // 🔍 Enhanced: Error logging with recommendations
-      log.error('[ConnectionValidation] Authentication failed', {
-        error: error instanceof Error ? error.message : String(error),
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-          ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-          : error.message?.includes('connection') || error.message?.includes('timeout')
-          ? 'Check network connectivity and Fluent Commerce API availability'
-          : 'Review error details and verify connection configuration'
-      });
-      throw error;
-    }
-  })
-)
-.catch((ctx: Context<any>) => {
-  const error = ctx.data instanceof Error ? ctx.data : new Error(String(ctx.data));
-  const errorDetails = {
-    message: error instanceof Error ? error.message : String(error),
-    stack: error instanceof Error ? error.stack : undefined,
-    errorType: error instanceof Error ? error.constructor.name : 'Error',
-    recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-      ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-      : error.message?.includes('connection') || error.message?.includes('timeout')
-      ? 'Check network connectivity and Fluent Commerce API availability'
-      : 'Review error details and verify workflow configuration'
-  };
-  ctx.log.error('[ConnectionValidation] Workflow failed', errorDetails);
-  return { success: false, error: error.message, recommendation: errorDetails.recommendation };
-});
-```
-### Example 2: Scheduled Workflow (Optional)
-```typescript
-export const scheduledProductIngestion = schedule('product-ingestion', '0 * * * *')
-.then(
-  http('execute-ingestion', { connection: 'fluent_commerce' }, async (ctx) => {
-    const { log, activation } = ctx;
-    // ✅ Optional: Validate connection (configurable via activation variable)
-    const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
-    const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-    if (validateConnection) {
-      log.info('✅ Connection validated successfully');
-    }
-    // Process files...
-    return result;
-  })
-);
-```
-### Example 3: Extraction Workflow
-```typescript
-export async function executeInventoryPositionExtraction(
-  ctx: VersoriContext,
-  params: ExtractionParams
-): Promise<ExtractionResult> {
-  const { log, openKv, activation } = ctx;
-  // ✅ Optional: Validate connection immediately (fail-fast mode)
-  const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
-  const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-  if (validateConnection) {
-    log.info('✅ Connection validated successfully - authentication confirmed', { jobId });
-  }
-  // Continue with extraction...
-}
-```
----
-## Activation Variable Configuration
-**Variable Name**: `validateConnectionOnStart`
-**Values**:
-- `'true'` - Enable validation (fail-fast mode)
-- `'false'` or unset - Disable validation (fast creation, default)
-**How to Set**:
-1. Go to Versori Activation Variables
-2. Add variable: `validateConnectionOnStart` = `true`
-3. Save activation
----
-## Benefits
-✅ **Fail-Fast**: Catch auth errors immediately, not on first API call
-✅ **Better Logging**: "authenticated" vs "instance created"
-✅ **Configurable**: Enable only when needed
-✅ **Performance**: No overhead when disabled (default)
-✅ **Backward Compatible**: Existing templates work unchanged
----
-## Default Behavior
-**Without `validateConnection` option** (default):
-- Fast client creation
-- No API call during creation
-- Validation happens on first API call
-- Errors surface when you try to use the client
-**With `validateConnection: true`**:
-- Executes `query { me { ref } }` immediately
-- Fails fast if authentication is invalid
-- Logs "created and authenticated" on success
-- Logs "Connection validation failed" on error
----
-## Automatic Connection Validation (v0.1.40+)
-**SDK Automatic Checks:**
-When you call `createClient(ctx)`, the SDK automatically validates:
-### 1. ctx.fetch Presence (CRITICAL)
-**Validates:** `ctx.fetch` exists
-**Throws:** `"Invalid Versori context: ctx.fetch is required. Ensure you are running in Versori platform and using createClient(ctx)."`
-**Purpose:** Ensures running in Versori runtime environment
-**Example:**
-```typescript
-// ❌ Wrong context - will throw
-const invalidCtx = { log: console };
-const client = await createClient(invalidCtx);
-// Error: Invalid Versori context: ctx.fetch is required...
-// ✅ Correct Versori context
-const client = await createClient(ctx); // ctx from Versori workflow
-```
-### 2. retailerId Detection (WARNING)
-**Attempts extraction from:**
-1. `ctx.connectionVariables.retailerId` (priority 1)
-2. `baseUrl` path regex `/\/retailer\/([^/]+)\/?$/` (priority 2)
-**Logs WARNING if not found:**
-- Message: `"[fc-connect-sdk:client] No retailerId found in connection config or baseUrl"`
-- Hint: `"Set connection.retailerId or use client.setRetailerId() for Event/Job/Batch APIs"`
-- Docs: `"GraphQL queries work without retailerId, but Event/Job/Batch APIs require it"`
-**Not an error because:**
-- retailerId is only required for Event/Job/Batch APIs
-- GraphQL queries work without retailerId
-- Can be set later via `client.setRetailerId()`
-**Example:**
-```typescript
-// Scenario 1: retailerId in connection variables
-const ctx = {
-  fetch: versoriManagedFetch,
-  log: versoriLog,
-  connectionVariables: { retailerId: '1' }
-};
-const client = await createClient(ctx);
-// ✅ Log: "[fc-connect-sdk:client] Using retailerId from connection variables"
-// Scenario 2: retailerId in baseUrl
-const ctx = {
-  fetch: versoriManagedFetch,
-  log: versoriLog,
-  baseUrl: 'https://api.fluentcommerce.com/retailer/123'
-};
-const client = await createClient(ctx);
-// ✅ Log: "[fc-connect-sdk:client] Extracted retailerId from baseUrl"
-// Scenario 3: No retailerId
-const ctx = {
-  fetch: versoriManagedFetch,
-  log: versoriLog,
-  baseUrl: 'https://api.fluentcommerce.com'
-};
-const client = await createClient(ctx);
-// ⚠️ Warning: "No retailerId found..." (but still creates client)
-```
-### 3. ctx.log Check
-**Validates:** `ctx.log` exists
-**Action:** Logs warning to console if missing (logs will be disabled)
-**Does not throw:** SDK continues without logging
-### When retailerId is REQUIRED
-**✅ Required for:**
-- `sendEvent()` - Validated before API call
-- `createJob()` - Validated before API call
-- Batch operations - Validated in job payload
-**❌ NOT Required for:**
-- `graphql()` - Works without retailerId
-- `query()` - Works without retailerId
-- `mutate()` - Works without retailerId
-**Validation happens at API call time:**
-```typescript
-// Step 1: Create client (warning logged if no retailerId)
-const client = await createClient(ctx);
-// ⚠️ Warning: "No retailerId found..."
-// Step 2: Try to use Event API (validation throws error)
-await client.sendEvent(event);
-// ❌ Error: "retailerId is required for Event API..."
-// Step 3: Fix by setting retailerId
-client.setRetailerId('1');
-await client.sendEvent(event);
-// ✅ Works!
-```
-### Example Validation Flow
-**Complete validation flow with all checks:**
-```typescript
-export const workflow = http('inventory-sync', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // STEP 1: Automatic validation during createClient()
-  const client = await createClient(ctx);
-  // ✅ ctx.fetch validated (throws if missing)
-  // ⚠️ retailerId detection attempted (warning if missing)
-  // ✅ ctx.log checked (console warning if missing)
-  // STEP 2: Configure retailerId if using Event/Job/Batch APIs
-  const fluentRetailerId = ctx.activation?.getVariable('FLUENT_RETAILER_ID');
-  if (fluentRetailerId) {
-    client.setRetailerId(fluentRetailerId);
-    ctx.log?.info?.('retailerId configured', { retailerId: fluentRetailerId });
-  }
-  // STEP 3: API call (automatic validation before request)
-  try {
-    await client.sendEvent(event);
-    // ✅ Validates retailerId exists before API call
-  } catch (error) {
-    if (error.message.includes('retailerId is required')) {
-      ctx.log?.error?.('retailerId not configured', {
-        hint: 'Set FLUENT_RETAILER_ID activation variable',
-        docs: 'See batch-api-guide.md for configuration options'
-      });
-    }
-    throw error;
-  }
-});
-```
-### Configuration Best Practices
-**Recommended:** Use connection variables for retailerId
-```typescript
-// Configure in Versori Connection UI:
-// Custom Parameters (JSON):
-{
-  "retailerId": "1"
-}
-// SDK auto-detects - no code changes needed
-const client = await createClient(ctx);
-await client.sendEvent(event); // ✅ Works automatically
-```
-**Alternative:** Use activation variables
-```typescript
-// Set in Versori connector activation
-const fluentRetailerId = ctx.activation?.getVariable('FLUENT_RETAILER_ID');
-client.setRetailerId(fluentRetailerId);
-```
-**Last Resort:** Hardcode (not recommended for production)
-```typescript
-client.setRetailerId('1'); // ❌ Not environment-agnostic
-```
----
-## Template Update Checklist
-When updating templates, add the pattern:
-- [ ] Add comment explaining optional validation
-- [ ] Check activation variable `validateConnectionOnStart`
-- [ ] Pass options to `createClient()` conditionally
-- [ ] Log success when validation is enabled
-- [ ] Keep default behavior (fast, no validation)
----
-## Production Patterns
-### Pattern: Client Initialization with retailerId
-When using Event API or Batch API operations, `retailerId` must be configured on the client after creation.
-```typescript
-// ✅ Complete client initialization pattern
-export const dailyInventorySync = schedule('daily-inventory-sync', '*/5 * * * *').then(
-  http('run-inventory-batch', { connection: 'fluent_commerce' }, async (ctx) => {
-    const { log, activation } = ctx;
-    // Step 1: Create client (optionally with validation)
-    const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
-    const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-    if (validateConnection) {
-      log.info('✅ Connection validated successfully - authentication confirmed');
-    }
-    // Step 2: Configure retailerId for Event/Batch API operations
-    const fluentRetailerId = activation.getVariable('fluentRetailerId');
-    if (!fluentRetailerId) {
-      log.error('❌ Missing required fluentRetailerId activation variable');
-      return {
-        success: false,
-        error: 'fluentRetailerId activation variable is required for Event API operations',
-        recommendation: 'Please configure fluentRetailerId in the Activation Variables section',
-      };
-    }
-    client.setRetailerId(fluentRetailerId);
-    log.info('✅ Client initialized with retailerId', { retailerId: fluentRetailerId });
-    // Step 3: Proceed with Event/Batch API operations
-    // ... business logic
-  })
-);
-```
-### Pattern: Credential Retrieval from Connections
-For workflows requiring SFTP or external service credentials:
-```typescript
-import { Buffer } from 'node:buffer';
-export const sftpIngestion = schedule('sftp-ingestion', '*/5 * * * *').then(
-  http('process-files', { connection: 'fluent_commerce' }, async (ctx) => {
-    const { log } = ctx;
-    try {
-      // ✅ Retrieve credentials from connection configuration
-      const sftpCred = await ctx.credentials().getAccessToken('SFTP');
-      if (!sftpCred?.accessToken) {
-        throw new Error('No SFTP credentials found in connection configuration');
-      }
-      // Decode base64 accessToken to get "username:password"
-      const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
-      const parts = rawBasicAuth.split(':');
-      if (parts.length !== 2) {
-        throw new Error('Invalid SFTP credential format - expected username:password');
-      }
-      const [sftpUsername, sftpPassword] = parts;
-      log.info('✅ SFTP credentials retrieved successfully', {
-        hasUsername: !!sftpUsername,
-        hasPassword: !!sftpPassword,
-      });
-      // Use credentials with SftpDataSource
-      const sftp = new SftpDataSource({
-        type: 'SFTP_XML',
-        connectionId: 'sftp-inventory-sync',
-        name: 'inventory-sync',
-        settings: {
-          host: activation.getVariable('sftpHost'),
-          port: parseInt(activation.getVariable('sftpPort') || '22', 10),
-          username: sftpUsername,
-          password: sftpPassword,
-          // ... other settings
-        },
-      }, log);
-      // Always dispose when done
-      try {
-        // ... file processing
-      } finally {
-        await sftp.dispose();
-        log.info('✅ SFTP connection disposed successfully');
-      }
-    } catch (error: any) {
-      log.error('❌ Failed to retrieve SFTP credentials', {
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-      });
-      return {
-        success: false,
-        error: 'Failed to retrieve SFTP credentials from connection configuration',
-        details: error?.message,
-        recommendation: 'Please ensure the SFTP connection is configured with Basic Authentication',
-      };
-    }
-  })
-);
-```
-### Pattern: Complete Error Handling with Recommendations
-Production-ready error handling with actionable recommendations:
-```typescript
-try {
-  // Client creation and validation
-  const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
-  const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-  if (validateConnection) {
-    log.info('✅ Connection validated successfully');
-  }
-  // Business logic...
-} catch (error: any) {
-  const errorMessage = error instanceof Error ? error.message : String(error);
-  const errorType = error instanceof Error ? error.constructor.name : 'Error';
-  // 🔍 Enhanced error logging with contextual recommendations
-  log.error('❌ Workflow execution failed', {
-    error: errorMessage,
-    errorType,
-    stack: error instanceof Error ? error.stack : undefined,
-    recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-      ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-      : error.message?.includes('connection') || error.message?.includes('timeout')
-      ? 'Check network connectivity and Fluent Commerce API availability'
-      : error.message?.includes('retailerId') || error.message?.includes('RETAILER_ID')
-      ? 'Verify fluentRetailerId activation variable is configured for Event/Batch API operations'
-      : error.message?.includes('SFTP') || error.message?.includes('credentials')
-      ? 'Verify SFTP connection is configured with valid Basic Authentication credentials'
-      : 'Review error details and verify workflow configuration',
-  });
-  return {
-    success: false,
-    error: errorMessage,
-    errorType,
-    recommendation: 'See logs for detailed troubleshooting guidance',
-  };
-}
-```
-### Pattern: Emoji Logging for Better Visibility
-Use emojis consistently for visual scanning in logs:
-```typescript
-// ✅ Success states
-log.info('✅ Connection validated successfully');
-log.info('✅ Client initialized with retailerId', { retailerId });
-log.info('✅ SFTP credentials retrieved successfully');
-log.info('✅ File processed successfully', { fileName });
-// ❌ Error states
-log.error('❌ Missing required fluentRetailerId activation variable');
-log.error('❌ Failed to retrieve SFTP credentials');
-log.error('❌ Authentication failed');
-// 🔍 Debugging/Investigation
-log.info('🔍 Starting credential retrieval');
-log.info('🔍 Processing file', { fileName });
-// 📊 Stats/Metrics
-log.info('📊 Processing complete', {
-  filesProcessed: 42,
-  filesSkipped: 3,
-  filesFailed: 1,
-});
-```
----
-## Error Handling Best Practices
-### 1. Structured Error Objects
-Always include error type and actionable recommendations:
-```typescript
-catch (error: any) {
-  const errorDetails = {
-    message: error instanceof Error ? error.message : String(error),
-    errorType: error instanceof Error ? error.constructor.name : 'Error',
-    stack: error instanceof Error ? error.stack : undefined,
-    recommendation: getRecommendation(error),
-  };
-  log.error('Operation failed', errorDetails);
-  return { success: false, ...errorDetails };
-}
-```
-### 2. Context-Aware Recommendations
-Provide specific guidance based on error patterns:
-```typescript
-function getRecommendation(error: any): string {
-  const message = error?.message?.toLowerCase() || '';
-  if (message.includes('authentication') || message.includes('401')) {
-    return 'Verify connection credentials in Connections section';
-  }
-  if (message.includes('connection') || message.includes('timeout')) {
-    return 'Check network connectivity and API availability';
-  }
-  if (message.includes('retailerid') || message.includes('retailer_id')) {
-    return 'Verify fluentRetailerId activation variable is configured';
-  }
-  if (message.includes('sftp') || message.includes('credentials')) {
-    return 'Verify SFTP connection with valid Basic Authentication';
-  }
-  return 'Review error details and verify configuration';
-}
-```
-### 3. Always Dispose Resources
-Use try/finally to ensure cleanup:
-```typescript
-const sftp = new SftpDataSource(config, log);
-try {
-  // File processing operations
-  const files = await sftp.listFiles();
-  // ... process files
-} catch (error: any) {
-  log.error('Processing failed', { error: error.message });
-  throw error;
-} finally {
-  // ✅ Always dispose, even on error
-  await sftp.dispose();
-  log.info('✅ SFTP connection disposed');
-}
-```
-### 4. Validation Before Operations
-Fail fast with clear error messages:
-```typescript
-// ✅ Validate required configuration early
-const fluentRetailerId = activation.getVariable('fluentRetailerId');
-if (!fluentRetailerId) {
-  log.error('❌ Missing required configuration');
-  return {
-    success: false,
-    error: 'fluentRetailerId activation variable is required',
-    recommendation: 'Configure fluentRetailerId in Activation Variables',
-  };
-}
-// Proceed with validated configuration
-client.setRetailerId(fluentRetailerId);
-```
----
-## Related Documentation
-- [Client Architecture](../../../04-REFERENCE/architecture/architecture-02-client-architecture.md)
-- [createClient API](../../../04-REFERENCE/architecture/architecture-02-client-architecture.md#best-practices)
+# Connection Validation Pattern
+**Pattern**: Optional connection validation for `createClient()` with fail-fast authentication checking
+**Version**: SDK ^0.1.34+
+---
+## Overview
+The `createClient()` function supports optional connection validation via the `validateConnection` option. When enabled, it executes a minimal GraphQL query (`query { me { ref } }`) to verify authentication immediately, providing fail-fast error detection.
+---
+## Pattern: Make It Configurable
+**Recommended Approach**: Use activation variable to enable/disable validation
+```typescript
+// ✅ OPTIONAL: Validate connection immediately (fail-fast mode)
+// Set activation variable 'validateConnectionOnStart' = 'true' to enable
+// When enabled: Executes query { me { ref } } to verify authentication
+// When disabled: Fast creation, validation happens on first API call (default)
+const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
+const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+if (validateConnection) {
+  log.info('✅ Connection validated successfully - authentication confirmed', { jobId });
+}
+```
+---
+## When to Use
+### ✅ **Enable Validation** (`validateConnection: true`)
+- **Webhook workflows** - Quick error responses to callers
+- **Critical production workflows** - Fail-fast on auth errors
+- **Long-running workflows** - Catch auth issues before processing
+- **Debugging scenarios** - Verify credentials immediately
+### ❌ **Disable Validation** (default)
+- **High-frequency scheduled workflows** - Avoid extra API call overhead
+- **Development/testing** - Speed matters more than early validation
+- **Workflows that handle errors gracefully** - Errors surface on first API call anyway
+- **Batch processing** - Multiple client creations per workflow
+---
+## Complete Examples
+### Example 1: Webhook Workflow (Fail-Fast Recommended)
+```typescript
+export const orderIngestion = webhook('order-ingestion')
+.then(
+  http('process-order', { connection: 'fluent_commerce' }, async (ctx) => {
+    const { log, activation } = ctx;
+    try {
+      // ✅ Fail-fast: Validate connection immediately for webhooks
+      const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
+      const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+      if (validateConnection) {
+        log.info('✅ Connection validated successfully - authentication confirmed');
+      }
+      // Process order...
+      return { success: true };
+    } catch (error: any) {
+      // 🔍 Enhanced: Error logging with recommendations
+      log.error('[ConnectionValidation] Authentication failed', {
+        error: error instanceof Error ? error.message : String(error),
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+          ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+          : error.message?.includes('connection') || error.message?.includes('timeout')
+          ? 'Check network connectivity and Fluent Commerce API availability'
+          : 'Review error details and verify connection configuration'
+      });
+      throw error;
+    }
+  })
+)
+.catch((ctx: Context<any>) => {
+  const error = ctx.data instanceof Error ? ctx.data : new Error(String(ctx.data));
+  const errorDetails = {
+    message: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+    errorType: error instanceof Error ? error.constructor.name : 'Error',
+    recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+      ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+      : error.message?.includes('connection') || error.message?.includes('timeout')
+      ? 'Check network connectivity and Fluent Commerce API availability'
+      : 'Review error details and verify workflow configuration'
+  };
+  ctx.log.error('[ConnectionValidation] Workflow failed', errorDetails);
+  return { success: false, error: error.message, recommendation: errorDetails.recommendation };
+});
+```
+### Example 2: Scheduled Workflow (Optional)
+```typescript
+export const scheduledProductIngestion = schedule('product-ingestion', '0 * * * *')
+.then(
+  http('execute-ingestion', { connection: 'fluent_commerce' }, async (ctx) => {
+    const { log, activation } = ctx;
+    // ✅ Optional: Validate connection (configurable via activation variable)
+    const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
+    const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+    if (validateConnection) {
+      log.info('✅ Connection validated successfully');
+    }
+    // Process files...
+    return result;
+  })
+);
+```
+### Example 3: Extraction Workflow
+```typescript
+export async function executeInventoryPositionExtraction(
+  ctx: VersoriContext,
+  params: ExtractionParams
+): Promise<ExtractionResult> {
+  const { log, openKv, activation } = ctx;
+  // ✅ Optional: Validate connection immediately (fail-fast mode)
+  const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
+  const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+  if (validateConnection) {
+    log.info('✅ Connection validated successfully - authentication confirmed', { jobId });
+  }
+  // Continue with extraction...
+}
+```
+---
+## Activation Variable Configuration
+**Variable Name**: `validateConnectionOnStart`
+**Values**:
+- `'true'` - Enable validation (fail-fast mode)
+- `'false'` or unset - Disable validation (fast creation, default)
+**How to Set**:
+1. Go to Versori Activation Variables
+2. Add variable: `validateConnectionOnStart` = `true`
+3. Save activation
+---
+## Benefits
+✅ **Fail-Fast**: Catch auth errors immediately, not on first API call
+✅ **Better Logging**: "authenticated" vs "instance created"
+✅ **Configurable**: Enable only when needed
+✅ **Performance**: No overhead when disabled (default)
+✅ **Backward Compatible**: Existing templates work unchanged
+---
+## Default Behavior
+**Without `validateConnection` option** (default):
+- Fast client creation
+- No API call during creation
+- Validation happens on first API call
+- Errors surface when you try to use the client
+**With `validateConnection: true`**:
+- Executes `query { me { ref } }` immediately
+- Fails fast if authentication is invalid
+- Logs "created and authenticated" on success
+- Logs "Connection validation failed" on error
+---
+## Automatic Connection Validation (v0.1.40+)
+**SDK Automatic Checks:**
+When you call `createClient(ctx)`, the SDK automatically validates:
+### 1. ctx.fetch Presence (CRITICAL)
+**Validates:** `ctx.fetch` exists
+**Throws:** `"Invalid Versori context: ctx.fetch is required. Ensure you are running in Versori platform and using createClient(ctx)."`
+**Purpose:** Ensures running in Versori runtime environment
+**Example:**
+```typescript
+// ❌ Wrong context - will throw
+const invalidCtx = { log: console };
+const client = await createClient(invalidCtx);
+// Error: Invalid Versori context: ctx.fetch is required...
+// ✅ Correct Versori context
+const client = await createClient(ctx); // ctx from Versori workflow
+```
+### 2. retailerId Detection (WARNING)
+**Attempts extraction from:**
+1. `ctx.connectionVariables.retailerId` (priority 1)
+2. `baseUrl` path regex `/\/retailer\/([^/]+)\/?$/` (priority 2)
+**Logs WARNING if not found:**
+- Message: `"[fc-connect-sdk:client] No retailerId found in connection config or baseUrl"`
+- Hint: `"Set connection.retailerId or use client.setRetailerId() for Event/Job/Batch APIs"`
+- Docs: `"GraphQL queries work without retailerId, but Event/Job/Batch APIs require it"`
+**Not an error because:**
+- retailerId is only required for Event/Job/Batch APIs
+- GraphQL queries work without retailerId
+- Can be set later via `client.setRetailerId()`
+**Example:**
+```typescript
+// Scenario 1: retailerId in connection variables
+const ctx = {
+  fetch: versoriManagedFetch,
+  log: versoriLog,
+  connectionVariables: { retailerId: '1' }
+};
+const client = await createClient(ctx);
+// ✅ Log: "[fc-connect-sdk:client] Using retailerId from connection variables"
+// Scenario 2: retailerId in baseUrl
+const ctx = {
+  fetch: versoriManagedFetch,
+  log: versoriLog,
+  baseUrl: 'https://api.fluentcommerce.com/retailer/123'
+};
+const client = await createClient(ctx);
+// ✅ Log: "[fc-connect-sdk:client] Extracted retailerId from baseUrl"
+// Scenario 3: No retailerId
+const ctx = {
+  fetch: versoriManagedFetch,
+  log: versoriLog,
+  baseUrl: 'https://api.fluentcommerce.com'
+};
+const client = await createClient(ctx);
+// ⚠️ Warning: "No retailerId found..." (but still creates client)
+```
+### 3. ctx.log Check
+**Validates:** `ctx.log` exists
+**Action:** Logs warning to console if missing (logs will be disabled)
+**Does not throw:** SDK continues without logging
+### When retailerId is REQUIRED
+**✅ Required for:**
+- `sendEvent()` - Validated before API call
+- `createJob()` - Validated before API call
+- Batch operations - Validated in job payload
+**❌ NOT Required for:**
+- `graphql()` - Works without retailerId
+- `query()` - Works without retailerId
+- `mutate()` - Works without retailerId
+**Validation happens at API call time:**
+```typescript
+// Step 1: Create client (warning logged if no retailerId)
+const client = await createClient(ctx);
+// ⚠️ Warning: "No retailerId found..."
+// Step 2: Try to use Event API (validation throws error)
+await client.sendEvent(event);
+// ❌ Error: "retailerId is required for Event API..."
+// Step 3: Fix by setting retailerId
+client.setRetailerId('1');
+await client.sendEvent(event);
+// ✅ Works!
+```
+### Example Validation Flow
+**Complete validation flow with all checks:**
+```typescript
+export const workflow = http('inventory-sync', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // STEP 1: Automatic validation during createClient()
+  const client = await createClient(ctx);
+  // ✅ ctx.fetch validated (throws if missing)
+  // ⚠️ retailerId detection attempted (warning if missing)
+  // ✅ ctx.log checked (console warning if missing)
+  // STEP 2: Configure retailerId if using Event/Job/Batch APIs
+  const fluentRetailerId = ctx.activation?.getVariable('FLUENT_RETAILER_ID');
+  if (fluentRetailerId) {
+    client.setRetailerId(fluentRetailerId);
+    ctx.log?.info?.('retailerId configured', { retailerId: fluentRetailerId });
+  }
+  // STEP 3: API call (automatic validation before request)
+  try {
+    await client.sendEvent(event);
+    // ✅ Validates retailerId exists before API call
+  } catch (error) {
+    if (error.message.includes('retailerId is required')) {
+      ctx.log?.error?.('retailerId not configured', {
+        hint: 'Set FLUENT_RETAILER_ID activation variable',
+        docs: 'See batch-api-guide.md for configuration options'
+      });
+    }
+    throw error;
+  }
+});
+```
+### Configuration Best Practices
+**Recommended:** Use connection variables for retailerId
+```typescript
+// Configure in Versori Connection UI:
+// Custom Parameters (JSON):
+{
+  "retailerId": "1"
+}
+// SDK auto-detects - no code changes needed
+const client = await createClient(ctx);
+await client.sendEvent(event); // ✅ Works automatically
+```
+**Alternative:** Use activation variables
+```typescript
+// Set in Versori connector activation
+const fluentRetailerId = ctx.activation?.getVariable('FLUENT_RETAILER_ID');
+client.setRetailerId(fluentRetailerId);
+```
+**Last Resort:** Hardcode (not recommended for production)
+```typescript
+client.setRetailerId('1'); // ❌ Not environment-agnostic
+```
+---
+## Template Update Checklist
+When updating templates, add the pattern:
+- [ ] Add comment explaining optional validation
+- [ ] Check activation variable `validateConnectionOnStart`
+- [ ] Pass options to `createClient()` conditionally
+- [ ] Log success when validation is enabled
+- [ ] Keep default behavior (fast, no validation)
+---
+## Production Patterns
+### Pattern: Client Initialization with retailerId
+When using Event API or Batch API operations, `retailerId` must be configured on the client after creation.
+```typescript
+// ✅ Complete client initialization pattern
+export const dailyInventorySync = schedule('daily-inventory-sync', '*/5 * * * *').then(
+  http('run-inventory-batch', { connection: 'fluent_commerce' }, async (ctx) => {
+    const { log, activation } = ctx;
+    // Step 1: Create client (optionally with validation)
+    const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
+    const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+    if (validateConnection) {
+      log.info('✅ Connection validated successfully - authentication confirmed');
+    }
+    // Step 2: Configure retailerId for Event/Batch API operations
+    const fluentRetailerId = activation.getVariable('fluentRetailerId');
+    if (!fluentRetailerId) {
+      log.error('❌ Missing required fluentRetailerId activation variable');
+      return {
+        success: false,
+        error: 'fluentRetailerId activation variable is required for Event API operations',
+        recommendation: 'Please configure fluentRetailerId in the Activation Variables section',
+      };
+    }
+    client.setRetailerId(fluentRetailerId);
+    log.info('✅ Client initialized with retailerId', { retailerId: fluentRetailerId });
+    // Step 3: Proceed with Event/Batch API operations
+    // ... business logic
+  })
+);
+```
+### Pattern: Credential Retrieval from Connections
+For workflows requiring SFTP or external service credentials:
+```typescript
+import { Buffer } from 'node:buffer';
+export const sftpIngestion = schedule('sftp-ingestion', '*/5 * * * *').then(
+  http('process-files', { connection: 'fluent_commerce' }, async (ctx) => {
+    const { log } = ctx;
+    try {
+      // ✅ Retrieve credentials from connection configuration
+      const sftpCred = await ctx.credentials().getAccessToken('SFTP');
+      if (!sftpCred?.accessToken) {
+        throw new Error('No SFTP credentials found in connection configuration');
+      }
+      // Decode base64 accessToken to get "username:password"
+      const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
+      const parts = rawBasicAuth.split(':');
+      if (parts.length !== 2) {
+        throw new Error('Invalid SFTP credential format - expected username:password');
+      }
+      const [sftpUsername, sftpPassword] = parts;
+      log.info('✅ SFTP credentials retrieved successfully', {
+        hasUsername: !!sftpUsername,
+        hasPassword: !!sftpPassword,
+      });
+      // Use credentials with SftpDataSource
+      const sftp = new SftpDataSource({
+        type: 'SFTP_XML',
+        connectionId: 'sftp-inventory-sync',
+        name: 'inventory-sync',
+        settings: {
+          host: activation.getVariable('sftpHost'),
+          port: parseInt(activation.getVariable('sftpPort') || '22', 10),
+          username: sftpUsername,
+          password: sftpPassword,
+          // ... other settings
+        },
+      }, log);
+      // Always dispose when done
+      try {
+        // ... file processing
+      } finally {
+        await sftp.dispose();
+        log.info('✅ SFTP connection disposed successfully');
+      }
+    } catch (error: any) {
+      log.error('❌ Failed to retrieve SFTP credentials', {
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+      return {
+        success: false,
+        error: 'Failed to retrieve SFTP credentials from connection configuration',
+        details: error?.message,
+        recommendation: 'Please ensure the SFTP connection is configured with Basic Authentication',
+      };
+    }
+  })
+);
+```
+### Pattern: Complete Error Handling with Recommendations
+Production-ready error handling with actionable recommendations:
+```typescript
+try {
+  // Client creation and validation
+  const validateConnection = activation.getVariable('validateConnectionOnStart') === 'true';
+  const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+  if (validateConnection) {
+    log.info('✅ Connection validated successfully');
+  }
+  // Business logic...
+} catch (error: any) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorType = error instanceof Error ? error.constructor.name : 'Error';
+  // 🔍 Enhanced error logging with contextual recommendations
+  log.error('❌ Workflow execution failed', {
+    error: errorMessage,
+    errorType,
+    stack: error instanceof Error ? error.stack : undefined,
+    recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+      ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+      : error.message?.includes('connection') || error.message?.includes('timeout')
+      ? 'Check network connectivity and Fluent Commerce API availability'
+      : error.message?.includes('retailerId') || error.message?.includes('RETAILER_ID')
+      ? 'Verify fluentRetailerId activation variable is configured for Event/Batch API operations'
+      : error.message?.includes('SFTP') || error.message?.includes('credentials')
+      ? 'Verify SFTP connection is configured with valid Basic Authentication credentials'
+      : 'Review error details and verify workflow configuration',
+  });
+  return {
+    success: false,
+    error: errorMessage,
+    errorType,
+    recommendation: 'See logs for detailed troubleshooting guidance',
+  };
+}
+```
+### Pattern: Emoji Logging for Better Visibility
+Use emojis consistently for visual scanning in logs:
+```typescript
+// ✅ Success states
+log.info('✅ Connection validated successfully');
+log.info('✅ Client initialized with retailerId', { retailerId });
+log.info('✅ SFTP credentials retrieved successfully');
+log.info('✅ File processed successfully', { fileName });
+// ❌ Error states
+log.error('❌ Missing required fluentRetailerId activation variable');
+log.error('❌ Failed to retrieve SFTP credentials');
+log.error('❌ Authentication failed');
+// 🔍 Debugging/Investigation
+log.info('🔍 Starting credential retrieval');
+log.info('🔍 Processing file', { fileName });
+// 📊 Stats/Metrics
+log.info('📊 Processing complete', {
+  filesProcessed: 42,
+  filesSkipped: 3,
+  filesFailed: 1,
+});
+```
+---
+## Error Handling Best Practices
+### 1. Structured Error Objects
+Always include error type and actionable recommendations:
+```typescript
+catch (error: any) {
+  const errorDetails = {
+    message: error instanceof Error ? error.message : String(error),
+    errorType: error instanceof Error ? error.constructor.name : 'Error',
+    stack: error instanceof Error ? error.stack : undefined,
+    recommendation: getRecommendation(error),
+  };
+  log.error('Operation failed', errorDetails);
+  return { success: false, ...errorDetails };
+}
+```
+### 2. Context-Aware Recommendations
+Provide specific guidance based on error patterns:
+```typescript
+function getRecommendation(error: any): string {
+  const message = error?.message?.toLowerCase() || '';
+  if (message.includes('authentication') || message.includes('401')) {
+    return 'Verify connection credentials in Connections section';
+  }
+  if (message.includes('connection') || message.includes('timeout')) {
+    return 'Check network connectivity and API availability';
+  }
+  if (message.includes('retailerid') || message.includes('retailer_id')) {
+    return 'Verify fluentRetailerId activation variable is configured';
+  }
+  if (message.includes('sftp') || message.includes('credentials')) {
+    return 'Verify SFTP connection with valid Basic Authentication';
+  }
+  return 'Review error details and verify configuration';
+}
+```
+### 3. Always Dispose Resources
+Use try/finally to ensure cleanup:
+```typescript
+const sftp = new SftpDataSource(config, log);
+try {
+  // File processing operations
+  const files = await sftp.listFiles();
+  // ... process files
+} catch (error: any) {
+  log.error('Processing failed', { error: error.message });
+  throw error;
+} finally {
+  // ✅ Always dispose, even on error
+  await sftp.dispose();
+  log.info('✅ SFTP connection disposed');
+}
+```
+### 4. Validation Before Operations
+Fail fast with clear error messages:
+```typescript
+// ✅ Validate required configuration early
+const fluentRetailerId = activation.getVariable('fluentRetailerId');
+if (!fluentRetailerId) {
+  log.error('❌ Missing required configuration');
+  return {
+    success: false,
+    error: 'fluentRetailerId activation variable is required',
+    recommendation: 'Configure fluentRetailerId in Activation Variables',
+  };
+}
+// Proceed with validated configuration
+client.setRetailerId(fluentRetailerId);
+```
+---
+## Related Documentation
+- [Client Architecture](../../../04-REFERENCE/architecture/architecture-02-client-architecture.md)
+- [createClient API](../../../04-REFERENCE/architecture/architecture-02-client-architecture.md#best-practices)