@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/error-handling-patterns.md

@@ -1,401 +1,401 @@
-# Error Handling Patterns
-
-**⏱️ Read Time:** 5 minutes | **When:** Implementing error handling in your integration
-
----
-
-## Overview
-
-The SDK provides two error handling patterns for mappers:
-
-1. **`map()` - Throws errors** (use with try/catch)
-2. **`mapSafe()` - Returns result objects** (recommended for production)
-
-Both `GraphQLMutationMapper` and `UniversalMapper` support these patterns, but with slight differences.
-
----
-
-## GraphQLMutationMapper Error Handling
-
-### Pattern 1: `map()` - Throws Errors
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(config, logger);
-
-try {
-  const payload = await mapper.map(sourceData);
-  await client.graphql(payload);
-  console.log('✅ Success');
-} catch (error) {
-  console.error('❌ Mapping failed:', error);
-  // Handle error (log, retry, skip, etc.)
-}
-```
-
-**When to use:**
-- Simple error handling (fail fast)
-- You want exceptions to propagate up
-- Error handling is centralized (e.g., in a wrapper function)
-
-**Limitations:**
-- Requires try/catch blocks
-- Can't easily check for partial failures
-- Less flexible for batch processing
-
----
-
-### Pattern 2: `mapSafe()` - Returns Result Objects (Recommended)
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(config, logger);
-
-const result = await mapper.mapSafe(sourceData);
-
-if (!result.success) {
-  console.error('❌ Mapping failed:', result.errors);
-  // Handle error (log, retry, skip, etc.)
-  return;
-}
-
-// Success - execute GraphQL mutation
-await client.graphql({
-  query: result.query,
-  variables: result.variables,
-});
-console.log('✅ Success');
-```
-
-**Result Object Structure:**
-```typescript
-interface MapResult {
-  success: boolean;
-  query: string;           // GraphQL mutation query (empty string on error)
-  variables: Record<string, any>;  // Variables for GraphQL (empty object on error)
-  errors?: string[];       // Array of error messages (only present on failure)
-}
-```
-
-**When to use:**
-- ✅ **Production code** (recommended)
-- Batch processing (check each item individually)
-- Need to handle errors gracefully without stopping the entire process
-- Want to log errors but continue processing
-- Need to distinguish between different error types
-
-**Benefits:**
-- No try/catch required
-- Can check `result.success` before proceeding
-- Errors are structured (array of messages)
-- Consistent with `UniversalMapper.map()` pattern
-
----
-
-## UniversalMapper Error Handling
-
-`UniversalMapper` **always** returns result objects (never throws):
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper(config);
-
-const result = await mapper.map(sourceData);
-
-if (!result.success) {
-  console.error('❌ Mapping failed:', result.errors);
-  // Handle error
-  return;
-}
-
-// Success - use result.data
-console.log('✅ Mapped data:', result.data);
-```
-
-**Result Object Structure:**
-```typescript
-interface MappingResult {
-  success: boolean;
-  data: any | null;              // Mapped data (null on error)
-  errors?: string[];             // Array of error messages
-  skippedFields?: string[];      // Fields that were skipped (optional)
-}
-```
-
----
-
-## Comparison Table
-
-| Feature | `map()` (throws) | `mapSafe()` (result object) | `UniversalMapper.map()` |
-|---------|------------------|------------------------------|-------------------------|
-| **Error Handling** | Try/catch required | Check `result.success` | Check `result.success` |
-| **Error Information** | Exception object | `result.errors` array | `result.errors` array |
-| **Partial Failures** | ❌ No (throws immediately) | ✅ Yes (can continue) | ✅ Yes (can continue) |
-| **Batch Processing** | ❌ Difficult | ✅ Easy | ✅ Easy |
-| **Production Ready** | ⚠️ Requires careful error handling | ✅ Recommended | ✅ Recommended |
-| **Available In** | GraphQLMutationMapper only | GraphQLMutationMapper only | UniversalMapper only |
-
----
-
-## Real-World Examples
-
-### Example 1: Batch Processing with Error Handling
-
-```typescript
-// Process 100 locations from CSV
-const locations = await parser.parse(csvContent);
-
-const mapper = new GraphQLMutationMapper(config, logger);
-let successCount = 0;
-let errorCount = 0;
-
-for (const location of locations) {
-  const result = await mapper.mapSafe(location);
-  
-  if (!result.success) {
-    errorCount++;
-    logger.error(`Failed to map location ${location.ref}:`, result.errors);
-    continue; // Skip to next location
-  }
-
-  try {
-    await client.graphql({
-      query: result.query,
-      variables: result.variables,
-    });
-    successCount++;
-  } catch (apiError) {
-    errorCount++;
-    logger.error(`API error for location ${location.ref}:`, apiError);
-  }
-}
-
-console.log(`✅ Processed: ${successCount} successful, ${errorCount} errors`);
-```
-
-### Example 2: Webhook Handler with Error Handling
-
-```typescript
-export async function handleWebhook(event: WebhookEvent) {
-  const mapper = new GraphQLMutationMapper(config, logger);
-  
-  const result = await mapper.mapSafe(event.payload);
-  
-  if (!result.success) {
-    // Log error but don't crash the webhook handler
-    logger.error('Webhook mapping failed:', {
-      eventId: event.id,
-      errors: result.errors,
-    });
-    
-    // Return error response to webhook caller
-    return {
-      statusCode: 400,
-      body: JSON.stringify({ errors: result.errors }),
-    };
-  }
-
-  // Execute mutation
-  const apiResult = await client.graphql({
-    query: result.query,
-    variables: result.variables,
-  });
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify(apiResult),
-  };
-}
-```
-
-### Example 3: Retry Logic with Error Handling
-
-```typescript
-async function mapWithRetry(
-  mapper: GraphQLMutationMapper,
-  sourceData: any,
-  maxRetries = 3
-): Promise<MapResult> {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    const result = await mapper.mapSafe(sourceData);
-    
-    if (result.success) {
-      return result;
-    }
-
-    // Log error
-    logger.warn(`Mapping attempt ${attempt} failed:`, result.errors);
-    
-    // Wait before retry (exponential backoff)
-    if (attempt < maxRetries) {
-      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
-    }
-  }
-
-  // All retries failed
-  return {
-    success: false,
-    query: '',
-    variables: {},
-    errors: ['All retry attempts failed'],
-  };
-}
-```
-
----
-
-## Best Practices
-
-### ✅ DO
-
-1. **Use `mapSafe()` in production code**
-   - More robust error handling
-   - Better for batch processing
-   - Consistent with `UniversalMapper` pattern
-
-2. **Check `result.success` before proceeding**
-   ```typescript
-   const result = await mapper.mapSafe(data);
-   if (!result.success) {
-     // Handle error
-     return;
-   }
-   // Proceed with success case
-   ```
-
-3. **Log errors with context**
-   ```typescript
-   if (!result.success) {
-     logger.error('Mapping failed', {
-       sourceData: data,
-       errors: result.errors,
-       timestamp: new Date().toISOString(),
-     });
-   }
-   ```
-
-4. **Handle errors gracefully in batch processing**
-   - Don't stop entire batch on single error
-   - Log errors but continue processing
-   - Track success/error counts
-
-### ❌ DON'T
-
-1. **Don't ignore errors**
-   ```typescript
-   // ❌ BAD - ignores errors
-   const result = await mapper.mapSafe(data);
-   await client.graphql({ query: result.query, variables: result.variables });
-   ```
-
-2. **Don't use `map()` without try/catch**
-   ```typescript
-   // ❌ BAD - unhandled exception
-   const payload = await mapper.map(data);
-   await client.graphql(payload);
-   ```
-
-3. **Don't assume success**
-   ```typescript
-   // ❌ BAD - doesn't check success
-   const result = await mapper.mapSafe(data);
-   await client.graphql({ query: result.query, variables: result.variables });
-   ```
-
----
-
-## Migration Guide
-
-### Migrating from `map()` to `mapSafe()`
-
-**Before:**
-```typescript
-try {
-  const payload = await mapper.map(sourceData);
-  await client.graphql(payload);
-} catch (error) {
-  console.error('Error:', error);
-}
-```
-
-**After:**
-```typescript
-const result = await mapper.mapSafe(sourceData);
-if (!result.success) {
-  console.error('Error:', result.errors);
-  return;
-}
-await client.graphql({ query: result.query, variables: result.variables });
-```
-
-**Benefits:**
-- No try/catch needed
-- Structured error information (`result.errors` array)
-- Easier to handle in batch processing
-- Consistent with `UniversalMapper` pattern
-
----
-
-## GraphQL Error Classification
-
-After executing a GraphQL mutation, you may receive errors from the Fluent Commerce API. The SDK provides error classification to help determine if errors are retryable:
-
-```typescript
-import { classifyErrors, type GraphQLError } from '@fluentcommerce/fc-connect-sdk';
-
-const result = await client.graphql({
-  query: result.query,
-  variables: result.variables,
-});
-
-if (result.errors) {
-  const classification = classifyErrors(result.errors);
-  
-  if (classification.retryable) {
-    // Wait and retry
-    await delay(classification.retryDelaySeconds * 1000);
-    // retry logic...
-  } else {
-    // Don't retry - show error to user
-    logger.error('Non-retryable error:', {
-      errorCode: classification.errorCode,
-      message: classification.userMessage,
-      action: classification.action,
-    });
-  }
-}
-```
-
-**Error Classification Result:**
-```typescript
-interface ErrorClassification {
-  retryable: boolean;              // Whether to retry
-  category: 'CLIENT_ERROR' | 'SERVER_ERROR' | 'THIRD_PARTY_ERROR' | 'UNKNOWN';
-  userMessage: string;              // User-friendly message
-  action: 'FIX_AND_RETRY' | 'RETRY_LATER' | 'CONTACT_SUPPORT' | 'VERIFY_PAYLOAD';
-  retryDelaySeconds?: number;       // Recommended delay (if retryable)
-  errorCode?: string;               // Error code (e.g., 'C0121E')
-}
-```
-
-**Common Error Codes:**
-- **C0121E** - Order already exists (non-retryable, verify payload)
-- **C0140E** - Missing required variables (non-retryable, fix and retry)
-- **S0002E** - Server error (retryable, retry later)
-- **C0011E** - Rate limit exceeded (retryable, retry later)
-
-See [GraphQL Error Classification Guide](../api-reference/graphql-error-classification.md) for complete error code reference.
-
----
-
-## Related Documentation
-
-- [Mapper Comparison Guide](./mapping-mapper-comparison-guide.md) - Complete mapper comparison
-- [Resolver Registration Guide](./resolver-registration.md) - How to register custom resolvers
-- [GraphQL Mutation Mapping](../graphql-mutation-mapping/) - GraphQLMutationMapper details
-- [Universal Mapping](./) - UniversalMapper details
-- [GraphQL Error Classification](../api-reference/graphql-error-classification.md) - Error code reference
-
+# Error Handling Patterns
+
+**⏱️ Read Time:** 5 minutes | **When:** Implementing error handling in your integration
+
+---
+
+## Overview
+
+The SDK provides two error handling patterns for mappers:
+
+1. **`map()` - Throws errors** (use with try/catch)
+2. **`mapSafe()` - Returns result objects** (recommended for production)
+
+Both `GraphQLMutationMapper` and `UniversalMapper` support these patterns, but with slight differences.
+
+---
+
+## GraphQLMutationMapper Error Handling
+
+### Pattern 1: `map()` - Throws Errors
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(config, logger);
+
+try {
+  const payload = await mapper.map(sourceData);
+  await client.graphql(payload);
+  console.log('✅ Success');
+} catch (error) {
+  console.error('❌ Mapping failed:', error);
+  // Handle error (log, retry, skip, etc.)
+}
+```
+
+**When to use:**
+- Simple error handling (fail fast)
+- You want exceptions to propagate up
+- Error handling is centralized (e.g., in a wrapper function)
+
+**Limitations:**
+- Requires try/catch blocks
+- Can't easily check for partial failures
+- Less flexible for batch processing
+
+---
+
+### Pattern 2: `mapSafe()` - Returns Result Objects (Recommended)
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(config, logger);
+
+const result = await mapper.mapSafe(sourceData);
+
+if (!result.success) {
+  console.error('❌ Mapping failed:', result.errors);
+  // Handle error (log, retry, skip, etc.)
+  return;
+}
+
+// Success - execute GraphQL mutation
+await client.graphql({
+  query: result.query,
+  variables: result.variables,
+});
+console.log('✅ Success');
+```
+
+**Result Object Structure:**
+```typescript
+interface MapResult {
+  success: boolean;
+  query: string;           // GraphQL mutation query (empty string on error)
+  variables: Record<string, any>;  // Variables for GraphQL (empty object on error)
+  errors?: string[];       // Array of error messages (only present on failure)
+}
+```
+
+**When to use:**
+- ✅ **Production code** (recommended)
+- Batch processing (check each item individually)
+- Need to handle errors gracefully without stopping the entire process
+- Want to log errors but continue processing
+- Need to distinguish between different error types
+
+**Benefits:**
+- No try/catch required
+- Can check `result.success` before proceeding
+- Errors are structured (array of messages)
+- Consistent with `UniversalMapper.map()` pattern
+
+---
+
+## UniversalMapper Error Handling
+
+`UniversalMapper` **always** returns result objects (never throws):
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper(config);
+
+const result = await mapper.map(sourceData);
+
+if (!result.success) {
+  console.error('❌ Mapping failed:', result.errors);
+  // Handle error
+  return;
+}
+
+// Success - use result.data
+console.log('✅ Mapped data:', result.data);
+```
+
+**Result Object Structure:**
+```typescript
+interface MappingResult {
+  success: boolean;
+  data: any | null;              // Mapped data (null on error)
+  errors?: string[];             // Array of error messages
+  skippedFields?: string[];      // Fields that were skipped (optional)
+}
+```
+
+---
+
+## Comparison Table
+
+| Feature | `map()` (throws) | `mapSafe()` (result object) | `UniversalMapper.map()` |
+|---------|------------------|------------------------------|-------------------------|
+| **Error Handling** | Try/catch required | Check `result.success` | Check `result.success` |
+| **Error Information** | Exception object | `result.errors` array | `result.errors` array |
+| **Partial Failures** | ❌ No (throws immediately) | ✅ Yes (can continue) | ✅ Yes (can continue) |
+| **Batch Processing** | ❌ Difficult | ✅ Easy | ✅ Easy |
+| **Production Ready** | ⚠️ Requires careful error handling | ✅ Recommended | ✅ Recommended |
+| **Available In** | GraphQLMutationMapper only | GraphQLMutationMapper only | UniversalMapper only |
+
+---
+
+## Real-World Examples
+
+### Example 1: Batch Processing with Error Handling
+
+```typescript
+// Process 100 locations from CSV
+const locations = await parser.parse(csvContent);
+
+const mapper = new GraphQLMutationMapper(config, logger);
+let successCount = 0;
+let errorCount = 0;
+
+for (const location of locations) {
+  const result = await mapper.mapSafe(location);
+  
+  if (!result.success) {
+    errorCount++;
+    logger.error(`Failed to map location ${location.ref}:`, result.errors);
+    continue; // Skip to next location
+  }
+
+  try {
+    await client.graphql({
+      query: result.query,
+      variables: result.variables,
+    });
+    successCount++;
+  } catch (apiError) {
+    errorCount++;
+    logger.error(`API error for location ${location.ref}:`, apiError);
+  }
+}
+
+console.log(`✅ Processed: ${successCount} successful, ${errorCount} errors`);
+```
+
+### Example 2: Webhook Handler with Error Handling
+
+```typescript
+export async function handleWebhook(event: WebhookEvent) {
+  const mapper = new GraphQLMutationMapper(config, logger);
+  
+  const result = await mapper.mapSafe(event.payload);
+  
+  if (!result.success) {
+    // Log error but don't crash the webhook handler
+    logger.error('Webhook mapping failed:', {
+      eventId: event.id,
+      errors: result.errors,
+    });
+    
+    // Return error response to webhook caller
+    return {
+      statusCode: 400,
+      body: JSON.stringify({ errors: result.errors }),
+    };
+  }
+
+  // Execute mutation
+  const apiResult = await client.graphql({
+    query: result.query,
+    variables: result.variables,
+  });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(apiResult),
+  };
+}
+```
+
+### Example 3: Retry Logic with Error Handling
+
+```typescript
+async function mapWithRetry(
+  mapper: GraphQLMutationMapper,
+  sourceData: any,
+  maxRetries = 3
+): Promise<MapResult> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const result = await mapper.mapSafe(sourceData);
+    
+    if (result.success) {
+      return result;
+    }
+
+    // Log error
+    logger.warn(`Mapping attempt ${attempt} failed:`, result.errors);
+    
+    // Wait before retry (exponential backoff)
+    if (attempt < maxRetries) {
+      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+    }
+  }
+
+  // All retries failed
+  return {
+    success: false,
+    query: '',
+    variables: {},
+    errors: ['All retry attempts failed'],
+  };
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+1. **Use `mapSafe()` in production code**
+   - More robust error handling
+   - Better for batch processing
+   - Consistent with `UniversalMapper` pattern
+
+2. **Check `result.success` before proceeding**
+   ```typescript
+   const result = await mapper.mapSafe(data);
+   if (!result.success) {
+     // Handle error
+     return;
+   }
+   // Proceed with success case
+   ```
+
+3. **Log errors with context**
+   ```typescript
+   if (!result.success) {
+     logger.error('Mapping failed', {
+       sourceData: data,
+       errors: result.errors,
+       timestamp: new Date().toISOString(),
+     });
+   }
+   ```
+
+4. **Handle errors gracefully in batch processing**
+   - Don't stop entire batch on single error
+   - Log errors but continue processing
+   - Track success/error counts
+
+### ❌ DON'T
+
+1. **Don't ignore errors**
+   ```typescript
+   // ❌ BAD - ignores errors
+   const result = await mapper.mapSafe(data);
+   await client.graphql({ query: result.query, variables: result.variables });
+   ```
+
+2. **Don't use `map()` without try/catch**
+   ```typescript
+   // ❌ BAD - unhandled exception
+   const payload = await mapper.map(data);
+   await client.graphql(payload);
+   ```
+
+3. **Don't assume success**
+   ```typescript
+   // ❌ BAD - doesn't check success
+   const result = await mapper.mapSafe(data);
+   await client.graphql({ query: result.query, variables: result.variables });
+   ```
+
+---
+
+## Migration Guide
+
+### Migrating from `map()` to `mapSafe()`
+
+**Before:**
+```typescript
+try {
+  const payload = await mapper.map(sourceData);
+  await client.graphql(payload);
+} catch (error) {
+  console.error('Error:', error);
+}
+```
+
+**After:**
+```typescript
+const result = await mapper.mapSafe(sourceData);
+if (!result.success) {
+  console.error('Error:', result.errors);
+  return;
+}
+await client.graphql({ query: result.query, variables: result.variables });
+```
+
+**Benefits:**
+- No try/catch needed
+- Structured error information (`result.errors` array)
+- Easier to handle in batch processing
+- Consistent with `UniversalMapper` pattern
+
+---
+
+## GraphQL Error Classification
+
+After executing a GraphQL mutation, you may receive errors from the Fluent Commerce API. The SDK provides error classification to help determine if errors are retryable:
+
+```typescript
+import { classifyErrors, type GraphQLError } from '@fluentcommerce/fc-connect-sdk';
+
+const result = await client.graphql({
+  query: result.query,
+  variables: result.variables,
+});
+
+if (result.errors) {
+  const classification = classifyErrors(result.errors);
+  
+  if (classification.retryable) {
+    // Wait and retry
+    await delay(classification.retryDelaySeconds * 1000);
+    // retry logic...
+  } else {
+    // Don't retry - show error to user
+    logger.error('Non-retryable error:', {
+      errorCode: classification.errorCode,
+      message: classification.userMessage,
+      action: classification.action,
+    });
+  }
+}
+```
+
+**Error Classification Result:**
+```typescript
+interface ErrorClassification {
+  retryable: boolean;              // Whether to retry
+  category: 'CLIENT_ERROR' | 'SERVER_ERROR' | 'THIRD_PARTY_ERROR' | 'UNKNOWN';
+  userMessage: string;              // User-friendly message
+  action: 'FIX_AND_RETRY' | 'RETRY_LATER' | 'CONTACT_SUPPORT' | 'VERIFY_PAYLOAD';
+  retryDelaySeconds?: number;       // Recommended delay (if retryable)
+  errorCode?: string;               // Error code (e.g., 'C0121E')
+}
+```
+
+**Common Error Codes:**
+- **C0121E** - Order already exists (non-retryable, verify payload)
+- **C0140E** - Missing required variables (non-retryable, fix and retry)
+- **S0002E** - Server error (retryable, retry later)
+- **C0011E** - Rate limit exceeded (retryable, retry later)
+
+See [GraphQL Error Classification Guide](../api-reference/graphql-error-classification.md) for complete error code reference.
+
+---
+
+## Related Documentation
+
+- [Mapper Comparison Guide](./mapping-mapper-comparison-guide.md) - Complete mapper comparison
+- [Resolver Registration Guide](./resolver-registration.md) - How to register custom resolvers
+- [GraphQL Mutation Mapping](../graphql-mutation-mapping/) - GraphQLMutationMapper details
+- [Universal Mapping](./) - UniversalMapper details
+- [GraphQL Error Classification](../api-reference/graphql-error-classification.md) - Error code reference
+