@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/testing/modules/04-reference-testing-01-foundations.md

@@ -1,267 +1,267 @@
-# Module 1: Foundations
-
-**Level:** Beginner
-**Estimated Time:** 15 minutes
-
-## Overview
-
-This module introduces the SDK's testing utilities and explains the core concepts behind testing connectivity and operations. You'll learn what testing utilities are available, when to use each one, and understand the standardized test result format.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand the three categories of testing utilities
-- ✅ Know when to use each testing utility
-- ✅ Understand the standardized `TestResult` interface
-- ✅ Be able to interpret test results and errors
-
-## Testing Utilities Overview
-
-The FC Connect SDK provides complete testing utilities to validate connectivity, test integrations, and compare different approaches.
-
-### Three Categories of Testing
-
-#### 1. S3 Testing Utilities
-
-Test S3 connectivity and operations using different approaches:
-
-- **S3SDKTester** - Tests using AWS SDK credentials (server-side)
-- **S3PresignedTester** - Tests using presigned URLs (client-side)
-
-```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'
-});
-
-// Test all operations in bucket
-const results = await tester.testAll('test-bucket');
-console.log(`Tests: ${results.summary.failed === 0 ? 'PASSED' : 'FAILED'}`);
-```
-
-#### 2. Fluent Commerce Testing Utilities
-
-Test Fluent Commerce API connectivity and operations:
-
-- **FluentConnectionTester** - Validates API connectivity, authentication, and endpoint operations
-
-```typescript
-import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient(fluentConfig);
-const tester = new FluentConnectionTester(
-  client,
-  {
-    retailerId: '1'
-  }
-);
-
-// Test Fluent API connection
-const result = await tester.testConnection();
-console.log(`API Tests: ${result.success ? 'PASSED' : 'FAILED'}`);
-```
-
-#### 3. Integration Testing Patterns
-
-Combine multiple testers for end-to-end validation:
-
-```typescript
-// Test S3 → Fluent pipeline
-const s3Results = await s3Tester.testAll('my-bucket');
-const fluentResult = await fluentTester.testConnection();
-
-if (s3Results.summary.failed === 0 && fluentResult.success) {
-  console.log('✅ Integration ready!');
-} else {
-  console.error('❌ Integration not ready');
-}
-```
-
-## TestResult Interface
-
-All testers return a standardized `TestResult` interface for consistent error handling:
-
-```typescript
-interface TestResult {
-  success: boolean;          // Overall test success
-  message?: string;          // Human-readable status message
-  operation?: string;        // Name of operation tested
-  details?: any;             // Operation-specific details
-  errors?: any[];            // List of errors that occurred
-  error?: string;            // Single error message if operation failed
-  timestamp?: string;        // When test was executed (ISO 8601)
-  duration?: number;         // Execution time in milliseconds
-}
-```
-
-### TestResult Fields Explained
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `success` | `boolean` | `true` if test passed, `false` if any failed |
-| `message` | `string` | Human-readable status message describing result |
-| `operation` | `string` | Name of the operation tested (e.g., "listObjects", "testConnection") |
-| `details` | `any` | Operation-specific details or metadata |
-| `errors` | `any[]` | Array of error objects that occurred during testing |
-| `error` | `string` | Single error message if operation failed |
-| `timestamp` | `string` | When the test was executed (ISO 8601 format) |
-| `duration` | `number` | Total execution time in milliseconds |
-
-### Example: Interpreting TestResult
-
-```typescript
-const result = await s3Tester.testAll('my-bucket');
-
-// Check overall success
-if (result.success) {
-  console.log(`✅ ${result.operation} passed in ${result.duration}ms`);
-  console.log(`Message: ${result.message}`);
-} else {
-  console.error(`❌ ${result.operation} failed:`);
-  console.error(`Error: ${result.error}`);
-
-  if (result.errors && result.errors.length > 0) {
-    result.errors.forEach(err => {
-      console.error(`  - ${err.message || err}`);
-    });
-  }
-}
-
-// Access operation details
-if (result.details) {
-  console.log('Operation details:', result.details);
-  // Example details:
-  // {
-  //   bucket: 'my-bucket',
-  //   region: 'us-east-1',
-  //   operationsCompleted: 5,
-  //   operationsFailed: 0
-  // }
-}
-
-// Test timestamp
-if (result.timestamp) {
-  console.log(`Executed at: ${result.timestamp}`);
-}
-```
-
-## When to Use Each Testing Utility
-
-### Use S3SDKTester When:
-
-- ✅ Testing server-side S3 access with AWS credentials
-- ✅ Validating IAM permissions for S3 operations
-- ✅ Testing list, read, write, delete, copy, head operations
-- ✅ Building backend services that directly access S3
-
-### Use S3PresignedTester When:
-
-- ✅ Testing client-side S3 access (browser, mobile)
-- ✅ Validating presigned URL generation
-- ✅ Testing read/write operations via presigned URLs
-- ✅ Building applications that share temporary S3 access
-
-
-### Use FluentConnectionTester When:
-
-- ✅ Validating Fluent API connectivity
-- ✅ Testing authentication (OAuth2)
-- ✅ Verifying endpoint access (GraphQL, events, jobs, batches)
-- ✅ Building health check endpoints
-- ✅ Debugging API connection issues
-
-## Testing Workflow
-
-### Typical Testing Flow
-
-```typescript
-// 1. Import testing utilities
-import { S3SDKTester, FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// 2. Configure testers
-const s3Tester = new S3SDKTester(s3Config);
-const fluentTester = new FluentConnectionTester(
-  await createClient(fluentConfig),
-  {
-    retailerId: '1'
-  }
-);
-
-// 3. Run tests
-const s3Results = await s3Tester.testAll('my-bucket');
-const fluentResult = await fluentTester.testConnection();
-
-// 4. Analyze results
-if (s3Results.summary.failed === 0 && fluentResult.success) {
-  console.log('✅ All systems operational');
-  // Proceed with integration
-} else {
-  console.error('❌ Tests failed');
-  // Debug issues before proceeding
-}
-```
-
-## Key Takeaways
-
-- 🎯 SDK provides testers for S3 and Fluent connectivity
-- 🎯 All testers return standardized `TestResult` for consistent error handling
-- 🎯 Use `testAll(bucket)` for S3 operations, `testConnection()` for Fluent API
-- 🎯 Test early to catch connectivity issues before development
-- 🎯 Use `result.success` for pass/fail, `result.error` and `result.errors` for debugging
-- 🎯 Check `result.operation` and `result.message` for human-readable status
-
-## Practice Exercise
-
-Create a simple connectivity test script:
-
-```typescript
-import { S3SDKTester, createClient, FluentConnectionTester } from '@fluentcommerce/fc-connect-sdk';
-
-async function testConnectivity() {
-  // TODO: Configure S3 tester
-  const s3Tester = new S3SDKTester({
-    // Your S3 config here
-  });
-
-  // TODO: Run S3 tests
-  const s3Result = await s3Tester.testAll('my-bucket');
-
-  // TODO: Configure Fluent tester
-  const client = await createClient({
-    // Your Fluent config here
-  });
-  const fluentTester = new FluentConnectionTester(
-    client,
-    {
-      retailerId: '1'
-    }
-  );
-
-  // TODO: Run Fluent tests
-  const fluentResult = await fluentTester.testConnection();
-
-  // TODO: Print results with details
-  console.log('S3:', s3Results.summary.failed === 0 ? '✅' : '❌', `(${s3Results.summary.passed}/${s3Results.summary.total} passed)`);
-  console.log('Fluent:', fluentResult.success ? '✅' : '❌', `(${fluentResult.message})`);
-
-  return s3Results.summary.failed === 0 && fluentResult.success;
-}
-
-testConnectivity();
-```
-
-**Solution:** See [examples/integration-test.ts](../examples/integration-test.ts)
-
-## Next Steps
-
-Continue to [Module 2: S3 Testing →](./04-reference-testing-02-s3-testing.md) to learn about S3 testing utilities in depth.
-
----
-
-**Module Navigation:**
-- **Current:** Module 1 - Foundations
-- **Next:** [Module 2 - S3 Testing](./04-reference-testing-02-s3-testing.md)
-- **Back to:** [Testing Guide Index](../testing-readme.md)
+# Module 1: Foundations
+
+**Level:** Beginner
+**Estimated Time:** 15 minutes
+
+## Overview
+
+This module introduces the SDK's testing utilities and explains the core concepts behind testing connectivity and operations. You'll learn what testing utilities are available, when to use each one, and understand the standardized test result format.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand the three categories of testing utilities
+- ✅ Know when to use each testing utility
+- ✅ Understand the standardized `TestResult` interface
+- ✅ Be able to interpret test results and errors
+
+## Testing Utilities Overview
+
+The FC Connect SDK provides complete testing utilities to validate connectivity, test integrations, and compare different approaches.
+
+### Three Categories of Testing
+
+#### 1. S3 Testing Utilities
+
+Test S3 connectivity and operations using different approaches:
+
+- **S3SDKTester** - Tests using AWS SDK credentials (server-side)
+- **S3PresignedTester** - Tests using presigned URLs (client-side)
+
+```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'
+});
+
+// Test all operations in bucket
+const results = await tester.testAll('test-bucket');
+console.log(`Tests: ${results.summary.failed === 0 ? 'PASSED' : 'FAILED'}`);
+```
+
+#### 2. Fluent Commerce Testing Utilities
+
+Test Fluent Commerce API connectivity and operations:
+
+- **FluentConnectionTester** - Validates API connectivity, authentication, and endpoint operations
+
+```typescript
+import { FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient(fluentConfig);
+const tester = new FluentConnectionTester(
+  client,
+  {
+    retailerId: '1'
+  }
+);
+
+// Test Fluent API connection
+const result = await tester.testConnection();
+console.log(`API Tests: ${result.success ? 'PASSED' : 'FAILED'}`);
+```
+
+#### 3. Integration Testing Patterns
+
+Combine multiple testers for end-to-end validation:
+
+```typescript
+// Test S3 → Fluent pipeline
+const s3Results = await s3Tester.testAll('my-bucket');
+const fluentResult = await fluentTester.testConnection();
+
+if (s3Results.summary.failed === 0 && fluentResult.success) {
+  console.log('✅ Integration ready!');
+} else {
+  console.error('❌ Integration not ready');
+}
+```
+
+## TestResult Interface
+
+All testers return a standardized `TestResult` interface for consistent error handling:
+
+```typescript
+interface TestResult {
+  success: boolean;          // Overall test success
+  message?: string;          // Human-readable status message
+  operation?: string;        // Name of operation tested
+  details?: any;             // Operation-specific details
+  errors?: any[];            // List of errors that occurred
+  error?: string;            // Single error message if operation failed
+  timestamp?: string;        // When test was executed (ISO 8601)
+  duration?: number;         // Execution time in milliseconds
+}
+```
+
+### TestResult Fields Explained
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `boolean` | `true` if test passed, `false` if any failed |
+| `message` | `string` | Human-readable status message describing result |
+| `operation` | `string` | Name of the operation tested (e.g., "listObjects", "testConnection") |
+| `details` | `any` | Operation-specific details or metadata |
+| `errors` | `any[]` | Array of error objects that occurred during testing |
+| `error` | `string` | Single error message if operation failed |
+| `timestamp` | `string` | When the test was executed (ISO 8601 format) |
+| `duration` | `number` | Total execution time in milliseconds |
+
+### Example: Interpreting TestResult
+
+```typescript
+const result = await s3Tester.testAll('my-bucket');
+
+// Check overall success
+if (result.success) {
+  console.log(`✅ ${result.operation} passed in ${result.duration}ms`);
+  console.log(`Message: ${result.message}`);
+} else {
+  console.error(`❌ ${result.operation} failed:`);
+  console.error(`Error: ${result.error}`);
+
+  if (result.errors && result.errors.length > 0) {
+    result.errors.forEach(err => {
+      console.error(`  - ${err.message || err}`);
+    });
+  }
+}
+
+// Access operation details
+if (result.details) {
+  console.log('Operation details:', result.details);
+  // Example details:
+  // {
+  //   bucket: 'my-bucket',
+  //   region: 'us-east-1',
+  //   operationsCompleted: 5,
+  //   operationsFailed: 0
+  // }
+}
+
+// Test timestamp
+if (result.timestamp) {
+  console.log(`Executed at: ${result.timestamp}`);
+}
+```
+
+## When to Use Each Testing Utility
+
+### Use S3SDKTester When:
+
+- ✅ Testing server-side S3 access with AWS credentials
+- ✅ Validating IAM permissions for S3 operations
+- ✅ Testing list, read, write, delete, copy, head operations
+- ✅ Building backend services that directly access S3
+
+### Use S3PresignedTester When:
+
+- ✅ Testing client-side S3 access (browser, mobile)
+- ✅ Validating presigned URL generation
+- ✅ Testing read/write operations via presigned URLs
+- ✅ Building applications that share temporary S3 access
+
+
+### Use FluentConnectionTester When:
+
+- ✅ Validating Fluent API connectivity
+- ✅ Testing authentication (OAuth2)
+- ✅ Verifying endpoint access (GraphQL, events, jobs, batches)
+- ✅ Building health check endpoints
+- ✅ Debugging API connection issues
+
+## Testing Workflow
+
+### Typical Testing Flow
+
+```typescript
+// 1. Import testing utilities
+import { S3SDKTester, FluentConnectionTester, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// 2. Configure testers
+const s3Tester = new S3SDKTester(s3Config);
+const fluentTester = new FluentConnectionTester(
+  await createClient(fluentConfig),
+  {
+    retailerId: '1'
+  }
+);
+
+// 3. Run tests
+const s3Results = await s3Tester.testAll('my-bucket');
+const fluentResult = await fluentTester.testConnection();
+
+// 4. Analyze results
+if (s3Results.summary.failed === 0 && fluentResult.success) {
+  console.log('✅ All systems operational');
+  // Proceed with integration
+} else {
+  console.error('❌ Tests failed');
+  // Debug issues before proceeding
+}
+```
+
+## Key Takeaways
+
+- 🎯 SDK provides testers for S3 and Fluent connectivity
+- 🎯 All testers return standardized `TestResult` for consistent error handling
+- 🎯 Use `testAll(bucket)` for S3 operations, `testConnection()` for Fluent API
+- 🎯 Test early to catch connectivity issues before development
+- 🎯 Use `result.success` for pass/fail, `result.error` and `result.errors` for debugging
+- 🎯 Check `result.operation` and `result.message` for human-readable status
+
+## Practice Exercise
+
+Create a simple connectivity test script:
+
+```typescript
+import { S3SDKTester, createClient, FluentConnectionTester } from '@fluentcommerce/fc-connect-sdk';
+
+async function testConnectivity() {
+  // TODO: Configure S3 tester
+  const s3Tester = new S3SDKTester({
+    // Your S3 config here
+  });
+
+  // TODO: Run S3 tests
+  const s3Result = await s3Tester.testAll('my-bucket');
+
+  // TODO: Configure Fluent tester
+  const client = await createClient({
+    // Your Fluent config here
+  });
+  const fluentTester = new FluentConnectionTester(
+    client,
+    {
+      retailerId: '1'
+    }
+  );
+
+  // TODO: Run Fluent tests
+  const fluentResult = await fluentTester.testConnection();
+
+  // TODO: Print results with details
+  console.log('S3:', s3Results.summary.failed === 0 ? '✅' : '❌', `(${s3Results.summary.passed}/${s3Results.summary.total} passed)`);
+  console.log('Fluent:', fluentResult.success ? '✅' : '❌', `(${fluentResult.message})`);
+
+  return s3Results.summary.failed === 0 && fluentResult.success;
+}
+
+testConnectivity();
+```
+
+**Solution:** See [examples/integration-test.ts](../examples/integration-test.ts)
+
+## Next Steps
+
+Continue to [Module 2: S3 Testing →](./04-reference-testing-02-s3-testing.md) to learn about S3 testing utilities in depth.
+
+---
+
+**Module Navigation:**
+- **Current:** Module 1 - Foundations
+- **Next:** [Module 2 - S3 Testing](./04-reference-testing-02-s3-testing.md)
+- **Back to:** [Testing Guide Index](../testing-readme.md)