@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/platforms/versori/platforms-versori-s3-sftp-configuration-guide.md

@@ -1,1425 +1,1425 @@
-# S3 & SFTP Configuration Guide for Versori
-
-**FC Connect SDK | Versori Platform Guide**
-
-> **Purpose**: Learn the two ways to configure S3 and SFTP connections in Versori workflows, understand when to use each approach, and implement secure, production-ready configurations.
-
-**Complexity**: Intermediate | **Time**: 15 minutes
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Two Configuration Approaches](#two-configuration-approaches)
-- [Decision Matrix](#decision-matrix)
-- [Approach 1: Versori Connections](#approach-1-versori-connections-recommended-for-production)
-- [Approach 2: Activation Variables](#approach-2-activation-variables-development-simple-use-cases)
-- [Side-by-Side Code Examples](#side-by-side-code-examples)
-- [Security Best Practices](#security-best-practices)
-- [Migration Guide](#migration-guide)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-When building Versori workflows that interact with **S3** or **SFTP** servers, you have **two ways** to provide credentials and configuration:
-
-| Approach | What It Is | Best For |
-|----------|-----------|----------|
-| **Versori Connections** | Centralized credential management in Versori UI | Production, multi-workflow setups, team collaboration |
-| **Activation Variables** | Per-workflow environment variables | Development, prototyping, single-use workflows |
-
-**Both approaches work with FC Connect SDK** - you choose based on your requirements.
-
----
-
-## Two Configuration Approaches
-
-### Quick Comparison
-
-```typescript
-// ❶ VERSORI CONNECTION (Centralized)
-const s3 = new S3DataSource({
-  type: 'S3_CSV',
-  connectionId: 's3-production',  // References centralized connection
-  name: 'Production S3',
-  s3Config: {
-    bucket: ctx.activation?.connection?.params?.bucket,
-    region: ctx.activation?.connection?.params?.region,
-    credentials: ctx.activation?.connection?.credentials
-  }
-}, logger);
-
-// ❷ ACTIVATION VARIABLES (Per-workflow)
-const s3 = new S3DataSource({
-  type: 'S3_CSV',
-  connectionId: 'inline-config',
-  name: 'S3 Data Source',
-  s3Config: {
-    bucket: ctx.activation?.getVariable('s3BucketName') as string,
-    region: ctx.activation?.getVariable('awsRegion') as string,
-    accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
-    secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string
-  }
-}, logger);
-```
-
-**Key Difference:**
-- **Connections** → Credentials stored once in Versori, referenced by name
-- **Variables** → Credentials stored per-workflow as activation variables
-
----
-
-## Decision Matrix
-
-Use this table to choose the right approach:
-
-| Factor | Versori Connections | Activation Variables |
-|--------|---------------------|---------------------|
-| **Setup Complexity** | ⚠️ Medium (UI setup required) | ✅ Simple (just add variables) |
-| **Credential Security** | ✅✅ Centralized, encrypted, audited | ⚠️ Duplicated across workflows |
-| **Reusability** | ✅✅ Share across multiple workflows | ❌ One workflow only |
-| **Credential Rotation** | ✅✅ Update once, affects all workflows | ❌ Update every workflow individually |
-| **Team Collaboration** | ✅✅ Central management, access control | ⚠️ Each dev needs credentials |
-| **Development Speed** | ⚠️ Slower (create connection first) | ✅ Faster (directly add variables) |
-| **Best For** | **Production environments** | **Development, prototyping, POC** |
-| **SDK Support** | ✅ Full support | ✅ Full support |
-
-### 🎯 Recommendations
-
-**Use Versori Connections when:**
-- ✅ Deploying to production
-- ✅ Multiple workflows use the same S3 bucket or SFTP server
-- ✅ Working in a team (shared credential management)
-- ✅ Security/compliance requires centralized credential storage
-- ✅ Credentials need to be rotated regularly
-
-**Use Activation Variables when:**
-- ✅ Prototyping or proof-of-concept
-- ✅ One-off data migration or testing
-- ✅ Each workflow needs different S3/SFTP credentials
-- ✅ Local development or sandbox environments
-- ✅ Quick iteration without UI configuration
-
----
-
-## Approach 1: Versori Connections (Recommended for Production)
-
-### Benefits
-
-✅ **Centralized Management** - One place to manage credentials
-✅ **Reusable** - Reference the same connection across multiple workflows
-✅ **Secure** - Encrypted storage with access control
-✅ **Auditable** - Track who uses which credentials
-✅ **Easy Rotation** - Update once, all workflows inherit changes
-
----
-
-## Credential Management: Connection vs Activation
-
-**IMPORTANT:** There are **two secure approaches** to fetch credentials - choose based on your security requirements.
-
-**⚠️ Versori/Deno Runtime Note:** When decoding Base64 credentials, always import Buffer:
-```typescript
-import { Buffer } from 'node:buffer';
-```
-This is required in Deno/Versori runtime (unlike Node.js where Buffer is global).
-
-### Approach 1A: Fetch from Versori Connection (Most Secure - Production)
-
-**Why Use This:**
-- ✅ **Most secure** - Credentials stored in Versori connection vault, not activation variables
-- ✅ **Centralized management** - Update connection in one place
-- ✅ **Access control** - Versori manages who can access credentials
-- ✅ **Audit trail** - Connection usage is logged by platform
-- ✅ **Production-ready** - Best practice for deployed workflows
-
-**How It Works:**
-1. **Create Basic Auth connection in Versori:**
-   - Connection Name: `versori_ftp_server`
-   - Type: Basic Auth
-   - Username: your-sftp-username
-   - Password: your-sftp-password
-
-2. **Versori encodes credentials:**
-   - Format: `username:password`
-   - Encoding: Base64
-   - Stored as `accessToken`
-
-3. **Your code decodes:**
-   - `ctx.connections.connection_name.accessToken` → get base64 token from connection object
-   - Decode base64 → get `username:password` string
-   - Split by `:` → extract username and password
-
-**Example: SFTP with Connection Credentials**
-
-```typescript
-import { Buffer } from 'node:buffer';
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpIngestion = schedule('sftp-sync', '0 2 * * *').then(
-  http('process-sftp-files', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { log, activation } = ctx;
-
-    // ✅ APPROACH 1A: Fetch credentials from Versori connection (SECURE - Production)
-    // IMPORTANT: Access connections directly via ctx.connections (Versori platform pattern)
-    const { connections } = ctx;
-    const conn = connections.versori_ftp_server;
-    const rawAccessToken = conn.accessToken;
-
-    // Decode base64-encoded "username:password"
-    const rawBasicAuth = Buffer.from(rawAccessToken, 'base64').toString('utf-8');
-    const [username, password] = rawBasicAuth.split(':');
-
-    // Initialize SftpDataSource with connection credentials
-    const sftp = new SftpDataSource({
-      type: 'SFTP_CSV',
-      connectionId: 'versori_ftp_server',
-      name: 'FTP Server',
-      settings: {
-        host: activation.getVariable('sftpHost'),
-        port: parseInt(activation.getVariable('sftpPort') || '22'),
-        username,        // ← From connection (secure)
-        password,        // ← From connection (secure)
-        remotePath: '/incoming',
-        filePattern: '*.csv'
-      }
-    }, log);
-
-    try {
-      // Use SFTP normally
-      const files = await sftp.listFiles({ directory: '/incoming' });
-      log.info(`Found ${files.length} files`);
-
-      for (const file of files) {
-        const content = await sftp.downloadFile(file.path, { encoding: 'utf8' });
-        log.info('File downloaded', { file: file.name, size: content.length });
-        // Process file...
-      }
-
-      return { success: true, filesProcessed: files.length };
-    } finally {
-      await sftp.disconnect();
-    }
-  })
-);
-```
-
-### Approach 1B: Activation Variables (Development/Testing)
-
-**When Use This:**
-- Development/testing environments
-- Quick prototyping
-- When connection setup is not yet complete
-
-**Example: SFTP with Activation Variables**
-
-```typescript
-import { Buffer } from 'node:buffer';
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpIngestion = schedule('sftp-sync', '0 2 * * *').then(
-  http('process-sftp-files', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { log, activation } = ctx;
-
-    // ✅ APPROACH 1B: Activation variables (Development/Testing)
-    const sftp = new SftpDataSource({
-      type: 'SFTP_CSV',
-      connectionId: 'sftp-server',
-      name: 'FTP Server',
-      settings: {
-        host: activation.getVariable('sftpHost'),
-        port: parseInt(activation.getVariable('sftpPort') || '22'),
-        username: activation.getVariable('sftpUsername'),  // ← From activation
-        password: activation.getVariable('sftpPassword'),  // ← From activation
-        remotePath: '/incoming',
-        filePattern: '*.csv'
-      }
-    }, log);
-
-    try {
-      const files = await sftp.listFiles({ directory: '/incoming' });
-      log.info(`Found ${files.length} files`);
-      return { success: true, filesProcessed: files.length };
-    } finally {
-      await sftp.disconnect();
-    }
-  })
-);
-```
-
-### Comparison: Connection vs Activation
-
-| Factor | Connection (1A) | Activation (1B) |
-|--------|----------------|-----------------|
-| **Security** | ✅✅ Vault storage | ⚠️ Variable storage |
-| **Setup Complexity** | ⚠️ Requires connection creation | ✅ Quick variable setup |
-| **Credential Rotation** | ✅✅ Update once | ❌ Update each workflow |
-| **Team Collaboration** | ✅✅ Central management | ⚠️ Each dev needs creds |
-| **Audit Trail** | ✅✅ Platform-logged | ⚠️ Variable access only |
-| **Best For** | **Production** | **Development/Testing** |
-
-### Complete Working Example: Hybrid Approach
-
-**Support both methods with fallback for maximum flexibility:**
-
-```typescript
-import { Buffer } from 'node:buffer';
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpIngestion = schedule('sftp-sync', '0 2 * * *').then(
-  http('process-sftp-files', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { log, activation } = ctx;
-
-    // Try connection-based credentials first (production), fallback to activation (development)
-    let username: string;
-    let password: string;
-
-    try {
-      // ✅ PRIMARY: Try connection credentials (most secure)
-      const { connections } = ctx;
-      const conn = connections.versori_ftp_server;
-      const rawAccessToken = conn.accessToken;
-      const rawBasicAuth = Buffer.from(rawAccessToken, 'base64').toString('utf-8');
-      [username, password] = rawBasicAuth.split(':');
-
-      log.info('Using connection credentials for SFTP');
-    } catch (error) {
-      // ⚠️ FALLBACK: Use activation variables (development/testing)
-      username = activation.getVariable('sftpUsername');
-      password = activation.getVariable('sftpPassword');
-
-      log.warn('Connection credentials unavailable, using activation variables');
-    }
-
-    // Validate credentials are available
-    if (!username || !password) {
-      throw new Error('SFTP credentials not found in connection or activation variables');
-    }
-
-    // Initialize SftpDataSource
-    const sftp = new SftpDataSource({
-      type: 'SFTP_CSV',
-      connectionId: 'versori_ftp_server',
-      name: 'FTP Server',
-      settings: {
-        host: activation.getVariable('sftpHost'),
-        port: parseInt(activation.getVariable('sftpPort') || '22'),
-        username,
-        password,
-        remotePath: '/incoming',
-        filePattern: '*.csv'
-      }
-    }, log);
-
-    try {
-      const files = await sftp.listFiles({ directory: '/incoming' });
-      log.info(`Found ${files.length} files`);
-      return { success: true, filesProcessed: files.length };
-    } finally {
-      await sftp.disconnect();
-    }
-  })
-);
-```
-
----
-
-### Setup: AWS S3 Connection
-
-#### Step 1: Create Connection in Versori UI
-
-1. **Navigate to Versori Dashboard** → **Connections** tab
-2. Click **"Add Connection"**
-3. **Configure Connection:**
-
-```
-Name: s3-production
-Description: Production S3 bucket for inventory data
-Type: AWS S3 (or API Key if S3 not available)
-```
-
-4. **Authentication Details:**
-
-```
-AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
-AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-Region: us-east-1
-```
-
-5. **Additional Parameters (Optional):**
-
-```json
-{
-  "bucket": "my-production-inventory",
-  "prefix": "inventory/incoming/"
-}
-```
-
-6. **Test Connection** → Verify access
-7. **Save Connection**
-
-#### Step 2: Use Connection in Workflow Code
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const inventorySync = schedule('daily-sync', '0 2 * * *').then(
-  http('process-s3-files', {
-    connection: 'fluent_commerce',  // Fluent connection
-    additionalConnections: {
-      s3: 's3-production'            // ← Reference S3 connection by name
-    }
-  }, async (ctx) => {
-    const log = ctx.log;
-
-    // Access S3 connection
-    const s3Connection = ctx.activation?.connections?.s3;
-
-    // Initialize S3DataSource with connection credentials
-    const s3DataSource = new S3DataSource({
-      type: 'S3_CSV',
-      connectionId: s3Connection?.id || 's3-production',
-      name: 'Production S3',
-      s3Config: {
-        bucket: s3Connection?.params?.bucket || ctx.activation?.getVariable('s3BucketName') as string,
-        region: s3Connection?.params?.region || 'us-east-1',
-        accessKeyId: s3Connection?.credentials?.accessKeyId,
-        secretAccessKey: s3Connection?.credentials?.secretAccessKey
-      }
-    }, log);
-
-    // Use S3DataSource normally
-    const files = await s3DataSource.listFiles({ prefix: 'inventory/' });
-    log.info(`Found ${files.length} files`);
-
-    return { success: true, filesFound: files.length };
-  })
-);
-```
-
-**Key Points:**
-- ✅ `additionalConnections` parameter references the connection name
-- ✅ Access via `ctx.activation?.connections?.s3`
-- ✅ Fallback to activation variables for flexibility
-- ✅ No credentials in code
-
-#### Step 3: Test & Deploy
-
-```bash
-# Deploy workflow
-versori deploy
-
-# Verify connection
-versori logs --workflow daily-sync
-```
-
----
-
-### Setup: SFTP Connection
-
-#### Step 1: Create Connection in Versori UI
-
-1. **Navigate to** → **Connections** → **"Add Connection"**
-2. **Configure:**
-
-```
-Name: sftp-partner-server
-Description: Partner SFTP server for exports
-Type: SFTP (or Custom if not available)
-```
-
-3. **SFTP Details:**
-
-```
-Host: sftp.partner.com
-Port: 22
-Username: inventory_export
-Authentication: Password (or SSH Key)
-Password: ******** (or upload private key)
-```
-
-4. **Additional Parameters:**
-
-```json
-{
-  "remotePath": "/incoming/inventory/",
-  "timeout": 30000,
-  "keepalive": 10000
-}
-```
-
-5. **Test Connection** → **Save**
-
-#### Step 2: Use Connection in Workflow
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpExport = schedule('daily-export', '0 3 * * *').then(
-  http('export-to-sftp', {
-    connection: 'fluent_commerce',
-    additionalConnections: {
-      sftp: 'sftp-partner-server'  // ← Reference SFTP connection
-    }
-  }, async (ctx) => {
-    const log = ctx.log;
-
-    // Access SFTP connection
-    const sftpConnection = ctx.activation?.connections?.sftp;
-
-    // Initialize SftpDataSource with connection credentials
-    const sftpDataSource = new SftpDataSource({
-      type: 'SFTP_CSV',
-      connectionId: sftpConnection?.id || 'sftp-partner',
-      name: 'Partner SFTP',
-      sftpConfig: {
-        host: sftpConnection?.params?.host || ctx.activation?.getVariable('sftpHost') as string,
-        port: parseInt(sftpConnection?.params?.port || '22'),
-        username: sftpConnection?.credentials?.username,
-        password: sftpConnection?.credentials?.password,
-        privateKey: sftpConnection?.credentials?.privateKey,
-        timeout: parseInt(sftpConnection?.params?.timeout || '30000'),
-        keepaliveInterval: parseInt(sftpConnection?.params?.keepalive || '10000')
-      }
-    }, log);
-
-    try {
-      // Upload file to SFTP
-      const csvData = 'sku,qty\nSKU-001,100\n';
-      await sftpDataSource.uploadFile(
-        '/incoming/inventory/inventory-export.csv',
-        Buffer.from(csvData, 'utf-8'),
-        { encoding: 'utf-8' }
-      );
-
-      log.info('File uploaded successfully');
-      return { success: true };
-    } finally {
-      // Always disconnect SFTP
-      await sftpDataSource.disconnect();
-    }
-  })
-);
-```
-
-**Key Points:**
-- ✅ `additionalConnections.sftp` references connection
-- ✅ Support for password OR SSH key authentication
-- ✅ Always call `disconnect()` in finally block
-- ✅ Timeout and keep-alive from connection config
-
----
-
-## Approach 2: Activation Variables (Development & Simple Use Cases)
-
-### Benefits
-
-✅ **Quick Setup** - No UI configuration needed
-✅ **Per-Workflow Control** - Each workflow has independent config
-✅ **Development-Friendly** - Easy to test with different credentials
-✅ **Explicit** - All configuration visible in code
-
-### Setup: AWS S3 with Activation Variables
-
-#### Step 1: Define Activation Variables
-
-In Versori UI → **Workflow Settings** → **Activation Variables**:
-
-```json
-{
-  "s3BucketName": "my-inventory-bucket",
-  "awsRegion": "us-east-1",
-  "awsAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
-  "awsSecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
-  "s3Prefix": "inventory/incoming/"
-}
-```
-
-**Security Note:** These are encrypted by Versori platform.
-
-#### Step 2: Use Variables in Code
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const inventorySync = schedule('daily-sync', '0 2 * * *').then(
-  http('process-s3-files', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const log = ctx.log;
-
-    // Load configuration from activation variables
-    const config = {
-      s3Bucket: ctx.activation?.getVariable('s3BucketName') as string,
-      s3Region: ctx.activation?.getVariable('awsRegion') as string || 'us-east-1',
-      s3AccessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
-      s3SecretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string,
-      s3Prefix: ctx.activation?.getVariable('s3Prefix') as string || 'inventory/'
-    };
-
-    // Validate required variables
-    const missingVars: string[] = [];
-    if (!config.s3Bucket) missingVars.push('s3BucketName');
-    if (!config.s3AccessKeyId) missingVars.push('awsAccessKeyId');
-    if (!config.s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
-
-    if (missingVars.length > 0) {
-      const errorMsg = `Missing required activation variables: ${missingVars.join(', ')}`;
-      log.error(errorMsg);
-      return { success: false, error: errorMsg };
-    }
-
-    // Initialize S3DataSource with activation variables
-    const s3DataSource = new S3DataSource({
-      type: 'S3_CSV',
-      connectionId: 'inline-s3-config',
-      name: 'S3 Data Source',
-      s3Config: {
-        bucket: config.s3Bucket,
-        region: config.s3Region,
-        accessKeyId: config.s3AccessKeyId,
-        secretAccessKey: config.s3SecretAccessKey
-      }
-    }, log);
-
-    // Use S3DataSource
-    const files = await s3DataSource.listFiles({ prefix: config.s3Prefix });
-    log.info(`Found ${files.length} files`);
-
-    return { success: true, filesFound: files.length };
-  })
-);
-```
-
-**Key Points:**
-- ✅ All config loaded via `ctx.activation?.getVariable()`
-- ✅ Validation ensures required variables are present
-- ✅ Fallback values for optional variables
-- ✅ Clear error messages for missing config
-
----
-
-### Setup: SFTP with Activation Variables
-
-#### Step 1: Define Activation Variables
-
-```json
-{
-  "sftpHost": "sftp.partner.com",
-  "sftpPort": "22",
-  "sftpUsername": "inventory_export",
-  "sftpPassword": "********",
-  "sftpRemotePath": "/incoming/inventory/",
-  "sftpTimeout": "30000"
-}
-```
-
-**SSH Key Authentication (Alternative):**
-
-```json
-{
-  "sftpHost": "sftp.partner.com",
-  "sftpPort": "22",
-  "sftpUsername": "inventory_export",
-  "sftpPrivateKey": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
-  "sftpPassphrase": "keypassphrase",
-  "sftpRemotePath": "/incoming/inventory/"
-}
-```
-
-#### Step 2: Use Variables in Code
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpExport = schedule('daily-export', '0 3 * * *').then(
-  http('export-to-sftp', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const log = ctx.log;
-
-    // Load SFTP configuration from activation variables
-    const config = {
-      sftpHost: ctx.activation?.getVariable('sftpHost') as string,
-      sftpPort: parseInt(ctx.activation?.getVariable('sftpPort') as string || '22'),
-      sftpUsername: ctx.activation?.getVariable('sftpUsername') as string,
-      sftpPassword: ctx.activation?.getVariable('sftpPassword') as string,
-      sftpPrivateKey: ctx.activation?.getVariable('sftpPrivateKey') as string,
-      sftpPassphrase: ctx.activation?.getVariable('sftpPassphrase') as string,
-      sftpRemotePath: ctx.activation?.getVariable('sftpRemotePath') as string || '/',
-      sftpTimeout: parseInt(ctx.activation?.getVariable('sftpTimeout') as string || '30000')
-    };
-
-    // Validate required variables
-    const missingVars: string[] = [];
-    if (!config.sftpHost) missingVars.push('sftpHost');
-    if (!config.sftpUsername) missingVars.push('sftpUsername');
-    if (!config.sftpPassword && !config.sftpPrivateKey) {
-      missingVars.push('sftpPassword OR sftpPrivateKey');
-    }
-
-    if (missingVars.length > 0) {
-      const errorMsg = `Missing required activation variables: ${missingVars.join(', ')}`;
-      log.error(errorMsg);
-      return { success: false, error: errorMsg };
-    }
-
-    // Initialize SftpDataSource
-    const sftpDataSource = new SftpDataSource({
-      type: 'SFTP_CSV',
-      connectionId: 'inline-sftp-config',
-      name: 'SFTP Data Source',
-      sftpConfig: {
-        host: config.sftpHost,
-        port: config.sftpPort,
-        username: config.sftpUsername,
-        password: config.sftpPassword,
-        privateKey: config.sftpPrivateKey,
-        passphrase: config.sftpPassphrase,
-        timeout: config.sftpTimeout,
-        keepaliveInterval: 10000,
-        retryDelay: 2000,
-        maxRetries: 3
-      }
-    }, log);
-
-    try {
-      // Upload file
-      const csvData = 'sku,qty\nSKU-001,100\n';
-      const remotePath = `${config.sftpRemotePath}/inventory-export-${Date.now()}.csv`;
-
-      await sftpDataSource.uploadFile(
-        remotePath,
-        Buffer.from(csvData, 'utf-8'),
-        { encoding: 'utf-8' }
-      );
-
-      log.info(`File uploaded to ${remotePath}`);
-      return { success: true, remotePath };
-    } catch (error: any) {
-      log.error('SFTP upload failed', { error: error.message });
-      return { success: false, error: error.message };
-    } finally {
-      // Always disconnect
-      await sftpDataSource.disconnect();
-    }
-  })
-);
-```
-
-**Key Points:**
-- ✅ Support for password OR SSH key authentication
-- ✅ Validation for mutually exclusive auth methods
-- ✅ Always disconnect in finally block
-- ✅ Comprehensive error handling
-
----
-
-## Side-by-Side Code Examples
-
-### S3DataSource: Both Approaches
-
-```typescript
-// ═══════════════════════════════════════════════════════════════
-// APPROACH 1: VERSORI CONNECTION
-// ═══════════════════════════════════════════════════════════════
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-// In workflow with additionalConnections: { s3: 's3-production' }
-const s3Connection = ctx.activation?.connections?.s3;
-
-const s3DataSource = new S3DataSource({
-  type: 'S3_CSV',
-  connectionId: s3Connection?.id,
-  name: 'Production S3',
-  s3Config: {
-    bucket: s3Connection?.params?.bucket,           // From connection
-    region: s3Connection?.params?.region,           // From connection
-    accessKeyId: s3Connection?.credentials?.accessKeyId,       // From connection
-    secretAccessKey: s3Connection?.credentials?.secretAccessKey // From connection
-  }
-}, logger);
-
-// ═══════════════════════════════════════════════════════════════
-// APPROACH 2: ACTIVATION VARIABLES
-// ═══════════════════════════════════════════════════════════════
-const s3DataSource = new S3DataSource({
-  type: 'S3_CSV',
-  connectionId: 'inline-config',
-  name: 'S3 Data Source',
-  s3Config: {
-    bucket: ctx.activation?.getVariable('s3BucketName') as string,       // From variable
-    region: ctx.activation?.getVariable('awsRegion') as string,          // From variable
-    accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,     // From variable
-    secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string // From variable
-  }
-}, logger);
-
-// ═══════════════════════════════════════════════════════════════
-// USAGE: SAME FOR BOTH APPROACHES
-// ═══════════════════════════════════════════════════════════════
-const files = await s3DataSource.listFiles({ prefix: 'inventory/' });
-const fileContent = await s3DataSource.downloadFile(files[0].path, { encoding: 'utf8' });
-await s3DataSource.uploadFile('output/result.csv', Buffer.from(csvData), {});
-```
-
----
-
-### SftpDataSource: Both Approaches
-
-```typescript
-// ═══════════════════════════════════════════════════════════════
-// APPROACH 1: VERSORI CONNECTION
-// ═══════════════════════════════════════════════════════════════
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-// In workflow with additionalConnections: { sftp: 'sftp-partner' }
-const sftpConnection = ctx.activation?.connections?.sftp;
-
-const sftpDataSource = new SftpDataSource({
-  type: 'SFTP_CSV',
-  connectionId: sftpConnection?.id,
-  name: 'Partner SFTP',
-  sftpConfig: {
-    host: sftpConnection?.params?.host,                // From connection
-    port: parseInt(sftpConnection?.params?.port || '22'),
-    username: sftpConnection?.credentials?.username,   // From connection
-    password: sftpConnection?.credentials?.password,   // From connection
-    privateKey: sftpConnection?.credentials?.privateKey, // From connection
-    timeout: parseInt(sftpConnection?.params?.timeout || '30000'),
-    keepaliveInterval: 10000
-  }
-}, logger);
-
-// ═══════════════════════════════════════════════════════════════
-// APPROACH 2: ACTIVATION VARIABLES
-// ═══════════════════════════════════════════════════════════════
-const sftpDataSource = new SftpDataSource({
-  type: 'SFTP_CSV',
-  connectionId: 'inline-config',
-  name: 'SFTP Data Source',
-  sftpConfig: {
-    host: ctx.activation?.getVariable('sftpHost') as string,       // From variable
-    port: parseInt(ctx.activation?.getVariable('sftpPort') as string || '22'),
-    username: ctx.activation?.getVariable('sftpUsername') as string,   // From variable
-    password: ctx.activation?.getVariable('sftpPassword') as string,   // From variable
-    privateKey: ctx.activation?.getVariable('sftpPrivateKey') as string, // From variable
-    timeout: parseInt(ctx.activation?.getVariable('sftpTimeout') as string || '30000'),
-    keepaliveInterval: 10000,
-    retryDelay: 2000,
-    maxRetries: 3
-  }
-}, logger);
-
-// ═══════════════════════════════════════════════════════════════
-// USAGE: SAME FOR BOTH APPROACHES
-// ═══════════════════════════════════════════════════════════════
-try {
-  const files = await sftpDataSource.listFiles({ directory: '/incoming' });
-  const fileContent = await sftpDataSource.downloadFile(files[0].path, { encoding: 'utf8' });
-  await sftpDataSource.uploadFile('/outgoing/result.csv', Buffer.from(csvData), {});
-} finally {
-  await sftpDataSource.disconnect();  // ⚠️ ALWAYS disconnect SFTP!
-}
-```
-
----
-
-## Security Best Practices
-
-### 1. Never Hardcode Credentials
-
-```typescript
-// ❌ NEVER DO THIS
-const s3DataSource = new S3DataSource({
-  s3Config: {
-    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',      // ❌ Hardcoded!
-    secretAccessKey: 'wJalrXUtnFEMI/K...'     // ❌ Hardcoded!
-  }
-});
-
-// ✅ ALWAYS DO THIS (Connection)
-const s3DataSource = new S3DataSource({
-  s3Config: {
-    accessKeyId: ctx.activation?.connections?.s3?.credentials?.accessKeyId,
-    secretAccessKey: ctx.activation?.connections?.s3?.credentials?.secretAccessKey
-  }
-});
-
-// ✅ OR THIS (Variables)
-const s3DataSource = new S3DataSource({
-  s3Config: {
-    accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
-    secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string
-  }
-});
-```
-
-### 2. Use IAM Roles for S3 (When Possible)
-
-If running on AWS infrastructure (EC2, Lambda), use IAM roles instead of access keys:
-
-```typescript
-// Best: IAM Role (no credentials needed)
-const s3DataSource = new S3DataSource({
-  type: 'S3_CSV',
-  s3Config: {
-    bucket: 'my-bucket',
-    region: 'us-east-1'
-    // No accessKeyId/secretAccessKey - uses IAM role
-  }
-}, logger);
-```
-
-### 3. Use SSH Keys for SFTP (Not Passwords)
-
-```typescript
-// ⚠️ Password authentication (less secure)
-sftpConfig: {
-  username: 'user',
-  password: 'password123'  // Can be brute-forced
-}
-
-// ✅ SSH Key authentication (more secure)
-sftpConfig: {
-  username: 'user',
-  privateKey: ctx.activation?.getVariable('sftpPrivateKey') as string,
-  passphrase: ctx.activation?.getVariable('sftpPassphrase') as string
-}
-```
-
-### 4. Principle of Least Privilege
-
-**S3 IAM Policy (Minimal Permissions):**
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "s3:GetObject",
-        "s3:PutObject",
-        "s3:ListBucket"
-      ],
-      "Resource": [
-        "arn:aws:s3:::my-inventory-bucket",
-        "arn:aws:s3:::my-inventory-bucket/*"
-      ]
-    }
-  ]
-}
-```
-
-**SFTP User Permissions:**
-- Read-only for ingestion workflows
-- Write-only for extraction workflows
-- Restrict to specific directories via chroot
-
-### 5. Credential Rotation
-
-**With Versori Connections (Easy):**
-1. Update connection in Versori UI
-2. All workflows automatically use new credentials
-3. Zero code changes needed
-
-**With Activation Variables (Manual):**
-1. Update each workflow's activation variables individually
-2. Redeploy each affected workflow
-3. Risk of missed workflows
-
-### 6. Audit Logging
-
-Enable logging for credential usage:
-
-```typescript
-// Log connection info (NOT credentials)
-log.info('Using S3 connection', {
-  connectionId: s3Connection?.id,
-  bucket: s3Connection?.params?.bucket,
-  region: s3Connection?.params?.region,
-  // ❌ NEVER log: accessKeyId, secretAccessKey
-});
-```
-
-### 7. Environment Separation
-
-Use different connections/variables per environment:
-
-```
-Development:
-  - Connection: s3-dev
-  - Variables: s3BucketName=dev-inventory
-
-Staging:
-  - Connection: s3-staging
-  - Variables: s3BucketName=staging-inventory
-
-Production:
-  - Connection: s3-production
-  - Variables: s3BucketName=prod-inventory
-```
-
----
-
-## Migration Guide
-
-### From Activation Variables → Versori Connections
-
-**Step 1: Create Connection**
-
-Extract current activation variables and create Versori connection:
-
-**Current Activation Variables:**
-```json
-{
-  "s3BucketName": "my-inventory-bucket",
-  "awsRegion": "us-east-1",
-  "awsAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
-  "awsSecretAccessKey": "wJalrXUtnFEMI..."
-}
-```
-
-**New Versori Connection:**
-- Name: `s3-production`
-- Type: AWS S3
-- Access Key ID: `AKIAIOSFODNN7EXAMPLE`
-- Secret Access Key: `wJalrXUtnFEMI...`
-- Region: `us-east-1`
-- Parameters: `{ "bucket": "my-inventory-bucket" }`
-
-**Step 2: Update Workflow Code**
-
-**Before (Activation Variables):**
-```typescript
-export const sync = schedule('daily', '0 2 * * *').then(
-  http('process', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const s3 = new S3DataSource({
-      type: 'S3_CSV',
-      s3Config: {
-        bucket: ctx.activation?.getVariable('s3BucketName') as string,
-        region: ctx.activation?.getVariable('awsRegion') as string,
-        accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
-        secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string
-      }
-    }, ctx.log);
-    // ... rest of code
-  })
-);
-```
-
-**After (Versori Connection):**
-```typescript
-export const sync = schedule('daily', '0 2 * * *').then(
-  http('process', {
-    connection: 'fluent_commerce',
-    additionalConnections: {
-      s3: 's3-production'  // ← Add this
-    }
-  }, async (ctx) => {
-    const s3Conn = ctx.activation?.connections?.s3;
-    const s3 = new S3DataSource({
-      type: 'S3_CSV',
-      s3Config: {
-        bucket: s3Conn?.params?.bucket,
-        region: s3Conn?.params?.region,
-        accessKeyId: s3Conn?.credentials?.accessKeyId,
-        secretAccessKey: s3Conn?.credentials?.secretAccessKey
-      }
-    }, ctx.log);
-    // ... rest of code (unchanged)
-  })
-);
-```
-
-**Step 3: Test & Deploy**
-
-```bash
-# Test locally
-versori dev
-
-# Deploy to production
-versori deploy
-
-# Verify logs
-versori logs --workflow daily
-```
-
-**Step 4: Remove Old Activation Variables**
-
-After verifying the connection works, remove the old activation variables from workflow settings.
-
----
-
-## Troubleshooting
-
-### Issue 1: "Connection not found"
-
-**Error:**
-```
-Error: Connection 's3-production' not found
-```
-
-**Causes:**
-- Typo in connection name
-- Connection not created in Versori UI
-- Connection not added to `additionalConnections`
-
-**Solution:**
-```typescript
-// 1. Verify connection exists in Versori UI
-// 2. Check name matches exactly (case-sensitive)
-additionalConnections: {
-  s3: 's3-production'  // ← Must match UI name exactly
-}
-
-// 3. Add fallback
-const s3Conn = ctx.activation?.connections?.s3;
-if (!s3Conn) {
-  log.error('S3 connection not found');
-  return { success: false, error: 'S3 connection required' };
-}
-```
-
----
-
-### Issue 2: "Missing activation variable"
-
-**Error:**
-```
-Missing required activation variables: awsAccessKeyId
-```
-
-**Causes:**
-- Variable not defined in workflow settings
-- Typo in variable name
-- Variable name case mismatch
-
-**Solution:**
-```typescript
-// 1. Verify activation variable exists in Versori UI
-// 2. Check exact name (case-sensitive)
-const accessKeyId = ctx.activation?.getVariable('awsAccessKeyId') as string;
-//                                                ^^^^^^^^^^^^^^^
-//                                                Must match UI exactly
-
-// 3. Add validation with helpful error
-if (!accessKeyId) {
-  log.error('Missing activation variable: awsAccessKeyId');
-  log.info('Available variables:', Object.keys(ctx.activation?.variables || {}));
-  throw new Error('Configuration error: awsAccessKeyId required');
-}
-```
-
----
-
-### Issue 3: S3 Access Denied
-
-**Error:**
-```
-AccessDenied: User: arn:aws:iam::123456789012:user/app-user is not authorized to perform: s3:ListBucket
-```
-
-**Causes:**
-- Insufficient IAM permissions
-- Wrong bucket name
-- Incorrect region
-
-**Solution:**
-```typescript
-// 1. Verify IAM permissions include required actions:
-// - s3:ListBucket (for listFiles)
-// - s3:GetObject (for downloadFile)
-// - s3:PutObject (for uploadFile)
-
-// 2. Test connection with minimal operation
-try {
-  const files = await s3DataSource.listFiles({ prefix: '', maxKeys: 1 });
-  log.info('S3 connection successful');
-} catch (error: any) {
-  log.error('S3 access denied', {
-    bucket: config.s3Bucket,
-    region: config.s3Region,
-    error: error.message
-  });
-  throw error;
-}
-```
-
----
-
-### Issue 4: SFTP Connection Timeout
-
-**Error:**
-```
-Error: Timeout while connecting to SFTP server
-```
-
-**Causes:**
-- Firewall blocking port 22
-- Incorrect host/port
-- Server not responding
-
-**Solution:**
-```typescript
-// 1. Increase timeout
-sftpConfig: {
-  timeout: 60000,  // 60 seconds (default: 30s)
-  keepaliveInterval: 10000
-}
-
-// 2. Test connection manually
-ssh username@sftp.partner.com -p 22
-
-// 3. Check firewall rules
-// Ensure Versori platform can reach SFTP server
-
-// 4. Add retry logic
-async function connectSftpWithRetry(config, maxRetries = 3) {
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      const sftp = new SftpDataSource(config, log);
-      await sftp.listFiles({ directory: '/' });
-      return sftp;
-    } catch (error: any) {
-      if (i === maxRetries - 1) throw error;
-      const delay = 2000 * Math.pow(2, i);
-      log.warn(`SFTP connection failed, retrying in ${delay}ms...`);
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-}
-```
-
----
-
-### Issue 5: SFTP Permission Denied
-
-**Error:**
-```
-Error: Permission denied: /incoming/inventory.csv
-```
-
-**Causes:**
-- User lacks write permissions to directory
-- Directory doesn't exist
-- Wrong remote path
-
-**Solution:**
-```typescript
-// 1. Create directory if needed (requires permissions)
-try {
-  await sftpDataSource.createDirectory(remotePath);
-} catch (error: any) {
-  log.warn('Could not create directory', { remotePath, error: error.message });
-}
-
-// 2. Test with read operation first
-const files = await sftpDataSource.listFiles({ directory: '/' });
-log.info('SFTP readable directories:', files);
-
-// 3. Verify path from SFTP root
-// Remote path should be absolute: /incoming/inventory.csv
-// NOT relative: incoming/inventory.csv
-```
-
----
-
-### Issue 6: Connection vs Variable Confusion
-
-**Problem:** Code expects connection but variables are provided (or vice versa)
-
-**Solution:** Support both with fallback:
-
-```typescript
-// Hybrid approach: Try connection first, fallback to variables
-const s3Bucket =
-  ctx.activation?.connections?.s3?.params?.bucket ||   // Try connection
-  ctx.activation?.getVariable('s3BucketName') as string;  // Fallback to variable
-
-const s3AccessKey =
-  ctx.activation?.connections?.s3?.credentials?.accessKeyId ||
-  ctx.activation?.getVariable('awsAccessKeyId') as string;
-
-// Validate
-if (!s3Bucket || !s3AccessKey) {
-  throw new Error('S3 configuration required via connection or activation variables');
-}
-```
-
----
-
-### Issue 7: Incorrect Credential Access Pattern
-
-**Error:**
-```
-TypeError: credentials is not a function
-ReferenceError: credentials is not defined
-```
-
-**Problem:** Documentation showed importing and calling `credentials` from `@versori/run`, but this export doesn't exist.
-
-**Incorrect Pattern (OLD - DO NOT USE):**
-```typescript
-// ❌ WRONG - This doesn't exist!
-const cred = await ctx.credentials().get('connection_name');
-```
-
-**Correct Patterns:**
-
-**Option A: Using http task with connection (Recommended):**
-```typescript
-// ✅ CORRECT - Use connectionVariables from ctx
-import { Buffer } from 'node:buffer';
-import { http } from '@versori/run';
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-http("task", { connection: "sftp_server" }, async (ctx) => {
-  const { connectionVariables } = ctx;
-
-  const sftpConfig = {
-    host: connectionVariables.host,
-    port: connectionVariables.port || 22,
-    username: connectionVariables.username,
-    password: Buffer.from(connectionVariables.password, 'base64').toString('utf-8')
-  };
-
-  const sftp = new SftpDataSource({ type: 'SFTP_CSV', settings: sftpConfig }, ctx.log);
-});
-```
-
-**Option B: Using ctx.connections directly:**
-```typescript
-// ✅ CORRECT - Use ctx.connections directly
-import { Buffer } from 'node:buffer';
-import { fn } from '@versori/run';
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-fn("task", async (ctx) => {
-  const { connections } = ctx;
-  const conn = connections.sftp_server;
-
-  const sftpConfig = {
-    host: ctx.activation.getVariable('sftpHost'),
-    port: 22,
-    username: conn.username || Buffer.from(conn.accessToken, 'base64').toString('utf-8').split(':')[0],
-    password: conn.password || Buffer.from(conn.accessToken, 'base64').toString('utf-8').split(':')[1]
-  };
-
-  const sftp = new SftpDataSource({ type: 'SFTP_CSV', settings: sftpConfig }, ctx.log);
-});
-```
-
-**Key Points:**
-- ✅ No `credentials` export exists from `@versori/run`
-- ✅ Use `connectionVariables` (http tasks) or `ctx.connections` directly
-- ✅ Always import `Buffer` from `node:buffer` when decoding base64
-- ✅ Both patterns are valid - choose based on task type
-
-**Migration Guide:**
-1. Remove `credentials` from import statement
-2. Add `import { Buffer } from 'node:buffer'`
-3. Replace `ctx.credentials().get()` with `ctx.credentials().getAccessToken('connection_name')` for credential retrieval
-4. Or use `connectionVariables` directly in http tasks (recommended for http tasks)
-5. Or use `ctx.connections.connection_name` for direct connection access
-
----
-
-## Related Documentation
-
-- **[Module 5: Connection Management](./modules/platforms-versori-05-connections.md)** - Detailed Versori connection types
-- **[S3 CSV Inventory Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Complete S3 workflow example
-- **[SFTP CSV Control Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md)** - Complete SFTP workflow example
-- **[Security Best Practices](./modules/platforms-versori-08-best-practices.md)** - Comprehensive security guide
-
----
-
-## Quick Reference
-
-### S3 Activation Variables
-
-```json
-{
-  "s3BucketName": "string (required)",
-  "awsRegion": "string (default: us-east-1)",
-  "awsAccessKeyId": "string (required)",
-  "awsSecretAccessKey": "string (required)",
-  "s3Prefix": "string (optional, default: empty)"
-}
-```
-
-### SFTP Activation Variables
-
-```json
-{
-  "sftpHost": "string (required)",
-  "sftpPort": "number (default: 22)",
-  "sftpUsername": "string (required)",
-  "sftpPassword": "string (required if no privateKey)",
-  "sftpPrivateKey": "string (required if no password)",
-  "sftpPassphrase": "string (optional, for encrypted keys)",
-  "sftpRemotePath": "string (default: /)",
-  "sftpTimeout": "number (default: 30000ms)"
-}
-```
-
-### Versori Connection Structure
-
-```typescript
-interface VersoriConnection {
-  id: string;
-  name: string;
-  type: string;
-  params?: {
-    bucket?: string;
-    region?: string;
-    host?: string;
-    port?: string;
-    remotePath?: string;
-    timeout?: string;
-    [key: string]: string | undefined;
-  };
-  credentials?: {
-    accessKeyId?: string;
-    secretAccessKey?: string;
-    username?: string;
-    password?: string;
-    privateKey?: string;
-    passphrase?: string;
-    [key: string]: string | undefined;
-  };
-}
-```
-
----
-
-## Summary
-
-✅ **Two configuration approaches** - Connections (production) vs Variables (development)
-✅ **Clear decision matrix** - When to use each approach
-✅ **Complete setup guides** - Step-by-step for both S3 and SFTP
-✅ **Side-by-side code examples** - Easy comparison
-✅ **Security best practices** - Never hardcode, least privilege, rotation
-✅ **Migration guide** - Move from variables to connections
-✅ **Troubleshooting** - Common issues and solutions
-
-**Choose the right approach for your use case and follow security best practices!**
+# S3 & SFTP Configuration Guide for Versori
+
+**FC Connect SDK | Versori Platform Guide**
+
+> **Purpose**: Learn the two ways to configure S3 and SFTP connections in Versori workflows, understand when to use each approach, and implement secure, production-ready configurations.
+
+**Complexity**: Intermediate | **Time**: 15 minutes
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Two Configuration Approaches](#two-configuration-approaches)
+- [Decision Matrix](#decision-matrix)
+- [Approach 1: Versori Connections](#approach-1-versori-connections-recommended-for-production)
+- [Approach 2: Activation Variables](#approach-2-activation-variables-development-simple-use-cases)
+- [Side-by-Side Code Examples](#side-by-side-code-examples)
+- [Security Best Practices](#security-best-practices)
+- [Migration Guide](#migration-guide)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+When building Versori workflows that interact with **S3** or **SFTP** servers, you have **two ways** to provide credentials and configuration:
+
+| Approach | What It Is | Best For |
+|----------|-----------|----------|
+| **Versori Connections** | Centralized credential management in Versori UI | Production, multi-workflow setups, team collaboration |
+| **Activation Variables** | Per-workflow environment variables | Development, prototyping, single-use workflows |
+
+**Both approaches work with FC Connect SDK** - you choose based on your requirements.
+
+---
+
+## Two Configuration Approaches
+
+### Quick Comparison
+
+```typescript
+// ❶ VERSORI CONNECTION (Centralized)
+const s3 = new S3DataSource({
+  type: 'S3_CSV',
+  connectionId: 's3-production',  // References centralized connection
+  name: 'Production S3',
+  s3Config: {
+    bucket: ctx.activation?.connection?.params?.bucket,
+    region: ctx.activation?.connection?.params?.region,
+    credentials: ctx.activation?.connection?.credentials
+  }
+}, logger);
+
+// ❷ ACTIVATION VARIABLES (Per-workflow)
+const s3 = new S3DataSource({
+  type: 'S3_CSV',
+  connectionId: 'inline-config',
+  name: 'S3 Data Source',
+  s3Config: {
+    bucket: ctx.activation?.getVariable('s3BucketName') as string,
+    region: ctx.activation?.getVariable('awsRegion') as string,
+    accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
+    secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string
+  }
+}, logger);
+```
+
+**Key Difference:**
+- **Connections** → Credentials stored once in Versori, referenced by name
+- **Variables** → Credentials stored per-workflow as activation variables
+
+---
+
+## Decision Matrix
+
+Use this table to choose the right approach:
+
+| Factor | Versori Connections | Activation Variables |
+|--------|---------------------|---------------------|
+| **Setup Complexity** | ⚠️ Medium (UI setup required) | ✅ Simple (just add variables) |
+| **Credential Security** | ✅✅ Centralized, encrypted, audited | ⚠️ Duplicated across workflows |
+| **Reusability** | ✅✅ Share across multiple workflows | ❌ One workflow only |
+| **Credential Rotation** | ✅✅ Update once, affects all workflows | ❌ Update every workflow individually |
+| **Team Collaboration** | ✅✅ Central management, access control | ⚠️ Each dev needs credentials |
+| **Development Speed** | ⚠️ Slower (create connection first) | ✅ Faster (directly add variables) |
+| **Best For** | **Production environments** | **Development, prototyping, POC** |
+| **SDK Support** | ✅ Full support | ✅ Full support |
+
+### 🎯 Recommendations
+
+**Use Versori Connections when:**
+- ✅ Deploying to production
+- ✅ Multiple workflows use the same S3 bucket or SFTP server
+- ✅ Working in a team (shared credential management)
+- ✅ Security/compliance requires centralized credential storage
+- ✅ Credentials need to be rotated regularly
+
+**Use Activation Variables when:**
+- ✅ Prototyping or proof-of-concept
+- ✅ One-off data migration or testing
+- ✅ Each workflow needs different S3/SFTP credentials
+- ✅ Local development or sandbox environments
+- ✅ Quick iteration without UI configuration
+
+---
+
+## Approach 1: Versori Connections (Recommended for Production)
+
+### Benefits
+
+✅ **Centralized Management** - One place to manage credentials
+✅ **Reusable** - Reference the same connection across multiple workflows
+✅ **Secure** - Encrypted storage with access control
+✅ **Auditable** - Track who uses which credentials
+✅ **Easy Rotation** - Update once, all workflows inherit changes
+
+---
+
+## Credential Management: Connection vs Activation
+
+**IMPORTANT:** There are **two secure approaches** to fetch credentials - choose based on your security requirements.
+
+**⚠️ Versori/Deno Runtime Note:** When decoding Base64 credentials, always import Buffer:
+```typescript
+import { Buffer } from 'node:buffer';
+```
+This is required in Deno/Versori runtime (unlike Node.js where Buffer is global).
+
+### Approach 1A: Fetch from Versori Connection (Most Secure - Production)
+
+**Why Use This:**
+- ✅ **Most secure** - Credentials stored in Versori connection vault, not activation variables
+- ✅ **Centralized management** - Update connection in one place
+- ✅ **Access control** - Versori manages who can access credentials
+- ✅ **Audit trail** - Connection usage is logged by platform
+- ✅ **Production-ready** - Best practice for deployed workflows
+
+**How It Works:**
+1. **Create Basic Auth connection in Versori:**
+   - Connection Name: `versori_ftp_server`
+   - Type: Basic Auth
+   - Username: your-sftp-username
+   - Password: your-sftp-password
+
+2. **Versori encodes credentials:**
+   - Format: `username:password`
+   - Encoding: Base64
+   - Stored as `accessToken`
+
+3. **Your code decodes:**
+   - `ctx.connections.connection_name.accessToken` → get base64 token from connection object
+   - Decode base64 → get `username:password` string
+   - Split by `:` → extract username and password
+
+**Example: SFTP with Connection Credentials**
+
+```typescript
+import { Buffer } from 'node:buffer';
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpIngestion = schedule('sftp-sync', '0 2 * * *').then(
+  http('process-sftp-files', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { log, activation } = ctx;
+
+    // ✅ APPROACH 1A: Fetch credentials from Versori connection (SECURE - Production)
+    // IMPORTANT: Access connections directly via ctx.connections (Versori platform pattern)
+    const { connections } = ctx;
+    const conn = connections.versori_ftp_server;
+    const rawAccessToken = conn.accessToken;
+
+    // Decode base64-encoded "username:password"
+    const rawBasicAuth = Buffer.from(rawAccessToken, 'base64').toString('utf-8');
+    const [username, password] = rawBasicAuth.split(':');
+
+    // Initialize SftpDataSource with connection credentials
+    const sftp = new SftpDataSource({
+      type: 'SFTP_CSV',
+      connectionId: 'versori_ftp_server',
+      name: 'FTP Server',
+      settings: {
+        host: activation.getVariable('sftpHost'),
+        port: parseInt(activation.getVariable('sftpPort') || '22'),
+        username,        // ← From connection (secure)
+        password,        // ← From connection (secure)
+        remotePath: '/incoming',
+        filePattern: '*.csv'
+      }
+    }, log);
+
+    try {
+      // Use SFTP normally
+      const files = await sftp.listFiles({ directory: '/incoming' });
+      log.info(`Found ${files.length} files`);
+
+      for (const file of files) {
+        const content = await sftp.downloadFile(file.path, { encoding: 'utf8' });
+        log.info('File downloaded', { file: file.name, size: content.length });
+        // Process file...
+      }
+
+      return { success: true, filesProcessed: files.length };
+    } finally {
+      await sftp.disconnect();
+    }
+  })
+);
+```
+
+### Approach 1B: Activation Variables (Development/Testing)
+
+**When Use This:**
+- Development/testing environments
+- Quick prototyping
+- When connection setup is not yet complete
+
+**Example: SFTP with Activation Variables**
+
+```typescript
+import { Buffer } from 'node:buffer';
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpIngestion = schedule('sftp-sync', '0 2 * * *').then(
+  http('process-sftp-files', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { log, activation } = ctx;
+
+    // ✅ APPROACH 1B: Activation variables (Development/Testing)
+    const sftp = new SftpDataSource({
+      type: 'SFTP_CSV',
+      connectionId: 'sftp-server',
+      name: 'FTP Server',
+      settings: {
+        host: activation.getVariable('sftpHost'),
+        port: parseInt(activation.getVariable('sftpPort') || '22'),
+        username: activation.getVariable('sftpUsername'),  // ← From activation
+        password: activation.getVariable('sftpPassword'),  // ← From activation
+        remotePath: '/incoming',
+        filePattern: '*.csv'
+      }
+    }, log);
+
+    try {
+      const files = await sftp.listFiles({ directory: '/incoming' });
+      log.info(`Found ${files.length} files`);
+      return { success: true, filesProcessed: files.length };
+    } finally {
+      await sftp.disconnect();
+    }
+  })
+);
+```
+
+### Comparison: Connection vs Activation
+
+| Factor | Connection (1A) | Activation (1B) |
+|--------|----------------|-----------------|
+| **Security** | ✅✅ Vault storage | ⚠️ Variable storage |
+| **Setup Complexity** | ⚠️ Requires connection creation | ✅ Quick variable setup |
+| **Credential Rotation** | ✅✅ Update once | ❌ Update each workflow |
+| **Team Collaboration** | ✅✅ Central management | ⚠️ Each dev needs creds |
+| **Audit Trail** | ✅✅ Platform-logged | ⚠️ Variable access only |
+| **Best For** | **Production** | **Development/Testing** |
+
+### Complete Working Example: Hybrid Approach
+
+**Support both methods with fallback for maximum flexibility:**
+
+```typescript
+import { Buffer } from 'node:buffer';
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpIngestion = schedule('sftp-sync', '0 2 * * *').then(
+  http('process-sftp-files', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { log, activation } = ctx;
+
+    // Try connection-based credentials first (production), fallback to activation (development)
+    let username: string;
+    let password: string;
+
+    try {
+      // ✅ PRIMARY: Try connection credentials (most secure)
+      const { connections } = ctx;
+      const conn = connections.versori_ftp_server;
+      const rawAccessToken = conn.accessToken;
+      const rawBasicAuth = Buffer.from(rawAccessToken, 'base64').toString('utf-8');
+      [username, password] = rawBasicAuth.split(':');
+
+      log.info('Using connection credentials for SFTP');
+    } catch (error) {
+      // ⚠️ FALLBACK: Use activation variables (development/testing)
+      username = activation.getVariable('sftpUsername');
+      password = activation.getVariable('sftpPassword');
+
+      log.warn('Connection credentials unavailable, using activation variables');
+    }
+
+    // Validate credentials are available
+    if (!username || !password) {
+      throw new Error('SFTP credentials not found in connection or activation variables');
+    }
+
+    // Initialize SftpDataSource
+    const sftp = new SftpDataSource({
+      type: 'SFTP_CSV',
+      connectionId: 'versori_ftp_server',
+      name: 'FTP Server',
+      settings: {
+        host: activation.getVariable('sftpHost'),
+        port: parseInt(activation.getVariable('sftpPort') || '22'),
+        username,
+        password,
+        remotePath: '/incoming',
+        filePattern: '*.csv'
+      }
+    }, log);
+
+    try {
+      const files = await sftp.listFiles({ directory: '/incoming' });
+      log.info(`Found ${files.length} files`);
+      return { success: true, filesProcessed: files.length };
+    } finally {
+      await sftp.disconnect();
+    }
+  })
+);
+```
+
+---
+
+### Setup: AWS S3 Connection
+
+#### Step 1: Create Connection in Versori UI
+
+1. **Navigate to Versori Dashboard** → **Connections** tab
+2. Click **"Add Connection"**
+3. **Configure Connection:**
+
+```
+Name: s3-production
+Description: Production S3 bucket for inventory data
+Type: AWS S3 (or API Key if S3 not available)
+```
+
+4. **Authentication Details:**
+
+```
+AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
+AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+Region: us-east-1
+```
+
+5. **Additional Parameters (Optional):**
+
+```json
+{
+  "bucket": "my-production-inventory",
+  "prefix": "inventory/incoming/"
+}
+```
+
+6. **Test Connection** → Verify access
+7. **Save Connection**
+
+#### Step 2: Use Connection in Workflow Code
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const inventorySync = schedule('daily-sync', '0 2 * * *').then(
+  http('process-s3-files', {
+    connection: 'fluent_commerce',  // Fluent connection
+    additionalConnections: {
+      s3: 's3-production'            // ← Reference S3 connection by name
+    }
+  }, async (ctx) => {
+    const log = ctx.log;
+
+    // Access S3 connection
+    const s3Connection = ctx.activation?.connections?.s3;
+
+    // Initialize S3DataSource with connection credentials
+    const s3DataSource = new S3DataSource({
+      type: 'S3_CSV',
+      connectionId: s3Connection?.id || 's3-production',
+      name: 'Production S3',
+      s3Config: {
+        bucket: s3Connection?.params?.bucket || ctx.activation?.getVariable('s3BucketName') as string,
+        region: s3Connection?.params?.region || 'us-east-1',
+        accessKeyId: s3Connection?.credentials?.accessKeyId,
+        secretAccessKey: s3Connection?.credentials?.secretAccessKey
+      }
+    }, log);
+
+    // Use S3DataSource normally
+    const files = await s3DataSource.listFiles({ prefix: 'inventory/' });
+    log.info(`Found ${files.length} files`);
+
+    return { success: true, filesFound: files.length };
+  })
+);
+```
+
+**Key Points:**
+- ✅ `additionalConnections` parameter references the connection name
+- ✅ Access via `ctx.activation?.connections?.s3`
+- ✅ Fallback to activation variables for flexibility
+- ✅ No credentials in code
+
+#### Step 3: Test & Deploy
+
+```bash
+# Deploy workflow
+versori deploy
+
+# Verify connection
+versori logs --workflow daily-sync
+```
+
+---
+
+### Setup: SFTP Connection
+
+#### Step 1: Create Connection in Versori UI
+
+1. **Navigate to** → **Connections** → **"Add Connection"**
+2. **Configure:**
+
+```
+Name: sftp-partner-server
+Description: Partner SFTP server for exports
+Type: SFTP (or Custom if not available)
+```
+
+3. **SFTP Details:**
+
+```
+Host: sftp.partner.com
+Port: 22
+Username: inventory_export
+Authentication: Password (or SSH Key)
+Password: ******** (or upload private key)
+```
+
+4. **Additional Parameters:**
+
+```json
+{
+  "remotePath": "/incoming/inventory/",
+  "timeout": 30000,
+  "keepalive": 10000
+}
+```
+
+5. **Test Connection** → **Save**
+
+#### Step 2: Use Connection in Workflow
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpExport = schedule('daily-export', '0 3 * * *').then(
+  http('export-to-sftp', {
+    connection: 'fluent_commerce',
+    additionalConnections: {
+      sftp: 'sftp-partner-server'  // ← Reference SFTP connection
+    }
+  }, async (ctx) => {
+    const log = ctx.log;
+
+    // Access SFTP connection
+    const sftpConnection = ctx.activation?.connections?.sftp;
+
+    // Initialize SftpDataSource with connection credentials
+    const sftpDataSource = new SftpDataSource({
+      type: 'SFTP_CSV',
+      connectionId: sftpConnection?.id || 'sftp-partner',
+      name: 'Partner SFTP',
+      sftpConfig: {
+        host: sftpConnection?.params?.host || ctx.activation?.getVariable('sftpHost') as string,
+        port: parseInt(sftpConnection?.params?.port || '22'),
+        username: sftpConnection?.credentials?.username,
+        password: sftpConnection?.credentials?.password,
+        privateKey: sftpConnection?.credentials?.privateKey,
+        timeout: parseInt(sftpConnection?.params?.timeout || '30000'),
+        keepaliveInterval: parseInt(sftpConnection?.params?.keepalive || '10000')
+      }
+    }, log);
+
+    try {
+      // Upload file to SFTP
+      const csvData = 'sku,qty\nSKU-001,100\n';
+      await sftpDataSource.uploadFile(
+        '/incoming/inventory/inventory-export.csv',
+        Buffer.from(csvData, 'utf-8'),
+        { encoding: 'utf-8' }
+      );
+
+      log.info('File uploaded successfully');
+      return { success: true };
+    } finally {
+      // Always disconnect SFTP
+      await sftpDataSource.disconnect();
+    }
+  })
+);
+```
+
+**Key Points:**
+- ✅ `additionalConnections.sftp` references connection
+- ✅ Support for password OR SSH key authentication
+- ✅ Always call `disconnect()` in finally block
+- ✅ Timeout and keep-alive from connection config
+
+---
+
+## Approach 2: Activation Variables (Development & Simple Use Cases)
+
+### Benefits
+
+✅ **Quick Setup** - No UI configuration needed
+✅ **Per-Workflow Control** - Each workflow has independent config
+✅ **Development-Friendly** - Easy to test with different credentials
+✅ **Explicit** - All configuration visible in code
+
+### Setup: AWS S3 with Activation Variables
+
+#### Step 1: Define Activation Variables
+
+In Versori UI → **Workflow Settings** → **Activation Variables**:
+
+```json
+{
+  "s3BucketName": "my-inventory-bucket",
+  "awsRegion": "us-east-1",
+  "awsAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
+  "awsSecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+  "s3Prefix": "inventory/incoming/"
+}
+```
+
+**Security Note:** These are encrypted by Versori platform.
+
+#### Step 2: Use Variables in Code
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const inventorySync = schedule('daily-sync', '0 2 * * *').then(
+  http('process-s3-files', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const log = ctx.log;
+
+    // Load configuration from activation variables
+    const config = {
+      s3Bucket: ctx.activation?.getVariable('s3BucketName') as string,
+      s3Region: ctx.activation?.getVariable('awsRegion') as string || 'us-east-1',
+      s3AccessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
+      s3SecretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string,
+      s3Prefix: ctx.activation?.getVariable('s3Prefix') as string || 'inventory/'
+    };
+
+    // Validate required variables
+    const missingVars: string[] = [];
+    if (!config.s3Bucket) missingVars.push('s3BucketName');
+    if (!config.s3AccessKeyId) missingVars.push('awsAccessKeyId');
+    if (!config.s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
+
+    if (missingVars.length > 0) {
+      const errorMsg = `Missing required activation variables: ${missingVars.join(', ')}`;
+      log.error(errorMsg);
+      return { success: false, error: errorMsg };
+    }
+
+    // Initialize S3DataSource with activation variables
+    const s3DataSource = new S3DataSource({
+      type: 'S3_CSV',
+      connectionId: 'inline-s3-config',
+      name: 'S3 Data Source',
+      s3Config: {
+        bucket: config.s3Bucket,
+        region: config.s3Region,
+        accessKeyId: config.s3AccessKeyId,
+        secretAccessKey: config.s3SecretAccessKey
+      }
+    }, log);
+
+    // Use S3DataSource
+    const files = await s3DataSource.listFiles({ prefix: config.s3Prefix });
+    log.info(`Found ${files.length} files`);
+
+    return { success: true, filesFound: files.length };
+  })
+);
+```
+
+**Key Points:**
+- ✅ All config loaded via `ctx.activation?.getVariable()`
+- ✅ Validation ensures required variables are present
+- ✅ Fallback values for optional variables
+- ✅ Clear error messages for missing config
+
+---
+
+### Setup: SFTP with Activation Variables
+
+#### Step 1: Define Activation Variables
+
+```json
+{
+  "sftpHost": "sftp.partner.com",
+  "sftpPort": "22",
+  "sftpUsername": "inventory_export",
+  "sftpPassword": "********",
+  "sftpRemotePath": "/incoming/inventory/",
+  "sftpTimeout": "30000"
+}
+```
+
+**SSH Key Authentication (Alternative):**
+
+```json
+{
+  "sftpHost": "sftp.partner.com",
+  "sftpPort": "22",
+  "sftpUsername": "inventory_export",
+  "sftpPrivateKey": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
+  "sftpPassphrase": "keypassphrase",
+  "sftpRemotePath": "/incoming/inventory/"
+}
+```
+
+#### Step 2: Use Variables in Code
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpExport = schedule('daily-export', '0 3 * * *').then(
+  http('export-to-sftp', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const log = ctx.log;
+
+    // Load SFTP configuration from activation variables
+    const config = {
+      sftpHost: ctx.activation?.getVariable('sftpHost') as string,
+      sftpPort: parseInt(ctx.activation?.getVariable('sftpPort') as string || '22'),
+      sftpUsername: ctx.activation?.getVariable('sftpUsername') as string,
+      sftpPassword: ctx.activation?.getVariable('sftpPassword') as string,
+      sftpPrivateKey: ctx.activation?.getVariable('sftpPrivateKey') as string,
+      sftpPassphrase: ctx.activation?.getVariable('sftpPassphrase') as string,
+      sftpRemotePath: ctx.activation?.getVariable('sftpRemotePath') as string || '/',
+      sftpTimeout: parseInt(ctx.activation?.getVariable('sftpTimeout') as string || '30000')
+    };
+
+    // Validate required variables
+    const missingVars: string[] = [];
+    if (!config.sftpHost) missingVars.push('sftpHost');
+    if (!config.sftpUsername) missingVars.push('sftpUsername');
+    if (!config.sftpPassword && !config.sftpPrivateKey) {
+      missingVars.push('sftpPassword OR sftpPrivateKey');
+    }
+
+    if (missingVars.length > 0) {
+      const errorMsg = `Missing required activation variables: ${missingVars.join(', ')}`;
+      log.error(errorMsg);
+      return { success: false, error: errorMsg };
+    }
+
+    // Initialize SftpDataSource
+    const sftpDataSource = new SftpDataSource({
+      type: 'SFTP_CSV',
+      connectionId: 'inline-sftp-config',
+      name: 'SFTP Data Source',
+      sftpConfig: {
+        host: config.sftpHost,
+        port: config.sftpPort,
+        username: config.sftpUsername,
+        password: config.sftpPassword,
+        privateKey: config.sftpPrivateKey,
+        passphrase: config.sftpPassphrase,
+        timeout: config.sftpTimeout,
+        keepaliveInterval: 10000,
+        retryDelay: 2000,
+        maxRetries: 3
+      }
+    }, log);
+
+    try {
+      // Upload file
+      const csvData = 'sku,qty\nSKU-001,100\n';
+      const remotePath = `${config.sftpRemotePath}/inventory-export-${Date.now()}.csv`;
+
+      await sftpDataSource.uploadFile(
+        remotePath,
+        Buffer.from(csvData, 'utf-8'),
+        { encoding: 'utf-8' }
+      );
+
+      log.info(`File uploaded to ${remotePath}`);
+      return { success: true, remotePath };
+    } catch (error: any) {
+      log.error('SFTP upload failed', { error: error.message });
+      return { success: false, error: error.message };
+    } finally {
+      // Always disconnect
+      await sftpDataSource.disconnect();
+    }
+  })
+);
+```
+
+**Key Points:**
+- ✅ Support for password OR SSH key authentication
+- ✅ Validation for mutually exclusive auth methods
+- ✅ Always disconnect in finally block
+- ✅ Comprehensive error handling
+
+---
+
+## Side-by-Side Code Examples
+
+### S3DataSource: Both Approaches
+
+```typescript
+// ═══════════════════════════════════════════════════════════════
+// APPROACH 1: VERSORI CONNECTION
+// ═══════════════════════════════════════════════════════════════
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+// In workflow with additionalConnections: { s3: 's3-production' }
+const s3Connection = ctx.activation?.connections?.s3;
+
+const s3DataSource = new S3DataSource({
+  type: 'S3_CSV',
+  connectionId: s3Connection?.id,
+  name: 'Production S3',
+  s3Config: {
+    bucket: s3Connection?.params?.bucket,           // From connection
+    region: s3Connection?.params?.region,           // From connection
+    accessKeyId: s3Connection?.credentials?.accessKeyId,       // From connection
+    secretAccessKey: s3Connection?.credentials?.secretAccessKey // From connection
+  }
+}, logger);
+
+// ═══════════════════════════════════════════════════════════════
+// APPROACH 2: ACTIVATION VARIABLES
+// ═══════════════════════════════════════════════════════════════
+const s3DataSource = new S3DataSource({
+  type: 'S3_CSV',
+  connectionId: 'inline-config',
+  name: 'S3 Data Source',
+  s3Config: {
+    bucket: ctx.activation?.getVariable('s3BucketName') as string,       // From variable
+    region: ctx.activation?.getVariable('awsRegion') as string,          // From variable
+    accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,     // From variable
+    secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string // From variable
+  }
+}, logger);
+
+// ═══════════════════════════════════════════════════════════════
+// USAGE: SAME FOR BOTH APPROACHES
+// ═══════════════════════════════════════════════════════════════
+const files = await s3DataSource.listFiles({ prefix: 'inventory/' });
+const fileContent = await s3DataSource.downloadFile(files[0].path, { encoding: 'utf8' });
+await s3DataSource.uploadFile('output/result.csv', Buffer.from(csvData), {});
+```
+
+---
+
+### SftpDataSource: Both Approaches
+
+```typescript
+// ═══════════════════════════════════════════════════════════════
+// APPROACH 1: VERSORI CONNECTION
+// ═══════════════════════════════════════════════════════════════
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+// In workflow with additionalConnections: { sftp: 'sftp-partner' }
+const sftpConnection = ctx.activation?.connections?.sftp;
+
+const sftpDataSource = new SftpDataSource({
+  type: 'SFTP_CSV',
+  connectionId: sftpConnection?.id,
+  name: 'Partner SFTP',
+  sftpConfig: {
+    host: sftpConnection?.params?.host,                // From connection
+    port: parseInt(sftpConnection?.params?.port || '22'),
+    username: sftpConnection?.credentials?.username,   // From connection
+    password: sftpConnection?.credentials?.password,   // From connection
+    privateKey: sftpConnection?.credentials?.privateKey, // From connection
+    timeout: parseInt(sftpConnection?.params?.timeout || '30000'),
+    keepaliveInterval: 10000
+  }
+}, logger);
+
+// ═══════════════════════════════════════════════════════════════
+// APPROACH 2: ACTIVATION VARIABLES
+// ═══════════════════════════════════════════════════════════════
+const sftpDataSource = new SftpDataSource({
+  type: 'SFTP_CSV',
+  connectionId: 'inline-config',
+  name: 'SFTP Data Source',
+  sftpConfig: {
+    host: ctx.activation?.getVariable('sftpHost') as string,       // From variable
+    port: parseInt(ctx.activation?.getVariable('sftpPort') as string || '22'),
+    username: ctx.activation?.getVariable('sftpUsername') as string,   // From variable
+    password: ctx.activation?.getVariable('sftpPassword') as string,   // From variable
+    privateKey: ctx.activation?.getVariable('sftpPrivateKey') as string, // From variable
+    timeout: parseInt(ctx.activation?.getVariable('sftpTimeout') as string || '30000'),
+    keepaliveInterval: 10000,
+    retryDelay: 2000,
+    maxRetries: 3
+  }
+}, logger);
+
+// ═══════════════════════════════════════════════════════════════
+// USAGE: SAME FOR BOTH APPROACHES
+// ═══════════════════════════════════════════════════════════════
+try {
+  const files = await sftpDataSource.listFiles({ directory: '/incoming' });
+  const fileContent = await sftpDataSource.downloadFile(files[0].path, { encoding: 'utf8' });
+  await sftpDataSource.uploadFile('/outgoing/result.csv', Buffer.from(csvData), {});
+} finally {
+  await sftpDataSource.disconnect();  // ⚠️ ALWAYS disconnect SFTP!
+}
+```
+
+---
+
+## Security Best Practices
+
+### 1. Never Hardcode Credentials
+
+```typescript
+// ❌ NEVER DO THIS
+const s3DataSource = new S3DataSource({
+  s3Config: {
+    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',      // ❌ Hardcoded!
+    secretAccessKey: 'wJalrXUtnFEMI/K...'     // ❌ Hardcoded!
+  }
+});
+
+// ✅ ALWAYS DO THIS (Connection)
+const s3DataSource = new S3DataSource({
+  s3Config: {
+    accessKeyId: ctx.activation?.connections?.s3?.credentials?.accessKeyId,
+    secretAccessKey: ctx.activation?.connections?.s3?.credentials?.secretAccessKey
+  }
+});
+
+// ✅ OR THIS (Variables)
+const s3DataSource = new S3DataSource({
+  s3Config: {
+    accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
+    secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string
+  }
+});
+```
+
+### 2. Use IAM Roles for S3 (When Possible)
+
+If running on AWS infrastructure (EC2, Lambda), use IAM roles instead of access keys:
+
+```typescript
+// Best: IAM Role (no credentials needed)
+const s3DataSource = new S3DataSource({
+  type: 'S3_CSV',
+  s3Config: {
+    bucket: 'my-bucket',
+    region: 'us-east-1'
+    // No accessKeyId/secretAccessKey - uses IAM role
+  }
+}, logger);
+```
+
+### 3. Use SSH Keys for SFTP (Not Passwords)
+
+```typescript
+// ⚠️ Password authentication (less secure)
+sftpConfig: {
+  username: 'user',
+  password: 'password123'  // Can be brute-forced
+}
+
+// ✅ SSH Key authentication (more secure)
+sftpConfig: {
+  username: 'user',
+  privateKey: ctx.activation?.getVariable('sftpPrivateKey') as string,
+  passphrase: ctx.activation?.getVariable('sftpPassphrase') as string
+}
+```
+
+### 4. Principle of Least Privilege
+
+**S3 IAM Policy (Minimal Permissions):**
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject",
+        "s3:ListBucket"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-inventory-bucket",
+        "arn:aws:s3:::my-inventory-bucket/*"
+      ]
+    }
+  ]
+}
+```
+
+**SFTP User Permissions:**
+- Read-only for ingestion workflows
+- Write-only for extraction workflows
+- Restrict to specific directories via chroot
+
+### 5. Credential Rotation
+
+**With Versori Connections (Easy):**
+1. Update connection in Versori UI
+2. All workflows automatically use new credentials
+3. Zero code changes needed
+
+**With Activation Variables (Manual):**
+1. Update each workflow's activation variables individually
+2. Redeploy each affected workflow
+3. Risk of missed workflows
+
+### 6. Audit Logging
+
+Enable logging for credential usage:
+
+```typescript
+// Log connection info (NOT credentials)
+log.info('Using S3 connection', {
+  connectionId: s3Connection?.id,
+  bucket: s3Connection?.params?.bucket,
+  region: s3Connection?.params?.region,
+  // ❌ NEVER log: accessKeyId, secretAccessKey
+});
+```
+
+### 7. Environment Separation
+
+Use different connections/variables per environment:
+
+```
+Development:
+  - Connection: s3-dev
+  - Variables: s3BucketName=dev-inventory
+
+Staging:
+  - Connection: s3-staging
+  - Variables: s3BucketName=staging-inventory
+
+Production:
+  - Connection: s3-production
+  - Variables: s3BucketName=prod-inventory
+```
+
+---
+
+## Migration Guide
+
+### From Activation Variables → Versori Connections
+
+**Step 1: Create Connection**
+
+Extract current activation variables and create Versori connection:
+
+**Current Activation Variables:**
+```json
+{
+  "s3BucketName": "my-inventory-bucket",
+  "awsRegion": "us-east-1",
+  "awsAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
+  "awsSecretAccessKey": "wJalrXUtnFEMI..."
+}
+```
+
+**New Versori Connection:**
+- Name: `s3-production`
+- Type: AWS S3
+- Access Key ID: `AKIAIOSFODNN7EXAMPLE`
+- Secret Access Key: `wJalrXUtnFEMI...`
+- Region: `us-east-1`
+- Parameters: `{ "bucket": "my-inventory-bucket" }`
+
+**Step 2: Update Workflow Code**
+
+**Before (Activation Variables):**
+```typescript
+export const sync = schedule('daily', '0 2 * * *').then(
+  http('process', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const s3 = new S3DataSource({
+      type: 'S3_CSV',
+      s3Config: {
+        bucket: ctx.activation?.getVariable('s3BucketName') as string,
+        region: ctx.activation?.getVariable('awsRegion') as string,
+        accessKeyId: ctx.activation?.getVariable('awsAccessKeyId') as string,
+        secretAccessKey: ctx.activation?.getVariable('awsSecretAccessKey') as string
+      }
+    }, ctx.log);
+    // ... rest of code
+  })
+);
+```
+
+**After (Versori Connection):**
+```typescript
+export const sync = schedule('daily', '0 2 * * *').then(
+  http('process', {
+    connection: 'fluent_commerce',
+    additionalConnections: {
+      s3: 's3-production'  // ← Add this
+    }
+  }, async (ctx) => {
+    const s3Conn = ctx.activation?.connections?.s3;
+    const s3 = new S3DataSource({
+      type: 'S3_CSV',
+      s3Config: {
+        bucket: s3Conn?.params?.bucket,
+        region: s3Conn?.params?.region,
+        accessKeyId: s3Conn?.credentials?.accessKeyId,
+        secretAccessKey: s3Conn?.credentials?.secretAccessKey
+      }
+    }, ctx.log);
+    // ... rest of code (unchanged)
+  })
+);
+```
+
+**Step 3: Test & Deploy**
+
+```bash
+# Test locally
+versori dev
+
+# Deploy to production
+versori deploy
+
+# Verify logs
+versori logs --workflow daily
+```
+
+**Step 4: Remove Old Activation Variables**
+
+After verifying the connection works, remove the old activation variables from workflow settings.
+
+---
+
+## Troubleshooting
+
+### Issue 1: "Connection not found"
+
+**Error:**
+```
+Error: Connection 's3-production' not found
+```
+
+**Causes:**
+- Typo in connection name
+- Connection not created in Versori UI
+- Connection not added to `additionalConnections`
+
+**Solution:**
+```typescript
+// 1. Verify connection exists in Versori UI
+// 2. Check name matches exactly (case-sensitive)
+additionalConnections: {
+  s3: 's3-production'  // ← Must match UI name exactly
+}
+
+// 3. Add fallback
+const s3Conn = ctx.activation?.connections?.s3;
+if (!s3Conn) {
+  log.error('S3 connection not found');
+  return { success: false, error: 'S3 connection required' };
+}
+```
+
+---
+
+### Issue 2: "Missing activation variable"
+
+**Error:**
+```
+Missing required activation variables: awsAccessKeyId
+```
+
+**Causes:**
+- Variable not defined in workflow settings
+- Typo in variable name
+- Variable name case mismatch
+
+**Solution:**
+```typescript
+// 1. Verify activation variable exists in Versori UI
+// 2. Check exact name (case-sensitive)
+const accessKeyId = ctx.activation?.getVariable('awsAccessKeyId') as string;
+//                                                ^^^^^^^^^^^^^^^
+//                                                Must match UI exactly
+
+// 3. Add validation with helpful error
+if (!accessKeyId) {
+  log.error('Missing activation variable: awsAccessKeyId');
+  log.info('Available variables:', Object.keys(ctx.activation?.variables || {}));
+  throw new Error('Configuration error: awsAccessKeyId required');
+}
+```
+
+---
+
+### Issue 3: S3 Access Denied
+
+**Error:**
+```
+AccessDenied: User: arn:aws:iam::123456789012:user/app-user is not authorized to perform: s3:ListBucket
+```
+
+**Causes:**
+- Insufficient IAM permissions
+- Wrong bucket name
+- Incorrect region
+
+**Solution:**
+```typescript
+// 1. Verify IAM permissions include required actions:
+// - s3:ListBucket (for listFiles)
+// - s3:GetObject (for downloadFile)
+// - s3:PutObject (for uploadFile)
+
+// 2. Test connection with minimal operation
+try {
+  const files = await s3DataSource.listFiles({ prefix: '', maxKeys: 1 });
+  log.info('S3 connection successful');
+} catch (error: any) {
+  log.error('S3 access denied', {
+    bucket: config.s3Bucket,
+    region: config.s3Region,
+    error: error.message
+  });
+  throw error;
+}
+```
+
+---
+
+### Issue 4: SFTP Connection Timeout
+
+**Error:**
+```
+Error: Timeout while connecting to SFTP server
+```
+
+**Causes:**
+- Firewall blocking port 22
+- Incorrect host/port
+- Server not responding
+
+**Solution:**
+```typescript
+// 1. Increase timeout
+sftpConfig: {
+  timeout: 60000,  // 60 seconds (default: 30s)
+  keepaliveInterval: 10000
+}
+
+// 2. Test connection manually
+ssh username@sftp.partner.com -p 22
+
+// 3. Check firewall rules
+// Ensure Versori platform can reach SFTP server
+
+// 4. Add retry logic
+async function connectSftpWithRetry(config, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const sftp = new SftpDataSource(config, log);
+      await sftp.listFiles({ directory: '/' });
+      return sftp;
+    } catch (error: any) {
+      if (i === maxRetries - 1) throw error;
+      const delay = 2000 * Math.pow(2, i);
+      log.warn(`SFTP connection failed, retrying in ${delay}ms...`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+```
+
+---
+
+### Issue 5: SFTP Permission Denied
+
+**Error:**
+```
+Error: Permission denied: /incoming/inventory.csv
+```
+
+**Causes:**
+- User lacks write permissions to directory
+- Directory doesn't exist
+- Wrong remote path
+
+**Solution:**
+```typescript
+// 1. Create directory if needed (requires permissions)
+try {
+  await sftpDataSource.createDirectory(remotePath);
+} catch (error: any) {
+  log.warn('Could not create directory', { remotePath, error: error.message });
+}
+
+// 2. Test with read operation first
+const files = await sftpDataSource.listFiles({ directory: '/' });
+log.info('SFTP readable directories:', files);
+
+// 3. Verify path from SFTP root
+// Remote path should be absolute: /incoming/inventory.csv
+// NOT relative: incoming/inventory.csv
+```
+
+---
+
+### Issue 6: Connection vs Variable Confusion
+
+**Problem:** Code expects connection but variables are provided (or vice versa)
+
+**Solution:** Support both with fallback:
+
+```typescript
+// Hybrid approach: Try connection first, fallback to variables
+const s3Bucket =
+  ctx.activation?.connections?.s3?.params?.bucket ||   // Try connection
+  ctx.activation?.getVariable('s3BucketName') as string;  // Fallback to variable
+
+const s3AccessKey =
+  ctx.activation?.connections?.s3?.credentials?.accessKeyId ||
+  ctx.activation?.getVariable('awsAccessKeyId') as string;
+
+// Validate
+if (!s3Bucket || !s3AccessKey) {
+  throw new Error('S3 configuration required via connection or activation variables');
+}
+```
+
+---
+
+### Issue 7: Incorrect Credential Access Pattern
+
+**Error:**
+```
+TypeError: credentials is not a function
+ReferenceError: credentials is not defined
+```
+
+**Problem:** Documentation showed importing and calling `credentials` from `@versori/run`, but this export doesn't exist.
+
+**Incorrect Pattern (OLD - DO NOT USE):**
+```typescript
+// ❌ WRONG - This doesn't exist!
+const cred = await ctx.credentials().get('connection_name');
+```
+
+**Correct Patterns:**
+
+**Option A: Using http task with connection (Recommended):**
+```typescript
+// ✅ CORRECT - Use connectionVariables from ctx
+import { Buffer } from 'node:buffer';
+import { http } from '@versori/run';
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+http("task", { connection: "sftp_server" }, async (ctx) => {
+  const { connectionVariables } = ctx;
+
+  const sftpConfig = {
+    host: connectionVariables.host,
+    port: connectionVariables.port || 22,
+    username: connectionVariables.username,
+    password: Buffer.from(connectionVariables.password, 'base64').toString('utf-8')
+  };
+
+  const sftp = new SftpDataSource({ type: 'SFTP_CSV', settings: sftpConfig }, ctx.log);
+});
+```
+
+**Option B: Using ctx.connections directly:**
+```typescript
+// ✅ CORRECT - Use ctx.connections directly
+import { Buffer } from 'node:buffer';
+import { fn } from '@versori/run';
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+fn("task", async (ctx) => {
+  const { connections } = ctx;
+  const conn = connections.sftp_server;
+
+  const sftpConfig = {
+    host: ctx.activation.getVariable('sftpHost'),
+    port: 22,
+    username: conn.username || Buffer.from(conn.accessToken, 'base64').toString('utf-8').split(':')[0],
+    password: conn.password || Buffer.from(conn.accessToken, 'base64').toString('utf-8').split(':')[1]
+  };
+
+  const sftp = new SftpDataSource({ type: 'SFTP_CSV', settings: sftpConfig }, ctx.log);
+});
+```
+
+**Key Points:**
+- ✅ No `credentials` export exists from `@versori/run`
+- ✅ Use `connectionVariables` (http tasks) or `ctx.connections` directly
+- ✅ Always import `Buffer` from `node:buffer` when decoding base64
+- ✅ Both patterns are valid - choose based on task type
+
+**Migration Guide:**
+1. Remove `credentials` from import statement
+2. Add `import { Buffer } from 'node:buffer'`
+3. Replace `ctx.credentials().get()` with `ctx.credentials().getAccessToken('connection_name')` for credential retrieval
+4. Or use `connectionVariables` directly in http tasks (recommended for http tasks)
+5. Or use `ctx.connections.connection_name` for direct connection access
+
+---
+
+## Related Documentation
+
+- **[Module 5: Connection Management](./modules/platforms-versori-05-connections.md)** - Detailed Versori connection types
+- **[S3 CSV Inventory Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Complete S3 workflow example
+- **[SFTP CSV Control Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md)** - Complete SFTP workflow example
+- **[Security Best Practices](./modules/platforms-versori-08-best-practices.md)** - Comprehensive security guide
+
+---
+
+## Quick Reference
+
+### S3 Activation Variables
+
+```json
+{
+  "s3BucketName": "string (required)",
+  "awsRegion": "string (default: us-east-1)",
+  "awsAccessKeyId": "string (required)",
+  "awsSecretAccessKey": "string (required)",
+  "s3Prefix": "string (optional, default: empty)"
+}
+```
+
+### SFTP Activation Variables
+
+```json
+{
+  "sftpHost": "string (required)",
+  "sftpPort": "number (default: 22)",
+  "sftpUsername": "string (required)",
+  "sftpPassword": "string (required if no privateKey)",
+  "sftpPrivateKey": "string (required if no password)",
+  "sftpPassphrase": "string (optional, for encrypted keys)",
+  "sftpRemotePath": "string (default: /)",
+  "sftpTimeout": "number (default: 30000ms)"
+}
+```
+
+### Versori Connection Structure
+
+```typescript
+interface VersoriConnection {
+  id: string;
+  name: string;
+  type: string;
+  params?: {
+    bucket?: string;
+    region?: string;
+    host?: string;
+    port?: string;
+    remotePath?: string;
+    timeout?: string;
+    [key: string]: string | undefined;
+  };
+  credentials?: {
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    username?: string;
+    password?: string;
+    privateKey?: string;
+    passphrase?: string;
+    [key: string]: string | undefined;
+  };
+}
+```
+
+---
+
+## Summary
+
+✅ **Two configuration approaches** - Connections (production) vs Variables (development)
+✅ **Clear decision matrix** - When to use each approach
+✅ **Complete setup guides** - Step-by-step for both S3 and SFTP
+✅ **Side-by-side code examples** - Easy comparison
+✅ **Security best practices** - Never hardcode, least privilege, rotation
+✅ **Migration guide** - Move from variables to connections
+✅ **Troubleshooting** - Common issues and solutions
+
+**Choose the right approach for your use case and follow security best practices!**