@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/testing/modules/04-reference-testing-08-api-reference.md

@@ -1,634 +1,634 @@
-# Module 8: API Reference
-
-**Level:** Reference
-**Estimated Time:** As needed
-
-## Overview
-
-This module provides complete API reference documentation for all testing utilities.
-
-## TestResult Interface
-
-All testers return a standardized `TestResult` interface:
-
-```typescript
-interface TestResult {
-  success: boolean;           // Test success status
-  message?: string;          // Human-readable test result message
-  operation?: string;        // Operation name (e.g., 'fluent_connection', 'list', 'read')
-  duration?: number;         // Test duration in milliseconds
-  errors?: any[];            // Array of errors (if failed)
-  error?: string;            // Single error message (if failed)
-  details?: any;             // Test-specific result details
-  timestamp?: string;        // Test execution timestamp (ISO string)
-}
-```
-
-## S3SDKTester
-
-Tests S3 operations using the AWS SDK implementation (not presigned URLs).
-
-### Constructor
-
-```typescript
-new S3SDKTester(config: S3ServiceConfig)
-```
-
-### Configuration
-
-```typescript
-interface S3ServiceConfig {
-  accessKeyId: string;          // AWS access key ID
-  secretAccessKey: string;      // AWS secret access key
-  region: string;               // AWS region (e.g., 'us-east-1')
-  sessionToken?: string;        // Optional session token for temporary credentials
-}
-```
-
-### Method
-
-#### testAll()
-
-Tests all S3 operations including SDK-specific features.
-
-```typescript
-async testAll(testBucket: string): Promise<SDKTestResults>
-```
-
-**Parameters:**
-- `testBucket`: S3 bucket name to use for testing
-
-**Returns:**
-```typescript
-interface SDKTestResults {
-  implementation: 'sdk';
-  timestamp: string;
-  tests: Record<string, TestResult>;  // Individual test results
-  summary?: {
-    total: number;
-    passed: number;
-    failed: number;
-    successRate: number;
-    totalDuration: number;
-    averageDuration: number;
-  };
-}
-```
-
-**Tests performed:**
-- `list`: List objects (S3 ListObjectsV2)
-- `write`: Write object (S3 PutObject)
-- `read`: Read object (S3 GetObject)
-- `copy`: Copy object (S3 CopyObject)
-- `head`: Get object metadata (S3 HeadObject)
-- `move`: Move object (copy + delete)
-- `delete`: Delete object (S3 DeleteObject)
-- `multipart`: Multipart upload (SDK-only)
-- `select`: S3 Select query (SDK-only)
-
-**Example:**
-```typescript
-import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
-
-const tester = new S3SDKTester({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  region: 'us-east-1'
-});
-
-const results = await tester.testAll('my-test-bucket');
-console.log(`Passed: ${results.summary?.passed}/${results.summary?.total}`);
-```
-
-## S3PresignedTester
-
-Tests S3 operations using presigned URL implementation (no AWS SDK required).
-
-### Constructor
-
-```typescript
-new S3PresignedTester(config: S3ServiceConfig, fetch: typeof globalThis.fetch)
-```
-
-### Configuration
-
-```typescript
-interface S3ServiceConfig {
-  accessKeyId: string;          // AWS access key ID
-  secretAccessKey: string;      // AWS secret access key
-  region: string;               // AWS region (e.g., 'us-east-1')
-  sessionToken?: string;        // Optional session token for temporary credentials
-}
-```
-
-**Parameters:**
-- `config`: S3 service configuration
-- `fetch`: Fetch implementation (use `ctx.fetch` in Versori, or `globalThis.fetch` in Node.js)
-
-### Method
-
-#### testAll()
-
-Tests all S3 operations available with presigned URLs.
-
-```typescript
-async testAll(testBucket: string): Promise<PresignedTestResults>
-```
-
-**Parameters:**
-- `testBucket`: S3 bucket name to use for testing
-
-**Returns:**
-```typescript
-interface PresignedTestResults {
-  implementation: 'presigned';
-  timestamp: string;
-  tests: Record<string, TestResult>;  // Individual test results
-  summary?: {
-    total: number;
-    passed: number;
-    failed: number;
-    successRate: number;
-    totalDuration: number;
-    averageDuration: number;
-  };
-}
-```
-
-**Tests performed:**
-- `list`: List objects via presigned URL
-- `write`: Write object via presigned URL
-- `read`: Read object via presigned URL
-- `copy`: Copy object via presigned URL
-- `head`: Get object metadata via presigned URL
-- `move`: Move object (copy + delete via presigned URLs)
-- `delete`: Delete object via presigned URL
-- `advancedFeatures`: Verify advanced features are unavailable (expected)
-
-**Example:**
-```typescript
-import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
-
-const tester = new S3PresignedTester({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  region: 'us-east-1'
-}, fetch);
-
-const results = await tester.testAll('my-test-bucket');
-console.log(`Passed: ${results.summary?.passed}/${results.summary?.total}`);
-```
-
-## S3ComparisonTester
-
-Compares SDK and presigned URL implementations to ensure both produce the same results.
-
-### Constructor
-
-```typescript
-new S3ComparisonTester()
-```
-
-No configuration needed. Takes config as parameters to comparison methods.
-
-### Methods
-
-#### compareImplementations()
-
-Runs tests with both implementations and compares results.
-
-```typescript
-async compareImplementations(
-  config: S3ServiceConfig,
-  testBucket: string,
-  customFetch?: typeof globalThis.fetch
-): Promise<ComparisonResults>
-```
-
-**Parameters:**
-- `config`: S3 service configuration
-- `testBucket`: S3 bucket name to use for testing
-- `customFetch` (optional): Custom fetch implementation (defaults to `globalThis.fetch`)
-
-**Returns:**
-```typescript
-interface ComparisonResults {
-  timestamp: string;
-  duration: number;
-  sdk: SDKTestResults;              // Full SDK test results
-  presigned: PresignedTestResults;  // Full presigned test results
-  comparison: ComparisonDetails;    // Detailed comparison
-  summary: {
-    totalOperations: number;
-    commonOperations: number;        // Operations available in both
-    matchingResults: number;         // Operations with same result
-    mismatchingResults: number;      // Operations with different results
-    matchRate: number;               // Percentage of matching results
-    discrepancyCount: number;        // Number of discrepancies found
-    avgPerformanceRatio: number;     // Presigned/SDK duration ratio
-    performanceAnalysis: string;     // Performance comparison text
-  };
-}
-```
-
-**Example:**
-```typescript
-import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
-
-const tester = new S3ComparisonTester();
-const results = await tester.compareImplementations(
-  {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    region: 'us-east-1'
-  },
-  'my-test-bucket'
-);
-
-console.log('Performance:', results.summary.performanceAnalysis);
-console.log(`Match rate: ${results.summary.matchRate}%`);
-```
-
-#### compareSpecificOperation()
-
-Compares a specific operation between both implementations.
-
-```typescript
-async compareSpecificOperation(
-  config: S3ServiceConfig,
-  testBucket: string,
-  operation: 'list' | 'read' | 'write' | 'copy' | 'delete',
-  customFetch?: typeof globalThis.fetch
-): Promise<OperationComparison>
-```
-
-**Parameters:**
-- `config`: S3 service configuration
-- `testBucket`: S3 bucket name to use for testing
-- `operation`: Specific operation to test
-- `customFetch` (optional): Custom fetch implementation
-
-**Returns:**
-```typescript
-interface OperationComparison {
-  operation: string;
-  sdk: {
-    success: boolean;
-    result?: any;
-    error?: any;
-    duration: number;
-  };
-  presigned: {
-    success: boolean;
-    result?: any;
-    error?: any;
-    duration: number;
-  };
-  matches: boolean;              // Do results match?
-  performanceRatio: number;      // Presigned/SDK duration ratio
-}
-```
-
-**Example:**
-```typescript
-const comparison = await tester.compareSpecificOperation(
-  config,
-  'my-test-bucket',
-  'read'
-);
-
-console.log(`Operation: ${comparison.operation}`);
-console.log(`Match: ${comparison.matches}`);
-console.log(`Performance ratio: ${comparison.performanceRatio.toFixed(2)}x`);
-```
-
-## FluentConnectionTester
-
-Tests connection to Fluent Commerce API using the 'me' query.
-
-### Constructor
-
-```typescript
-new FluentConnectionTester(client: FluentClient, config: FluentTestConfig)
-```
-
-**Parameters:**
-- `client`: FluentClient instance to test
-- `config`: Test configuration
-
-### Configuration
-
-```typescript
-interface FluentTestConfig {
-  retailerId: string;        // Retailer ID for testing
-  testJobId?: string;        // Optional job ID for testing
-  testQuery?: string;        // Optional custom query
-  testEvent?: any;           // Optional event for testing
-  testBatch?: any[];         // Optional batch data for testing
-  logger?: Logger;           // Optional logger
-}
-
-interface Logger {
-  info: (message: string, meta?: any) => void;
-  error: (message: string, meta?: any) => void;
-  warn: (message: string, meta?: any) => void;
-  debug: (message: string, meta?: any) => void;
-  success?: (message: string, meta?: any) => void;
-}
-```
-
-### Method
-
-#### testConnection()
-
-Tests connection to Fluent Commerce using the 'me' query.
-
-```typescript
-async testConnection(): Promise<TestResult>
-```
-
-**Returns:**
-```typescript
-interface TestResult {
-  success: boolean;
-  operation: 'fluent_connection';
-  duration: number;
-  details?: {
-    userId: string;
-    username: string;
-    userType: string;
-    userStatus: string;
-    retailerId?: string;
-    retailerRef?: string;
-    retailerName?: string;
-    locationId?: string;
-    locationRef?: string;
-    locationName?: string;
-  };
-  error?: string;  // If connection failed
-}
-```
-
-**What it tests:**
-- OAuth2 authentication
-- GraphQL API connectivity
-- User information retrieval
-- Retailer and location access
-
-**Example:**
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-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: '1'
-  }
-});
-
-const tester = new FluentConnectionTester(client, {
-  retailerId: '1',
-  logger: console
-});
-
-const result = await tester.testConnection();
-
-if (result.success) {
-  console.log(`Connected as: ${result.details?.username}`);
-  console.log(`Retailer: ${result.details?.retailerName}`);
-} else {
-  console.error(`Connection failed: ${result.error}`);
-}
-```
-
-## Complete Usage Examples
-
-### S3 Testing Workflow
-
-```typescript
-import {
-  S3SDKTester,
-  S3PresignedTester,
-  S3ComparisonTester
-} from '@fluentcommerce/fc-connect-sdk';
-
-const config = {
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  region: 'us-east-1'
-};
-
-const testBucket = 'my-test-bucket';
-
-// 1. Test SDK implementation
-console.log('Testing SDK implementation...');
-const sdkTester = new S3SDKTester(config);
-const sdkResults = await sdkTester.testAll(testBucket);
-console.log(`SDK: ${sdkResults.summary?.passed}/${sdkResults.summary?.total} tests passed`);
-
-// 2. Test presigned URL implementation
-console.log('\nTesting presigned URL implementation...');
-const presignedTester = new S3PresignedTester(config, fetch);
-const presignedResults = await presignedTester.testAll(testBucket);
-console.log(`Presigned: ${presignedResults.summary?.passed}/${presignedResults.summary?.total} tests passed`);
-
-// 3. Compare both implementations
-console.log('\nComparing implementations...');
-const comparisonTester = new S3ComparisonTester();
-const comparison = await comparisonTester.compareImplementations(config, testBucket);
-console.log(`Match rate: ${comparison.summary.matchRate}%`);
-console.log(`Performance: ${comparison.summary.performanceAnalysis}`);
-
-// 4. Test specific operation
-const readComparison = await comparisonTester.compareSpecificOperation(
-  config,
-  testBucket,
-  'read'
-);
-console.log(`\nRead operation comparison:`);
-console.log(`- Match: ${readComparison.matches}`);
-console.log(`- Performance ratio: ${readComparison.performanceRatio.toFixed(2)}x`);
-```
-
-### Fluent Connection Testing
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// 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: '1'
-  }
-});
-
-// Test connection
-const tester = new FluentConnectionTester(client, {
-  retailerId: '1',
-  logger: {
-    info: (msg, meta) => console.log(`[INFO] ${msg}`, meta || ''),
-    error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta || ''),
-    warn: (msg, meta) => console.warn(`[WARN] ${msg}`, meta || ''),
-    debug: (msg, meta) => console.debug(`[DEBUG] ${msg}`, meta || ''),
-    success: (msg, meta) => console.log(`[SUCCESS] ${msg}`, meta || '')
-  }
-});
-
-const result = await tester.testConnection();
-
-if (result.success) {
-  console.log('\n✅ Connection successful!');
-  console.log(`Duration: ${result.duration}ms`);
-  console.log(`User: ${result.details?.username} (${result.details?.userType})`);
-  console.log(`Retailer: ${result.details?.retailerName}`);
-  if (result.details?.locationName) {
-    console.log(`Location: ${result.details.locationName}`);
-  }
-} else {
-  console.error('\n❌ Connection failed!');
-  console.error(`Error: ${result.error}`);
-  process.exit(1);
-}
-```
-
-### Versori Platform Integration
-
-```typescript
-import { schedule, http } from '@versori/run';
-import {
-  S3PresignedTester,
-  FluentConnectionTester,
-  createClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const testConnections = schedule('test-connections', '0 0 * * *').then(
-  http('test', { connections: ['aws_s3', 'fluent_commerce'] }, async (ctx) => {
-    const { log, connections, fetch } = ctx;
-
-    // Test S3 (presigned - Versori compatible)
-    log.info('Testing S3 connection...');
-    const s3Tester = new S3PresignedTester(
-      {
-        accessKeyId: connections.aws_s3.config.accessKeyId,
-        secretAccessKey: connections.aws_s3.config.secretAccessKey,
-        region: connections.aws_s3.config.region
-      },
-      fetch
-    );
-    const s3Results = await s3Tester.testAll('test-bucket');
-    log.info(`S3: ${s3Results.summary?.passed}/${s3Results.summary?.total} tests passed`);
-
-    // Test Fluent
-    log.info('Testing Fluent connection...');
-    const fluentClient = await createClient(ctx);
-    const fluentTester = new FluentConnectionTester(fluentClient, {
-      retailerId: connections.fluent_commerce.config.retailerId,
-      logger: log
-    });
-    const fluentResult = await fluentTester.testConnection();
-
-    if (!fluentResult.success) {
-      throw new Error(`Fluent connection failed: ${fluentResult.error}`);
-    }
-
-    return {
-      s3: {
-        passed: s3Results.summary?.passed,
-        total: s3Results.summary?.total,
-        successRate: s3Results.summary?.successRate
-      },
-      fluent: {
-        success: fluentResult.success,
-        duration: fluentResult.duration,
-        user: fluentResult.details?.username
-      }
-    };
-  })
-);
-```
-
-## Error Codes
-
-Common error messages and their meanings:
-
-| Error Message | Cause | Solution |
-|--------------|-------|----------|
-| `AccessDenied` | Insufficient IAM permissions | Check IAM policy includes required S3 actions |
-| `NoSuchBucket` | Bucket doesn't exist | Verify bucket name is correct |
-| `401 Unauthorized` | Invalid credentials | Check OAuth2 credentials (clientId, clientSecret) |
-| `403 Forbidden` | Insufficient permissions | Verify user has required Fluent permissions |
-| `ENOTFOUND` | DNS resolution failed | Check network connectivity |
-| `ETIMEDOUT` | Request timed out | Increase timeout or check service availability |
-| `ECONNREFUSED` | Connection refused | Verify service is running and accessible |
-
-## Type Definitions Summary
-
-### Core Types
-
-```typescript
-// Common to all testers
-interface TestResult {
-  success: boolean;
-  message?: string;
-  operation?: string;
-  duration?: number;
-  errors?: any[];
-  error?: string;
-  details?: any;
-  timestamp?: string;
-}
-
-// S3 configuration
-interface S3ServiceConfig {
-  accessKeyId: string;
-  secretAccessKey: string;
-  region: string;
-  sessionToken?: string;
-}
-
-// Fluent test configuration
-interface FluentTestConfig {
-  retailerId: string;
-  testJobId?: string;
-  testQuery?: string;
-  testEvent?: any;
-  testBatch?: any[];
-  logger?: Logger;
-}
-
-// Logger interface
-interface Logger {
-  info: (message: string, meta?: any) => void;
-  error: (message: string, meta?: any) => void;
-  warn: (message: string, meta?: any) => void;
-  debug: (message: string, meta?: any) => void;
-  success?: (message: string, meta?: any) => void;
-}
-```
-
-## Key Takeaways
-
-- All testers return standardized `TestResult` interface
-- S3SDKTester tests AWS SDK implementation (9 operations including multipart and S3 Select)
-- S3PresignedTester tests presigned URL implementation (8 operations)
-- S3ComparisonTester compares both implementations to ensure consistency
-- FluentConnectionTester validates Fluent API connectivity using the 'me' query
-- Use `testAll()` methods for comprehensive testing
-- Use comparison testers to validate implementation equivalence
-- All test methods include timing information for performance analysis
-
----
-
-**Module Navigation:**
-- **Previous:** [Module 7 - Best Practices](./04-reference-testing-07-best-practices.md)
-- **Current:** Module 8 - API Reference
-- **Back to:** [Testing Guide Index](../testing-readme.md)
+# Module 8: API Reference
+
+**Level:** Reference
+**Estimated Time:** As needed
+
+## Overview
+
+This module provides complete API reference documentation for all testing utilities.
+
+## TestResult Interface
+
+All testers return a standardized `TestResult` interface:
+
+```typescript
+interface TestResult {
+  success: boolean;           // Test success status
+  message?: string;          // Human-readable test result message
+  operation?: string;        // Operation name (e.g., 'fluent_connection', 'list', 'read')
+  duration?: number;         // Test duration in milliseconds
+  errors?: any[];            // Array of errors (if failed)
+  error?: string;            // Single error message (if failed)
+  details?: any;             // Test-specific result details
+  timestamp?: string;        // Test execution timestamp (ISO string)
+}
+```
+
+## S3SDKTester
+
+Tests S3 operations using the AWS SDK implementation (not presigned URLs).
+
+### Constructor
+
+```typescript
+new S3SDKTester(config: S3ServiceConfig)
+```
+
+### Configuration
+
+```typescript
+interface S3ServiceConfig {
+  accessKeyId: string;          // AWS access key ID
+  secretAccessKey: string;      // AWS secret access key
+  region: string;               // AWS region (e.g., 'us-east-1')
+  sessionToken?: string;        // Optional session token for temporary credentials
+}
+```
+
+### Method
+
+#### testAll()
+
+Tests all S3 operations including SDK-specific features.
+
+```typescript
+async testAll(testBucket: string): Promise<SDKTestResults>
+```
+
+**Parameters:**
+- `testBucket`: S3 bucket name to use for testing
+
+**Returns:**
+```typescript
+interface SDKTestResults {
+  implementation: 'sdk';
+  timestamp: string;
+  tests: Record<string, TestResult>;  // Individual test results
+  summary?: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    totalDuration: number;
+    averageDuration: number;
+  };
+}
+```
+
+**Tests performed:**
+- `list`: List objects (S3 ListObjectsV2)
+- `write`: Write object (S3 PutObject)
+- `read`: Read object (S3 GetObject)
+- `copy`: Copy object (S3 CopyObject)
+- `head`: Get object metadata (S3 HeadObject)
+- `move`: Move object (copy + delete)
+- `delete`: Delete object (S3 DeleteObject)
+- `multipart`: Multipart upload (SDK-only)
+- `select`: S3 Select query (SDK-only)
+
+**Example:**
+```typescript
+import { S3SDKTester } from '@fluentcommerce/fc-connect-sdk';
+
+const tester = new S3SDKTester({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  region: 'us-east-1'
+});
+
+const results = await tester.testAll('my-test-bucket');
+console.log(`Passed: ${results.summary?.passed}/${results.summary?.total}`);
+```
+
+## S3PresignedTester
+
+Tests S3 operations using presigned URL implementation (no AWS SDK required).
+
+### Constructor
+
+```typescript
+new S3PresignedTester(config: S3ServiceConfig, fetch: typeof globalThis.fetch)
+```
+
+### Configuration
+
+```typescript
+interface S3ServiceConfig {
+  accessKeyId: string;          // AWS access key ID
+  secretAccessKey: string;      // AWS secret access key
+  region: string;               // AWS region (e.g., 'us-east-1')
+  sessionToken?: string;        // Optional session token for temporary credentials
+}
+```
+
+**Parameters:**
+- `config`: S3 service configuration
+- `fetch`: Fetch implementation (use `ctx.fetch` in Versori, or `globalThis.fetch` in Node.js)
+
+### Method
+
+#### testAll()
+
+Tests all S3 operations available with presigned URLs.
+
+```typescript
+async testAll(testBucket: string): Promise<PresignedTestResults>
+```
+
+**Parameters:**
+- `testBucket`: S3 bucket name to use for testing
+
+**Returns:**
+```typescript
+interface PresignedTestResults {
+  implementation: 'presigned';
+  timestamp: string;
+  tests: Record<string, TestResult>;  // Individual test results
+  summary?: {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    totalDuration: number;
+    averageDuration: number;
+  };
+}
+```
+
+**Tests performed:**
+- `list`: List objects via presigned URL
+- `write`: Write object via presigned URL
+- `read`: Read object via presigned URL
+- `copy`: Copy object via presigned URL
+- `head`: Get object metadata via presigned URL
+- `move`: Move object (copy + delete via presigned URLs)
+- `delete`: Delete object via presigned URL
+- `advancedFeatures`: Verify advanced features are unavailable (expected)
+
+**Example:**
+```typescript
+import { S3PresignedTester } from '@fluentcommerce/fc-connect-sdk';
+
+const tester = new S3PresignedTester({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  region: 'us-east-1'
+}, fetch);
+
+const results = await tester.testAll('my-test-bucket');
+console.log(`Passed: ${results.summary?.passed}/${results.summary?.total}`);
+```
+
+## S3ComparisonTester
+
+Compares SDK and presigned URL implementations to ensure both produce the same results.
+
+### Constructor
+
+```typescript
+new S3ComparisonTester()
+```
+
+No configuration needed. Takes config as parameters to comparison methods.
+
+### Methods
+
+#### compareImplementations()
+
+Runs tests with both implementations and compares results.
+
+```typescript
+async compareImplementations(
+  config: S3ServiceConfig,
+  testBucket: string,
+  customFetch?: typeof globalThis.fetch
+): Promise<ComparisonResults>
+```
+
+**Parameters:**
+- `config`: S3 service configuration
+- `testBucket`: S3 bucket name to use for testing
+- `customFetch` (optional): Custom fetch implementation (defaults to `globalThis.fetch`)
+
+**Returns:**
+```typescript
+interface ComparisonResults {
+  timestamp: string;
+  duration: number;
+  sdk: SDKTestResults;              // Full SDK test results
+  presigned: PresignedTestResults;  // Full presigned test results
+  comparison: ComparisonDetails;    // Detailed comparison
+  summary: {
+    totalOperations: number;
+    commonOperations: number;        // Operations available in both
+    matchingResults: number;         // Operations with same result
+    mismatchingResults: number;      // Operations with different results
+    matchRate: number;               // Percentage of matching results
+    discrepancyCount: number;        // Number of discrepancies found
+    avgPerformanceRatio: number;     // Presigned/SDK duration ratio
+    performanceAnalysis: string;     // Performance comparison text
+  };
+}
+```
+
+**Example:**
+```typescript
+import { S3ComparisonTester } from '@fluentcommerce/fc-connect-sdk';
+
+const tester = new S3ComparisonTester();
+const results = await tester.compareImplementations(
+  {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    region: 'us-east-1'
+  },
+  'my-test-bucket'
+);
+
+console.log('Performance:', results.summary.performanceAnalysis);
+console.log(`Match rate: ${results.summary.matchRate}%`);
+```
+
+#### compareSpecificOperation()
+
+Compares a specific operation between both implementations.
+
+```typescript
+async compareSpecificOperation(
+  config: S3ServiceConfig,
+  testBucket: string,
+  operation: 'list' | 'read' | 'write' | 'copy' | 'delete',
+  customFetch?: typeof globalThis.fetch
+): Promise<OperationComparison>
+```
+
+**Parameters:**
+- `config`: S3 service configuration
+- `testBucket`: S3 bucket name to use for testing
+- `operation`: Specific operation to test
+- `customFetch` (optional): Custom fetch implementation
+
+**Returns:**
+```typescript
+interface OperationComparison {
+  operation: string;
+  sdk: {
+    success: boolean;
+    result?: any;
+    error?: any;
+    duration: number;
+  };
+  presigned: {
+    success: boolean;
+    result?: any;
+    error?: any;
+    duration: number;
+  };
+  matches: boolean;              // Do results match?
+  performanceRatio: number;      // Presigned/SDK duration ratio
+}
+```
+
+**Example:**
+```typescript
+const comparison = await tester.compareSpecificOperation(
+  config,
+  'my-test-bucket',
+  'read'
+);
+
+console.log(`Operation: ${comparison.operation}`);
+console.log(`Match: ${comparison.matches}`);
+console.log(`Performance ratio: ${comparison.performanceRatio.toFixed(2)}x`);
+```
+
+## FluentConnectionTester
+
+Tests connection to Fluent Commerce API using the 'me' query.
+
+### Constructor
+
+```typescript
+new FluentConnectionTester(client: FluentClient, config: FluentTestConfig)
+```
+
+**Parameters:**
+- `client`: FluentClient instance to test
+- `config`: Test configuration
+
+### Configuration
+
+```typescript
+interface FluentTestConfig {
+  retailerId: string;        // Retailer ID for testing
+  testJobId?: string;        // Optional job ID for testing
+  testQuery?: string;        // Optional custom query
+  testEvent?: any;           // Optional event for testing
+  testBatch?: any[];         // Optional batch data for testing
+  logger?: Logger;           // Optional logger
+}
+
+interface Logger {
+  info: (message: string, meta?: any) => void;
+  error: (message: string, meta?: any) => void;
+  warn: (message: string, meta?: any) => void;
+  debug: (message: string, meta?: any) => void;
+  success?: (message: string, meta?: any) => void;
+}
+```
+
+### Method
+
+#### testConnection()
+
+Tests connection to Fluent Commerce using the 'me' query.
+
+```typescript
+async testConnection(): Promise<TestResult>
+```
+
+**Returns:**
+```typescript
+interface TestResult {
+  success: boolean;
+  operation: 'fluent_connection';
+  duration: number;
+  details?: {
+    userId: string;
+    username: string;
+    userType: string;
+    userStatus: string;
+    retailerId?: string;
+    retailerRef?: string;
+    retailerName?: string;
+    locationId?: string;
+    locationRef?: string;
+    locationName?: string;
+  };
+  error?: string;  // If connection failed
+}
+```
+
+**What it tests:**
+- OAuth2 authentication
+- GraphQL API connectivity
+- User information retrieval
+- Retailer and location access
+
+**Example:**
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+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: '1'
+  }
+});
+
+const tester = new FluentConnectionTester(client, {
+  retailerId: '1',
+  logger: console
+});
+
+const result = await tester.testConnection();
+
+if (result.success) {
+  console.log(`Connected as: ${result.details?.username}`);
+  console.log(`Retailer: ${result.details?.retailerName}`);
+} else {
+  console.error(`Connection failed: ${result.error}`);
+}
+```
+
+## Complete Usage Examples
+
+### S3 Testing Workflow
+
+```typescript
+import {
+  S3SDKTester,
+  S3PresignedTester,
+  S3ComparisonTester
+} from '@fluentcommerce/fc-connect-sdk';
+
+const config = {
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  region: 'us-east-1'
+};
+
+const testBucket = 'my-test-bucket';
+
+// 1. Test SDK implementation
+console.log('Testing SDK implementation...');
+const sdkTester = new S3SDKTester(config);
+const sdkResults = await sdkTester.testAll(testBucket);
+console.log(`SDK: ${sdkResults.summary?.passed}/${sdkResults.summary?.total} tests passed`);
+
+// 2. Test presigned URL implementation
+console.log('\nTesting presigned URL implementation...');
+const presignedTester = new S3PresignedTester(config, fetch);
+const presignedResults = await presignedTester.testAll(testBucket);
+console.log(`Presigned: ${presignedResults.summary?.passed}/${presignedResults.summary?.total} tests passed`);
+
+// 3. Compare both implementations
+console.log('\nComparing implementations...');
+const comparisonTester = new S3ComparisonTester();
+const comparison = await comparisonTester.compareImplementations(config, testBucket);
+console.log(`Match rate: ${comparison.summary.matchRate}%`);
+console.log(`Performance: ${comparison.summary.performanceAnalysis}`);
+
+// 4. Test specific operation
+const readComparison = await comparisonTester.compareSpecificOperation(
+  config,
+  testBucket,
+  'read'
+);
+console.log(`\nRead operation comparison:`);
+console.log(`- Match: ${readComparison.matches}`);
+console.log(`- Performance ratio: ${readComparison.performanceRatio.toFixed(2)}x`);
+```
+
+### Fluent Connection Testing
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// 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: '1'
+  }
+});
+
+// Test connection
+const tester = new FluentConnectionTester(client, {
+  retailerId: '1',
+  logger: {
+    info: (msg, meta) => console.log(`[INFO] ${msg}`, meta || ''),
+    error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta || ''),
+    warn: (msg, meta) => console.warn(`[WARN] ${msg}`, meta || ''),
+    debug: (msg, meta) => console.debug(`[DEBUG] ${msg}`, meta || ''),
+    success: (msg, meta) => console.log(`[SUCCESS] ${msg}`, meta || '')
+  }
+});
+
+const result = await tester.testConnection();
+
+if (result.success) {
+  console.log('\n✅ Connection successful!');
+  console.log(`Duration: ${result.duration}ms`);
+  console.log(`User: ${result.details?.username} (${result.details?.userType})`);
+  console.log(`Retailer: ${result.details?.retailerName}`);
+  if (result.details?.locationName) {
+    console.log(`Location: ${result.details.locationName}`);
+  }
+} else {
+  console.error('\n❌ Connection failed!');
+  console.error(`Error: ${result.error}`);
+  process.exit(1);
+}
+```
+
+### Versori Platform Integration
+
+```typescript
+import { schedule, http } from '@versori/run';
+import {
+  S3PresignedTester,
+  FluentConnectionTester,
+  createClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const testConnections = schedule('test-connections', '0 0 * * *').then(
+  http('test', { connections: ['aws_s3', 'fluent_commerce'] }, async (ctx) => {
+    const { log, connections, fetch } = ctx;
+
+    // Test S3 (presigned - Versori compatible)
+    log.info('Testing S3 connection...');
+    const s3Tester = new S3PresignedTester(
+      {
+        accessKeyId: connections.aws_s3.config.accessKeyId,
+        secretAccessKey: connections.aws_s3.config.secretAccessKey,
+        region: connections.aws_s3.config.region
+      },
+      fetch
+    );
+    const s3Results = await s3Tester.testAll('test-bucket');
+    log.info(`S3: ${s3Results.summary?.passed}/${s3Results.summary?.total} tests passed`);
+
+    // Test Fluent
+    log.info('Testing Fluent connection...');
+    const fluentClient = await createClient(ctx);
+    const fluentTester = new FluentConnectionTester(fluentClient, {
+      retailerId: connections.fluent_commerce.config.retailerId,
+      logger: log
+    });
+    const fluentResult = await fluentTester.testConnection();
+
+    if (!fluentResult.success) {
+      throw new Error(`Fluent connection failed: ${fluentResult.error}`);
+    }
+
+    return {
+      s3: {
+        passed: s3Results.summary?.passed,
+        total: s3Results.summary?.total,
+        successRate: s3Results.summary?.successRate
+      },
+      fluent: {
+        success: fluentResult.success,
+        duration: fluentResult.duration,
+        user: fluentResult.details?.username
+      }
+    };
+  })
+);
+```
+
+## Error Codes
+
+Common error messages and their meanings:
+
+| Error Message | Cause | Solution |
+|--------------|-------|----------|
+| `AccessDenied` | Insufficient IAM permissions | Check IAM policy includes required S3 actions |
+| `NoSuchBucket` | Bucket doesn't exist | Verify bucket name is correct |
+| `401 Unauthorized` | Invalid credentials | Check OAuth2 credentials (clientId, clientSecret) |
+| `403 Forbidden` | Insufficient permissions | Verify user has required Fluent permissions |
+| `ENOTFOUND` | DNS resolution failed | Check network connectivity |
+| `ETIMEDOUT` | Request timed out | Increase timeout or check service availability |
+| `ECONNREFUSED` | Connection refused | Verify service is running and accessible |
+
+## Type Definitions Summary
+
+### Core Types
+
+```typescript
+// Common to all testers
+interface TestResult {
+  success: boolean;
+  message?: string;
+  operation?: string;
+  duration?: number;
+  errors?: any[];
+  error?: string;
+  details?: any;
+  timestamp?: string;
+}
+
+// S3 configuration
+interface S3ServiceConfig {
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+}
+
+// Fluent test configuration
+interface FluentTestConfig {
+  retailerId: string;
+  testJobId?: string;
+  testQuery?: string;
+  testEvent?: any;
+  testBatch?: any[];
+  logger?: Logger;
+}
+
+// Logger interface
+interface Logger {
+  info: (message: string, meta?: any) => void;
+  error: (message: string, meta?: any) => void;
+  warn: (message: string, meta?: any) => void;
+  debug: (message: string, meta?: any) => void;
+  success?: (message: string, meta?: any) => void;
+}
+```
+
+## Key Takeaways
+
+- All testers return standardized `TestResult` interface
+- S3SDKTester tests AWS SDK implementation (9 operations including multipart and S3 Select)
+- S3PresignedTester tests presigned URL implementation (8 operations)
+- S3ComparisonTester compares both implementations to ensure consistency
+- FluentConnectionTester validates Fluent API connectivity using the 'me' query
+- Use `testAll()` methods for comprehensive testing
+- Use comparison testers to validate implementation equivalence
+- All test methods include timing information for performance analysis
+
+---
+
+**Module Navigation:**
+- **Previous:** [Module 7 - Best Practices](./04-reference-testing-07-best-practices.md)
+- **Current:** Module 8 - API Reference
+- **Back to:** [Testing Guide Index](../testing-readme.md)