@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-05-connections.md

@@ -1,1167 +1,1167 @@
-# Module 5: Connection Management & Security
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 5 of 8** | **Level**: Intermediate | **Time**: 20 minutes
-
----
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- ✅ Understand different connection types in Versori
-- ✅ Configure OAuth2 connections for Fluent Commerce
-- ✅ Manage API key connections for S3 and other services
-- ✅ Validate connections before deployment
-- ✅ Implement connection security best practices
-- ✅ Handle multi-connection scenarios
-- ✅ Troubleshoot connection issues
-
----
-
-## Connection Types Overview
-
-Versori supports multiple connection types for different authentication methods:
-
-| Connection Type | Use Case                                 | Examples                       | Auth Method                        |
-| --------------- | ---------------------------------------- | ------------------------------ | ---------------------------------- |
-| **OAuth2**      | API authentication with token management | Fluent Commerce, Salesforce    | Client credentials, password grant |
-| **API Key**     | Simple token-based auth                  | AWS S3, third-party APIs       | Static API key                     |
-| **Basic Auth**  | Username/password auth                   | Older APIs, internal services | HTTP Basic                         |
-| **Custom**      | Proprietary auth methods                 | Custom headers, signatures     | Custom implementation              |
-
----
-
-## OAuth2 Connections
-
-### Fluent Commerce OAuth2 Configuration
-
-The most common connection type for Fluent Commerce integrations.
-
-#### Step-by-Step Configuration
-
-1. **Navigate to Versori Dashboard**
-   - Go to **Connections** tab
-   - Click **"Add Connection"**
-
-2. **Basic Information**
-
-   ```
-   Name: fluent_commerce
-   Description: Fluent Commerce Production API
-   Type: OAuth2
-   ```
-
-3. **OAuth2 Settings**
-
-   ```
-   Grant Type: client_credentials
-   Auth URL: https://api.fluentcommerce.com/oauth/token
-   Token URL: https://api.fluentcommerce.com/oauth/token
-   Scope: (leave empty for Fluent)
-   ```
-
-4. **Client Credentials**
-
-   ```
-   Client ID: [Your Fluent OAuth2 Client ID]
-   Client Secret: [Your Fluent OAuth2 Client Secret]
-   ```
-
-5. **Additional Configuration**
-
-   ```
-   Base URL: https://api.fluentcommerce.com
-   Custom Headers: {"Content-Type": "application/json"}
-   Custom Parameters: {"retailerId": "1"}
-   ```
-
-6. **Test Connection**
-   - Click **"Test Connection"**
-   - Verify successful token retrieval
-   - Check token expiration settings
-
-### Accessing OAuth2 Connection in Code
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const useConnection = http(
-  'use-connection',
-  {
-    connection: 'fluent_commerce', // Must match connection name in UI
-  },
-  async ctx => {
-    // Auto-configured client from connection
-    const client = await createClient(ctx);
-
-    // Access connection metadata
-    const connectionInfo = ctx.activation?.connection;
-    ctx.log('info', 'Connection details', {
-      url: connectionInfo?.url,
-      hasHeaders: !!connectionInfo?.headers,
-      retailerId: connectionInfo?.params?.retailerId,
-    });
-
-    // Use client normally
-    const result = await client.graphql({
-      query: `query { products(first: 10) { edges { node { id ref } } } }`,
-    });
-
-    return result.data;
-  }
-);
-```
-
-### OAuth2 Token Management
-
-Versori automatically handles:
-
-- **Token acquisition** on first request
-- **Token caching** for subsequent requests
-- **Token refresh** when expired
-- **Error handling** on token failures
-
-**You don't need to manage tokens manually!**
-
----
-
-## API Key Connections
-
-For services that use simple API key authentication (e.g., AWS S3, third-party APIs).
-
-### AWS S3 Connection Example
-
-1. **Create Connection**
-
-   ```
-   Name: aws_s3
-   Description: AWS S3 for inventory files
-   Type: API Key
-   ```
-
-2. **Configuration**
-
-   ```
-   Authentication: Configure on the connection (no inline headers)
-   Additional Headers:
-     - x-secret-key: [Your AWS Secret Key]
-     - x-region: us-east-1
-   ```
-
-3. **Access in Code**
-
-   ```typescript
-   export const readFromS3 = http(
-     'read-s3',
-     {
-       connection: 'aws_s3',
-     },
-     async ctx => {
-       const s3Client = new S3Client({
-         credentials: {
-           accessKeyId: ctx.activation?.connection?.headers?.['x-api-key'],
-           secretAccessKey: ctx.activation?.connection?.headers?.['x-secret-key'],
-         },
-         region: ctx.activation?.connection?.headers?.['x-region'],
-       });
-
-       // Use S3 client...
-     }
-   );
-   ```
-
-### Third-Party API Key Example
-
-```typescript
-export const callThirdParty = http(
-  'third-party-api',
-  {
-    connection: 'third_party_service',
-  },
-  async ctx => {
-    // API key is automatically included in headers
-    const response = await ctx.fetch('https://api.thirdparty.com/data', {
-      method: 'GET',
-      // Headers from connection are automatically included
-    });
-
-    const data = await response.json();
-    return data;
-  }
-);
-```
-
----
-
-## Multi-Connection Scenarios
-
-Many integrations require multiple connections (e.g., Fluent + S3).
-
-### Pattern 1: Primary Connection + SDK Client
-
-```typescript
-import { http } from '@versori/run';
-import { createClient, S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Fetch from S3, send to Fluent
- *
- * Uses: fluent_commerce (primary connection) + S3 credentials from env vars
- */
-export const s3ToFluent = http(
-  's3-to-fluent',
-  {
-    connection: 'fluent_commerce', // Primary connection
-  },
-  async ctx => {
-    // Fluent client from primary connection
-    const client = await createClient(ctx);
-
-    // S3 client from environment variables
-    const s3 = new S3DataSource({
-      region: ctx.vars?.AWS_REGION || 'us-east-1',
-      credentials: {
-        accessKeyId: ctx.vars?.AWS_ACCESS_KEY_ID,
-        secretAccessKey: ctx.vars?.AWS_SECRET_ACCESS_KEY,
-      },
-    });
-
-    // Fetch from S3
-    const csvData = await s3.readFile('inventory-bucket', 'inventory.csv');
-
-    // Parse and send to Fluent
-    const records = parseCSV(csvData);
-    const job = await client.createJob({ name: 'S3 Import' });
-    await client.sendBatch(job.id, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: records,
-    });
-
-    return { success: true, recordCount: records.length };
-  }
-);
-```
-
-### Pattern 2: Multiple Connections via ctx.connections
-
-```typescript
-export const multiConnection = http(
-  'multi-connection',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    // Primary connection (Fluent)
-    const fluentClient = await createClient(ctx);
-
-    // Access other connections
-    const s3Connection = ctx.connections?.aws_s3;
-    const sfccConnection = ctx.connections?.sfcc_api;
-
-    // Use multiple services
-    const fluentData = await fluentClient.graphql({ query: '...' });
-    const s3Data = await fetchFromS3WithConnection(s3Connection);
-    const sfccData = await fetchFromSFCCWithConnection(sfccConnection);
-
-    return {
-      fluent: fluentData,
-      s3: s3Data,
-      sfcc: sfccData,
-    };
-  }
-);
-```
-
----
-
-## Connection Validation
-
-### Pre-Deployment Validation
-
-Before deploying, validate all connections:
-
-```typescript
-import { fn } from '@versori/run';
-
-/**
- * Validate all required connections
- *
- * Run manually before deployment
- */
-export const validateConnections = fn('validate-connections', async ctx => {
-  const requiredConnections = ['fluent_commerce', 'aws_s3', 'sfcc_api'];
-
-  const results = {};
-
-  for (const connName of requiredConnections) {
-    const conn = ctx.connections?.[connName];
-
-    if (!conn) {
-      results[connName] = {
-        status: 'missing',
-        error: 'Connection not configured',
-      };
-      continue;
-    }
-
-    // Basic validation
-    results[connName] = {
-      status: 'configured',
-      hasUrl: !!conn.url,
-      hasHeaders: !!conn.headers,
-      hasParams: !!conn.params,
-    };
-  }
-
-  ctx.log('info', 'Connection validation complete', results);
-
-  return results;
-});
-```
-
-### Runtime Connection Testing
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Test Fluent Commerce connection
- *
- * GET https://{workspace}.versori.run/test-connection
- */
-export const testConnection = http(
-  'test-connection',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    try {
-      const client = await createClient(ctx);
-
-      // Simple query to test connection
-      const result = await client.graphql({
-        query: `query { __typename }`,
-      });
-
-      if (result.errors?.length) {
-        return {
-          success: false,
-          error: 'GraphQL error',
-          details: result.errors[0].message,
-        };
-      }
-
-      ctx.log('info', 'Connection test successful');
-
-      return {
-        success: true,
-        message: 'Connection working',
-        timestamp: new Date().toISOString(),
-      };
-    } catch (error) {
-      ctx.log('error', 'Connection test failed', {
-        error: error instanceof Error ? error.message : String(error),
-      });
-
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : 'Connection failed',
-      };
-    }
-  }
-);
-```
-
----
-
-## Security Best Practices
-
-### 1. Never Hardcode Credentials
-
-```typescript
-// ❌ WRONG - Hardcoded credentials
-export const bad = http(
-  'bad',
-  {
-    connection: 'fluent',
-  },
-  async ctx => {
-    const clientId = 'my-client-id'; // NEVER do this!
-    const clientSecret = 'my-secret'; // NEVER do this!
-  }
-);
-
-// ✅ CORRECT - Use connection or environment variables
-export const good = http(
-  'good',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const client = await createClient(ctx); // Credentials from connection
-  }
-);
-```
-
-### 2. Use Connector Variables for Secrets
-
-Configure sensitive values in Versori UI:
-
-**Versori Dashboard → Connector → Variables**:
-
-```
-Name: FLUENT_WEBHOOK_PUBLIC_KEY
-Value: -----BEGIN PUBLIC KEY-----...
-Type: Secret
-```
-
-**Access in code**:
-
-```typescript
-export const useSecrets = webhook('use-secrets', async ctx => {
-  // Access secret variable
-  const publicKey = ctx.vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
-
-  if (!publicKey) {
-    return { error: 'Missing public key configuration' };
-  }
-
-  // Use securely
-  const validator = new WebhookValidationService({ publicKey });
-  // ...
-});
-```
-
-### 3. Environment-Specific Connections
-
-Maintain separate connections for each environment:
-
-```
-Development:
-  - fluent_commerce_dev
-  - aws_s3_dev
-
-Staging:
-  - fluent_commerce_staging
-  - aws_s3_staging
-
-Production:
-  - fluent_commerce_prod
-  - aws_s3_prod
-```
-
-**Code pattern**:
-
-```typescript
-export const envAwareWorkflow = http(
-  'env-aware',
-  {
-    connection:
-      process.env.NODE_ENV === 'production' ? 'fluent_commerce_prod' : 'fluent_commerce_dev',
-  },
-  async ctx => {
-    const client = await createClient(ctx);
-    // ...
-  }
-);
-```
-
-### 4. Rotate Credentials Regularly
-
-- **OAuth2 Client Secrets**: Rotate every 90 days
-- **API Keys**: Rotate every 180 days
-- **Webhook Public Keys**: Rotate on security events
-
-**Update process**:
-
-1. Generate new credentials in source system
-2. Update connection in Versori UI
-3. Test connection
-4. Deactivate old credentials after confirmation
-
-### 5. Audit Connection Access
-
-```typescript
-export const auditedWorkflow = http(
-  'audited',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    // Log connection usage
-    ctx.log('info', 'Connection accessed', {
-      workflow: 'audited',
-      connection: 'fluent_commerce',
-      timestamp: Date.now(),
-      executionId: ctx.executionId,
-      user: ctx.activation?.user || 'system',
-    });
-
-    const client = await createClient(ctx);
-    // ... rest of workflow
-  }
-);
-```
-
----
-
-## Accessing All Connections (v0.4.x+)
-
-### NEW: activation.connections Array
-
-As of @versori/run v0.4.x, you can access **all configured connections** for the current activation via `ctx.activation.connections`.
-
-#### Connection Structure
-
-```typescript
-type Connection = {
-  id: string;              // Unique connection ID
-  name: string;            // Connection name (matches UI)
-  templateId: string;      // Connection template/type ID
-  dynamic: boolean;        // Whether connection is dynamic
-  baseUrl: string;         // Base URL for the connection
-  createdAt: string;       // ISO timestamp
-  updatedAt: string;       // ISO timestamp
-  credentials: ConnectionCredential[];  // Credential details
-}
-```
-
-#### Listing All Available Connections
-
-```typescript
-import { fn } from '@versori/run';
-
-/**
- * List all connections for current activation
- */
-export const listConnections = fn('list-connections', ctx => {
-  const connections = ctx.activation.connections;
-
-  if (!connections || connections.length === 0) {
-    return { message: 'No connections configured', count: 0 };
-  }
-
-  ctx.log.info('Available connections', {
-    count: connections.length,
-    names: connections.map(c => c.name)
-  });
-
-  return {
-    count: connections.length,
-    connections: connections.map(c => ({
-      name: c.name,
-      id: c.id,
-      baseUrl: c.baseUrl,
-      dynamic: c.dynamic,
-      createdAt: c.createdAt
-    }))
-  };
-});
-```
-
-#### Finding Specific Connection
-
-```typescript
-import { fn } from '@versori/run';
-
-/**
- * Check if Fluent Commerce connection exists
- */
-export const checkFluentConnection = fn('check-fluent-connection', ctx => {
-  const connections = ctx.activation.connections;
-  const fluentConn = connections?.find(c => c.name === 'fluent_commerce');
-
-  if (!fluentConn) {
-    throw new Error('Fluent Commerce connection not configured');
-  }
-
-  ctx.log.info('Fluent connection found', {
-    id: fluentConn.id,
-    baseUrl: fluentConn.baseUrl,
-    dynamic: fluentConn.dynamic
-  });
-
-  return {
-    found: true,
-    connectionId: fluentConn.id,
-    baseUrl: fluentConn.baseUrl
-  };
-});
-```
-
-### Multi-Tenant Pattern with activation.connections
-
-**Use Case**: One connector serves multiple customers, each with their own Fluent instance.
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Multi-tenant order creation
- *
- * POST https://{workspace}.versori.run/create-order
- * Body: { customerId: "customer-a", orderData: {...} }
- */
-export const multiTenantOrderCreate = webhook('multi-tenant-order-create', {
-  response: { mode: 'sync' },
-})
-  // Step 1: Route to correct Fluent connection (fn)
-  .then(fn('route-connection', ctx => {
-    const { customerId, orderData } = ctx.data;
-
-    if (!customerId) {
-      throw new Error('customerId is required');
-    }
-
-    // Access all connections
-    const connections = ctx.activation.connections;
-
-    if (!connections || connections.length === 0) {
-      throw new Error('No connections configured for this activation');
-    }
-
-    // Find customer-specific connection
-    // Convention: connections named fluent_customer-a, fluent_customer-b, etc.
-    const connectionName = `fluent_${customerId.toLowerCase()}`;
-    const connection = connections.find(c => c.name === connectionName);
-
-    if (!connection) {
-      throw new Error(`No Fluent connection found for customer: ${customerId}`);
-    }
-
-    ctx.log.info('Routed to customer connection', {
-      customerId,
-      connectionName: connection.name,
-      connectionId: connection.id,
-      baseUrl: connection.baseUrl
-    });
-
-    return {
-      connectionName: connection.name,
-      customerId,
-      orderData
-    };
-  }))
-
-  // Step 2: Create order in customer's Fluent instance (http)
-  .then(http('create-order', (ctx) => {
-    // Return dynamic connection based on routing
-    return { connection: ctx.data.connectionName };
-  }, async ctx => {
-    const { customerId, orderData } = ctx.data;
-
-    // Create client with customer-specific connection
-    const client = await createClient(ctx);
-
-    // Create order
-    const result = await client.graphql({
-      query: `
-        mutation CreateOrder($input: CreateOrderInput!) {
-          createOrder(input: $input) {
-            id
-            ref
-            status
-          }
-        }
-      `,
-      variables: { input: orderData }
-    });
-
-    if (result.errors?.length) {
-      throw new Error(`Order creation failed: ${result.errors[0].message}`);
-    }
-
-    ctx.log.info('Order created', {
-      customerId,
-      orderId: result.data.createOrder.id
-    });
-
-    return {
-      success: true,
-      customerId,
-      orderId: result.data.createOrder.id,
-      orderRef: result.data.createOrder.ref
-    };
-  }))
-
-  .catch(({ data }) => ({
-    success: false,
-    error: data instanceof Error ? data.message : String(data),
-    status: 500
-  }));
-```
-
-### Iterating Through Multiple Connections
-
-**Use Case**: Health check across all Fluent connections.
-
-```typescript
-import { fn, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Test all Fluent connections
- *
- * GET https://{workspace}.versori.run/test-all-connections
- */
-export const testAllConnections = fn('test-all-fluent', async ctx => {
-  const connections = ctx.activation.connections;
-
-  // Filter to only Fluent connections (by name convention)
-  const fluentConnections = connections?.filter(c =>
-    c.name.startsWith('fluent_')
-  ) || [];
-
-  if (fluentConnections.length === 0) {
-    return { message: 'No Fluent connections found', count: 0 };
-  }
-
-  ctx.log.info('Testing Fluent connections', {
-    count: fluentConnections.length
-  });
-
-  const results = [];
-
-  // Test each connection
-  for (const conn of fluentConnections) {
-    try {
-      // Note: To actually test, we'd need to use http() with the connection
-      // This example shows discovery only
-      results.push({
-        name: conn.name,
-        id: conn.id,
-        baseUrl: conn.baseUrl,
-        status: 'configured',
-        available: true
-      });
-    } catch (error) {
-      results.push({
-        name: conn.name,
-        id: conn.id,
-        status: 'error',
-        available: false,
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-
-  return {
-    totalConnections: fluentConnections.length,
-    results
-  };
-});
-```
-
-### Validation Pattern: Required Connections
-
-```typescript
-import { fn } from '@versori/run';
-
-/**
- * Validate required connections exist
- *
- * Recommended to run at connector startup
- */
-export const validateRequiredConnections = fn('validate-required', ctx => {
-  const required = ['fluent_commerce', 'aws_s3', 'sftp_warehouse'];
-  const connections = ctx.activation.connections || [];
-  const connectionNames = new Set(connections.map(c => c.name));
-
-  const missing = required.filter(name => !connectionNames.has(name));
-
-  if (missing.length > 0) {
-    throw new Error(`Missing required connections: ${missing.join(', ')}`);
-  }
-
-  ctx.log.info('All required connections configured', {
-    required: required.length,
-    configured: connections.length
-  });
-
-  return {
-    valid: true,
-    requiredConnections: required,
-    totalConnections: connections.length
-  };
-});
-```
-
----
-
-## Activation Environment & Dynamic Variables (v0.4.x+)
-
-### activation.environment
-
-Access the current activation's environment information:
-
-```typescript
-import { fn } from '@versori/run';
-
-/**
- * Check environment and apply environment-specific logic
- */
-export const envAwareWorkflow = fn('env-aware', ctx => {
-  const env = ctx.activation.environment;
-
-  if (!env) {
-    ctx.log.warn('No environment information available');
-    return { environment: 'unknown' };
-  }
-
-  ctx.log.info('Environment details', {
-    id: env.id,
-    name: env.name,
-    type: env.type  // e.g., 'development', 'staging', 'production'
-  });
-
-  // Conditional logic based on environment
-  if (env.name === 'production') {
-    // Use production-specific settings
-    return {
-      environment: 'production',
-      batchSize: 1000,
-      retryAttempts: 5,
-      timeout: 60000
-    };
-  } else if (env.name === 'staging') {
-    return {
-      environment: 'staging',
-      batchSize: 100,
-      retryAttempts: 3,
-      timeout: 30000
-    };
-  } else {
-    return {
-      environment: 'development',
-      batchSize: 10,
-      retryAttempts: 1,
-      timeout: 10000
-    };
-  }
-});
-```
-
-### activation.dynamicVariables
-
-Access dynamic variables set at the activation level:
-
-```typescript
-import { fn } from '@versori/run';
-
-/**
- * Access activation-level dynamic variables
- */
-export const useDynamicVars = fn('use-dynamic-vars', ctx => {
-  // Get variables using getVariable
-  const apiKey = ctx.activation.getVariable<string>('API_KEY');
-  const retailerId = ctx.activation.getVariable<number>('RETAILER_ID');
-  const region = ctx.activation.getVariable<string>('AWS_REGION');
-
-  ctx.log.info('Dynamic variables', {
-    hasApiKey: !!apiKey,
-    retailerId,
-    region
-  });
-
-  // Use variables in your workflow
-  return {
-    retailerId,
-    region,
-    configured: !!apiKey && !!retailerId
-  };
-});
-```
-
-### Setting Variables Programmatically
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Cache frequently-used data in activation variables
- */
-export const cacheRetailerConfig = http(
-  'cache-retailer-config',
-  { connection: 'fluent_commerce' },
-  async ctx => {
-    const client = await createClient(ctx);
-
-    // Query Fluent for retailer configuration
-    const result = await client.graphql({
-      query: `
-        query GetRetailer($id: Int!) {
-          retailer(id: $id) {
-            id
-            name
-            tradingName
-            supportEmail
-            primaryLocation {
-              ref
-            }
-          }
-        }
-      `,
-      variables: { id: 1 }
-    });
-
-    const retailer = result.data.retailer;
-
-    // Cache in activation variables for future workflows
-    await ctx.activation.setVariable('CACHED_RETAILER_ID', retailer.id);
-    await ctx.activation.setVariable('CACHED_RETAILER_NAME', retailer.name);
-    await ctx.activation.setVariable('CACHED_PRIMARY_LOCATION', retailer.primaryLocation.ref);
-    await ctx.activation.setVariable('LAST_CONFIG_REFRESH', Date.now());
-
-    ctx.log.info('Retailer config cached', {
-      retailerId: retailer.id,
-      retailerName: retailer.name
-    });
-
-    return {
-      cached: true,
-      retailer: {
-        id: retailer.id,
-        name: retailer.name
-      }
-    };
-  }
-);
-```
-
-### Complete ActivationImpl Reference
-
-```typescript
-interface ActivationImpl {
-  // Properties
-  get id(): string;                                     // Activation ID
-  get user(): EndUser;                                  // User info
-  get environment(): ProjectEnvironment | undefined;    // ✅ NEW in v0.4.x
-  get connections(): Array<Connection> | undefined;     // ✅ NEW in v0.4.x
-  get dynamicVariables(): DynamicVariables | undefined; // ✅ NEW in v0.4.x
-
-  // Methods
-  getVariable<T = unknown>(name: string): T | undefined;
-  setVariable(name: string, value: unknown): Promise<void>;
-}
-```
-
----
-
-## Troubleshooting Connection Issues
-
-### Common Issues & Solutions
-
-| Issue                    | Symptoms                             | Solution                                                   |
-| ------------------------ | ------------------------------------ | ---------------------------------------------------------- |
-| **Connection not found** | `Error: Connection 'xyz' not found`  | Verify connection name matches UI exactly (case-sensitive) |
-| **Token expired**        | `401 Unauthorized`                   | Versori should auto-refresh; check token URL configuration |
-| **Invalid credentials**  | `403 Forbidden`                      | Verify Client ID/Secret in Fluent dashboard                |
-| **Missing retailerId**   | `retailerId is required for job creation` | Use `client.setRetailerId('1')` or pass in method call. See [retailerId Configuration Guide](../../../../00-START-HERE/retailerid-configuration.md) |
-| **CORS errors**          | `CORS policy blocked`                | Enable CORS in webhook configuration                       |
-| **Rate limiting**        | `429 Too Many Requests`              | Implement retry with backoff, check Fluent API limits      |
-
-### Debug Connection Configuration
-
-```typescript
-export const debugConnection = http(
-  'debug-connection',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const conn = ctx.activation?.connection;
-
-    // Log all connection details (except secrets)
-    ctx.log('debug', 'Connection configuration', {
-      hasConnection: !!conn,
-      url: conn?.url,
-      headerKeys: conn?.headers ? Object.keys(conn.headers) : [],
-      paramKeys: conn?.params ? Object.keys(conn.params) : [],
-      retailerId: conn?.params?.retailerId,
-    });
-
-    // Test basic connectivity
-    try {
-      const response = await ctx.fetch(conn?.url || 'https://api.fluentcommerce.com', {
-        method: 'HEAD',
-      });
-
-      return {
-        connectionStatus: 'reachable',
-        statusCode: response.status,
-        headers: Object.fromEntries(response.headers.entries()),
-      };
-    } catch (error) {
-      return {
-        connectionStatus: 'unreachable',
-        error: error instanceof Error ? error.message : String(error),
-      };
-    }
-  }
-);
-```
-
-### Validate OAuth2 Token
-
-```typescript
-export const validateToken = http(
-  'validate-token',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const conn = ctx.activation?.connection;
-
-    // Extract token from headers (Versori auto-includes)
-    const authHeader = conn?.headers?.['Authorization'];
-
-    if (!authHeader) {
-      return { error: 'No authorization header found' };
-    }
-
-    // Parse token (Bearer <token>)
-    const token = authHeader.replace('Bearer ', '');
-
-    // Decode JWT (if applicable)
-    try {
-      const parts = token.split('.');
-      if (parts.length === 3) {
-        const payload = JSON.parse(atob(parts[1]));
-
-        return {
-          tokenValid: true,
-          expiresAt: payload.exp ? new Date(payload.exp * 1000).toISOString() : 'unknown',
-          issuedAt: payload.iat ? new Date(payload.iat * 1000).toISOString() : 'unknown',
-          scopes: payload.scope || [],
-        };
-      }
-    } catch (error) {
-      return {
-        tokenValid: false,
-        error: 'Invalid JWT format',
-      };
-    }
-
-    return { tokenValid: true, tokenLength: token.length };
-  }
-);
-```
-
----
-
-## Advanced Connection Patterns
-
-### Pattern 1: Connection Fallback
-
-```typescript
-export const withFallback = http(
-  'connection-fallback',
-  {
-    connection: 'fluent_commerce_primary',
-  },
-  async ctx => {
-    try {
-      // Try primary connection
-      const client = await createClient(ctx);
-      return await client.graphql({ query: '...' });
-    } catch (primaryError) {
-      ctx.log('warn', 'Primary connection failed, trying fallback');
-
-      try {
-        // Fallback to secondary connection
-        const fallbackClient = await createClient({
-          connection: ctx.connections?.fluent_commerce_secondary,
-          log: ctx.log,
-        });
-
-        return await fallbackClient.graphql({ query: '...' });
-      } catch (fallbackError) {
-        throw new Error('All connections failed');
-      }
-    }
-  }
-);
-```
-
-### Pattern 2: Dynamic Connection Selection
-
-```typescript
-export const dynamicConnection = http('dynamic-connection', async ctx => {
-  // Select connection based on request parameter
-  const environment = ctx.query?.env || 'production';
-
-  const connectionName =
-    environment === 'staging' ? 'fluent_commerce_staging' : 'fluent_commerce_prod';
-
-  ctx.log('info', 'Selected connection', { connectionName, environment });
-
-  // Note: This pattern requires accessing ctx.connections
-  const client = await createClient({
-    connection: ctx.connections?.[connectionName],
-    log: ctx.log,
-  });
-
-  return await client.graphql({ query: '...' });
-});
-```
-
----
-
-## Key Takeaways
-
-- 🎯 **OAuth2 connections** are managed by Versori - automatic token refresh
-- 🎯 **Connection name** in code must match UI exactly (case-sensitive)
-- 🎯 **Never hardcode** credentials - use connections or environment variables
-- 🎯 **Multi-connection scenarios** use primary connection + ctx.connections
-- 🎯 **Validate connections** before deployment with test workflows
-- 🎯 **Security best practices**: rotate credentials, use secrets, audit access
-- 🎯 **Troubleshooting**: check name match, token expiration, credential validity
-
----
-
-## Practice Exercise
-
-Create a workflow that:
-
-1. Uses OAuth2 connection to Fluent Commerce
-2. Validates connection on startup
-3. Falls back to secondary connection on failure
-4. Logs all connection attempts for audit
-5. Returns connection health status
-
-**Hints**:
-
-- Use `http()` with primary connection
-- Implement try/catch for fallback
-- Use `ctx.log()` for audit trail
-- Test token validity before GraphQL calls
-
-**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
-
----
-
-## Next Steps
-
-Now that you understand connection management, let's explore state management with KV storage.
-
-Continue to [Module 6: KV Storage →](./platforms-versori-06-kv-storage.md) to learn about distributed state, file tracking, and caching patterns.
-
----
-
-## Related Documentation
-
-- [Module 3: Authentication](./platforms-versori-03-authentication.md) - OAuth2 basics
-- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Using connections in workflows
-- [Module 6: KV Storage](./platforms-versori-06-kv-storage.md) - State management
-- [Module 8: Best Practices](./platforms-versori-08-best-practices.md) - Security hardening
-
----
-
-[← Previous: Module 4](./platforms-versori-04-workflows.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 6: KV Storage →](./platforms-versori-06-kv-storage.md)
+# Module 5: Connection Management & Security
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 5 of 8** | **Level**: Intermediate | **Time**: 20 minutes
+
+---
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- ✅ Understand different connection types in Versori
+- ✅ Configure OAuth2 connections for Fluent Commerce
+- ✅ Manage API key connections for S3 and other services
+- ✅ Validate connections before deployment
+- ✅ Implement connection security best practices
+- ✅ Handle multi-connection scenarios
+- ✅ Troubleshoot connection issues
+
+---
+
+## Connection Types Overview
+
+Versori supports multiple connection types for different authentication methods:
+
+| Connection Type | Use Case                                 | Examples                       | Auth Method                        |
+| --------------- | ---------------------------------------- | ------------------------------ | ---------------------------------- |
+| **OAuth2**      | API authentication with token management | Fluent Commerce, Salesforce    | Client credentials, password grant |
+| **API Key**     | Simple token-based auth                  | AWS S3, third-party APIs       | Static API key                     |
+| **Basic Auth**  | Username/password auth                   | Older APIs, internal services | HTTP Basic                         |
+| **Custom**      | Proprietary auth methods                 | Custom headers, signatures     | Custom implementation              |
+
+---
+
+## OAuth2 Connections
+
+### Fluent Commerce OAuth2 Configuration
+
+The most common connection type for Fluent Commerce integrations.
+
+#### Step-by-Step Configuration
+
+1. **Navigate to Versori Dashboard**
+   - Go to **Connections** tab
+   - Click **"Add Connection"**
+
+2. **Basic Information**
+
+   ```
+   Name: fluent_commerce
+   Description: Fluent Commerce Production API
+   Type: OAuth2
+   ```
+
+3. **OAuth2 Settings**
+
+   ```
+   Grant Type: client_credentials
+   Auth URL: https://api.fluentcommerce.com/oauth/token
+   Token URL: https://api.fluentcommerce.com/oauth/token
+   Scope: (leave empty for Fluent)
+   ```
+
+4. **Client Credentials**
+
+   ```
+   Client ID: [Your Fluent OAuth2 Client ID]
+   Client Secret: [Your Fluent OAuth2 Client Secret]
+   ```
+
+5. **Additional Configuration**
+
+   ```
+   Base URL: https://api.fluentcommerce.com
+   Custom Headers: {"Content-Type": "application/json"}
+   Custom Parameters: {"retailerId": "1"}
+   ```
+
+6. **Test Connection**
+   - Click **"Test Connection"**
+   - Verify successful token retrieval
+   - Check token expiration settings
+
+### Accessing OAuth2 Connection in Code
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const useConnection = http(
+  'use-connection',
+  {
+    connection: 'fluent_commerce', // Must match connection name in UI
+  },
+  async ctx => {
+    // Auto-configured client from connection
+    const client = await createClient(ctx);
+
+    // Access connection metadata
+    const connectionInfo = ctx.activation?.connection;
+    ctx.log('info', 'Connection details', {
+      url: connectionInfo?.url,
+      hasHeaders: !!connectionInfo?.headers,
+      retailerId: connectionInfo?.params?.retailerId,
+    });
+
+    // Use client normally
+    const result = await client.graphql({
+      query: `query { products(first: 10) { edges { node { id ref } } } }`,
+    });
+
+    return result.data;
+  }
+);
+```
+
+### OAuth2 Token Management
+
+Versori automatically handles:
+
+- **Token acquisition** on first request
+- **Token caching** for subsequent requests
+- **Token refresh** when expired
+- **Error handling** on token failures
+
+**You don't need to manage tokens manually!**
+
+---
+
+## API Key Connections
+
+For services that use simple API key authentication (e.g., AWS S3, third-party APIs).
+
+### AWS S3 Connection Example
+
+1. **Create Connection**
+
+   ```
+   Name: aws_s3
+   Description: AWS S3 for inventory files
+   Type: API Key
+   ```
+
+2. **Configuration**
+
+   ```
+   Authentication: Configure on the connection (no inline headers)
+   Additional Headers:
+     - x-secret-key: [Your AWS Secret Key]
+     - x-region: us-east-1
+   ```
+
+3. **Access in Code**
+
+   ```typescript
+   export const readFromS3 = http(
+     'read-s3',
+     {
+       connection: 'aws_s3',
+     },
+     async ctx => {
+       const s3Client = new S3Client({
+         credentials: {
+           accessKeyId: ctx.activation?.connection?.headers?.['x-api-key'],
+           secretAccessKey: ctx.activation?.connection?.headers?.['x-secret-key'],
+         },
+         region: ctx.activation?.connection?.headers?.['x-region'],
+       });
+
+       // Use S3 client...
+     }
+   );
+   ```
+
+### Third-Party API Key Example
+
+```typescript
+export const callThirdParty = http(
+  'third-party-api',
+  {
+    connection: 'third_party_service',
+  },
+  async ctx => {
+    // API key is automatically included in headers
+    const response = await ctx.fetch('https://api.thirdparty.com/data', {
+      method: 'GET',
+      // Headers from connection are automatically included
+    });
+
+    const data = await response.json();
+    return data;
+  }
+);
+```
+
+---
+
+## Multi-Connection Scenarios
+
+Many integrations require multiple connections (e.g., Fluent + S3).
+
+### Pattern 1: Primary Connection + SDK Client
+
+```typescript
+import { http } from '@versori/run';
+import { createClient, S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Fetch from S3, send to Fluent
+ *
+ * Uses: fluent_commerce (primary connection) + S3 credentials from env vars
+ */
+export const s3ToFluent = http(
+  's3-to-fluent',
+  {
+    connection: 'fluent_commerce', // Primary connection
+  },
+  async ctx => {
+    // Fluent client from primary connection
+    const client = await createClient(ctx);
+
+    // S3 client from environment variables
+    const s3 = new S3DataSource({
+      region: ctx.vars?.AWS_REGION || 'us-east-1',
+      credentials: {
+        accessKeyId: ctx.vars?.AWS_ACCESS_KEY_ID,
+        secretAccessKey: ctx.vars?.AWS_SECRET_ACCESS_KEY,
+      },
+    });
+
+    // Fetch from S3
+    const csvData = await s3.readFile('inventory-bucket', 'inventory.csv');
+
+    // Parse and send to Fluent
+    const records = parseCSV(csvData);
+    const job = await client.createJob({ name: 'S3 Import' });
+    await client.sendBatch(job.id, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: records,
+    });
+
+    return { success: true, recordCount: records.length };
+  }
+);
+```
+
+### Pattern 2: Multiple Connections via ctx.connections
+
+```typescript
+export const multiConnection = http(
+  'multi-connection',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    // Primary connection (Fluent)
+    const fluentClient = await createClient(ctx);
+
+    // Access other connections
+    const s3Connection = ctx.connections?.aws_s3;
+    const sfccConnection = ctx.connections?.sfcc_api;
+
+    // Use multiple services
+    const fluentData = await fluentClient.graphql({ query: '...' });
+    const s3Data = await fetchFromS3WithConnection(s3Connection);
+    const sfccData = await fetchFromSFCCWithConnection(sfccConnection);
+
+    return {
+      fluent: fluentData,
+      s3: s3Data,
+      sfcc: sfccData,
+    };
+  }
+);
+```
+
+---
+
+## Connection Validation
+
+### Pre-Deployment Validation
+
+Before deploying, validate all connections:
+
+```typescript
+import { fn } from '@versori/run';
+
+/**
+ * Validate all required connections
+ *
+ * Run manually before deployment
+ */
+export const validateConnections = fn('validate-connections', async ctx => {
+  const requiredConnections = ['fluent_commerce', 'aws_s3', 'sfcc_api'];
+
+  const results = {};
+
+  for (const connName of requiredConnections) {
+    const conn = ctx.connections?.[connName];
+
+    if (!conn) {
+      results[connName] = {
+        status: 'missing',
+        error: 'Connection not configured',
+      };
+      continue;
+    }
+
+    // Basic validation
+    results[connName] = {
+      status: 'configured',
+      hasUrl: !!conn.url,
+      hasHeaders: !!conn.headers,
+      hasParams: !!conn.params,
+    };
+  }
+
+  ctx.log('info', 'Connection validation complete', results);
+
+  return results;
+});
+```
+
+### Runtime Connection Testing
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Test Fluent Commerce connection
+ *
+ * GET https://{workspace}.versori.run/test-connection
+ */
+export const testConnection = http(
+  'test-connection',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    try {
+      const client = await createClient(ctx);
+
+      // Simple query to test connection
+      const result = await client.graphql({
+        query: `query { __typename }`,
+      });
+
+      if (result.errors?.length) {
+        return {
+          success: false,
+          error: 'GraphQL error',
+          details: result.errors[0].message,
+        };
+      }
+
+      ctx.log('info', 'Connection test successful');
+
+      return {
+        success: true,
+        message: 'Connection working',
+        timestamp: new Date().toISOString(),
+      };
+    } catch (error) {
+      ctx.log('error', 'Connection test failed', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Connection failed',
+      };
+    }
+  }
+);
+```
+
+---
+
+## Security Best Practices
+
+### 1. Never Hardcode Credentials
+
+```typescript
+// ❌ WRONG - Hardcoded credentials
+export const bad = http(
+  'bad',
+  {
+    connection: 'fluent',
+  },
+  async ctx => {
+    const clientId = 'my-client-id'; // NEVER do this!
+    const clientSecret = 'my-secret'; // NEVER do this!
+  }
+);
+
+// ✅ CORRECT - Use connection or environment variables
+export const good = http(
+  'good',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const client = await createClient(ctx); // Credentials from connection
+  }
+);
+```
+
+### 2. Use Connector Variables for Secrets
+
+Configure sensitive values in Versori UI:
+
+**Versori Dashboard → Connector → Variables**:
+
+```
+Name: FLUENT_WEBHOOK_PUBLIC_KEY
+Value: -----BEGIN PUBLIC KEY-----...
+Type: Secret
+```
+
+**Access in code**:
+
+```typescript
+export const useSecrets = webhook('use-secrets', async ctx => {
+  // Access secret variable
+  const publicKey = ctx.vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
+
+  if (!publicKey) {
+    return { error: 'Missing public key configuration' };
+  }
+
+  // Use securely
+  const validator = new WebhookValidationService({ publicKey });
+  // ...
+});
+```
+
+### 3. Environment-Specific Connections
+
+Maintain separate connections for each environment:
+
+```
+Development:
+  - fluent_commerce_dev
+  - aws_s3_dev
+
+Staging:
+  - fluent_commerce_staging
+  - aws_s3_staging
+
+Production:
+  - fluent_commerce_prod
+  - aws_s3_prod
+```
+
+**Code pattern**:
+
+```typescript
+export const envAwareWorkflow = http(
+  'env-aware',
+  {
+    connection:
+      process.env.NODE_ENV === 'production' ? 'fluent_commerce_prod' : 'fluent_commerce_dev',
+  },
+  async ctx => {
+    const client = await createClient(ctx);
+    // ...
+  }
+);
+```
+
+### 4. Rotate Credentials Regularly
+
+- **OAuth2 Client Secrets**: Rotate every 90 days
+- **API Keys**: Rotate every 180 days
+- **Webhook Public Keys**: Rotate on security events
+
+**Update process**:
+
+1. Generate new credentials in source system
+2. Update connection in Versori UI
+3. Test connection
+4. Deactivate old credentials after confirmation
+
+### 5. Audit Connection Access
+
+```typescript
+export const auditedWorkflow = http(
+  'audited',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    // Log connection usage
+    ctx.log('info', 'Connection accessed', {
+      workflow: 'audited',
+      connection: 'fluent_commerce',
+      timestamp: Date.now(),
+      executionId: ctx.executionId,
+      user: ctx.activation?.user || 'system',
+    });
+
+    const client = await createClient(ctx);
+    // ... rest of workflow
+  }
+);
+```
+
+---
+
+## Accessing All Connections (v0.4.x+)
+
+### NEW: activation.connections Array
+
+As of @versori/run v0.4.x, you can access **all configured connections** for the current activation via `ctx.activation.connections`.
+
+#### Connection Structure
+
+```typescript
+type Connection = {
+  id: string;              // Unique connection ID
+  name: string;            // Connection name (matches UI)
+  templateId: string;      // Connection template/type ID
+  dynamic: boolean;        // Whether connection is dynamic
+  baseUrl: string;         // Base URL for the connection
+  createdAt: string;       // ISO timestamp
+  updatedAt: string;       // ISO timestamp
+  credentials: ConnectionCredential[];  // Credential details
+}
+```
+
+#### Listing All Available Connections
+
+```typescript
+import { fn } from '@versori/run';
+
+/**
+ * List all connections for current activation
+ */
+export const listConnections = fn('list-connections', ctx => {
+  const connections = ctx.activation.connections;
+
+  if (!connections || connections.length === 0) {
+    return { message: 'No connections configured', count: 0 };
+  }
+
+  ctx.log.info('Available connections', {
+    count: connections.length,
+    names: connections.map(c => c.name)
+  });
+
+  return {
+    count: connections.length,
+    connections: connections.map(c => ({
+      name: c.name,
+      id: c.id,
+      baseUrl: c.baseUrl,
+      dynamic: c.dynamic,
+      createdAt: c.createdAt
+    }))
+  };
+});
+```
+
+#### Finding Specific Connection
+
+```typescript
+import { fn } from '@versori/run';
+
+/**
+ * Check if Fluent Commerce connection exists
+ */
+export const checkFluentConnection = fn('check-fluent-connection', ctx => {
+  const connections = ctx.activation.connections;
+  const fluentConn = connections?.find(c => c.name === 'fluent_commerce');
+
+  if (!fluentConn) {
+    throw new Error('Fluent Commerce connection not configured');
+  }
+
+  ctx.log.info('Fluent connection found', {
+    id: fluentConn.id,
+    baseUrl: fluentConn.baseUrl,
+    dynamic: fluentConn.dynamic
+  });
+
+  return {
+    found: true,
+    connectionId: fluentConn.id,
+    baseUrl: fluentConn.baseUrl
+  };
+});
+```
+
+### Multi-Tenant Pattern with activation.connections
+
+**Use Case**: One connector serves multiple customers, each with their own Fluent instance.
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Multi-tenant order creation
+ *
+ * POST https://{workspace}.versori.run/create-order
+ * Body: { customerId: "customer-a", orderData: {...} }
+ */
+export const multiTenantOrderCreate = webhook('multi-tenant-order-create', {
+  response: { mode: 'sync' },
+})
+  // Step 1: Route to correct Fluent connection (fn)
+  .then(fn('route-connection', ctx => {
+    const { customerId, orderData } = ctx.data;
+
+    if (!customerId) {
+      throw new Error('customerId is required');
+    }
+
+    // Access all connections
+    const connections = ctx.activation.connections;
+
+    if (!connections || connections.length === 0) {
+      throw new Error('No connections configured for this activation');
+    }
+
+    // Find customer-specific connection
+    // Convention: connections named fluent_customer-a, fluent_customer-b, etc.
+    const connectionName = `fluent_${customerId.toLowerCase()}`;
+    const connection = connections.find(c => c.name === connectionName);
+
+    if (!connection) {
+      throw new Error(`No Fluent connection found for customer: ${customerId}`);
+    }
+
+    ctx.log.info('Routed to customer connection', {
+      customerId,
+      connectionName: connection.name,
+      connectionId: connection.id,
+      baseUrl: connection.baseUrl
+    });
+
+    return {
+      connectionName: connection.name,
+      customerId,
+      orderData
+    };
+  }))
+
+  // Step 2: Create order in customer's Fluent instance (http)
+  .then(http('create-order', (ctx) => {
+    // Return dynamic connection based on routing
+    return { connection: ctx.data.connectionName };
+  }, async ctx => {
+    const { customerId, orderData } = ctx.data;
+
+    // Create client with customer-specific connection
+    const client = await createClient(ctx);
+
+    // Create order
+    const result = await client.graphql({
+      query: `
+        mutation CreateOrder($input: CreateOrderInput!) {
+          createOrder(input: $input) {
+            id
+            ref
+            status
+          }
+        }
+      `,
+      variables: { input: orderData }
+    });
+
+    if (result.errors?.length) {
+      throw new Error(`Order creation failed: ${result.errors[0].message}`);
+    }
+
+    ctx.log.info('Order created', {
+      customerId,
+      orderId: result.data.createOrder.id
+    });
+
+    return {
+      success: true,
+      customerId,
+      orderId: result.data.createOrder.id,
+      orderRef: result.data.createOrder.ref
+    };
+  }))
+
+  .catch(({ data }) => ({
+    success: false,
+    error: data instanceof Error ? data.message : String(data),
+    status: 500
+  }));
+```
+
+### Iterating Through Multiple Connections
+
+**Use Case**: Health check across all Fluent connections.
+
+```typescript
+import { fn, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Test all Fluent connections
+ *
+ * GET https://{workspace}.versori.run/test-all-connections
+ */
+export const testAllConnections = fn('test-all-fluent', async ctx => {
+  const connections = ctx.activation.connections;
+
+  // Filter to only Fluent connections (by name convention)
+  const fluentConnections = connections?.filter(c =>
+    c.name.startsWith('fluent_')
+  ) || [];
+
+  if (fluentConnections.length === 0) {
+    return { message: 'No Fluent connections found', count: 0 };
+  }
+
+  ctx.log.info('Testing Fluent connections', {
+    count: fluentConnections.length
+  });
+
+  const results = [];
+
+  // Test each connection
+  for (const conn of fluentConnections) {
+    try {
+      // Note: To actually test, we'd need to use http() with the connection
+      // This example shows discovery only
+      results.push({
+        name: conn.name,
+        id: conn.id,
+        baseUrl: conn.baseUrl,
+        status: 'configured',
+        available: true
+      });
+    } catch (error) {
+      results.push({
+        name: conn.name,
+        id: conn.id,
+        status: 'error',
+        available: false,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return {
+    totalConnections: fluentConnections.length,
+    results
+  };
+});
+```
+
+### Validation Pattern: Required Connections
+
+```typescript
+import { fn } from '@versori/run';
+
+/**
+ * Validate required connections exist
+ *
+ * Recommended to run at connector startup
+ */
+export const validateRequiredConnections = fn('validate-required', ctx => {
+  const required = ['fluent_commerce', 'aws_s3', 'sftp_warehouse'];
+  const connections = ctx.activation.connections || [];
+  const connectionNames = new Set(connections.map(c => c.name));
+
+  const missing = required.filter(name => !connectionNames.has(name));
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required connections: ${missing.join(', ')}`);
+  }
+
+  ctx.log.info('All required connections configured', {
+    required: required.length,
+    configured: connections.length
+  });
+
+  return {
+    valid: true,
+    requiredConnections: required,
+    totalConnections: connections.length
+  };
+});
+```
+
+---
+
+## Activation Environment & Dynamic Variables (v0.4.x+)
+
+### activation.environment
+
+Access the current activation's environment information:
+
+```typescript
+import { fn } from '@versori/run';
+
+/**
+ * Check environment and apply environment-specific logic
+ */
+export const envAwareWorkflow = fn('env-aware', ctx => {
+  const env = ctx.activation.environment;
+
+  if (!env) {
+    ctx.log.warn('No environment information available');
+    return { environment: 'unknown' };
+  }
+
+  ctx.log.info('Environment details', {
+    id: env.id,
+    name: env.name,
+    type: env.type  // e.g., 'development', 'staging', 'production'
+  });
+
+  // Conditional logic based on environment
+  if (env.name === 'production') {
+    // Use production-specific settings
+    return {
+      environment: 'production',
+      batchSize: 1000,
+      retryAttempts: 5,
+      timeout: 60000
+    };
+  } else if (env.name === 'staging') {
+    return {
+      environment: 'staging',
+      batchSize: 100,
+      retryAttempts: 3,
+      timeout: 30000
+    };
+  } else {
+    return {
+      environment: 'development',
+      batchSize: 10,
+      retryAttempts: 1,
+      timeout: 10000
+    };
+  }
+});
+```
+
+### activation.dynamicVariables
+
+Access dynamic variables set at the activation level:
+
+```typescript
+import { fn } from '@versori/run';
+
+/**
+ * Access activation-level dynamic variables
+ */
+export const useDynamicVars = fn('use-dynamic-vars', ctx => {
+  // Get variables using getVariable
+  const apiKey = ctx.activation.getVariable<string>('API_KEY');
+  const retailerId = ctx.activation.getVariable<number>('RETAILER_ID');
+  const region = ctx.activation.getVariable<string>('AWS_REGION');
+
+  ctx.log.info('Dynamic variables', {
+    hasApiKey: !!apiKey,
+    retailerId,
+    region
+  });
+
+  // Use variables in your workflow
+  return {
+    retailerId,
+    region,
+    configured: !!apiKey && !!retailerId
+  };
+});
+```
+
+### Setting Variables Programmatically
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Cache frequently-used data in activation variables
+ */
+export const cacheRetailerConfig = http(
+  'cache-retailer-config',
+  { connection: 'fluent_commerce' },
+  async ctx => {
+    const client = await createClient(ctx);
+
+    // Query Fluent for retailer configuration
+    const result = await client.graphql({
+      query: `
+        query GetRetailer($id: Int!) {
+          retailer(id: $id) {
+            id
+            name
+            tradingName
+            supportEmail
+            primaryLocation {
+              ref
+            }
+          }
+        }
+      `,
+      variables: { id: 1 }
+    });
+
+    const retailer = result.data.retailer;
+
+    // Cache in activation variables for future workflows
+    await ctx.activation.setVariable('CACHED_RETAILER_ID', retailer.id);
+    await ctx.activation.setVariable('CACHED_RETAILER_NAME', retailer.name);
+    await ctx.activation.setVariable('CACHED_PRIMARY_LOCATION', retailer.primaryLocation.ref);
+    await ctx.activation.setVariable('LAST_CONFIG_REFRESH', Date.now());
+
+    ctx.log.info('Retailer config cached', {
+      retailerId: retailer.id,
+      retailerName: retailer.name
+    });
+
+    return {
+      cached: true,
+      retailer: {
+        id: retailer.id,
+        name: retailer.name
+      }
+    };
+  }
+);
+```
+
+### Complete ActivationImpl Reference
+
+```typescript
+interface ActivationImpl {
+  // Properties
+  get id(): string;                                     // Activation ID
+  get user(): EndUser;                                  // User info
+  get environment(): ProjectEnvironment | undefined;    // ✅ NEW in v0.4.x
+  get connections(): Array<Connection> | undefined;     // ✅ NEW in v0.4.x
+  get dynamicVariables(): DynamicVariables | undefined; // ✅ NEW in v0.4.x
+
+  // Methods
+  getVariable<T = unknown>(name: string): T | undefined;
+  setVariable(name: string, value: unknown): Promise<void>;
+}
+```
+
+---
+
+## Troubleshooting Connection Issues
+
+### Common Issues & Solutions
+
+| Issue                    | Symptoms                             | Solution                                                   |
+| ------------------------ | ------------------------------------ | ---------------------------------------------------------- |
+| **Connection not found** | `Error: Connection 'xyz' not found`  | Verify connection name matches UI exactly (case-sensitive) |
+| **Token expired**        | `401 Unauthorized`                   | Versori should auto-refresh; check token URL configuration |
+| **Invalid credentials**  | `403 Forbidden`                      | Verify Client ID/Secret in Fluent dashboard                |
+| **Missing retailerId**   | `retailerId is required for job creation` | Use `client.setRetailerId('1')` or pass in method call. See [retailerId Configuration Guide](../../../../00-START-HERE/retailerid-configuration.md) |
+| **CORS errors**          | `CORS policy blocked`                | Enable CORS in webhook configuration                       |
+| **Rate limiting**        | `429 Too Many Requests`              | Implement retry with backoff, check Fluent API limits      |
+
+### Debug Connection Configuration
+
+```typescript
+export const debugConnection = http(
+  'debug-connection',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const conn = ctx.activation?.connection;
+
+    // Log all connection details (except secrets)
+    ctx.log('debug', 'Connection configuration', {
+      hasConnection: !!conn,
+      url: conn?.url,
+      headerKeys: conn?.headers ? Object.keys(conn.headers) : [],
+      paramKeys: conn?.params ? Object.keys(conn.params) : [],
+      retailerId: conn?.params?.retailerId,
+    });
+
+    // Test basic connectivity
+    try {
+      const response = await ctx.fetch(conn?.url || 'https://api.fluentcommerce.com', {
+        method: 'HEAD',
+      });
+
+      return {
+        connectionStatus: 'reachable',
+        statusCode: response.status,
+        headers: Object.fromEntries(response.headers.entries()),
+      };
+    } catch (error) {
+      return {
+        connectionStatus: 'unreachable',
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+);
+```
+
+### Validate OAuth2 Token
+
+```typescript
+export const validateToken = http(
+  'validate-token',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const conn = ctx.activation?.connection;
+
+    // Extract token from headers (Versori auto-includes)
+    const authHeader = conn?.headers?.['Authorization'];
+
+    if (!authHeader) {
+      return { error: 'No authorization header found' };
+    }
+
+    // Parse token (Bearer <token>)
+    const token = authHeader.replace('Bearer ', '');
+
+    // Decode JWT (if applicable)
+    try {
+      const parts = token.split('.');
+      if (parts.length === 3) {
+        const payload = JSON.parse(atob(parts[1]));
+
+        return {
+          tokenValid: true,
+          expiresAt: payload.exp ? new Date(payload.exp * 1000).toISOString() : 'unknown',
+          issuedAt: payload.iat ? new Date(payload.iat * 1000).toISOString() : 'unknown',
+          scopes: payload.scope || [],
+        };
+      }
+    } catch (error) {
+      return {
+        tokenValid: false,
+        error: 'Invalid JWT format',
+      };
+    }
+
+    return { tokenValid: true, tokenLength: token.length };
+  }
+);
+```
+
+---
+
+## Advanced Connection Patterns
+
+### Pattern 1: Connection Fallback
+
+```typescript
+export const withFallback = http(
+  'connection-fallback',
+  {
+    connection: 'fluent_commerce_primary',
+  },
+  async ctx => {
+    try {
+      // Try primary connection
+      const client = await createClient(ctx);
+      return await client.graphql({ query: '...' });
+    } catch (primaryError) {
+      ctx.log('warn', 'Primary connection failed, trying fallback');
+
+      try {
+        // Fallback to secondary connection
+        const fallbackClient = await createClient({
+          connection: ctx.connections?.fluent_commerce_secondary,
+          log: ctx.log,
+        });
+
+        return await fallbackClient.graphql({ query: '...' });
+      } catch (fallbackError) {
+        throw new Error('All connections failed');
+      }
+    }
+  }
+);
+```
+
+### Pattern 2: Dynamic Connection Selection
+
+```typescript
+export const dynamicConnection = http('dynamic-connection', async ctx => {
+  // Select connection based on request parameter
+  const environment = ctx.query?.env || 'production';
+
+  const connectionName =
+    environment === 'staging' ? 'fluent_commerce_staging' : 'fluent_commerce_prod';
+
+  ctx.log('info', 'Selected connection', { connectionName, environment });
+
+  // Note: This pattern requires accessing ctx.connections
+  const client = await createClient({
+    connection: ctx.connections?.[connectionName],
+    log: ctx.log,
+  });
+
+  return await client.graphql({ query: '...' });
+});
+```
+
+---
+
+## Key Takeaways
+
+- 🎯 **OAuth2 connections** are managed by Versori - automatic token refresh
+- 🎯 **Connection name** in code must match UI exactly (case-sensitive)
+- 🎯 **Never hardcode** credentials - use connections or environment variables
+- 🎯 **Multi-connection scenarios** use primary connection + ctx.connections
+- 🎯 **Validate connections** before deployment with test workflows
+- 🎯 **Security best practices**: rotate credentials, use secrets, audit access
+- 🎯 **Troubleshooting**: check name match, token expiration, credential validity
+
+---
+
+## Practice Exercise
+
+Create a workflow that:
+
+1. Uses OAuth2 connection to Fluent Commerce
+2. Validates connection on startup
+3. Falls back to secondary connection on failure
+4. Logs all connection attempts for audit
+5. Returns connection health status
+
+**Hints**:
+
+- Use `http()` with primary connection
+- Implement try/catch for fallback
+- Use `ctx.log()` for audit trail
+- Test token validity before GraphQL calls
+
+**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
+
+---
+
+## Next Steps
+
+Now that you understand connection management, let's explore state management with KV storage.
+
+Continue to [Module 6: KV Storage →](./platforms-versori-06-kv-storage.md) to learn about distributed state, file tracking, and caching patterns.
+
+---
+
+## Related Documentation
+
+- [Module 3: Authentication](./platforms-versori-03-authentication.md) - OAuth2 basics
+- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Using connections in workflows
+- [Module 6: KV Storage](./platforms-versori-06-kv-storage.md) - State management
+- [Module 8: Best Practices](./platforms-versori-08-best-practices.md) - Security hardening
+
+---
+
+[← Previous: Module 4](./platforms-versori-04-workflows.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 6: KV Storage →](./platforms-versori-06-kv-storage.md)