@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/testing/modules/04-reference-testing-03-fluent-testing.md

@@ -1,589 +1,589 @@
-# Module 3: Fluent Testing
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers the `FluentConnectionTester` utility for validating Fluent Commerce API connectivity. You'll learn how to test connections using the 'me' query and build health check endpoints.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand how to use FluentConnectionTester to validate API connectivity
-- ✅ Know how to interpret connection test results
-- ✅ Be able to implement health check endpoints
-- ✅ Understand how to debug Fluent API connection issues
-
-## FluentConnectionTester
-
-Validates Fluent Commerce API connectivity using the GraphQL 'me' query.
-
-### Basic Usage
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Create client
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    username: process.env.FLUENT_USERNAME,
-    password: process.env.FLUENT_PASSWORD,
-    retailerId: '1'
-  }
-});
-
-// Create tester with config
-const tester = new FluentConnectionTester(client, {
-  retailerId: '1',
-  logger: console
-});
-
-// Test connection
-const result = await tester.testConnection();
-
-if (result.success) {
-  console.log('✅ Fluent Commerce connection validated!');
-  console.log('User ID:', result.details.userId);
-  console.log('Username:', result.details.username);
-  console.log('Retailer:', result.details.retailerName);
-  console.log('Duration:', result.duration, 'ms');
-} else {
-  console.error('❌ Connection test failed:', result.error);
-}
-```
-
-### Constructor
-
-```typescript
-constructor(client: FluentClient, config: FluentTestConfig)
-```
-
-### Configuration Options
-
-```typescript
-interface FluentTestConfig {
-  retailerId: string;                 // Retailer ID for context
-  testJobId?: string;                 // Optional: Test job ID (reserved for future use)
-  testQuery?: string;                 // Optional: Custom test query (reserved for future use)
-  testEvent?: any;                    // Optional: Test event data (reserved for future use)
-  testBatch?: any[];                  // Optional: Test batch data (reserved for future use)
-  logger?: Logger;                    // Optional: Logger for output
-}
-```
-
-### Methods
-
-#### testConnection()
-
-Tests Fluent Commerce connection using the 'me' query.
-
-```typescript
-async testConnection(): Promise<TestResult>
-```
-
-### Test Result Structure
-
-The `testConnection()` method returns a `TestResult` object:
-
-```typescript
-interface TestResult {
-  success: boolean;                   // Test passed/failed
-  operation?: string;                 // Operation name (e.g., 'fluent_connection')
-  duration?: number;                  // Test duration in milliseconds
-  details?: {                         // Connection details (on success)
-    userId: string;                   // User ID
-    username: string;                 // Username
-    userType: string;                 // User type
-    userStatus: string;               // User status
-    retailerId?: string;              // Retailer ID
-    retailerRef?: string;             // Retailer reference
-    retailerName?: string;            // Retailer trading name
-    locationId?: string;              // Primary location ID
-    locationRef?: string;             // Primary location reference
-    locationName?: string;            // Primary location name
-  };
-  error?: string;                     // Error message (on failure)
-}
-```
-
-### Example: Detailed Output
-
-```typescript
-const result = await tester.testConnection();
-
-console.log('Connection Test Results:');
-console.log('Success:', result.success);
-console.log('Duration:', result.duration, 'ms');
-
-if (result.success && result.details) {
-  console.log('\nUser Information:');
-  console.log('  ID:', result.details.userId);
-  console.log('  Username:', result.details.username);
-  console.log('  Type:', result.details.userType);
-  console.log('  Status:', result.details.userStatus);
-
-  if (result.details.retailerId) {
-    console.log('\nRetailer Information:');
-    console.log('  ID:', result.details.retailerId);
-    console.log('  Ref:', result.details.retailerRef);
-    console.log('  Name:', result.details.retailerName);
-  }
-
-  if (result.details.locationId) {
-    console.log('\nLocation Information:');
-    console.log('  ID:', result.details.locationId);
-    console.log('  Ref:', result.details.locationRef);
-    console.log('  Name:', result.details.locationName);
-  }
-} else {
-  console.error('\nError:', result.error);
-}
-```
-
-## Health Check Implementation
-
-Create a health check endpoint for monitoring Fluent Commerce connectivity:
-
-### Basic Health Check
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function healthCheck() {
-  try {
-    // Create client
-    const client = await createClient({
-      config: {
-        baseUrl: process.env.FLUENT_BASE_URL!,
-        clientId: process.env.FLUENT_CLIENT_ID!,
-        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-        username: process.env.FLUENT_USERNAME!,
-        password: process.env.FLUENT_PASSWORD!,
-        retailerId: process.env.FLUENT_RETAILER_ID!
-      }
-    });
-
-    // Create tester
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-      logger: console
-    });
-
-    // Test connection
-    const result = await tester.testConnection();
-
-    // Return health status
-    return {
-      status: result.success ? 'healthy' : 'unhealthy',
-      fluent: {
-        connected: result.success,
-        duration: result.duration,
-        user: result.details?.username,
-        retailer: result.details?.retailerName
-      },
-      timestamp: new Date().toISOString()
-    };
-  } catch (error) {
-    return {
-      status: 'unhealthy',
-      error: error instanceof Error ? error.message : String(error),
-      timestamp: new Date().toISOString()
-    };
-  }
-}
-```
-
-### Express.js Health Endpoint
-
-```typescript
-import express from 'express';
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const app = express();
-
-// Health check endpoint
-app.get('/health', async (req, res) => {
-  try {
-    const client = await createClient({
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-
-    const result = await tester.testConnection();
-    const statusCode = result.success ? 200 : 503;
-
-    res.status(statusCode).json({
-      status: result.success ? 'healthy' : 'unhealthy',
-      fluent: {
-        connected: result.success,
-        duration: result.duration,
-        details: result.details
-      },
-      timestamp: new Date().toISOString()
-    });
-  } catch (error) {
-    res.status(503).json({
-      status: 'unhealthy',
-      error: error instanceof Error ? error.message : String(error),
-      timestamp: new Date().toISOString()
-    });
-  }
-});
-
-// Detailed health check with full connection details
-app.get('/health/detailed', async (req, res) => {
-  try {
-    const client = await createClient({
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-
-    const result = await tester.testConnection();
-
-    res.status(result.success ? 200 : 503).json({
-      status: result.success ? 'healthy' : 'unhealthy',
-      connection: result,
-      timestamp: new Date().toISOString()
-    });
-  } catch (error) {
-    res.status(503).json({
-      status: 'unhealthy',
-      error: error instanceof Error ? error.message : String(error),
-      timestamp: new Date().toISOString()
-    });
-  }
-});
-
-app.listen(3000, () => {
-  console.log('Health check server running on port 3000');
-});
-```
-
-### Versori Workflow Health Check
-
-```typescript
-import { http } from '@versori/run';
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Health check workflow
-export const healthCheck = http('GET /health', async (ctx) => {
-  try {
-    // Create client from Versori context
-    const client = await createClient(ctx);
-
-    // Test connectivity
-    const tester = new FluentConnectionTester(client, {
-      retailerId: ctx.activation.env.FLUENT_RETAILER_ID,
-      logger: ctx.log
-    });
-
-    const result = await tester.testConnection();
-
-    return {
-      status: result.success ? 200 : 503,
-      body: {
-        status: result.success ? 'healthy' : 'unhealthy',
-        fluent: {
-          connected: result.success,
-          duration: result.duration,
-          user: result.details?.username,
-          retailer: result.details?.retailerName
-        },
-        timestamp: new Date().toISOString()
-      }
-    };
-  } catch (error) {
-    return {
-      status: 503,
-      body: {
-        status: 'unhealthy',
-        error: error instanceof Error ? error.message : String(error),
-        timestamp: new Date().toISOString()
-      }
-    };
-  }
-});
-```
-
-## Interpreting Test Results
-
-### Understanding Connection Status
-
-```typescript
-function analyzeConnectionResult(result: TestResult) {
-  // Overall status
-  if (result.success) {
-    console.log('✅ Fluent Commerce connection successful');
-  } else {
-    console.log('❌ Fluent Commerce connection failed');
-    console.error('Error:', result.error);
-    return;
-  }
-
-  // Performance check
-  if (result.duration) {
-    console.log(`Response time: ${result.duration}ms`);
-    if (result.duration > 2000) {
-      console.warn('⚠️ Slow response detected (>2 seconds)');
-    }
-  }
-
-  // Connection details
-  if (result.details) {
-    console.log('\nConnection Details:');
-    console.log(`  User: ${result.details.username} (${result.details.userType})`);
-    console.log(`  Status: ${result.details.userStatus}`);
-
-    if (result.details.retailerName) {
-      console.log(`  Retailer: ${result.details.retailerName} (${result.details.retailerRef})`);
-    }
-
-    if (result.details.locationName) {
-      console.log(`  Location: ${result.details.locationName} (${result.details.locationRef})`);
-    }
-  }
-}
-```
-
-### Performance Thresholds
-
-Use these guidelines for interpreting response times:
-
-| Duration | Status | Action |
-|----------|--------|--------|
-| < 500ms | Excellent | No action needed |
-| 500ms - 1s | Good | Monitor for trends |
-| 1s - 2s | Acceptable | Investigate if persistent |
-| > 2s | Slow | Review network/credentials |
-| > 5s | Critical | Immediate investigation |
-
-## Troubleshooting Connection Issues
-
-### Common Error Messages
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `401 Unauthorized` | Invalid credentials | Verify clientId, clientSecret, username, password |
-| `403 Forbidden` | Insufficient permissions | Check user/client permissions in Fluent |
-| `Invalid response - missing me object` | GraphQL query failed | Check API endpoint and network connectivity |
-| `Network request failed` | Connection timeout/DNS | Verify baseUrl and network connectivity |
-| `Token refresh failed` | OAuth2 token expired | Verify client credentials are valid |
-
-### Diagnostic Script
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function diagnoseConnection() {
-  console.log('🔍 Diagnosing Fluent Commerce connection...\n');
-
-  // Check environment variables
-  console.log('Environment Variables:');
-  console.log('  FLUENT_BASE_URL:', process.env.FLUENT_BASE_URL ? '✅ Set' : '❌ Missing');
-  console.log('  FLUENT_CLIENT_ID:', process.env.FLUENT_CLIENT_ID ? '✅ Set' : '❌ Missing');
-  console.log('  FLUENT_CLIENT_SECRET:', process.env.FLUENT_CLIENT_SECRET ? '✅ Set' : '❌ Missing');
-  console.log('  FLUENT_USERNAME:', process.env.FLUENT_USERNAME ? '✅ Set' : '❌ Missing');
-  console.log('  FLUENT_PASSWORD:', process.env.FLUENT_PASSWORD ? '✅ Set' : '❌ Missing');
-  console.log('  FLUENT_RETAILER_ID:', process.env.FLUENT_RETAILER_ID ? '✅ Set' : '❌ Missing');
-  console.log();
-
-  try {
-    // Create client
-    const client = await createClient({
-      config: {
-        baseUrl: process.env.FLUENT_BASE_URL!,
-        clientId: process.env.FLUENT_CLIENT_ID!,
-        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-        username: process.env.FLUENT_USERNAME!,
-        password: process.env.FLUENT_PASSWORD!,
-        retailerId: process.env.FLUENT_RETAILER_ID!
-      }
-    });
-
-    console.log('✅ Client created successfully\n');
-
-    // Test connection
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-      logger: console
-    });
-
-    const result = await tester.testConnection();
-
-    if (result.success) {
-      console.log('\n✅ Connection test passed!');
-      console.log('All systems operational.');
-    } else {
-      console.log('\n❌ Connection test failed');
-      console.error('Error:', result.error);
-    }
-  } catch (error) {
-    console.error('\n❌ Fatal error:', error instanceof Error ? error.message : String(error));
-  }
-}
-
-diagnoseConnection();
-```
-
-## Complete Example: Fluent API Validation
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function validateFluentAPI() {
-  console.log('Validating Fluent Commerce API connectivity...\n');
-
-  try {
-    // Step 1: Create client
-    console.log('Step 1: Creating Fluent client...');
-    const client = await createClient({
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    });
-    console.log('✅ Client created\n');
-
-    // Step 2: Create tester
-    console.log('Step 2: Creating connection tester...');
-    const tester = new FluentConnectionTester(client, {
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-      logger: console
-    });
-    console.log('✅ Tester configured\n');
-
-    // Step 3: Test connection
-    console.log('Step 3: Testing connection...');
-    const result = await tester.testConnection();
-
-    // Step 4: Analyze results
-    console.log('\n=== Test Results ===');
-    if (result.success) {
-      console.log('✅ Connection test PASSED');
-      console.log(`   Duration: ${result.duration}ms`);
-
-      if (result.details) {
-        console.log('\n=== Connection Details ===');
-        console.log(`   User: ${result.details.username}`);
-        console.log(`   User Type: ${result.details.userType}`);
-        console.log(`   User Status: ${result.details.userStatus}`);
-
-        if (result.details.retailerName) {
-          console.log(`   Retailer: ${result.details.retailerName} (${result.details.retailerRef})`);
-        }
-
-        if (result.details.locationName) {
-          console.log(`   Location: ${result.details.locationName} (${result.details.locationRef})`);
-        }
-      }
-
-      return true;
-    } else {
-      console.error('❌ Connection test FAILED');
-      console.error(`   Error: ${result.error}`);
-      return false;
-    }
-  } catch (error) {
-    console.error('❌ Fatal error during validation');
-    console.error(error instanceof Error ? error.message : String(error));
-    return false;
-  }
-}
-
-// Run validation
-validateFluentAPI()
-  .then(success => {
-    console.log(`\nValidation ${success ? 'successful' : 'failed'}`);
-    process.exit(success ? 0 : 1);
-  })
-  .catch(error => {
-    console.error('Unexpected error:', error);
-    process.exit(1);
-  });
-```
-
-## Key Takeaways
-
-- 🎯 FluentConnectionTester validates Fluent API connectivity using the 'me' query
-- 🎯 Constructor requires FluentClient and FluentTestConfig parameters
-- 🎯 Use testConnection() method to test connectivity and retrieve user/retailer info
-- 🎯 Implement health check endpoints for monitoring production systems
-- 🎯 Analyze response times and connection details for troubleshooting
-- 🎯 Use the diagnostic script to check environment variables and connectivity
-
-## Practice Exercise
-
-Create a health check script for your Fluent Commerce integration:
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function healthCheck() {
-  // TODO: Create Fluent client with credentials
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      username: process.env.FLUENT_USERNAME!,
-      password: process.env.FLUENT_PASSWORD!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    }
-  });
-
-  // TODO: Create FluentConnectionTester
-  const tester = new FluentConnectionTester(client, {
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-    logger: console
-  });
-
-  // TODO: Test connection
-  const result = await tester.testConnection();
-
-  // TODO: Return health status
-  return {
-    status: result.success ? 'healthy' : 'unhealthy',
-    duration: result.duration,
-    details: result.details,
-    error: result.error
-  };
-}
-
-healthCheck().then(console.log);
-```
-
-**Solution:** See the [Complete Example](#complete-example-fluent-api-validation) section above.
-
-## Next Steps
-
-Continue to [Module 4: Integration Testing →](./04-reference-testing-04-integration-testing.md) to learn about end-to-end testing.
-
----
-
-**Module Navigation:**
-- **Previous:** [Module 2 - S3 Testing](./04-reference-testing-02-s3-testing.md)
-- **Current:** Module 3 - Fluent Testing
-- **Next:** [Module 4 - Integration Testing](./04-reference-testing-04-integration-testing.md)
-- **Back to:** [Testing Guide Index](../testing-readme.md)
+# Module 3: Fluent Testing
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers the `FluentConnectionTester` utility for validating Fluent Commerce API connectivity. You'll learn how to test connections using the 'me' query and build health check endpoints.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand how to use FluentConnectionTester to validate API connectivity
+- ✅ Know how to interpret connection test results
+- ✅ Be able to implement health check endpoints
+- ✅ Understand how to debug Fluent API connection issues
+
+## FluentConnectionTester
+
+Validates Fluent Commerce API connectivity using the GraphQL 'me' query.
+
+### Basic Usage
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Create client
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    username: process.env.FLUENT_USERNAME,
+    password: process.env.FLUENT_PASSWORD,
+    retailerId: '1'
+  }
+});
+
+// Create tester with config
+const tester = new FluentConnectionTester(client, {
+  retailerId: '1',
+  logger: console
+});
+
+// Test connection
+const result = await tester.testConnection();
+
+if (result.success) {
+  console.log('✅ Fluent Commerce connection validated!');
+  console.log('User ID:', result.details.userId);
+  console.log('Username:', result.details.username);
+  console.log('Retailer:', result.details.retailerName);
+  console.log('Duration:', result.duration, 'ms');
+} else {
+  console.error('❌ Connection test failed:', result.error);
+}
+```
+
+### Constructor
+
+```typescript
+constructor(client: FluentClient, config: FluentTestConfig)
+```
+
+### Configuration Options
+
+```typescript
+interface FluentTestConfig {
+  retailerId: string;                 // Retailer ID for context
+  testJobId?: string;                 // Optional: Test job ID (reserved for future use)
+  testQuery?: string;                 // Optional: Custom test query (reserved for future use)
+  testEvent?: any;                    // Optional: Test event data (reserved for future use)
+  testBatch?: any[];                  // Optional: Test batch data (reserved for future use)
+  logger?: Logger;                    // Optional: Logger for output
+}
+```
+
+### Methods
+
+#### testConnection()
+
+Tests Fluent Commerce connection using the 'me' query.
+
+```typescript
+async testConnection(): Promise<TestResult>
+```
+
+### Test Result Structure
+
+The `testConnection()` method returns a `TestResult` object:
+
+```typescript
+interface TestResult {
+  success: boolean;                   // Test passed/failed
+  operation?: string;                 // Operation name (e.g., 'fluent_connection')
+  duration?: number;                  // Test duration in milliseconds
+  details?: {                         // Connection details (on success)
+    userId: string;                   // User ID
+    username: string;                 // Username
+    userType: string;                 // User type
+    userStatus: string;               // User status
+    retailerId?: string;              // Retailer ID
+    retailerRef?: string;             // Retailer reference
+    retailerName?: string;            // Retailer trading name
+    locationId?: string;              // Primary location ID
+    locationRef?: string;             // Primary location reference
+    locationName?: string;            // Primary location name
+  };
+  error?: string;                     // Error message (on failure)
+}
+```
+
+### Example: Detailed Output
+
+```typescript
+const result = await tester.testConnection();
+
+console.log('Connection Test Results:');
+console.log('Success:', result.success);
+console.log('Duration:', result.duration, 'ms');
+
+if (result.success && result.details) {
+  console.log('\nUser Information:');
+  console.log('  ID:', result.details.userId);
+  console.log('  Username:', result.details.username);
+  console.log('  Type:', result.details.userType);
+  console.log('  Status:', result.details.userStatus);
+
+  if (result.details.retailerId) {
+    console.log('\nRetailer Information:');
+    console.log('  ID:', result.details.retailerId);
+    console.log('  Ref:', result.details.retailerRef);
+    console.log('  Name:', result.details.retailerName);
+  }
+
+  if (result.details.locationId) {
+    console.log('\nLocation Information:');
+    console.log('  ID:', result.details.locationId);
+    console.log('  Ref:', result.details.locationRef);
+    console.log('  Name:', result.details.locationName);
+  }
+} else {
+  console.error('\nError:', result.error);
+}
+```
+
+## Health Check Implementation
+
+Create a health check endpoint for monitoring Fluent Commerce connectivity:
+
+### Basic Health Check
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function healthCheck() {
+  try {
+    // Create client
+    const client = await createClient({
+      config: {
+        baseUrl: process.env.FLUENT_BASE_URL!,
+        clientId: process.env.FLUENT_CLIENT_ID!,
+        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+        username: process.env.FLUENT_USERNAME!,
+        password: process.env.FLUENT_PASSWORD!,
+        retailerId: process.env.FLUENT_RETAILER_ID!
+      }
+    });
+
+    // Create tester
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+      logger: console
+    });
+
+    // Test connection
+    const result = await tester.testConnection();
+
+    // Return health status
+    return {
+      status: result.success ? 'healthy' : 'unhealthy',
+      fluent: {
+        connected: result.success,
+        duration: result.duration,
+        user: result.details?.username,
+        retailer: result.details?.retailerName
+      },
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return {
+      status: 'unhealthy',
+      error: error instanceof Error ? error.message : String(error),
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+```
+
+### Express.js Health Endpoint
+
+```typescript
+import express from 'express';
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const app = express();
+
+// Health check endpoint
+app.get('/health', async (req, res) => {
+  try {
+    const client = await createClient({
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+
+    const result = await tester.testConnection();
+    const statusCode = result.success ? 200 : 503;
+
+    res.status(statusCode).json({
+      status: result.success ? 'healthy' : 'unhealthy',
+      fluent: {
+        connected: result.success,
+        duration: result.duration,
+        details: result.details
+      },
+      timestamp: new Date().toISOString()
+    });
+  } catch (error) {
+    res.status(503).json({
+      status: 'unhealthy',
+      error: error instanceof Error ? error.message : String(error),
+      timestamp: new Date().toISOString()
+    });
+  }
+});
+
+// Detailed health check with full connection details
+app.get('/health/detailed', async (req, res) => {
+  try {
+    const client = await createClient({
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+
+    const result = await tester.testConnection();
+
+    res.status(result.success ? 200 : 503).json({
+      status: result.success ? 'healthy' : 'unhealthy',
+      connection: result,
+      timestamp: new Date().toISOString()
+    });
+  } catch (error) {
+    res.status(503).json({
+      status: 'unhealthy',
+      error: error instanceof Error ? error.message : String(error),
+      timestamp: new Date().toISOString()
+    });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Health check server running on port 3000');
+});
+```
+
+### Versori Workflow Health Check
+
+```typescript
+import { http } from '@versori/run';
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Health check workflow
+export const healthCheck = http('GET /health', async (ctx) => {
+  try {
+    // Create client from Versori context
+    const client = await createClient(ctx);
+
+    // Test connectivity
+    const tester = new FluentConnectionTester(client, {
+      retailerId: ctx.activation.env.FLUENT_RETAILER_ID,
+      logger: ctx.log
+    });
+
+    const result = await tester.testConnection();
+
+    return {
+      status: result.success ? 200 : 503,
+      body: {
+        status: result.success ? 'healthy' : 'unhealthy',
+        fluent: {
+          connected: result.success,
+          duration: result.duration,
+          user: result.details?.username,
+          retailer: result.details?.retailerName
+        },
+        timestamp: new Date().toISOString()
+      }
+    };
+  } catch (error) {
+    return {
+      status: 503,
+      body: {
+        status: 'unhealthy',
+        error: error instanceof Error ? error.message : String(error),
+        timestamp: new Date().toISOString()
+      }
+    };
+  }
+});
+```
+
+## Interpreting Test Results
+
+### Understanding Connection Status
+
+```typescript
+function analyzeConnectionResult(result: TestResult) {
+  // Overall status
+  if (result.success) {
+    console.log('✅ Fluent Commerce connection successful');
+  } else {
+    console.log('❌ Fluent Commerce connection failed');
+    console.error('Error:', result.error);
+    return;
+  }
+
+  // Performance check
+  if (result.duration) {
+    console.log(`Response time: ${result.duration}ms`);
+    if (result.duration > 2000) {
+      console.warn('⚠️ Slow response detected (>2 seconds)');
+    }
+  }
+
+  // Connection details
+  if (result.details) {
+    console.log('\nConnection Details:');
+    console.log(`  User: ${result.details.username} (${result.details.userType})`);
+    console.log(`  Status: ${result.details.userStatus}`);
+
+    if (result.details.retailerName) {
+      console.log(`  Retailer: ${result.details.retailerName} (${result.details.retailerRef})`);
+    }
+
+    if (result.details.locationName) {
+      console.log(`  Location: ${result.details.locationName} (${result.details.locationRef})`);
+    }
+  }
+}
+```
+
+### Performance Thresholds
+
+Use these guidelines for interpreting response times:
+
+| Duration | Status | Action |
+|----------|--------|--------|
+| < 500ms | Excellent | No action needed |
+| 500ms - 1s | Good | Monitor for trends |
+| 1s - 2s | Acceptable | Investigate if persistent |
+| > 2s | Slow | Review network/credentials |
+| > 5s | Critical | Immediate investigation |
+
+## Troubleshooting Connection Issues
+
+### Common Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `401 Unauthorized` | Invalid credentials | Verify clientId, clientSecret, username, password |
+| `403 Forbidden` | Insufficient permissions | Check user/client permissions in Fluent |
+| `Invalid response - missing me object` | GraphQL query failed | Check API endpoint and network connectivity |
+| `Network request failed` | Connection timeout/DNS | Verify baseUrl and network connectivity |
+| `Token refresh failed` | OAuth2 token expired | Verify client credentials are valid |
+
+### Diagnostic Script
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function diagnoseConnection() {
+  console.log('🔍 Diagnosing Fluent Commerce connection...\n');
+
+  // Check environment variables
+  console.log('Environment Variables:');
+  console.log('  FLUENT_BASE_URL:', process.env.FLUENT_BASE_URL ? '✅ Set' : '❌ Missing');
+  console.log('  FLUENT_CLIENT_ID:', process.env.FLUENT_CLIENT_ID ? '✅ Set' : '❌ Missing');
+  console.log('  FLUENT_CLIENT_SECRET:', process.env.FLUENT_CLIENT_SECRET ? '✅ Set' : '❌ Missing');
+  console.log('  FLUENT_USERNAME:', process.env.FLUENT_USERNAME ? '✅ Set' : '❌ Missing');
+  console.log('  FLUENT_PASSWORD:', process.env.FLUENT_PASSWORD ? '✅ Set' : '❌ Missing');
+  console.log('  FLUENT_RETAILER_ID:', process.env.FLUENT_RETAILER_ID ? '✅ Set' : '❌ Missing');
+  console.log();
+
+  try {
+    // Create client
+    const client = await createClient({
+      config: {
+        baseUrl: process.env.FLUENT_BASE_URL!,
+        clientId: process.env.FLUENT_CLIENT_ID!,
+        clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+        username: process.env.FLUENT_USERNAME!,
+        password: process.env.FLUENT_PASSWORD!,
+        retailerId: process.env.FLUENT_RETAILER_ID!
+      }
+    });
+
+    console.log('✅ Client created successfully\n');
+
+    // Test connection
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+      logger: console
+    });
+
+    const result = await tester.testConnection();
+
+    if (result.success) {
+      console.log('\n✅ Connection test passed!');
+      console.log('All systems operational.');
+    } else {
+      console.log('\n❌ Connection test failed');
+      console.error('Error:', result.error);
+    }
+  } catch (error) {
+    console.error('\n❌ Fatal error:', error instanceof Error ? error.message : String(error));
+  }
+}
+
+diagnoseConnection();
+```
+
+## Complete Example: Fluent API Validation
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function validateFluentAPI() {
+  console.log('Validating Fluent Commerce API connectivity...\n');
+
+  try {
+    // Step 1: Create client
+    console.log('Step 1: Creating Fluent client...');
+    const client = await createClient({
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    });
+    console.log('✅ Client created\n');
+
+    // Step 2: Create tester
+    console.log('Step 2: Creating connection tester...');
+    const tester = new FluentConnectionTester(client, {
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+      logger: console
+    });
+    console.log('✅ Tester configured\n');
+
+    // Step 3: Test connection
+    console.log('Step 3: Testing connection...');
+    const result = await tester.testConnection();
+
+    // Step 4: Analyze results
+    console.log('\n=== Test Results ===');
+    if (result.success) {
+      console.log('✅ Connection test PASSED');
+      console.log(`   Duration: ${result.duration}ms`);
+
+      if (result.details) {
+        console.log('\n=== Connection Details ===');
+        console.log(`   User: ${result.details.username}`);
+        console.log(`   User Type: ${result.details.userType}`);
+        console.log(`   User Status: ${result.details.userStatus}`);
+
+        if (result.details.retailerName) {
+          console.log(`   Retailer: ${result.details.retailerName} (${result.details.retailerRef})`);
+        }
+
+        if (result.details.locationName) {
+          console.log(`   Location: ${result.details.locationName} (${result.details.locationRef})`);
+        }
+      }
+
+      return true;
+    } else {
+      console.error('❌ Connection test FAILED');
+      console.error(`   Error: ${result.error}`);
+      return false;
+    }
+  } catch (error) {
+    console.error('❌ Fatal error during validation');
+    console.error(error instanceof Error ? error.message : String(error));
+    return false;
+  }
+}
+
+// Run validation
+validateFluentAPI()
+  .then(success => {
+    console.log(`\nValidation ${success ? 'successful' : 'failed'}`);
+    process.exit(success ? 0 : 1);
+  })
+  .catch(error => {
+    console.error('Unexpected error:', error);
+    process.exit(1);
+  });
+```
+
+## Key Takeaways
+
+- 🎯 FluentConnectionTester validates Fluent API connectivity using the 'me' query
+- 🎯 Constructor requires FluentClient and FluentTestConfig parameters
+- 🎯 Use testConnection() method to test connectivity and retrieve user/retailer info
+- 🎯 Implement health check endpoints for monitoring production systems
+- 🎯 Analyze response times and connection details for troubleshooting
+- 🎯 Use the diagnostic script to check environment variables and connectivity
+
+## Practice Exercise
+
+Create a health check script for your Fluent Commerce integration:
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function healthCheck() {
+  // TODO: Create Fluent client with credentials
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      username: process.env.FLUENT_USERNAME!,
+      password: process.env.FLUENT_PASSWORD!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    }
+  });
+
+  // TODO: Create FluentConnectionTester
+  const tester = new FluentConnectionTester(client, {
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+    logger: console
+  });
+
+  // TODO: Test connection
+  const result = await tester.testConnection();
+
+  // TODO: Return health status
+  return {
+    status: result.success ? 'healthy' : 'unhealthy',
+    duration: result.duration,
+    details: result.details,
+    error: result.error
+  };
+}
+
+healthCheck().then(console.log);
+```
+
+**Solution:** See the [Complete Example](#complete-example-fluent-api-validation) section above.
+
+## Next Steps
+
+Continue to [Module 4: Integration Testing →](./04-reference-testing-04-integration-testing.md) to learn about end-to-end testing.
+
+---
+
+**Module Navigation:**
+- **Previous:** [Module 2 - S3 Testing](./04-reference-testing-02-s3-testing.md)
+- **Current:** Module 3 - Fluent Testing
+- **Next:** [Module 4 - Integration Testing](./04-reference-testing-04-integration-testing.md)
+- **Back to:** [Testing Guide Index](../testing-readme.md)