@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/readme.md

@@ -1,194 +1,194 @@
-# Core Guides
-
-> **Comprehensive documentation for FC Connect SDK core features**
-> Complete guides covering all fundamental SDK capabilities
-
-## Overview
-
-The Core Guides section provides in-depth documentation for all essential SDK features. Each guide is designed as a progressive learning path with modular structure, examples, and best practices.
-
-## Available Guides
-
-### Data Integration
-
-| Guide | Description | Level | Status |
-|-------|-------------|-------|--------|
-| **[Ingestion](./ingestion/)** | External data → Fluent Commerce | Intermediate | Complete |
-| **[Extraction](./extraction/)** | Fluent Commerce → External systems | Intermediate | Complete |
-| **[Auto-Pagination](./auto-pagination/)** | Automatic pagination for large datasets | Beginner | Complete |
-
-### Data Transformation
-
-| Guide | Description | Level | Status |
-|-------|-------------|-------|--------|
-| **[Mapping](./mapping/)** | Field transformation with UniversalMapper | Intermediate | Complete |
-| **[GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/)** | GraphQL mutation generation from data | Advanced | Complete |
-| **[Resolvers](./mapping/resolvers/)** | Custom transformation resolvers | Advanced | Complete |
-
-### Data Parsing
-
-| Guide | Description | Level | Status |
-|-------|-------------|-------|--------|
-| **[Parsers](./parsers/)** | CSV, XML, JSON, Parquet parsers | Beginner | Complete |
-| **[Data Sources](./data-sources/)** | S3, SFTP, local file operations | Intermediate | Complete |
-
-### Advanced Features
-
-| Guide | Description | Level | Status |
-|-------|-------------|-------|--------|
-| **[Webhook Validation](./webhook-validation/)** | Secure webhook integration | Intermediate | Complete |
-| **[Advanced Services](./advanced-services/)** | Batch archival, job tracking, recovery | Advanced | Complete |
-| **[API Reference](./api-reference/)** | Complete SDK API documentation | Reference | Complete |
-
-## Quick Navigation
-
-### By Use Case
-
-| I Want To... | Start Here | Then See |
-|--|--|--|
-| **Ingest inventory from S3** | [Ingestion Guide](./ingestion/) | [Data Sources](./data-sources/), [Parsers](./parsers/) |
-| **Extract orders to SFTP** | [Extraction Guide](./extraction/) | [Auto-Pagination](./auto-pagination/), [Data Sources](./data-sources/) |
-| **Transform CSV data** | [Mapping Guide](./mapping/) | [Parsers](./parsers/), [Resolvers](./mapping/resolvers/) |
-| **Parse XML files** | [Parsers Guide](./parsers/) | [Mapping](./mapping/) |
-| **Create GraphQL mutations** | [GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/) | [Mapping](./mapping/) |
-| **Handle large datasets** | [Auto-Pagination](./auto-pagination/) | [Extraction](./extraction/) |
-| **Validate webhooks** | [Webhook Validation](./webhook-validation/) | [API Reference](./api-reference/) |
-
-### By Skill Level
-
-**Beginner** (Start here if new to SDK)
-- [Auto-Pagination](./auto-pagination/) - Automatic pagination basics
-- [Parsers](./parsers/) - Reading CSV, JSON, XML files
-- [Data Sources](./data-sources/) - Working with S3, SFTP
-
-**Intermediate** (Core integration patterns)
-- [Ingestion](./ingestion/) - Complete data ingestion workflows
-- [Extraction](./extraction/) - Data extraction patterns
-- [Mapping](./mapping/) - Field transformation
-- [Webhook Validation](./webhook-validation/) - Secure webhook handling
-
-**Advanced** (Complex scenarios)
-- [GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/) - Dynamic mutation generation
-- [Resolvers](./mapping/resolvers/) - Custom transformation logic
-- [Advanced Services](./advanced-services/) - Batch recovery, archival
-
-### By Data Format
-
-| Format | Parser Guide | Mapping Guide | Example Use Case |
-|--------|--------------|---------------|------------------|
-| **CSV** | [Parsers: CSV](./parsers/) | [Mapping](./mapping/) | Inventory feeds |
-| **XML** | [Parsers: XML](./parsers/) | [Mapping](./mapping/) | Order imports |
-| **JSON** | [Parsers: JSON](./parsers/) | [Mapping](./mapping/) | API responses |
-| **Parquet** | [Parsers: Parquet](./parsers/) | [Extraction](./extraction/) | Analytics exports |
-
-## Guide Structure
-
-Each guide follows a consistent structure:
-
-```
-guide-name/
-├── readme.md                    # Main index (this file)
-├── quick-reference.md           # Cheat sheet
-├── modules/                     # Learning modules
-│   ├── readme.md                # Modules index
-│   ├── 01-foundations.md        # Concepts
-│   ├── 02-quick-start.md        # First example
-│   ├── 03-...md                 # Progressive topics
-│   └── XX-api-reference.md      # Complete API
-└── examples/                    # Code examples
-    ├── readme.md                # Examples index
-    └── *.ts                     # Runnable examples
-```
-
-## Documentation Conventions
-
-### Schema Validation
-
-All examples use validated schema fields:
-- ✅ GraphQL queries verified against Fluent schema
-- ✅ Field names match actual API
-- ✅ Types are correct (Int, String, Float)
-- ✅ Pagination patterns follow Relay spec
-
-### Code Examples
-
-- **Complete** - All imports, error handling included
-- **Runnable** - Can be copied and executed
-- **TypeScript** - Fully typed with SDK types
-- **Current** - Use latest SDK version
-
-### Documentation Standards
-
-- **No temporal references** - Avoid "as of 2024", "recently"
-- **No version numbers** - Always reference latest
-- **Real entities** - Use actual Fluent Commerce types
-- **Verified patterns** - All code is tested
-
-## Getting Started
-
-### Prerequisites
-
-Before exploring these guides:
-
-1. ✅ Install SDK: `npm install @fluentcommerce/fc-connect-sdk`
-2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
-3. ✅ Understand TypeScript basics
-4. ✅ Familiar with async/await patterns
-
-### Recommended Learning Path
-
-**Week 1: Foundations**
-1. [Auto-Pagination](./auto-pagination/) - Learn pagination basics (2-3 hours)
-2. [Parsers](./parsers/) - Understand data parsing (2-3 hours)
-3. [Data Sources](./data-sources/) - Work with S3, SFTP (2-3 hours)
-
-**Week 2: Integration**
-4. [Mapping](./mapping/) - Transform data (3-4 hours)
-5. [Ingestion](./ingestion/) - Complete ingestion workflow (4-5 hours)
-6. [Extraction](./extraction/) - Extract data patterns (3-4 hours)
-
-**Week 3: Advanced**
-7. [Webhook Validation](./webhook-validation/) - Secure webhooks (2 hours)
-8. [GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/) - Dynamic mutations (3-4 hours)
-9. [Resolvers](./mapping/resolvers/) - Custom logic (2-3 hours)
-10. [Advanced Services](./advanced-services/) - Production patterns (2-3 hours)
-
-## Related Documentation
-
-### SDK Documentation
-- [00-START-HERE](../00-START-HERE/) - Getting started guides
-- [01-TEMPLATES](../01-TEMPLATES/) - Production-ready templates
-- [03-PATTERN-GUIDES](../03-PATTERN-GUIDES/) - Integration patterns
-- [04-REFERENCE](../04-REFERENCE/) - Technical reference
-
-### External Resources
-- [npm Package](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-- [Fluent Commerce Docs](https://docs.fluentcommerce.com/)
-- [GitHub Repository](https://github.com/fluentcommerce/fc-connect-sdk)
-
-## Additional Resources
-
-### Quick References
-- [Ingestion Quick Reference](./ingestion/ingestion-quick-reference.md)
-- [Extraction Quick Reference](./extraction/extraction-quick-reference.md)
-- [Auto-Pagination Quick Reference](./auto-pagination/auto-pagination-quick-reference.md)
-- [Mapping Quick Reference](./mapping/mapping-readme.md)
-
-### API Documentation
-- [Complete API Reference](./api-reference/)
-- [Logging Guide](./logging-guide.md)
-
-## Support
-
-Need help?
-- Browse guide examples
-- Check quick reference sheets
-- Review troubleshooting sections
-- Contact support@fluentcommerce.com
-
----
-
-**Next Steps:**
-- New to SDK? Start with [Auto-Pagination Guide](./auto-pagination/)
-- Need data ingestion? See [Ingestion Guide](./ingestion/)
-- Want to extract data? Check [Extraction Guide](./extraction/)
+# Core Guides
+
+> **Comprehensive documentation for FC Connect SDK core features**
+> Complete guides covering all fundamental SDK capabilities
+
+## Overview
+
+The Core Guides section provides in-depth documentation for all essential SDK features. Each guide is designed as a progressive learning path with modular structure, examples, and best practices.
+
+## Available Guides
+
+### Data Integration
+
+| Guide | Description | Level | Status |
+|-------|-------------|-------|--------|
+| **[Ingestion](./ingestion/)** | External data → Fluent Commerce | Intermediate | Complete |
+| **[Extraction](./extraction/)** | Fluent Commerce → External systems | Intermediate | Complete |
+| **[Auto-Pagination](./auto-pagination/)** | Automatic pagination for large datasets | Beginner | Complete |
+
+### Data Transformation
+
+| Guide | Description | Level | Status |
+|-------|-------------|-------|--------|
+| **[Mapping](./mapping/)** | Field transformation with UniversalMapper | Intermediate | Complete |
+| **[GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/)** | GraphQL mutation generation from data | Advanced | Complete |
+| **[Resolvers](./mapping/resolvers/)** | Custom transformation resolvers | Advanced | Complete |
+
+### Data Parsing
+
+| Guide | Description | Level | Status |
+|-------|-------------|-------|--------|
+| **[Parsers](./parsers/)** | CSV, XML, JSON, Parquet parsers | Beginner | Complete |
+| **[Data Sources](./data-sources/)** | S3, SFTP, local file operations | Intermediate | Complete |
+
+### Advanced Features
+
+| Guide | Description | Level | Status |
+|-------|-------------|-------|--------|
+| **[Webhook Validation](./webhook-validation/)** | Secure webhook integration | Intermediate | Complete |
+| **[Advanced Services](./advanced-services/)** | Batch archival, job tracking, recovery | Advanced | Complete |
+| **[API Reference](./api-reference/)** | Complete SDK API documentation | Reference | Complete |
+
+## Quick Navigation
+
+### By Use Case
+
+| I Want To... | Start Here | Then See |
+|--|--|--|
+| **Ingest inventory from S3** | [Ingestion Guide](./ingestion/) | [Data Sources](./data-sources/), [Parsers](./parsers/) |
+| **Extract orders to SFTP** | [Extraction Guide](./extraction/) | [Auto-Pagination](./auto-pagination/), [Data Sources](./data-sources/) |
+| **Transform CSV data** | [Mapping Guide](./mapping/) | [Parsers](./parsers/), [Resolvers](./mapping/resolvers/) |
+| **Parse XML files** | [Parsers Guide](./parsers/) | [Mapping](./mapping/) |
+| **Create GraphQL mutations** | [GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/) | [Mapping](./mapping/) |
+| **Handle large datasets** | [Auto-Pagination](./auto-pagination/) | [Extraction](./extraction/) |
+| **Validate webhooks** | [Webhook Validation](./webhook-validation/) | [API Reference](./api-reference/) |
+
+### By Skill Level
+
+**Beginner** (Start here if new to SDK)
+- [Auto-Pagination](./auto-pagination/) - Automatic pagination basics
+- [Parsers](./parsers/) - Reading CSV, JSON, XML files
+- [Data Sources](./data-sources/) - Working with S3, SFTP
+
+**Intermediate** (Core integration patterns)
+- [Ingestion](./ingestion/) - Complete data ingestion workflows
+- [Extraction](./extraction/) - Data extraction patterns
+- [Mapping](./mapping/) - Field transformation
+- [Webhook Validation](./webhook-validation/) - Secure webhook handling
+
+**Advanced** (Complex scenarios)
+- [GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/) - Dynamic mutation generation
+- [Resolvers](./mapping/resolvers/) - Custom transformation logic
+- [Advanced Services](./advanced-services/) - Batch recovery, archival
+
+### By Data Format
+
+| Format | Parser Guide | Mapping Guide | Example Use Case |
+|--------|--------------|---------------|------------------|
+| **CSV** | [Parsers: CSV](./parsers/) | [Mapping](./mapping/) | Inventory feeds |
+| **XML** | [Parsers: XML](./parsers/) | [Mapping](./mapping/) | Order imports |
+| **JSON** | [Parsers: JSON](./parsers/) | [Mapping](./mapping/) | API responses |
+| **Parquet** | [Parsers: Parquet](./parsers/) | [Extraction](./extraction/) | Analytics exports |
+
+## Guide Structure
+
+Each guide follows a consistent structure:
+
+```
+guide-name/
+├── readme.md                    # Main index (this file)
+├── quick-reference.md           # Cheat sheet
+├── modules/                     # Learning modules
+│   ├── readme.md                # Modules index
+│   ├── 01-foundations.md        # Concepts
+│   ├── 02-quick-start.md        # First example
+│   ├── 03-...md                 # Progressive topics
+│   └── XX-api-reference.md      # Complete API
+└── examples/                    # Code examples
+    ├── readme.md                # Examples index
+    └── *.ts                     # Runnable examples
+```
+
+## Documentation Conventions
+
+### Schema Validation
+
+All examples use validated schema fields:
+- ✅ GraphQL queries verified against Fluent schema
+- ✅ Field names match actual API
+- ✅ Types are correct (Int, String, Float)
+- ✅ Pagination patterns follow Relay spec
+
+### Code Examples
+
+- **Complete** - All imports, error handling included
+- **Runnable** - Can be copied and executed
+- **TypeScript** - Fully typed with SDK types
+- **Current** - Use latest SDK version
+
+### Documentation Standards
+
+- **No temporal references** - Avoid "as of 2024", "recently"
+- **No version numbers** - Always reference latest
+- **Real entities** - Use actual Fluent Commerce types
+- **Verified patterns** - All code is tested
+
+## Getting Started
+
+### Prerequisites
+
+Before exploring these guides:
+
+1. ✅ Install SDK: `npm install @fluentcommerce/fc-connect-sdk`
+2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
+3. ✅ Understand TypeScript basics
+4. ✅ Familiar with async/await patterns
+
+### Recommended Learning Path
+
+**Week 1: Foundations**
+1. [Auto-Pagination](./auto-pagination/) - Learn pagination basics (2-3 hours)
+2. [Parsers](./parsers/) - Understand data parsing (2-3 hours)
+3. [Data Sources](./data-sources/) - Work with S3, SFTP (2-3 hours)
+
+**Week 2: Integration**
+4. [Mapping](./mapping/) - Transform data (3-4 hours)
+5. [Ingestion](./ingestion/) - Complete ingestion workflow (4-5 hours)
+6. [Extraction](./extraction/) - Extract data patterns (3-4 hours)
+
+**Week 3: Advanced**
+7. [Webhook Validation](./webhook-validation/) - Secure webhooks (2 hours)
+8. [GraphQL Mutation Mapping](./mapping/graphql-mutation-mapping/) - Dynamic mutations (3-4 hours)
+9. [Resolvers](./mapping/resolvers/) - Custom logic (2-3 hours)
+10. [Advanced Services](./advanced-services/) - Production patterns (2-3 hours)
+
+## Related Documentation
+
+### SDK Documentation
+- [00-START-HERE](../00-START-HERE/) - Getting started guides
+- [01-TEMPLATES](../01-TEMPLATES/) - Production-ready templates
+- [03-PATTERN-GUIDES](../03-PATTERN-GUIDES/) - Integration patterns
+- [04-REFERENCE](../04-REFERENCE/) - Technical reference
+
+### External Resources
+- [npm Package](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+- [Fluent Commerce Docs](https://docs.fluentcommerce.com/)
+- [GitHub Repository](https://github.com/fluentcommerce/fc-connect-sdk)
+
+## Additional Resources
+
+### Quick References
+- [Ingestion Quick Reference](./ingestion/ingestion-quick-reference.md)
+- [Extraction Quick Reference](./extraction/extraction-quick-reference.md)
+- [Auto-Pagination Quick Reference](./auto-pagination/auto-pagination-quick-reference.md)
+- [Mapping Quick Reference](./mapping/mapping-readme.md)
+
+### API Documentation
+- [Complete API Reference](./api-reference/)
+- [Logging Guide](./logging-guide.md)
+
+## Support
+
+Need help?
+- Browse guide examples
+- Check quick reference sheets
+- Review troubleshooting sections
+- Contact support@fluentcommerce.com
+
+---
+
+**Next Steps:**
+- New to SDK? Start with [Auto-Pagination Guide](./auto-pagination/)
+- Need data ingestion? See [Ingestion Guide](./ingestion/)
+- Want to extract data? Check [Extraction Guide](./extraction/)

package/docs/02-CORE-GUIDES/webhook-validation/examples/basic-validation.ts

@@ -1,108 +1,108 @@
-/**
- * Basic Webhook Validation Example
- *
- * Demonstrates minimal webhook validation pattern.
- */
-
-import {
-  WebhookValidationService,
-  WebhookValidationResult,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Validate a webhook with basic pattern
- */
-async function validateWebhook(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string
-): Promise<boolean> {
-  // Initialize logging
-  const loggingService = createConsoleLogger();
-  const logger = loggingService.createServiceLogger('webhook-validator');
-
-  // Create validator with strict validation
-  const validator = new WebhookValidationService({
-    strictValidation: true
-  }, logger);
-
-  try {
-    // Validate webhook (auto-detects algorithm)
-    const result: WebhookValidationResult = await validator.validateWebhook(
-      rawBody,
-      headers,
-      publicKey
-    );
-
-    if (!result.isValid) {
-      logger.error('Webhook validation failed', {
-        error: result.error,
-        algorithm: result.algorithm,
-        timestamp: result.timestamp.toISOString()
-      });
-      return false;
-    }
-
-    logger.info('Webhook validated successfully', {
-      algorithm: result.algorithm,
-      timestamp: result.timestamp.toISOString()
-    });
-
-    return true;
-
-  } catch (error: any) {
-    logger.error('Validation error', { error: error.message });
-    return false;
-  }
-}
-
-/**
- * Example usage
- */
-async function main() {
-  // Sample webhook data
-  const webhookBody = JSON.stringify({
-    eventId: 'evt_123',
-    entityType: 'ORDER',
-    entityId: 'order_456',
-    timestamp: new Date().toISOString(),
-    data: {
-      ref: 'ORD-123',
-      status: 'PLACED'
-    }
-  });
-
-  // Sample headers (replace with real signature from Fluent Commerce)
-  const webhookHeaders = {
-    'fluent-signature': 'YOUR_REAL_SIGNATURE_HERE',
-    'content-type': 'application/json'
-  };
-
-  // Get public key from environment
-  const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-  if (!publicKey) {
-    console.error('Error: FLUENT_WEBHOOK_PUBLIC_KEY environment variable not set');
-    process.exit(1);
-  }
-
-  // Validate
-  const isValid = await validateWebhook(webhookBody, webhookHeaders, publicKey);
-
-  if (isValid) {
-    console.log('✅ Webhook is valid! Safe to process.');
-    const data = JSON.parse(webhookBody);
-    console.log('Event ID:', data.eventId);
-    console.log('Entity Type:', data.entityType);
-  } else {
-    console.log('❌ Webhook validation failed! Do not process.');
-  }
-}
-
-// Run if executed directly
-if (require.main === module) {
-  main().catch(console.error);
-}
-
-export { validateWebhook };
+/**
+ * Basic Webhook Validation Example
+ *
+ * Demonstrates minimal webhook validation pattern.
+ */
+
+import {
+  WebhookValidationService,
+  WebhookValidationResult,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Validate a webhook with basic pattern
+ */
+async function validateWebhook(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string
+): Promise<boolean> {
+  // Initialize logging
+  const loggingService = createConsoleLogger();
+  const logger = loggingService.createServiceLogger('webhook-validator');
+
+  // Create validator with strict validation
+  const validator = new WebhookValidationService({
+    strictValidation: true
+  }, logger);
+
+  try {
+    // Validate webhook (auto-detects algorithm)
+    const result: WebhookValidationResult = await validator.validateWebhook(
+      rawBody,
+      headers,
+      publicKey
+    );
+
+    if (!result.isValid) {
+      logger.error('Webhook validation failed', {
+        error: result.error,
+        algorithm: result.algorithm,
+        timestamp: result.timestamp.toISOString()
+      });
+      return false;
+    }
+
+    logger.info('Webhook validated successfully', {
+      algorithm: result.algorithm,
+      timestamp: result.timestamp.toISOString()
+    });
+
+    return true;
+
+  } catch (error: any) {
+    logger.error('Validation error', { error: error.message });
+    return false;
+  }
+}
+
+/**
+ * Example usage
+ */
+async function main() {
+  // Sample webhook data
+  const webhookBody = JSON.stringify({
+    eventId: 'evt_123',
+    entityType: 'ORDER',
+    entityId: 'order_456',
+    timestamp: new Date().toISOString(),
+    data: {
+      ref: 'ORD-123',
+      status: 'PLACED'
+    }
+  });
+
+  // Sample headers (replace with real signature from Fluent Commerce)
+  const webhookHeaders = {
+    'fluent-signature': 'YOUR_REAL_SIGNATURE_HERE',
+    'content-type': 'application/json'
+  };
+
+  // Get public key from environment
+  const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+  if (!publicKey) {
+    console.error('Error: FLUENT_WEBHOOK_PUBLIC_KEY environment variable not set');
+    process.exit(1);
+  }
+
+  // Validate
+  const isValid = await validateWebhook(webhookBody, webhookHeaders, publicKey);
+
+  if (isValid) {
+    console.log('✅ Webhook is valid! Safe to process.');
+    const data = JSON.parse(webhookBody);
+    console.log('Event ID:', data.eventId);
+    console.log('Entity Type:', data.entityType);
+  } else {
+    console.log('❌ Webhook validation failed! Do not process.');
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export { validateWebhook };