@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/03-PATTERN-GUIDES/error-handling/examples/common-patterns.ts

@@ -1,438 +1,438 @@
-/**
- * Common Error Handling Patterns
- *
- * Copy-paste ready error handling snippets for the Fluent Connect SDK
- */
-
-import {
-  createClient,
-  XMLParserService,
-  GraphQLMutationMapper,
-  FileParsingError,
-  PathResolutionError,
-  MappingError,
-  ValidationError,
-  IngestionError,
-  IngestionErrorCode,
-  GraphQLExecutionError,
-  FluentAPIError
-} from '@fluentcommerce/fc-connect-sdk';
-
-// ============================================================================
-// Pattern 1: Basic Try-Catch
-// ============================================================================
-
-async function basicErrorHandling(data: string) {
-  try {
-    const parser = new XMLParserService();
-    const parsed = await parser.parse(data);
-    return parsed;
-
-  } catch (error) {
-    // Always log errors
-    console.error('Processing failed:', error);
-
-    // Always re-throw (don't silence errors!)
-    throw error;
-  }
-}
-
-// ============================================================================
-// Pattern 2: Type-Specific Error Handling
-// ============================================================================
-
-async function typeSpecificHandling(xmlContent: string) {
-  const logger = console;
-
-  try {
-    const parser = new XMLParserService();
-    const parsed = await parser.parse(xmlContent);
-    return parsed;
-
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      // Parse error - permanent failure
-      logger.error('Parse error (permanent):', {
-        fileName: error.fileName,
-        lineNumber: error.lineNumber,
-        code: error.code
-      });
-      throw error;  // Don't retry
-
-    } else if (error instanceof PathResolutionError) {
-      // Path error - configuration issue
-      logger.error('Path error (permanent):', {
-        path: error.path
-      });
-      throw error;  // Don't retry
-
-    } else if (error instanceof MappingError) {
-      // Mapping error - data or config issue
-      logger.error('Mapping error (permanent):', {
-        field: error.field,
-        sourcePath: error.sourcePath
-      });
-      throw error;  // Don't retry
-
-    } else if (error instanceof IngestionError) {
-      // Check if retryable
-      if (error.isRetryable()) {
-        logger.info('Retryable error - will retry');
-        // Implement retry logic
-      } else {
-        logger.error('Non-retryable ingestion error');
-        throw error;
-      }
-    }
-
-    // Unknown error
-    throw error;
-  }
-}
-
-// ============================================================================
-// Pattern 3: Using isRetryable()
-// ============================================================================
-
-async function checkRetryable(operation: () => Promise<any>) {
-  try {
-    return await operation();
-
-  } catch (error) {
-    if (error instanceof IngestionError && error.isRetryable()) {
-      console.log('Error is retryable:', error.code);
-      // Implement retry with exponential backoff
-      return scheduleRetry(operation);
-    }
-
-    // Not retryable - fail immediately
-    throw error;
-  }
-}
-
-function scheduleRetry(operation: () => Promise<any>): Promise<any> {
-  // Implement retry logic here
-  return new Promise((resolve) => {
-    setTimeout(() => resolve(operation()), 1000);
-  });
-}
-
-// ============================================================================
-// Pattern 4: Structured Logging with toJSON()
-// ============================================================================
-
-async function structuredLogging(data: any, metadata: any) {
-  const logger = console;
-
-  try {
-    return await processData(data);
-
-  } catch (error) {
-    // Use toJSON() for complete error data
-    const errorData = error instanceof IngestionError
-      ? error.toJSON()
-      : { message: error.message, stack: error.stack };
-
-    // Log with business context
-    logger.error('Processing failed:', {
-      ...errorData,
-      orderId: metadata.orderId,
-      customerId: metadata.customerId,
-      fileName: metadata.fileName,
-      environment: process.env.NODE_ENV,
-      timestamp: new Date().toISOString()
-    });
-
-    throw error;
-  }
-}
-
-async function processData(data: any): Promise<any> {
-  return data;
-}
-
-// ============================================================================
-// Pattern 5: Rate Limit Handling
-// ============================================================================
-
-async function handleRateLimit(operation: () => Promise<any>, maxRetries = 3) {
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await operation();
-
-    } catch (error) {
-      if (error instanceof IngestionError &&
-          error.code === IngestionErrorCode.RATE_LIMIT_ERROR) {
-
-        // Get retry-after from error context
-        const retryAfter = error.context?.retryAfter || 60;
-
-        console.log(`Rate limited - waiting ${retryAfter} seconds`);
-
-        if (attempt < maxRetries - 1) {
-          // Wait for rate limit to reset
-          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
-          continue;
-        }
-      }
-
-      // Not a rate limit error or max retries exceeded
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-
-// ============================================================================
-// Pattern 6: Network Error with Retry
-// ============================================================================
-
-async function handleNetworkError(operation: () => Promise<any>, maxRetries = 3) {
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await operation();
-
-    } catch (error) {
-      if (error instanceof IngestionError &&
-          error.code === IngestionErrorCode.NETWORK_ERROR) {
-
-        if (attempt < maxRetries - 1) {
-          // Exponential backoff
-          const delay = Math.pow(2, attempt) * 1000;
-          console.log(`Network error - retrying in ${delay}ms`);
-
-          await new Promise(resolve => setTimeout(resolve, delay));
-          continue;
-        }
-      }
-
-      // Not a network error or max retries exceeded
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-
-// ============================================================================
-// Pattern 7: Validation Error Details
-// ============================================================================
-
-async function handleValidationErrors(data: any) {
-  try {
-    return await validateAndProcess(data);
-
-  } catch (error) {
-    if (error instanceof ValidationError) {
-      console.error('Validation failed:');
-
-      // Log each validation error
-      error.validationErrors.forEach(validationError => {
-        console.error(`- Field '${validationError.field}': ${validationError.message}`);
-        console.error(`  Value: ${validationError.value}`);
-        console.error(`  Rule: ${validationError.rule}`);
-      });
-
-      throw error;  // Don't retry validation errors
-    }
-
-    throw error;
-  }
-}
-
-async function validateAndProcess(data: any): Promise<any> {
-  return data;
-}
-
-// ============================================================================
-// Pattern 8: Adding Correlation IDs
-// ============================================================================
-
-import { v4 as uuidv4 } from 'uuid';
-
-async function withCorrelationId(
-  operation: () => Promise<any>,
-  correlationId?: string
-) {
-  const id = correlationId || uuidv4();
-
-  try {
-    console.log(`[${id}] Operation started`);
-
-    const result = await operation();
-
-    console.log(`[${id}] Operation completed`);
-    return result;
-
-  } catch (error) {
-    const errorData = error instanceof IngestionError
-      ? error.toJSON()
-      : { message: error.message };
-
-    console.error(`[${id}] Operation failed:`, errorData);
-    throw error;
-  }
-}
-
-// ============================================================================
-// Pattern 9: Dead Letter Queue for Parse Errors
-// ============================================================================
-
-async function handleWithDeadLetter(xmlContent: string, fileName: string) {
-  try {
-    const parser = new XMLParserService();
-    return await parser.parse(xmlContent);
-
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      // Save to dead letter queue for manual review
-      await saveToDeadLetterQueue({
-        fileName,
-        content: xmlContent,
-        error: error.toJSON(),
-        timestamp: new Date().toISOString()
-      });
-
-      console.error('Parse error - saved to dead letter queue:', fileName);
-      throw error;  // Don't retry
-    }
-
-    throw error;
-  }
-}
-
-async function saveToDeadLetterQueue(item: any): Promise<void> {
-  // Implementation: Save to S3, database, or queue system
-  console.log('Saving to dead letter queue:', item.fileName);
-}
-
-// ============================================================================
-// Pattern 10: Comprehensive Error Handler
-// ============================================================================
-
-async function comprehensiveErrorHandler(
-  xmlContent: string,
-  metadata: any,
-  maxRetries = 3
-) {
-  const logger = console;
-  const correlationId = metadata.correlationId || uuidv4();
-
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      logger.info(`[${correlationId}] Processing attempt ${attempt + 1}/${maxRetries}`);
-
-      // Parse
-      const parser = new XMLParserService();
-      const parsed = await parser.parse(xmlContent);
-
-      // Map
-      const mapper = new GraphQLMutationMapper(
-        metadata.mappingConfig,
-        metadata.client,
-        logger
-      );
-      const payload = await mapper.map(parsed);
-
-      // Execute
-      const result = await metadata.client.graphql(payload);
-      logger.info(`[${correlationId}] Processing succeeded`);
-      return result.data;
-
-    } catch (error) {
-      // Log with full context
-      const errorContext = {
-        correlationId,
-        attempt: attempt + 1,
-        maxRetries,
-        orderId: metadata.orderId,
-        fileName: metadata.fileName,
-        error: error instanceof IngestionError ? error.toJSON() : error.message
-      };
-
-      // Check error type and decide whether to retry
-      if (error instanceof GraphQLExecutionError) {
-        // Check if retryable (e.g. timeout)
-        const firstError = error.graphqlErrors[0];
-        if (firstError?.extensions?.code === 'TIMEOUT' && attempt < maxRetries) {
-           const delay = Math.pow(2, attempt) * 1000;
-           logger.warn(`GraphQL timeout - retry in ${delay}ms`, errorContext);
-           await new Promise(resolve => setTimeout(resolve, delay));
-           continue;
-        }
-        // Permanent GraphQL error
-        logger.error('GraphQL error (permanent):', errorContext);
-        throw error;
-
-      } else if (error instanceof FluentAPIError) {
-        // Retry 5xx errors
-        if (error.statusCode >= 500 && attempt < maxRetries) {
-           const delay = Math.pow(2, attempt) * 1000;
-           logger.warn(`API error - retry in ${delay}ms`, errorContext);
-           await new Promise(resolve => setTimeout(resolve, delay));
-           continue;
-        }
-        throw error;
-
-      } else if (error instanceof FileParsingError) {
-        logger.error('Parse error (permanent):', errorContext);
-        await saveToDeadLetterQueue({ ...metadata, error: error.toJSON() });
-        throw error;  // Don't retry
-
-      } else if (error instanceof PathResolutionError) {
-        logger.error('Path error (permanent):', errorContext);
-        throw error;  // Don't retry
-
-      } else if (error instanceof MappingError) {
-        logger.error('Mapping error (permanent):', errorContext);
-        throw error;  // Don't retry
-
-      } else if (error instanceof IngestionError) {
-        if (!error.isRetryable()) {
-          logger.error('Non-retryable error:', errorContext);
-          throw error;
-        }
-
-        // Handle rate limiting
-        if (error.code === IngestionErrorCode.RATE_LIMIT_ERROR) {
-          const retryAfter = error.context?.retryAfter || 60;
-          logger.warn(`Rate limited - waiting ${retryAfter}s`, errorContext);
-          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
-          continue;
-        }
-
-        // Retry with exponential backoff
-        if (attempt < maxRetries - 1) {
-          const delay = Math.pow(2, attempt) * 1000;
-          logger.warn(`Retryable error - retry in ${delay}ms`, errorContext);
-          await new Promise(resolve => setTimeout(resolve, delay));
-          continue;
-        }
-
-        logger.error('Max retries exceeded:', errorContext);
-      }
-
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-
-// ============================================================================
-// Export all patterns
-// ============================================================================
-
-export {
-  basicErrorHandling,
-  typeSpecificHandling,
-  checkRetryable,
-  structuredLogging,
-  handleRateLimit,
-  handleNetworkError,
-  handleValidationErrors,
-  withCorrelationId,
-  handleWithDeadLetter,
-  comprehensiveErrorHandler
-};
+/**
+ * Common Error Handling Patterns
+ *
+ * Copy-paste ready error handling snippets for the Fluent Connect SDK
+ */
+
+import {
+  createClient,
+  XMLParserService,
+  GraphQLMutationMapper,
+  FileParsingError,
+  PathResolutionError,
+  MappingError,
+  ValidationError,
+  IngestionError,
+  IngestionErrorCode,
+  GraphQLExecutionError,
+  FluentAPIError
+} from '@fluentcommerce/fc-connect-sdk';
+
+// ============================================================================
+// Pattern 1: Basic Try-Catch
+// ============================================================================
+
+async function basicErrorHandling(data: string) {
+  try {
+    const parser = new XMLParserService();
+    const parsed = await parser.parse(data);
+    return parsed;
+
+  } catch (error) {
+    // Always log errors
+    console.error('Processing failed:', error);
+
+    // Always re-throw (don't silence errors!)
+    throw error;
+  }
+}
+
+// ============================================================================
+// Pattern 2: Type-Specific Error Handling
+// ============================================================================
+
+async function typeSpecificHandling(xmlContent: string) {
+  const logger = console;
+
+  try {
+    const parser = new XMLParserService();
+    const parsed = await parser.parse(xmlContent);
+    return parsed;
+
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      // Parse error - permanent failure
+      logger.error('Parse error (permanent):', {
+        fileName: error.fileName,
+        lineNumber: error.lineNumber,
+        code: error.code
+      });
+      throw error;  // Don't retry
+
+    } else if (error instanceof PathResolutionError) {
+      // Path error - configuration issue
+      logger.error('Path error (permanent):', {
+        path: error.path
+      });
+      throw error;  // Don't retry
+
+    } else if (error instanceof MappingError) {
+      // Mapping error - data or config issue
+      logger.error('Mapping error (permanent):', {
+        field: error.field,
+        sourcePath: error.sourcePath
+      });
+      throw error;  // Don't retry
+
+    } else if (error instanceof IngestionError) {
+      // Check if retryable
+      if (error.isRetryable()) {
+        logger.info('Retryable error - will retry');
+        // Implement retry logic
+      } else {
+        logger.error('Non-retryable ingestion error');
+        throw error;
+      }
+    }
+
+    // Unknown error
+    throw error;
+  }
+}
+
+// ============================================================================
+// Pattern 3: Using isRetryable()
+// ============================================================================
+
+async function checkRetryable(operation: () => Promise<any>) {
+  try {
+    return await operation();
+
+  } catch (error) {
+    if (error instanceof IngestionError && error.isRetryable()) {
+      console.log('Error is retryable:', error.code);
+      // Implement retry with exponential backoff
+      return scheduleRetry(operation);
+    }
+
+    // Not retryable - fail immediately
+    throw error;
+  }
+}
+
+function scheduleRetry(operation: () => Promise<any>): Promise<any> {
+  // Implement retry logic here
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(operation()), 1000);
+  });
+}
+
+// ============================================================================
+// Pattern 4: Structured Logging with toJSON()
+// ============================================================================
+
+async function structuredLogging(data: any, metadata: any) {
+  const logger = console;
+
+  try {
+    return await processData(data);
+
+  } catch (error) {
+    // Use toJSON() for complete error data
+    const errorData = error instanceof IngestionError
+      ? error.toJSON()
+      : { message: error.message, stack: error.stack };
+
+    // Log with business context
+    logger.error('Processing failed:', {
+      ...errorData,
+      orderId: metadata.orderId,
+      customerId: metadata.customerId,
+      fileName: metadata.fileName,
+      environment: process.env.NODE_ENV,
+      timestamp: new Date().toISOString()
+    });
+
+    throw error;
+  }
+}
+
+async function processData(data: any): Promise<any> {
+  return data;
+}
+
+// ============================================================================
+// Pattern 5: Rate Limit Handling
+// ============================================================================
+
+async function handleRateLimit(operation: () => Promise<any>, maxRetries = 3) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await operation();
+
+    } catch (error) {
+      if (error instanceof IngestionError &&
+          error.code === IngestionErrorCode.RATE_LIMIT_ERROR) {
+
+        // Get retry-after from error context
+        const retryAfter = error.context?.retryAfter || 60;
+
+        console.log(`Rate limited - waiting ${retryAfter} seconds`);
+
+        if (attempt < maxRetries - 1) {
+          // Wait for rate limit to reset
+          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
+          continue;
+        }
+      }
+
+      // Not a rate limit error or max retries exceeded
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+
+// ============================================================================
+// Pattern 6: Network Error with Retry
+// ============================================================================
+
+async function handleNetworkError(operation: () => Promise<any>, maxRetries = 3) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await operation();
+
+    } catch (error) {
+      if (error instanceof IngestionError &&
+          error.code === IngestionErrorCode.NETWORK_ERROR) {
+
+        if (attempt < maxRetries - 1) {
+          // Exponential backoff
+          const delay = Math.pow(2, attempt) * 1000;
+          console.log(`Network error - retrying in ${delay}ms`);
+
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+      }
+
+      // Not a network error or max retries exceeded
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+
+// ============================================================================
+// Pattern 7: Validation Error Details
+// ============================================================================
+
+async function handleValidationErrors(data: any) {
+  try {
+    return await validateAndProcess(data);
+
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      console.error('Validation failed:');
+
+      // Log each validation error
+      error.validationErrors.forEach(validationError => {
+        console.error(`- Field '${validationError.field}': ${validationError.message}`);
+        console.error(`  Value: ${validationError.value}`);
+        console.error(`  Rule: ${validationError.rule}`);
+      });
+
+      throw error;  // Don't retry validation errors
+    }
+
+    throw error;
+  }
+}
+
+async function validateAndProcess(data: any): Promise<any> {
+  return data;
+}
+
+// ============================================================================
+// Pattern 8: Adding Correlation IDs
+// ============================================================================
+
+import { v4 as uuidv4 } from 'uuid';
+
+async function withCorrelationId(
+  operation: () => Promise<any>,
+  correlationId?: string
+) {
+  const id = correlationId || uuidv4();
+
+  try {
+    console.log(`[${id}] Operation started`);
+
+    const result = await operation();
+
+    console.log(`[${id}] Operation completed`);
+    return result;
+
+  } catch (error) {
+    const errorData = error instanceof IngestionError
+      ? error.toJSON()
+      : { message: error.message };
+
+    console.error(`[${id}] Operation failed:`, errorData);
+    throw error;
+  }
+}
+
+// ============================================================================
+// Pattern 9: Dead Letter Queue for Parse Errors
+// ============================================================================
+
+async function handleWithDeadLetter(xmlContent: string, fileName: string) {
+  try {
+    const parser = new XMLParserService();
+    return await parser.parse(xmlContent);
+
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      // Save to dead letter queue for manual review
+      await saveToDeadLetterQueue({
+        fileName,
+        content: xmlContent,
+        error: error.toJSON(),
+        timestamp: new Date().toISOString()
+      });
+
+      console.error('Parse error - saved to dead letter queue:', fileName);
+      throw error;  // Don't retry
+    }
+
+    throw error;
+  }
+}
+
+async function saveToDeadLetterQueue(item: any): Promise<void> {
+  // Implementation: Save to S3, database, or queue system
+  console.log('Saving to dead letter queue:', item.fileName);
+}
+
+// ============================================================================
+// Pattern 10: Comprehensive Error Handler
+// ============================================================================
+
+async function comprehensiveErrorHandler(
+  xmlContent: string,
+  metadata: any,
+  maxRetries = 3
+) {
+  const logger = console;
+  const correlationId = metadata.correlationId || uuidv4();
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      logger.info(`[${correlationId}] Processing attempt ${attempt + 1}/${maxRetries}`);
+
+      // Parse
+      const parser = new XMLParserService();
+      const parsed = await parser.parse(xmlContent);
+
+      // Map
+      const mapper = new GraphQLMutationMapper(
+        metadata.mappingConfig,
+        metadata.client,
+        logger
+      );
+      const payload = await mapper.map(parsed);
+
+      // Execute
+      const result = await metadata.client.graphql(payload);
+      logger.info(`[${correlationId}] Processing succeeded`);
+      return result.data;
+
+    } catch (error) {
+      // Log with full context
+      const errorContext = {
+        correlationId,
+        attempt: attempt + 1,
+        maxRetries,
+        orderId: metadata.orderId,
+        fileName: metadata.fileName,
+        error: error instanceof IngestionError ? error.toJSON() : error.message
+      };
+
+      // Check error type and decide whether to retry
+      if (error instanceof GraphQLExecutionError) {
+        // Check if retryable (e.g. timeout)
+        const firstError = error.graphqlErrors[0];
+        if (firstError?.extensions?.code === 'TIMEOUT' && attempt < maxRetries) {
+           const delay = Math.pow(2, attempt) * 1000;
+           logger.warn(`GraphQL timeout - retry in ${delay}ms`, errorContext);
+           await new Promise(resolve => setTimeout(resolve, delay));
+           continue;
+        }
+        // Permanent GraphQL error
+        logger.error('GraphQL error (permanent):', errorContext);
+        throw error;
+
+      } else if (error instanceof FluentAPIError) {
+        // Retry 5xx errors
+        if (error.statusCode >= 500 && attempt < maxRetries) {
+           const delay = Math.pow(2, attempt) * 1000;
+           logger.warn(`API error - retry in ${delay}ms`, errorContext);
+           await new Promise(resolve => setTimeout(resolve, delay));
+           continue;
+        }
+        throw error;
+
+      } else if (error instanceof FileParsingError) {
+        logger.error('Parse error (permanent):', errorContext);
+        await saveToDeadLetterQueue({ ...metadata, error: error.toJSON() });
+        throw error;  // Don't retry
+
+      } else if (error instanceof PathResolutionError) {
+        logger.error('Path error (permanent):', errorContext);
+        throw error;  // Don't retry
+
+      } else if (error instanceof MappingError) {
+        logger.error('Mapping error (permanent):', errorContext);
+        throw error;  // Don't retry
+
+      } else if (error instanceof IngestionError) {
+        if (!error.isRetryable()) {
+          logger.error('Non-retryable error:', errorContext);
+          throw error;
+        }
+
+        // Handle rate limiting
+        if (error.code === IngestionErrorCode.RATE_LIMIT_ERROR) {
+          const retryAfter = error.context?.retryAfter || 60;
+          logger.warn(`Rate limited - waiting ${retryAfter}s`, errorContext);
+          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
+          continue;
+        }
+
+        // Retry with exponential backoff
+        if (attempt < maxRetries - 1) {
+          const delay = Math.pow(2, attempt) * 1000;
+          logger.warn(`Retryable error - retry in ${delay}ms`, errorContext);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+
+        logger.error('Max retries exceeded:', errorContext);
+      }
+
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+
+// ============================================================================
+// Export all patterns
+// ============================================================================
+
+export {
+  basicErrorHandling,
+  typeSpecificHandling,
+  checkRetryable,
+  structuredLogging,
+  handleRateLimit,
+  handleNetworkError,
+  handleValidationErrors,
+  withCorrelationId,
+  handleWithDeadLetter,
+  comprehensiveErrorHandler
+};