@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-08-best-practices.md

@@ -1,1111 +1,1111 @@
-# Module 8: Best Practices & Production Patterns
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 8 of 8** | **Level**: Advanced | **Time**: 30 minutes
-
----
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- ✅ Implement production-ready error handling patterns
-- ✅ Optimize workflow performance and reduce costs
-- ✅ Apply security hardening best practices
-- ✅ Implement robust retry and fallback strategies
-- ✅ Troubleshoot common production issues
-- ✅ Monitor and alert on critical metrics
-- ✅ Apply cost optimization techniques
-
----
-
-## Production-Ready Error Handling
-
-### Pattern 1: Comprehensive Try-Catch with Context
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const robustWorkflow = http(
-  'robust-workflow',
-  {
-    connection: 'fluent_commerce',
-    retry: {
-      attempts: 3,
-      delay: 1000,
-      backoff: 2, // Exponential backoff
-    },
-    timeout: 30000,
-  },
-  async ctx => {
-    const operationId = `${ctx.executionId}-${Date.now()}`;
-
-    ctx.log('info', 'Workflow started', {
-      operationId,
-      executionId: ctx.executionId,
-      timestamp: new Date().toISOString(),
-    });
-
-    try {
-      const client = await createClient(ctx);
-
-      // Validate input
-      if (!ctx.data?.orderId) {
-        throw new Error('Missing required field: orderId');
-      }
-
-      // GraphQL query - schema validated
-      const result = await client.graphql({
-        query: `
-        query GetOrder($ref: String!) {
-          order(ref: $ref) {
-            id
-            ref
-            status
-            totalPrice
-          }
-        }
-      `,
-        variables: { ref: ctx.data.orderId },
-      });
-
-      // Check GraphQL errors
-      if (result.errors?.length) {
-        throw new Error(`GraphQL error: ${result.errors[0].message}`);
-      }
-
-      // Check data exists
-      if (!result.data?.order) {
-        throw new Error(`Order not found: ${ctx.data.orderId}`);
-      }
-
-      ctx.log('info', 'Workflow completed successfully', {
-        operationId,
-        orderId: ctx.data.orderId,
-        orderStatus: result.data.order.status,
-      });
-
-      return {
-        success: true,
-        operationId,
-        data: result.data.order,
-      };
-    } catch (error) {
-      // Categorize error
-      const errorType =
-        error instanceof Error && error.message.includes('GraphQL')
-          ? 'GRAPHQL_ERROR'
-          : error instanceof Error && error.message.includes('not found')
-            ? 'NOT_FOUND'
-            : error instanceof Error && error.message.includes('Missing required')
-              ? 'VALIDATION_ERROR'
-              : 'UNKNOWN_ERROR';
-
-      ctx.log('error', 'Workflow failed', {
-        operationId,
-        errorType,
-        error: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        input: ctx.data,
-      });
-
-      // Return structured error response
-      return {
-        success: false,
-        operationId,
-        errorType,
-        error: error instanceof Error ? error.message : 'Unknown error occurred',
-        timestamp: new Date().toISOString(),
-      };
-    }
-  }
-);
-```
-
-### Pattern 2: Retry with Exponential Backoff
-
-```typescript
-async function retryWithBackoff<T>(
-  operation: () => Promise<T>,
-  maxAttempts: number = 3,
-  baseDelay: number = 1000,
-  logger: any
-): Promise<T> {
-  let lastError: Error | unknown;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      lastError = error;
-
-      if (attempt < maxAttempts) {
-        const delay = baseDelay * Math.pow(2, attempt - 1); // Exponential backoff
-        logger.warn(`Attempt ${attempt} failed, retrying in ${delay}ms`, {
-          error: error instanceof Error ? error.message : String(error),
-        });
-
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-  }
-
-  throw new Error(`Operation failed after ${maxAttempts} attempts: ${lastError}`);
-}
-
-// Usage
-export const withRetry = http(
-  'with-retry',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const client = await createClient(ctx);
-
-    const result = await retryWithBackoff(
-      async () => {
-        return await client.graphql({
-          query: `query { products(first: 10) { edges { node { id ref } } } }`,
-        });
-      },
-      3,
-      1000,
-      ctx
-    );
-
-    return result.data;
-  }
-);
-```
-
-### Pattern 3: Circuit Breaker
-
-```typescript
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-class CircuitBreaker {
-  private adapter: VersoriKVAdapter;
-  private key: string;
-  private threshold: number;
-  private timeout: number;
-
-  constructor(adapter: VersoriKVAdapter, key: string, threshold = 5, timeout = 60000) {
-    this.adapter = adapter;
-    this.key = `circuit-breaker:${key}`;
-    this.threshold = threshold;
-    this.timeout = timeout;
-  }
-
-  async execute<T>(operation: () => Promise<T>): Promise<T> {
-    const state = (await this.adapter.get<{ failures: number; openedAt?: number }>(this.key)) || {
-      failures: 0,
-    };
-
-    // Check if circuit is open
-    if (state.openedAt) {
-      const elapsed = Date.now() - state.openedAt;
-      if (elapsed < this.timeout) {
-        throw new Error('Circuit breaker is OPEN - service unavailable');
-      }
-      // Timeout elapsed, reset to half-open
-      await this.adapter.set(this.key, { failures: 0 });
-    }
-
-    try {
-      const result = await operation();
-      // Success - reset failures
-      await this.adapter.set(this.key, { failures: 0 });
-      return result;
-    } catch (error) {
-      // Failure - increment counter
-      const newFailures = state.failures + 1;
-
-      if (newFailures >= this.threshold) {
-        // Open circuit
-        await this.adapter.set(this.key, {
-          failures: newFailures,
-          openedAt: Date.now(),
-        });
-        throw new Error(`Circuit breaker OPENED after ${newFailures} failures`);
-      }
-
-      await this.adapter.set(this.key, { failures: newFailures });
-      throw error;
-    }
-  }
-}
-
-// Usage
-export const withCircuitBreaker = http(
-  'with-circuit-breaker',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const adapter = new VersoriKVAdapter(kv);
-    const breaker = new CircuitBreaker(adapter, 'fluent-api', 5, 60000);
-
-    const client = await createClient(ctx);
-
-    try {
-      const result = await breaker.execute(async () => {
-        return await client.graphql({
-          query: `query { products(first: 10) { edges { node { id ref } } } }`,
-        });
-      });
-
-      return { success: true, data: result.data };
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : 'Circuit breaker error',
-      };
-    }
-  }
-);
-```
-
----
-
-## Performance Optimization
-
-### 1. Batch Processing
-
-```typescript
-import { schedule } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Process large datasets in batches for memory efficiency
- */
-export const batchProcessor = schedule(
-  'batch-processor',
-  '0 */6 * * *',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const BATCH_SIZE = 100;
-    let processed = 0;
-    let hasMore = true;
-    let cursor: string | undefined = undefined;
-
-    const client = await createClient(ctx);
-
-    while (hasMore) {
-      // Fetch batch - schema validated
-      const result = await client.graphql({
-        query: `
-        query GetInventoryBatch($first: Int!, $after: String) {
-          inventoryPositions(first: $first, after: $after) {
-            edges {
-              node {
-                id
-                ref
-                productRef
-                locationRef
-                onHand
-              }
-              cursor
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      `,
-        variables: { first: BATCH_SIZE, after: cursor },
-      });
-
-      const items = result.data.inventoryPositions.edges;
-
-      // Process batch
-      await processBatch(items.map(e => e.node));
-
-      processed += items.length;
-      hasMore = result.data.inventoryPositions.pageInfo.hasNextPage;
-      cursor = result.data.inventoryPositions.pageInfo.endCursor;
-
-      ctx.log('info', `Processed batch`, {
-        batchSize: items.length,
-        totalProcessed: processed,
-        hasMore,
-      });
-
-      // Optional: Add small delay to avoid rate limits
-      if (hasMore) {
-        await new Promise(resolve => setTimeout(resolve, 100));
-      }
-    }
-
-    return { totalProcessed: processed };
-  }
-);
-```
-
-### 2. Caching Strategy
-
-```typescript
-import { http } from '@versori/run';
-import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Multi-level caching: memory + KV storage
- */
-const memoryCache = new Map<string, { data: any; expiresAt: number }>();
-
-async function getCached<T>(
-  key: string,
-  fetcher: () => Promise<T>,
-  ttl: number,
-  kvAdapter: VersoriKVAdapter,
-  logger: any
-): Promise<T> {
-  // Level 1: Memory cache (fastest)
-  const memCached = memoryCache.get(key);
-  if (memCached && memCached.expiresAt > Date.now()) {
-    logger.debug('Memory cache hit', { key });
-    return memCached.data as T;
-  }
-
-  // Level 2: KV storage (fast)
-  const kvCached = await kvAdapter.get<T>(key);
-  if (kvCached) {
-    logger.debug('KV cache hit', { key });
-    // Populate memory cache
-    memoryCache.set(key, { data: kvCached, expiresAt: Date.now() + ttl });
-    return kvCached;
-  }
-
-  // Level 3: Fetch from source (slow)
-  logger.debug('Cache miss - fetching from source', { key });
-  const data = await fetcher();
-
-  // Populate both caches
-  memoryCache.set(key, { data, expiresAt: Date.now() + ttl });
-  await kvAdapter.set(key, data, ttl);
-
-  return data;
-}
-
-export const cachedWorkflow = http(
-  'cached-workflow',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const adapter = new VersoriKVAdapter(kv);
-    const client = await createClient(ctx);
-
-    const products = await getCached(
-      'cache:products:list',
-      async () => {
-        const result = await client.graphql({
-          query: `
-          query GetProducts($first: Int!) {
-            products(first: $first) {
-              edges {
-                node {
-                  id
-                  ref
-                  name
-                  status
-                }
-              }
-            }
-          }
-        `,
-          variables: { first: 100 },
-        });
-        return result.data.products.edges.map(e => e.node);
-      },
-      3600000, // 1 hour
-      adapter,
-      ctx
-    );
-
-    return { data: products, cached: true };
-  }
-);
-```
-
-### 3. Parallel Processing
-
-**⚠️ CRITICAL**: When using Versori's `.unpack().parallel()`, remember it's **NOT fault-tolerant**. One failure stops everything. For production workloads, prefer `Promise.allSettled()`.
-
-#### Pattern 1: Promise.all() for Independent Operations
-
-```typescript
-export const parallelProcessor = http(
-  'parallel-processor',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const client = await createClient(ctx);
-
-    // Fetch multiple resources in parallel
-    const [products, orders, inventory] = await Promise.all([
-      client.graphql({
-        query: `query { products(first: 50) { edges { node { id ref } } } }`,
-      }),
-      client.graphql({
-        query: `query { orders(first: 50) { edges { node { id ref } } } }`,
-      }),
-      client.graphql({
-        query: `query { inventoryPositions(first: 50) { edges { node { id ref } } } }`,
-      }),
-    ]);
-
-    return {
-      products: products.data.products.edges.length,
-      orders: orders.data.orders.edges.length,
-      inventory: inventory.data.inventoryPositions.edges.length,
-    };
-  }
-);
-```
-
-#### Pattern 2: Promise.allSettled() for Fault Tolerance (Recommended)
-
-```typescript
-export const faultTolerantProcessor = http(
-  'fault-tolerant-processor',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const client = await createClient(ctx);
-    const files = ['file1.xml', 'file2.xml', 'file3.xml'];
-
-    // ✅ Continues even if some operations fail
-    const results = await Promise.allSettled(
-      files.map(file => processFile(file))
-    );
-
-    const successes = results
-      .filter(r => r.status === 'fulfilled')
-      .map(r => r.value);
-    
-    const failures = results
-      .filter(r => r.status === 'rejected')
-      .map(r => ({ file: r.reason.file, error: r.reason.message }));
-
-    ctx.log('info', 'Processing complete', {
-      successful: successes.length,
-      failed: failures.length,
-    });
-
-    // Handle failures
-    for (const failure of failures) {
-      ctx.log('error', 'File processing failed', failure);
-    }
-
-    return { successes, failures };
-  }
-);
-```
-
-#### Pattern 3: Versori .unpack().parallel() (Use with Caution)
-
-**⚠️ Only use if**:
-- All tasks **must** succeed (transactional)
-- You wrap each task with error handling that returns error objects instead of throwing
-- You're okay with losing all results on any failure
-
-```typescript
-// ✅ Safe usage: Handle errors inside each task
-schedule('process-files', '0 2 * * *')
-  .then(fn('fetch-files', (ctx) => ['file1.xml', 'file2.xml', 'file3.xml']))
-  .unpack()
-  .parallel(fn('process-file', async (ctx) => {
-    try {
-      const result = await processFile(ctx.data);
-      return { success: true, file: ctx.data, result };
-    } catch (error) {
-      // ✅ Return error object instead of throwing
-      return { 
-        success: false, 
-        file: ctx.data, 
-        error: error.message 
-      };
-    }
-  }))
-  .then(fn('process-results', (ctx) => {
-    // ✅ Now you have all results (success + failures)
-    const results = ctx.data;
-    const successes = results.filter(r => r.success);
-    const failures = results.filter(r => !r.success);
-    
-    ctx.log.info(`Processed ${successes.length} files, ${failures.length} failed`);
-    return { successes, failures };
-  }));
-```
-
-**See**: [Module 4: Workflows - Parallel Processing](./platforms-versori-04-workflows.md#-critical-parallel-processing-with-unpack-and-parallel) for detailed guidance.
-
----
-
-## Security Hardening
-
-### 1. Input Validation
-
-```typescript
-import { webhook } from '@versori/run';
-
-// Validation schemas
-const orderSchema = {
-  orderId: { type: 'string', required: true, pattern: /^ORD-\d{6}$/ },
-  customerId: { type: 'string', required: true },
-  items: { type: 'array', required: true, minLength: 1 },
-  totalPrice: { type: 'number', required: true, min: 0 },
-};
-
-function validateInput(data: any, schema: any): { valid: boolean; errors: string[] } {
-  const errors: string[] = [];
-
-  for (const [field, rules] of Object.entries(schema)) {
-    const value = data[field];
-
-    // Required check
-    if (rules.required && (value === undefined || value === null)) {
-      errors.push(`Missing required field: ${field}`);
-      continue;
-    }
-
-    // Type check
-    if (value !== undefined && rules.type) {
-      const actualType = Array.isArray(value) ? 'array' : typeof value;
-      if (actualType !== rules.type) {
-        errors.push(`Invalid type for ${field}: expected ${rules.type}, got ${actualType}`);
-      }
-    }
-
-    // Pattern check
-    if (value && rules.pattern && !rules.pattern.test(value)) {
-      errors.push(`Invalid format for ${field}`);
-    }
-
-    // Min/max checks
-    if (typeof value === 'number') {
-      if (rules.min !== undefined && value < rules.min) {
-        errors.push(`${field} must be >= ${rules.min}`);
-      }
-      if (rules.max !== undefined && value > rules.max) {
-        errors.push(`${field} must be <= ${rules.max}`);
-      }
-    }
-
-    // Array length checks
-    if (Array.isArray(value)) {
-      if (rules.minLength !== undefined && value.length < rules.minLength) {
-        errors.push(`${field} must have at least ${rules.minLength} items`);
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-export const validatedWebhook = webhook('validated-webhook', async ctx => {
-  // Validate input
-  const validation = validateInput(ctx.data, orderSchema);
-
-  if (!validation.valid) {
-    ctx.log('warn', 'Validation failed', { errors: validation.errors });
-    return {
-      success: false,
-      errors: validation.errors,
-      status: 400,
-    };
-  }
-
-  // Process validated data
-  ctx.log('info', 'Order validated successfully', { orderId: ctx.data.orderId });
-
-  return { success: true, orderId: ctx.data.orderId };
-});
-```
-
-### 2. Rate Limiting
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-async function checkRateLimit(
-  adapter: VersoriKVAdapter,
-  identifier: string,
-  maxRequests: number,
-  windowMs: number
-): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
-  const key = `ratelimit:${identifier}`;
-  const now = Date.now();
-
-  // Get current count
-  const current = await adapter.get<{ count: number; resetAt: number }>(key);
-
-  if (!current) {
-    // First request
-    const resetAt = now + windowMs;
-    await adapter.set(key, { count: 1, resetAt }, windowMs);
-    return { allowed: true, remaining: maxRequests - 1, resetAt };
-  }
-
-  if (now > current.resetAt) {
-    // Window expired, reset
-    const resetAt = now + windowMs;
-    await adapter.set(key, { count: 1, resetAt }, windowMs);
-    return { allowed: true, remaining: maxRequests - 1, resetAt };
-  }
-
-  if (current.count >= maxRequests) {
-    // Rate limit exceeded
-    return { allowed: false, remaining: 0, resetAt: current.resetAt };
-  }
-
-  // Increment count
-  await adapter.set(key, { count: current.count + 1, resetAt: current.resetAt }, windowMs);
-  return { allowed: true, remaining: maxRequests - current.count - 1, resetAt: current.resetAt };
-}
-
-export const rateLimitedEndpoint = http(
-  'rate-limited',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const adapter = new VersoriKVAdapter(kv);
-
-    const clientId = ctx.query?.clientId || 'anonymous';
-    const rateLimit = await checkRateLimit(adapter, clientId, 100, 3600000); // 100 req/hour
-
-    if (!rateLimit.allowed) {
-      const retryAfter = Math.ceil((rateLimit.resetAt - Date.now()) / 1000);
-      ctx.log('warn', 'Rate limit exceeded', { clientId, retryAfter });
-
-      return {
-        error: 'Rate limit exceeded',
-        retryAfter,
-        resetAt: new Date(rateLimit.resetAt).toISOString(),
-        status: 429,
-      };
-    }
-
-    // Process request
-    const client = await createClient(ctx);
-    const result = await client.graphql({
-      query: `query { products(first: 10) { edges { node { id ref } } } }`,
-    });
-
-    return {
-      data: result.data,
-      rateLimit: {
-        remaining: rateLimit.remaining,
-        resetAt: new Date(rateLimit.resetAt).toISOString(),
-      },
-    };
-  }
-);
-```
-
-### 3. Secrets Management
-
-```typescript
-// ❌ NEVER do this
-const BAD_EXAMPLE = {
-  clientId: 'my-client-id',
-  clientSecret: 'my-secret', // NEVER hardcode secrets!
-};
-
-// ✅ Use connector variables
-export const secureWorkflow = http(
-  'secure',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    // Access secrets from connector variables
-    const webhookKey = ctx.vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
-    const apiKey = ctx.vars?.THIRD_PARTY_API_KEY;
-
-    // Validate secrets exist
-    if (!webhookKey || !apiKey) {
-      ctx.log('error', 'Missing required secrets');
-      return { error: 'Configuration error', status: 500 };
-    }
-
-    // Use secrets securely (don't log them)
-    ctx.log('info', 'Secrets loaded', {
-      hasWebhookKey: !!webhookKey,
-      hasApiKey: !!apiKey,
-    });
-
-    // ... use secrets
-  }
-);
-```
-
----
-
-## Cost Optimization
-
-### 1. Minimize KV Operations
-
-```typescript
-// ❌ Expensive - sequential writes without atomicity
-for (const item of items) {
-  await kv.set(`item:${item.id}`, item); // N sequential operations
-}
-
-// ✅ Optimized - use atomic operations for batch writes
-// Note: VersoriKVAdapter doesn't have mset() method - use atomic() instead
-const adapter = new VersoriKVAdapter(kv);
-const atomic = adapter.atomic();
-for (const item of items) {
-  atomic.set(['item', item.id], item);
-}
-await atomic.commit(); // 1 atomic transaction - all succeed or all fail
-```
-
-### 2. Optimize Cron Schedules
-
-```typescript
-// ❌ Too frequent - runs every minute (1440 times/day)
-schedule('too-frequent', '* * * * *', handler);
-
-// ✅ Optimized - runs every 6 hours (4 times/day)
-schedule('optimized', '0 */6 * * *', handler);
-
-// ❌ Overlapping schedules
-schedule('sync-1', '0 * * * *', syncHandler); // Every hour
-schedule('sync-2', '30 * * * *', syncHandler); // Every hour at :30
-
-// ✅ Consolidated schedule
-schedule('unified-sync', '0 */2 * * *', async ctx => {
-  await syncHandler(ctx);
-  // Do both operations in one run
-});
-```
-
-### 3. Cache Expensive Operations
-
-```typescript
-export const costOptimized = http(
-  'cost-optimized',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const adapter = new VersoriKVAdapter(kv);
-
-    // Check cache first
-    const cacheKey = 'expensive:operation:result';
-    const cached = await adapter.get(cacheKey);
-
-    if (cached) {
-      ctx.log('info', 'Returning cached result');
-      return { data: cached, source: 'cache' };
-    }
-
-    // Expensive operation
-    const client = await createClient(ctx);
-    const result = await client.graphql({
-      query: `... complex query ...`,
-    });
-
-    // Cache for 1 hour
-    await adapter.set(cacheKey, result.data, 3600000);
-
-    return { data: result.data, source: 'api' };
-  }
-);
-```
-
----
-
-## Monitoring & Alerting
-
-### Critical Metrics Tracking
-
-```typescript
-import { schedule } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const metricsCollector = schedule('metrics-collector', '*/5 * * * *', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  // Note: VersoriKVAdapter doesn't have keys() method - use native Versori KV list() instead
-  const allKeys = await kv.list();
-  const processedFileKeys = await kv.list({ prefix: 'files:processed:' });
-
-  // Collect metrics
-  const metrics = {
-    timestamp: Date.now(),
-    workflows: {
-      totalExecutions: (await adapter.get(['metrics', 'total', 'executions'])) || 0,
-      failedExecutions: (await adapter.get(['metrics', 'failed', 'executions'])) || 0,
-      avgDuration: (await adapter.get(['metrics', 'avg', 'duration'])) || 0,
-    },
-    storage: {
-      kvKeys: allKeys.length,
-      processedFiles: processedFileKeys.length,
-    },
-    health: {
-      lastHealthCheck: await adapter.get(['health', 'last', 'check']),
-      fluentApiStatus: await adapter.get(['health', 'fluent', 'status']),
-    },
-  };
-
-  // Calculate derived metrics
-  const successRate =
-    metrics.workflows.totalExecutions > 0
-      ? (1 - metrics.workflows.failedExecutions / metrics.workflows.totalExecutions) * 100
-      : 100;
-
-  // Store metrics history
-  const metricsHistory = (await adapter.get(['metrics', 'history'])) || [];
-  metricsHistory.push({ ...metrics, successRate });
-
-  // Keep last 288 entries (24 hours at 5-minute intervals)
-  if (metricsHistory.length > 288) {
-    metricsHistory.shift();
-  }
-
-  await adapter.set(['metrics', 'history'], metricsHistory);
-
-  // Alert on critical thresholds
-  if (successRate < 95) {
-    ctx.log('error', 'ALERT: Success rate below threshold', {
-      successRate: successRate.toFixed(2),
-      threshold: 95,
-    });
-  }
-
-  if (metrics.workflows.avgDuration > 10000) {
-    ctx.log('warn', 'ALERT: Average duration above threshold', {
-      avgDuration: metrics.workflows.avgDuration,
-      threshold: 10000,
-    });
-  }
-
-  ctx.log('info', 'Metrics collected', {
-    successRate: successRate.toFixed(2),
-    avgDuration: metrics.workflows.avgDuration,
-  });
-
-  return metrics;
-});
-```
-
----
-
-## Troubleshooting Guide
-
-### Common Issues & Solutions
-
-#### Issue 1: "No authentication credentials found"
-
-**Symptoms**: Error when calling Fluent API
-
-**Cause**: Using `fn()` instead of `http()` for external API calls
-
-**Solution**:
-
-```typescript
-// ❌ Wrong
-export const bad = fn('bad', async ctx => {
-  const client = await createClient(ctx); // FAILS - no ctx.fetch
-});
-
-// ✅ Correct
-export const good = http(
-  'good',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const client = await createClient(ctx); // Works
-  }
-);
-```
-
-#### Issue 2: Duplicate File Processing
-
-**Symptoms**: Same file processed multiple times
-
-**Cause**: Missing or incorrect file tracking
-
-**Solution**:
-
-```typescript
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-const kv = ctx.openKv(':project:');
-const tracker = new VersoriFileTracker(kv, 'namespace');
-
-// Check before processing
-if (await tracker.wasFileProcessed(fileName)) {
-  return { skipped: true };
-}
-
-// Process file...
-
-// Mark as processed
-await tracker.markFileProcessed(fileName, { records: count });
-```
-
-#### Issue 3: Memory Errors with Large Datasets
-
-**Symptoms**: Out of memory errors
-
-**Cause**: Loading entire dataset into memory
-
-**Solution**:
-
-```typescript
-// ❌ Wrong - loads everything
-const allData = await fetchAllData();
-await processData(allData);
-
-// ✅ Correct - batch processing
-const BATCH_SIZE = 100;
-let cursor = undefined;
-let hasMore = true;
-
-while (hasMore) {
-  const batch = await fetchBatch(BATCH_SIZE, cursor);
-  await processBatch(batch);
-  hasMore = batch.pageInfo.hasNextPage;
-  cursor = batch.pageInfo.endCursor;
-}
-```
-
----
-
-## Practice Solutions
-
-### Module 2: Quick Start Exercise Solution
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Create inventory position
- * POST https://{workspace}.versori.run/create-inventory
- * Body: { productRef, locationRef, qty }
- */
-export const createInventoryPosition = http(
-  'create-inventory',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    ctx.log('info', 'Creating inventory position');
-
-    const { productRef, locationRef, qty } = ctx.data || {};
-
-    // Validation
-    if (!productRef || !locationRef || qty === undefined) {
-      return {
-        success: false,
-        error: 'Missing required fields: productRef, locationRef, qty',
-      };
-    }
-
-    try {
-      const client = await createClient(ctx);
-
-      const result = await client.graphql({
-        query: `
-        mutation CreateInventory($input: CreateInventoryPositionInput!) {
-          createInventoryPosition(input: $input) {
-            id
-            ref
-            productRef
-            locationRef
-            onHand
-          }
-        }
-      `,
-        variables: {
-          input: { productRef, locationRef, qty },
-        },
-      });
-
-      if (result.errors?.length) {
-        throw new Error(result.errors[0].message);
-      }
-
-      ctx.log('info', 'Inventory position created', {
-        id: result.data.createInventoryPosition.id,
-      });
-
-      return {
-        success: true,
-        data: result.data.createInventoryPosition,
-      };
-    } catch (error) {
-      ctx.log('error', 'Failed to create inventory position', {
-        error: error instanceof Error ? error.message : String(error),
-      });
-
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : 'Creation failed',
-      };
-    }
-  }
-);
-```
-
----
-
-## Key Takeaways
-
-- 🎯 **Error handling** with comprehensive try-catch, retry, and circuit breaker patterns
-- 🎯 **Performance** via batching, caching, and parallel processing
-- 🎯 **Security** through input validation, rate limiting, and secrets management
-- 🎯 **Cost optimization** by minimizing KV ops, optimizing schedules, and caching
-- 🎯 **Monitoring** with metrics tracking and alerting on critical thresholds
-- 🎯 **Troubleshooting** using structured debugging and common issue patterns
-
----
-
-## Conclusion
-
-You've completed the Versori Platform Integration Guide! You now have:
-
-- ✅ Understanding of Versori platform architecture
-- ✅ Ability to create all workflow types (http, webhook, schedule, fn)
-- ✅ Connection management expertise
-- ✅ KV storage and state management skills
-- ✅ Deployment and CI/CD knowledge
-- ✅ Production-ready patterns and best practices
-
-### Next Steps
-
-1. **Build Your Integration**: Apply these patterns to your specific use case
-2. **Review Examples**: Study the connector examples in `connectors/` directory
-3. **Consult SDK Guides**: Deep dive into specific SDK features
-4. **Join Community**: Engage with other developers using Versori
-
-### Additional Resources
-
-- [Versori Platform Documentation](https://docs.versori.com)
-- [FC Connect SDK API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md)
-- [Sample Connectors](../../../../01-TEMPLATES/versori/workflows/readme.md) - Production connector examples
-- [Webhook Response Patterns](.././modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
-
----
-
-[← Previous: Module 7](./platforms-versori-07-deployment.md) | [Back to Guide](../platforms-versori-readme.md)
+# Module 8: Best Practices & Production Patterns
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 8 of 8** | **Level**: Advanced | **Time**: 30 minutes
+
+---
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- ✅ Implement production-ready error handling patterns
+- ✅ Optimize workflow performance and reduce costs
+- ✅ Apply security hardening best practices
+- ✅ Implement robust retry and fallback strategies
+- ✅ Troubleshoot common production issues
+- ✅ Monitor and alert on critical metrics
+- ✅ Apply cost optimization techniques
+
+---
+
+## Production-Ready Error Handling
+
+### Pattern 1: Comprehensive Try-Catch with Context
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const robustWorkflow = http(
+  'robust-workflow',
+  {
+    connection: 'fluent_commerce',
+    retry: {
+      attempts: 3,
+      delay: 1000,
+      backoff: 2, // Exponential backoff
+    },
+    timeout: 30000,
+  },
+  async ctx => {
+    const operationId = `${ctx.executionId}-${Date.now()}`;
+
+    ctx.log('info', 'Workflow started', {
+      operationId,
+      executionId: ctx.executionId,
+      timestamp: new Date().toISOString(),
+    });
+
+    try {
+      const client = await createClient(ctx);
+
+      // Validate input
+      if (!ctx.data?.orderId) {
+        throw new Error('Missing required field: orderId');
+      }
+
+      // GraphQL query - schema validated
+      const result = await client.graphql({
+        query: `
+        query GetOrder($ref: String!) {
+          order(ref: $ref) {
+            id
+            ref
+            status
+            totalPrice
+          }
+        }
+      `,
+        variables: { ref: ctx.data.orderId },
+      });
+
+      // Check GraphQL errors
+      if (result.errors?.length) {
+        throw new Error(`GraphQL error: ${result.errors[0].message}`);
+      }
+
+      // Check data exists
+      if (!result.data?.order) {
+        throw new Error(`Order not found: ${ctx.data.orderId}`);
+      }
+
+      ctx.log('info', 'Workflow completed successfully', {
+        operationId,
+        orderId: ctx.data.orderId,
+        orderStatus: result.data.order.status,
+      });
+
+      return {
+        success: true,
+        operationId,
+        data: result.data.order,
+      };
+    } catch (error) {
+      // Categorize error
+      const errorType =
+        error instanceof Error && error.message.includes('GraphQL')
+          ? 'GRAPHQL_ERROR'
+          : error instanceof Error && error.message.includes('not found')
+            ? 'NOT_FOUND'
+            : error instanceof Error && error.message.includes('Missing required')
+              ? 'VALIDATION_ERROR'
+              : 'UNKNOWN_ERROR';
+
+      ctx.log('error', 'Workflow failed', {
+        operationId,
+        errorType,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        input: ctx.data,
+      });
+
+      // Return structured error response
+      return {
+        success: false,
+        operationId,
+        errorType,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+        timestamp: new Date().toISOString(),
+      };
+    }
+  }
+);
+```
+
+### Pattern 2: Retry with Exponential Backoff
+
+```typescript
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  maxAttempts: number = 3,
+  baseDelay: number = 1000,
+  logger: any
+): Promise<T> {
+  let lastError: Error | unknown;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt < maxAttempts) {
+        const delay = baseDelay * Math.pow(2, attempt - 1); // Exponential backoff
+        logger.warn(`Attempt ${attempt} failed, retrying in ${delay}ms`, {
+          error: error instanceof Error ? error.message : String(error),
+        });
+
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw new Error(`Operation failed after ${maxAttempts} attempts: ${lastError}`);
+}
+
+// Usage
+export const withRetry = http(
+  'with-retry',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const client = await createClient(ctx);
+
+    const result = await retryWithBackoff(
+      async () => {
+        return await client.graphql({
+          query: `query { products(first: 10) { edges { node { id ref } } } }`,
+        });
+      },
+      3,
+      1000,
+      ctx
+    );
+
+    return result.data;
+  }
+);
+```
+
+### Pattern 3: Circuit Breaker
+
+```typescript
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+class CircuitBreaker {
+  private adapter: VersoriKVAdapter;
+  private key: string;
+  private threshold: number;
+  private timeout: number;
+
+  constructor(adapter: VersoriKVAdapter, key: string, threshold = 5, timeout = 60000) {
+    this.adapter = adapter;
+    this.key = `circuit-breaker:${key}`;
+    this.threshold = threshold;
+    this.timeout = timeout;
+  }
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    const state = (await this.adapter.get<{ failures: number; openedAt?: number }>(this.key)) || {
+      failures: 0,
+    };
+
+    // Check if circuit is open
+    if (state.openedAt) {
+      const elapsed = Date.now() - state.openedAt;
+      if (elapsed < this.timeout) {
+        throw new Error('Circuit breaker is OPEN - service unavailable');
+      }
+      // Timeout elapsed, reset to half-open
+      await this.adapter.set(this.key, { failures: 0 });
+    }
+
+    try {
+      const result = await operation();
+      // Success - reset failures
+      await this.adapter.set(this.key, { failures: 0 });
+      return result;
+    } catch (error) {
+      // Failure - increment counter
+      const newFailures = state.failures + 1;
+
+      if (newFailures >= this.threshold) {
+        // Open circuit
+        await this.adapter.set(this.key, {
+          failures: newFailures,
+          openedAt: Date.now(),
+        });
+        throw new Error(`Circuit breaker OPENED after ${newFailures} failures`);
+      }
+
+      await this.adapter.set(this.key, { failures: newFailures });
+      throw error;
+    }
+  }
+}
+
+// Usage
+export const withCircuitBreaker = http(
+  'with-circuit-breaker',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const adapter = new VersoriKVAdapter(kv);
+    const breaker = new CircuitBreaker(adapter, 'fluent-api', 5, 60000);
+
+    const client = await createClient(ctx);
+
+    try {
+      const result = await breaker.execute(async () => {
+        return await client.graphql({
+          query: `query { products(first: 10) { edges { node { id ref } } } }`,
+        });
+      });
+
+      return { success: true, data: result.data };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Circuit breaker error',
+      };
+    }
+  }
+);
+```
+
+---
+
+## Performance Optimization
+
+### 1. Batch Processing
+
+```typescript
+import { schedule } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Process large datasets in batches for memory efficiency
+ */
+export const batchProcessor = schedule(
+  'batch-processor',
+  '0 */6 * * *',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const BATCH_SIZE = 100;
+    let processed = 0;
+    let hasMore = true;
+    let cursor: string | undefined = undefined;
+
+    const client = await createClient(ctx);
+
+    while (hasMore) {
+      // Fetch batch - schema validated
+      const result = await client.graphql({
+        query: `
+        query GetInventoryBatch($first: Int!, $after: String) {
+          inventoryPositions(first: $first, after: $after) {
+            edges {
+              node {
+                id
+                ref
+                productRef
+                locationRef
+                onHand
+              }
+              cursor
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      `,
+        variables: { first: BATCH_SIZE, after: cursor },
+      });
+
+      const items = result.data.inventoryPositions.edges;
+
+      // Process batch
+      await processBatch(items.map(e => e.node));
+
+      processed += items.length;
+      hasMore = result.data.inventoryPositions.pageInfo.hasNextPage;
+      cursor = result.data.inventoryPositions.pageInfo.endCursor;
+
+      ctx.log('info', `Processed batch`, {
+        batchSize: items.length,
+        totalProcessed: processed,
+        hasMore,
+      });
+
+      // Optional: Add small delay to avoid rate limits
+      if (hasMore) {
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+    }
+
+    return { totalProcessed: processed };
+  }
+);
+```
+
+### 2. Caching Strategy
+
+```typescript
+import { http } from '@versori/run';
+import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Multi-level caching: memory + KV storage
+ */
+const memoryCache = new Map<string, { data: any; expiresAt: number }>();
+
+async function getCached<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+  ttl: number,
+  kvAdapter: VersoriKVAdapter,
+  logger: any
+): Promise<T> {
+  // Level 1: Memory cache (fastest)
+  const memCached = memoryCache.get(key);
+  if (memCached && memCached.expiresAt > Date.now()) {
+    logger.debug('Memory cache hit', { key });
+    return memCached.data as T;
+  }
+
+  // Level 2: KV storage (fast)
+  const kvCached = await kvAdapter.get<T>(key);
+  if (kvCached) {
+    logger.debug('KV cache hit', { key });
+    // Populate memory cache
+    memoryCache.set(key, { data: kvCached, expiresAt: Date.now() + ttl });
+    return kvCached;
+  }
+
+  // Level 3: Fetch from source (slow)
+  logger.debug('Cache miss - fetching from source', { key });
+  const data = await fetcher();
+
+  // Populate both caches
+  memoryCache.set(key, { data, expiresAt: Date.now() + ttl });
+  await kvAdapter.set(key, data, ttl);
+
+  return data;
+}
+
+export const cachedWorkflow = http(
+  'cached-workflow',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const adapter = new VersoriKVAdapter(kv);
+    const client = await createClient(ctx);
+
+    const products = await getCached(
+      'cache:products:list',
+      async () => {
+        const result = await client.graphql({
+          query: `
+          query GetProducts($first: Int!) {
+            products(first: $first) {
+              edges {
+                node {
+                  id
+                  ref
+                  name
+                  status
+                }
+              }
+            }
+          }
+        `,
+          variables: { first: 100 },
+        });
+        return result.data.products.edges.map(e => e.node);
+      },
+      3600000, // 1 hour
+      adapter,
+      ctx
+    );
+
+    return { data: products, cached: true };
+  }
+);
+```
+
+### 3. Parallel Processing
+
+**⚠️ CRITICAL**: When using Versori's `.unpack().parallel()`, remember it's **NOT fault-tolerant**. One failure stops everything. For production workloads, prefer `Promise.allSettled()`.
+
+#### Pattern 1: Promise.all() for Independent Operations
+
+```typescript
+export const parallelProcessor = http(
+  'parallel-processor',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const client = await createClient(ctx);
+
+    // Fetch multiple resources in parallel
+    const [products, orders, inventory] = await Promise.all([
+      client.graphql({
+        query: `query { products(first: 50) { edges { node { id ref } } } }`,
+      }),
+      client.graphql({
+        query: `query { orders(first: 50) { edges { node { id ref } } } }`,
+      }),
+      client.graphql({
+        query: `query { inventoryPositions(first: 50) { edges { node { id ref } } } }`,
+      }),
+    ]);
+
+    return {
+      products: products.data.products.edges.length,
+      orders: orders.data.orders.edges.length,
+      inventory: inventory.data.inventoryPositions.edges.length,
+    };
+  }
+);
+```
+
+#### Pattern 2: Promise.allSettled() for Fault Tolerance (Recommended)
+
+```typescript
+export const faultTolerantProcessor = http(
+  'fault-tolerant-processor',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const client = await createClient(ctx);
+    const files = ['file1.xml', 'file2.xml', 'file3.xml'];
+
+    // ✅ Continues even if some operations fail
+    const results = await Promise.allSettled(
+      files.map(file => processFile(file))
+    );
+
+    const successes = results
+      .filter(r => r.status === 'fulfilled')
+      .map(r => r.value);
+    
+    const failures = results
+      .filter(r => r.status === 'rejected')
+      .map(r => ({ file: r.reason.file, error: r.reason.message }));
+
+    ctx.log('info', 'Processing complete', {
+      successful: successes.length,
+      failed: failures.length,
+    });
+
+    // Handle failures
+    for (const failure of failures) {
+      ctx.log('error', 'File processing failed', failure);
+    }
+
+    return { successes, failures };
+  }
+);
+```
+
+#### Pattern 3: Versori .unpack().parallel() (Use with Caution)
+
+**⚠️ Only use if**:
+- All tasks **must** succeed (transactional)
+- You wrap each task with error handling that returns error objects instead of throwing
+- You're okay with losing all results on any failure
+
+```typescript
+// ✅ Safe usage: Handle errors inside each task
+schedule('process-files', '0 2 * * *')
+  .then(fn('fetch-files', (ctx) => ['file1.xml', 'file2.xml', 'file3.xml']))
+  .unpack()
+  .parallel(fn('process-file', async (ctx) => {
+    try {
+      const result = await processFile(ctx.data);
+      return { success: true, file: ctx.data, result };
+    } catch (error) {
+      // ✅ Return error object instead of throwing
+      return { 
+        success: false, 
+        file: ctx.data, 
+        error: error.message 
+      };
+    }
+  }))
+  .then(fn('process-results', (ctx) => {
+    // ✅ Now you have all results (success + failures)
+    const results = ctx.data;
+    const successes = results.filter(r => r.success);
+    const failures = results.filter(r => !r.success);
+    
+    ctx.log.info(`Processed ${successes.length} files, ${failures.length} failed`);
+    return { successes, failures };
+  }));
+```
+
+**See**: [Module 4: Workflows - Parallel Processing](./platforms-versori-04-workflows.md#-critical-parallel-processing-with-unpack-and-parallel) for detailed guidance.
+
+---
+
+## Security Hardening
+
+### 1. Input Validation
+
+```typescript
+import { webhook } from '@versori/run';
+
+// Validation schemas
+const orderSchema = {
+  orderId: { type: 'string', required: true, pattern: /^ORD-\d{6}$/ },
+  customerId: { type: 'string', required: true },
+  items: { type: 'array', required: true, minLength: 1 },
+  totalPrice: { type: 'number', required: true, min: 0 },
+};
+
+function validateInput(data: any, schema: any): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  for (const [field, rules] of Object.entries(schema)) {
+    const value = data[field];
+
+    // Required check
+    if (rules.required && (value === undefined || value === null)) {
+      errors.push(`Missing required field: ${field}`);
+      continue;
+    }
+
+    // Type check
+    if (value !== undefined && rules.type) {
+      const actualType = Array.isArray(value) ? 'array' : typeof value;
+      if (actualType !== rules.type) {
+        errors.push(`Invalid type for ${field}: expected ${rules.type}, got ${actualType}`);
+      }
+    }
+
+    // Pattern check
+    if (value && rules.pattern && !rules.pattern.test(value)) {
+      errors.push(`Invalid format for ${field}`);
+    }
+
+    // Min/max checks
+    if (typeof value === 'number') {
+      if (rules.min !== undefined && value < rules.min) {
+        errors.push(`${field} must be >= ${rules.min}`);
+      }
+      if (rules.max !== undefined && value > rules.max) {
+        errors.push(`${field} must be <= ${rules.max}`);
+      }
+    }
+
+    // Array length checks
+    if (Array.isArray(value)) {
+      if (rules.minLength !== undefined && value.length < rules.minLength) {
+        errors.push(`${field} must have at least ${rules.minLength} items`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export const validatedWebhook = webhook('validated-webhook', async ctx => {
+  // Validate input
+  const validation = validateInput(ctx.data, orderSchema);
+
+  if (!validation.valid) {
+    ctx.log('warn', 'Validation failed', { errors: validation.errors });
+    return {
+      success: false,
+      errors: validation.errors,
+      status: 400,
+    };
+  }
+
+  // Process validated data
+  ctx.log('info', 'Order validated successfully', { orderId: ctx.data.orderId });
+
+  return { success: true, orderId: ctx.data.orderId };
+});
+```
+
+### 2. Rate Limiting
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+async function checkRateLimit(
+  adapter: VersoriKVAdapter,
+  identifier: string,
+  maxRequests: number,
+  windowMs: number
+): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
+  const key = `ratelimit:${identifier}`;
+  const now = Date.now();
+
+  // Get current count
+  const current = await adapter.get<{ count: number; resetAt: number }>(key);
+
+  if (!current) {
+    // First request
+    const resetAt = now + windowMs;
+    await adapter.set(key, { count: 1, resetAt }, windowMs);
+    return { allowed: true, remaining: maxRequests - 1, resetAt };
+  }
+
+  if (now > current.resetAt) {
+    // Window expired, reset
+    const resetAt = now + windowMs;
+    await adapter.set(key, { count: 1, resetAt }, windowMs);
+    return { allowed: true, remaining: maxRequests - 1, resetAt };
+  }
+
+  if (current.count >= maxRequests) {
+    // Rate limit exceeded
+    return { allowed: false, remaining: 0, resetAt: current.resetAt };
+  }
+
+  // Increment count
+  await adapter.set(key, { count: current.count + 1, resetAt: current.resetAt }, windowMs);
+  return { allowed: true, remaining: maxRequests - current.count - 1, resetAt: current.resetAt };
+}
+
+export const rateLimitedEndpoint = http(
+  'rate-limited',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const adapter = new VersoriKVAdapter(kv);
+
+    const clientId = ctx.query?.clientId || 'anonymous';
+    const rateLimit = await checkRateLimit(adapter, clientId, 100, 3600000); // 100 req/hour
+
+    if (!rateLimit.allowed) {
+      const retryAfter = Math.ceil((rateLimit.resetAt - Date.now()) / 1000);
+      ctx.log('warn', 'Rate limit exceeded', { clientId, retryAfter });
+
+      return {
+        error: 'Rate limit exceeded',
+        retryAfter,
+        resetAt: new Date(rateLimit.resetAt).toISOString(),
+        status: 429,
+      };
+    }
+
+    // Process request
+    const client = await createClient(ctx);
+    const result = await client.graphql({
+      query: `query { products(first: 10) { edges { node { id ref } } } }`,
+    });
+
+    return {
+      data: result.data,
+      rateLimit: {
+        remaining: rateLimit.remaining,
+        resetAt: new Date(rateLimit.resetAt).toISOString(),
+      },
+    };
+  }
+);
+```
+
+### 3. Secrets Management
+
+```typescript
+// ❌ NEVER do this
+const BAD_EXAMPLE = {
+  clientId: 'my-client-id',
+  clientSecret: 'my-secret', // NEVER hardcode secrets!
+};
+
+// ✅ Use connector variables
+export const secureWorkflow = http(
+  'secure',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    // Access secrets from connector variables
+    const webhookKey = ctx.vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
+    const apiKey = ctx.vars?.THIRD_PARTY_API_KEY;
+
+    // Validate secrets exist
+    if (!webhookKey || !apiKey) {
+      ctx.log('error', 'Missing required secrets');
+      return { error: 'Configuration error', status: 500 };
+    }
+
+    // Use secrets securely (don't log them)
+    ctx.log('info', 'Secrets loaded', {
+      hasWebhookKey: !!webhookKey,
+      hasApiKey: !!apiKey,
+    });
+
+    // ... use secrets
+  }
+);
+```
+
+---
+
+## Cost Optimization
+
+### 1. Minimize KV Operations
+
+```typescript
+// ❌ Expensive - sequential writes without atomicity
+for (const item of items) {
+  await kv.set(`item:${item.id}`, item); // N sequential operations
+}
+
+// ✅ Optimized - use atomic operations for batch writes
+// Note: VersoriKVAdapter doesn't have mset() method - use atomic() instead
+const adapter = new VersoriKVAdapter(kv);
+const atomic = adapter.atomic();
+for (const item of items) {
+  atomic.set(['item', item.id], item);
+}
+await atomic.commit(); // 1 atomic transaction - all succeed or all fail
+```
+
+### 2. Optimize Cron Schedules
+
+```typescript
+// ❌ Too frequent - runs every minute (1440 times/day)
+schedule('too-frequent', '* * * * *', handler);
+
+// ✅ Optimized - runs every 6 hours (4 times/day)
+schedule('optimized', '0 */6 * * *', handler);
+
+// ❌ Overlapping schedules
+schedule('sync-1', '0 * * * *', syncHandler); // Every hour
+schedule('sync-2', '30 * * * *', syncHandler); // Every hour at :30
+
+// ✅ Consolidated schedule
+schedule('unified-sync', '0 */2 * * *', async ctx => {
+  await syncHandler(ctx);
+  // Do both operations in one run
+});
+```
+
+### 3. Cache Expensive Operations
+
+```typescript
+export const costOptimized = http(
+  'cost-optimized',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const adapter = new VersoriKVAdapter(kv);
+
+    // Check cache first
+    const cacheKey = 'expensive:operation:result';
+    const cached = await adapter.get(cacheKey);
+
+    if (cached) {
+      ctx.log('info', 'Returning cached result');
+      return { data: cached, source: 'cache' };
+    }
+
+    // Expensive operation
+    const client = await createClient(ctx);
+    const result = await client.graphql({
+      query: `... complex query ...`,
+    });
+
+    // Cache for 1 hour
+    await adapter.set(cacheKey, result.data, 3600000);
+
+    return { data: result.data, source: 'api' };
+  }
+);
+```
+
+---
+
+## Monitoring & Alerting
+
+### Critical Metrics Tracking
+
+```typescript
+import { schedule } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const metricsCollector = schedule('metrics-collector', '*/5 * * * *', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  // Note: VersoriKVAdapter doesn't have keys() method - use native Versori KV list() instead
+  const allKeys = await kv.list();
+  const processedFileKeys = await kv.list({ prefix: 'files:processed:' });
+
+  // Collect metrics
+  const metrics = {
+    timestamp: Date.now(),
+    workflows: {
+      totalExecutions: (await adapter.get(['metrics', 'total', 'executions'])) || 0,
+      failedExecutions: (await adapter.get(['metrics', 'failed', 'executions'])) || 0,
+      avgDuration: (await adapter.get(['metrics', 'avg', 'duration'])) || 0,
+    },
+    storage: {
+      kvKeys: allKeys.length,
+      processedFiles: processedFileKeys.length,
+    },
+    health: {
+      lastHealthCheck: await adapter.get(['health', 'last', 'check']),
+      fluentApiStatus: await adapter.get(['health', 'fluent', 'status']),
+    },
+  };
+
+  // Calculate derived metrics
+  const successRate =
+    metrics.workflows.totalExecutions > 0
+      ? (1 - metrics.workflows.failedExecutions / metrics.workflows.totalExecutions) * 100
+      : 100;
+
+  // Store metrics history
+  const metricsHistory = (await adapter.get(['metrics', 'history'])) || [];
+  metricsHistory.push({ ...metrics, successRate });
+
+  // Keep last 288 entries (24 hours at 5-minute intervals)
+  if (metricsHistory.length > 288) {
+    metricsHistory.shift();
+  }
+
+  await adapter.set(['metrics', 'history'], metricsHistory);
+
+  // Alert on critical thresholds
+  if (successRate < 95) {
+    ctx.log('error', 'ALERT: Success rate below threshold', {
+      successRate: successRate.toFixed(2),
+      threshold: 95,
+    });
+  }
+
+  if (metrics.workflows.avgDuration > 10000) {
+    ctx.log('warn', 'ALERT: Average duration above threshold', {
+      avgDuration: metrics.workflows.avgDuration,
+      threshold: 10000,
+    });
+  }
+
+  ctx.log('info', 'Metrics collected', {
+    successRate: successRate.toFixed(2),
+    avgDuration: metrics.workflows.avgDuration,
+  });
+
+  return metrics;
+});
+```
+
+---
+
+## Troubleshooting Guide
+
+### Common Issues & Solutions
+
+#### Issue 1: "No authentication credentials found"
+
+**Symptoms**: Error when calling Fluent API
+
+**Cause**: Using `fn()` instead of `http()` for external API calls
+
+**Solution**:
+
+```typescript
+// ❌ Wrong
+export const bad = fn('bad', async ctx => {
+  const client = await createClient(ctx); // FAILS - no ctx.fetch
+});
+
+// ✅ Correct
+export const good = http(
+  'good',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const client = await createClient(ctx); // Works
+  }
+);
+```
+
+#### Issue 2: Duplicate File Processing
+
+**Symptoms**: Same file processed multiple times
+
+**Cause**: Missing or incorrect file tracking
+
+**Solution**:
+
+```typescript
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+const kv = ctx.openKv(':project:');
+const tracker = new VersoriFileTracker(kv, 'namespace');
+
+// Check before processing
+if (await tracker.wasFileProcessed(fileName)) {
+  return { skipped: true };
+}
+
+// Process file...
+
+// Mark as processed
+await tracker.markFileProcessed(fileName, { records: count });
+```
+
+#### Issue 3: Memory Errors with Large Datasets
+
+**Symptoms**: Out of memory errors
+
+**Cause**: Loading entire dataset into memory
+
+**Solution**:
+
+```typescript
+// ❌ Wrong - loads everything
+const allData = await fetchAllData();
+await processData(allData);
+
+// ✅ Correct - batch processing
+const BATCH_SIZE = 100;
+let cursor = undefined;
+let hasMore = true;
+
+while (hasMore) {
+  const batch = await fetchBatch(BATCH_SIZE, cursor);
+  await processBatch(batch);
+  hasMore = batch.pageInfo.hasNextPage;
+  cursor = batch.pageInfo.endCursor;
+}
+```
+
+---
+
+## Practice Solutions
+
+### Module 2: Quick Start Exercise Solution
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Create inventory position
+ * POST https://{workspace}.versori.run/create-inventory
+ * Body: { productRef, locationRef, qty }
+ */
+export const createInventoryPosition = http(
+  'create-inventory',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    ctx.log('info', 'Creating inventory position');
+
+    const { productRef, locationRef, qty } = ctx.data || {};
+
+    // Validation
+    if (!productRef || !locationRef || qty === undefined) {
+      return {
+        success: false,
+        error: 'Missing required fields: productRef, locationRef, qty',
+      };
+    }
+
+    try {
+      const client = await createClient(ctx);
+
+      const result = await client.graphql({
+        query: `
+        mutation CreateInventory($input: CreateInventoryPositionInput!) {
+          createInventoryPosition(input: $input) {
+            id
+            ref
+            productRef
+            locationRef
+            onHand
+          }
+        }
+      `,
+        variables: {
+          input: { productRef, locationRef, qty },
+        },
+      });
+
+      if (result.errors?.length) {
+        throw new Error(result.errors[0].message);
+      }
+
+      ctx.log('info', 'Inventory position created', {
+        id: result.data.createInventoryPosition.id,
+      });
+
+      return {
+        success: true,
+        data: result.data.createInventoryPosition,
+      };
+    } catch (error) {
+      ctx.log('error', 'Failed to create inventory position', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Creation failed',
+      };
+    }
+  }
+);
+```
+
+---
+
+## Key Takeaways
+
+- 🎯 **Error handling** with comprehensive try-catch, retry, and circuit breaker patterns
+- 🎯 **Performance** via batching, caching, and parallel processing
+- 🎯 **Security** through input validation, rate limiting, and secrets management
+- 🎯 **Cost optimization** by minimizing KV ops, optimizing schedules, and caching
+- 🎯 **Monitoring** with metrics tracking and alerting on critical thresholds
+- 🎯 **Troubleshooting** using structured debugging and common issue patterns
+
+---
+
+## Conclusion
+
+You've completed the Versori Platform Integration Guide! You now have:
+
+- ✅ Understanding of Versori platform architecture
+- ✅ Ability to create all workflow types (http, webhook, schedule, fn)
+- ✅ Connection management expertise
+- ✅ KV storage and state management skills
+- ✅ Deployment and CI/CD knowledge
+- ✅ Production-ready patterns and best practices
+
+### Next Steps
+
+1. **Build Your Integration**: Apply these patterns to your specific use case
+2. **Review Examples**: Study the connector examples in `connectors/` directory
+3. **Consult SDK Guides**: Deep dive into specific SDK features
+4. **Join Community**: Engage with other developers using Versori
+
+### Additional Resources
+
+- [Versori Platform Documentation](https://docs.versori.com)
+- [FC Connect SDK API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md)
+- [Sample Connectors](../../../../01-TEMPLATES/versori/workflows/readme.md) - Production connector examples
+- [Webhook Response Patterns](.././modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
+
+---
+
+[← Previous: Module 7](./platforms-versori-07-deployment.md) | [Back to Guide](../platforms-versori-readme.md)