@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/docs/readme.md

@@ -1,245 +1,245 @@
-# Fluent Commerce Connect SDK Documentation
-
-Comprehensive documentation for the Fluent Commerce Connect SDK - a TypeScript/JavaScript library for building integrations with inventory ingestion and extraction capabilities.
-
-**Current Version:** Latest
-**Node.js:** >= 18.0.0
-**TypeScript:** 5.9.2
-**Platform Support:** Node.js, Deno, Versori
-
-> **Tip:** For installation and quick start, see the main [readme.md](../readme.md). This document provides navigation to detailed guides.
-
----
-
-## 📑 Documentation Index
-
-### 🚀 Quick Start
-
-- **[Getting Started](./00-START-HERE/getting-started.md)** - Installation, configuration, and quick examples
-- **[API Reference](./02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete API documentation for all SDK methods
-- **[SDK Philosophy](./00-START-HERE/sdk-philosophy.md)** - Design principles and architecture decisions
-
-### 🏗️ Architecture
-
-- **[Architecture Overview](./04-REFERENCE/architecture/readme.md)** - Complete SDK architecture documentation
-- **[Client Architecture](./04-REFERENCE/architecture/architecture-02-client-architecture.md)** - Client system design
-- **[Data Flow](./04-REFERENCE/architecture/architecture-03-data-flow.md)** - How data moves through the SDK
-- **[Service Layer](./04-REFERENCE/architecture/architecture-04-service-layer.md)** - Service organization and patterns
-- **[State Management](./04-REFERENCE/architecture/architecture-06-state-management.md)** - State tracking and duplicate prevention
-
-### 🎯 Scenarios & Patterns
-
-- **[Connector Scenarios](./03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md)** - Example connector scenarios
-- **[Integration Patterns](./03-PATTERN-GUIDES/integration-patterns/)** - Common patterns and practices
-- **[Orchestrators Guide](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md)** - Production orchestrators for inventory workflows
-
-### 🔄 Data Workflows
-
-- **[Ingestion Guide](./02-CORE-GUIDES/ingestion/)** - Complete guide for ingesting data into Fluent Commerce
-- **[Extraction Guide](./02-CORE-GUIDES/extraction/)** - Extract and transform data from Fluent Commerce
-- **[Auto-Pagination Guide](./02-CORE-GUIDES/auto-pagination/)** - 🌟 Automatic GraphQL pagination with zero boilerplate (modules + examples)
-
-### 🔄 Data Transformation
-
-- **[Universal Mapping Guide](./02-CORE-GUIDES/mapping/mapping-readme.md)** - Progressive learning path for field mapping and transformation
-- **[Resolver Guide](./02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md)** - Complete resolver development guide with modules and cookbook patterns
-- **[Resolver Signature](./04-REFERENCE/resolver-signature/resolver-signature-readme.md)** - Detailed resolver function signatures and contracts
-- **[GraphQL Mutation Mapping](./02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - Map XML/JSON to GraphQL mutations
-- **[Multiple Connections](./03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md)** - Handle multiple Fluent connections
-
-### 🌐 Platform Integration
-
-- **[Versori Platform APIs](./versori-apis/README.md)** - Complete Versori Platform API documentation
-  - Platform Management APIs (Control Plane)
-  - Workflow Runtime APIs (Data Plane)
-  - Postman collections for both API layers
-  - OpenAPI specifications
-  - SDK reference for `@versori/run`
-
-### 📄 Parser Learning Paths
-
-- **[CSV Parser](./02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md#csv-parser)** - Built-in CSV parsing with validation
-- **[Parser Guide](./02-CORE-GUIDES/parsers/parsers-readme.md)** - Complete learning path for JSON/JSONL and XML parsing with streaming support
-- **[Parquet Guide](./03-PATTERN-GUIDES/parquet/)** - Work with Parquet files for big data operations
-
-### 📁 Data Sources Learning Paths
-
-- **[Data Sources Guide](./02-CORE-GUIDES/data-sources/data-sources-readme.md)** - Complete learning path for S3 and SFTP integrations
-- **[SFTP Quick Reference](./02-CORE-GUIDES/data-sources/data-sources-quick-reference.md)** - Quick examples and recipes
-- **[File Operations Guide](./03-PATTERN-GUIDES/file-operations/file-operations-readme.md)** - Overview of all file operation capabilities
-
-### 🔒 Validation & Security
-
-- **[Webhook Validation Guide](./02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)** - Validate webhook signatures from Fluent Commerce
-- **[Error Handling Guide](./03-PATTERN-GUIDES/error-handling/error-handling-readme.md)** - Comprehensive error handling patterns and strategies
-- **[GraphQL Error Classification](./02-CORE-GUIDES/api-reference/graphql-error-classification.md)** - 🌟 Classify GraphQL errors (retryable vs non-retryable) with error codes
-- **[GraphQL Mapping Error Handling](./02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)** - Error handling for GraphQL operations
-- **[Testing Guide](./04-REFERENCE/testing/testing-readme.md)** - Test utilities and validation tools
-
-### 🌐 Platform Integration
-
-- **[Versori Platform](./04-REFERENCE/platforms/versori/)** - Complete Versori platform integration guide
-- **[Versori Webhook Response Patterns](./04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)** - ⚠️ **CRITICAL**: Returning XML/HTML/CSV from webhooks
-- **[Deno Compatibility](./04-REFERENCE/platforms/deno/)** - Deno runtime support and compatibility
-
-### 📚 Use Cases & Examples
-
-- **[Use Cases Index](./01-TEMPLATES/readme.md)** - Complete catalog of use cases and examples with decision tree
-
-#### Patterns (Reusable Components)
-
-- **[Custom Resolvers](./01-TEMPLATES/patterns/custom-resolvers.md)** - Custom transformation functions
-- **[Error Handling & Retry](./01-TEMPLATES/patterns/error-handling-retry.md)** - Circuit breakers, retries, fallbacks
-- **[Field Mapping Universal](./01-TEMPLATES/patterns/field-mapping-universal.md)** - Universal field transformation patterns
-- **[Pagination & Streaming](./01-TEMPLATES/patterns/pagination-streaming.md)** - Handle large datasets efficiently
-- **[State & Duplicate Prevention](./01-TEMPLATES/patterns/state-duplicate-prevention.md)** - Prevent duplicate processing
-- **[Large File Splitting](./01-TEMPLATES/patterns/large-file-splitting.md)** - Handle GB-sized files
-- **[Master Data ETL](./01-TEMPLATES/patterns/master-data-etl.md)** - Load locations, products, controls
-- **[CSV Schema Validation](./01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md)** - Validate and report CSV issues
-
-#### Standalone Scripts (Node.js/Deno)
-
-- **[S3 CSV → Batch API](./01-TEMPLATES/standalone/s3-csv-batch-api.md)** - Complete standalone S3 CSV ingestion
-- **[SFTP XML → GraphQL](./01-TEMPLATES/standalone/sftp-xml-graphql.md)** - SFTP XML order ingestion
-- **[GraphQL Query Export](./01-TEMPLATES/standalone/graphql-query-export.md)** - Export data via GraphQL queries
-- **[Multi-Source Aggregation](./01-TEMPLATES/standalone/multi-source-aggregation.md)** - Combine multiple data sources
-- **[S3 CSV Inventory Batch](./01-TEMPLATES/standalone/s3-csv-batch-api.md)** - CSV inventory processing
-- **[GraphQL → Parquet S3](./01-TEMPLATES/standalone/graphql-to-parquet-partitioned-s3.md)** - Export to partitioned Parquet
-- **[Multi-Channel Sync](./01-TEMPLATES/standalone/multi-channel-inventory-sync.md)** - Sync across channels
-- **[ASN Inbound Processing](./01-TEMPLATES/standalone/asn-inbound-processing.md)** - Process ASN/EDI 856 files
-
-#### Versori Platform Examples
-
-**Webhooks** (Real-time):
-- **[XML Order Ingestion](./01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)** - Process XML orders via webhooks
-- **[Payment Gateway Integration](./01-TEMPLATES/versori/webhooks/template-webhook-payment-gateway-integration.md)** - Adyen payment flows (Capture, Refund, Cancel, ReAuth)
-- **[Dropship Routing](./01-TEMPLATES/versori/webhooks/template-webhook-dropship-routing.md)** - Route dropship orders
-- **[Flash Sale Reserve](./01-TEMPLATES/versori/webhooks/template-webhook-flash-sale-reserve.md)** - Handle flash sale reservations
-- **[Generic XML Order](./01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md)** - Generic XML order processing
-- **[RMA Returns](./01-TEMPLATES/versori/webhooks/template-webhook-rma-returns-comprehensive.md)** - Comprehensive returns processing
-- **[ASN Purchase Order](./01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md)** - ASN webhook processing
-
-**Scheduled** (Batch):
-- **[Bulk Price Updates](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Schedule price updates
-- **[CSV Inventory Sync](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled CSV ingestion
-- **[Cycle Count Reconciliation](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Inventory counting
-- **[Master Data Adapter](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Master data loading
-- **[Multi-Channel Sync](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled multi-channel sync
-- **[SFTP CSV Ingestion](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)** - SFTP scheduled ingestion
-
-**Patterns** (Versori-specific):
-- **[Dual Workflow Connector](./01-TEMPLATES/versori/patterns/dual-workflow-connector.md)** - Webhook + scheduled combination
-- **[KV State Management](./01-TEMPLATES/versori/patterns/kv-state-management.md)** - Versori KV store patterns
-- **[XML Response Patterns](./01-TEMPLATES/versori/patterns/xml-response-patterns.md)** - Return XML from webhooks
-
-**Business Examples** (Complex workflows):
-- **[Dropship Order Routing](./01-TEMPLATES/versori/business-examples/dropship-order-routing.md)** - Complete dropship workflow
-- **[GraphQL Parquet Extraction](./01-TEMPLATES/versori/business-examples/graphql-parquet-extraction.md)** - Extract to Parquet format
-- **[Inter-Location Transfers](./01-TEMPLATES/versori/business-examples/inter-location-transfers.md)** - Transfer inventory between locations
-- **[Pre-Order Allocation](./01-TEMPLATES/versori/business-examples/pre-order-allocation.md)** - Pre-order reservation system
-
----
-
-## 🔍 Find What You Need
-
-| **I Want To...** | **Start Here** | **Then See** |
-|---|---|---|
-| **Build a production connector** | 🌟 [Connector Scenarios](./03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md) | [Integration Patterns](./03-PATTERN-GUIDES/integration-patterns/) |
-| **Get started quickly** | [Getting Started](./00-START-HERE/getting-started.md) | [API Reference](./02-CORE-GUIDES/api-reference/api-reference-readme.md) |
-| **Configure retailerId (optional)** | [retailerId Configuration](./00-START-HERE/retailerid-configuration.md) | [Authentication](./02-CORE-GUIDES/api-reference/modules/api-reference-03-authentication.md) |
-| **Fetch ALL results (not just first page)** | ⚠️ [Auto-Pagination](./02-CORE-GUIDES/auto-pagination/) | [Quick Start](./02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md) |
-| **Set up inventory sync** | [Ingestion Guide](./02-CORE-GUIDES/ingestion/) | [Data Sources](./02-CORE-GUIDES/data-sources/data-sources-readme.md) |
-| **Use SFTP (no platform needed)** | 🌟 [Data Sources Guide](./02-CORE-GUIDES/data-sources/data-sources-readme.md) | [SFTP Quick Reference](./02-CORE-GUIDES/data-sources/data-sources-quick-reference.md) |
-| **Export data from Fluent** | [Extraction Guide](./02-CORE-GUIDES/extraction/) | [ExtractionOrchestrator Guide](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) |
-| **High-level extraction (auto-pagination)** | 🌟 [ExtractionOrchestrator](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [Extraction Guide](./02-CORE-GUIDES/extraction/) |
-| **Handle webhooks** | [Webhook Validation](./02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Webhook Examples](./01-TEMPLATES/versori/webhooks/) |
-| **Validate webhook signatures** | [Webhook Validation](./02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Quick Start Guide](./02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md) |
-| **Track job lifecycle** | [JobTracker Usage](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [State Management](./04-REFERENCE/architecture/architecture-06-state-management.md) |
-| **Retry partial batch failures** | [Batch Recovery Patterns](./03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [PartialBatchRecovery API](./02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md#partialbatchrecovery-new) |
-| **Pre-validate connector config** | [PreflightValidator Guide](./04-REFERENCE/testing/testing-readme.md) | [Testing Patterns](./04-REFERENCE/testing/) |
-| **Return XML/HTML from webhook** | ⚠️ [Webhook Response Patterns](./04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) | [Versori Platform](./04-REFERENCE/platforms/versori/) |
-| **Deploy on Versori** | [Versori Platform](./04-REFERENCE/platforms/versori/) | [Versori Examples](./01-TEMPLATES/versori/) |
-| **Look up API methods** | [API Reference](./02-CORE-GUIDES/api-reference/api-reference-readme.md) | [SDK Philosophy](./00-START-HERE/sdk-philosophy.md) |
-| **Transform data fields** | [Universal Mapping](./02-CORE-GUIDES/mapping/mapping-readme.md) | [Resolver Guide](./02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md) |
-| **Parse CSV data** | [API Reference](./02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md#csv-parser) | [CSV Validation Pattern](./01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md) |
-| **Parse XML/JSON data** | [Parser Guide](./02-CORE-GUIDES/parsers/parsers-readme.md) | [GraphQL Mutation Mapping](./02-CORE-GUIDES/mapping/graphql-mutation-mapping/) |
-| **Work with S3** | [Data Sources Guide](./02-CORE-GUIDES/data-sources/data-sources-readme.md) | [S3 Examples](./01-TEMPLATES/standalone/s3-csv-batch-api.md) |
-| **Debug issues** | [Error Handling Guide](./03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [Testing Guide](./04-REFERENCE/testing/testing-readme.md) |
-| **Prevent duplicates** | [State Management](./01-TEMPLATES/patterns/state-duplicate-prevention.md) | [Architecture](./04-REFERENCE/architecture/architecture-06-state-management.md) |
-| **Handle large files** | [Large File Splitting](./01-TEMPLATES/patterns/large-file-splitting.md) | [Pagination & Streaming](./01-TEMPLATES/patterns/pagination-streaming.md) |
-| **See complete examples** | [Use Cases Index](./01-TEMPLATES/readme.md) | [FAQ](./01-TEMPLATES/faq.md) |
-
----
-
-## 📖 Documentation Structure
-
-**New 5-folder organization** for better AI context loading and navigation:
-
-```
-docs/
-├── readme.md (this file)
-├── template-loading-matrix.md (template selection guide)
-│
-├── 00-START-HERE/ (essential docs - read first)
-│   ├── getting-started.md (installation & setup)
-│   ├── decision-tree.md (which approach to use)
-│   ├── sdk-philosophy.md (design principles)
-│   └── troubleshooting-quick-reference.md (90% of issues)
-│
-├── 01-TEMPLATES/ (complete working examples)
-│   ├── readme.md (complete catalog with decision tree)
-│   ├── faq.md (troubleshooting guide)
-│   ├── patterns/ (9 reusable components)
-│   ├── standalone/ (9 Node.js/Deno scripts)
-│   └── versori/ (32 Versori platform examples)
-│       ├── webhooks/ (7 real-time)
-│       ├── scheduled/ (6 batch)
-│       ├── patterns/ (3 Versori-specific)
-│       └── business-examples/ (4 complex workflows)
-│
-├── 02-CORE-GUIDES/ (progressive learning paths)
-│   ├── api-reference/ (complete API docs)
-│   ├── ingestion/ (data into Fluent)
-│   ├── extraction/ (data from Fluent)
-│   ├── auto-pagination/ (7 modules - cursor pagination)
-│   ├── data-sources/ (S3, SFTP guides)
-│   ├── parsers/ (CSV, XML, JSON, Parquet)
-│   ├── webhook-validation/ (webhook security)
-│   └── mapping/ (field transformation)
-│       ├── modules/ (universal mapping)
-│       ├── resolvers/ (7 modules - custom functions)
-│       └── graphql-mutation-mapping/ (XML/JSON → GraphQL)
-│
-├── 03-PATTERN-GUIDES/ (reusable patterns)
-│   ├── error-handling/ (retry, circuit breakers)
-│   ├── file-operations/ (S3, SFTP patterns)
-│   ├── integration-patterns/ (common workflows)
-│   ├── multiple-connections/ (multi-tenant)
-│   ├── orchestrators/ (high-level workflows)
-│   ├── parquet/ (big data operations)
-│   └── [other patterns]
-│
-└── 04-REFERENCE/ (deep dives & platform docs)
-    ├── architecture/ (7 docs - system design)
-    ├── testing/ (test utilities)
-    ├── platforms/versori/ (Versori integration)
-    ├── schema/ (GraphQL schema docs)
-    └── troubleshooting/ (detailed debugging)
-```
-
----
-
-## 🔗 External Resources
-
-- **[NPM Package](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)** - Install the SDK
-- **[GitHub Repository](https://github.com/fluentcommerce/fc-connect-sdk)** - Source code and issues
-- **[Fluent Commerce API Docs](https://docs.fluentcommerce.com)** - Fluent Commerce platform documentation
-- **[Versori Platform](https://versori.com)** - Versori integration platform
-
----
-
-## 📝 Contributing
-
-Found an issue or want to improve the docs? Please see the main [readme.md](../readme.md) for contribution guidelines.
-
-**License:** MIT | **Current Version:** Latest
+# Fluent Commerce Connect SDK Documentation
+
+Comprehensive documentation for the Fluent Commerce Connect SDK - a TypeScript/JavaScript library for building integrations with inventory ingestion and extraction capabilities.
+
+**Current Version:** Latest
+**Node.js:** >= 18.0.0
+**TypeScript:** 5.9.2
+**Platform Support:** Node.js, Deno, Versori
+
+> **Tip:** For installation and quick start, see the main [readme.md](../readme.md). This document provides navigation to detailed guides.
+
+---
+
+## 📑 Documentation Index
+
+### 🚀 Quick Start
+
+- **[Getting Started](./00-START-HERE/getting-started.md)** - Installation, configuration, and quick examples
+- **[API Reference](./02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete API documentation for all SDK methods
+- **[SDK Philosophy](./00-START-HERE/sdk-philosophy.md)** - Design principles and architecture decisions
+
+### 🏗️ Architecture
+
+- **[Architecture Overview](./04-REFERENCE/architecture/readme.md)** - Complete SDK architecture documentation
+- **[Client Architecture](./04-REFERENCE/architecture/architecture-02-client-architecture.md)** - Client system design
+- **[Data Flow](./04-REFERENCE/architecture/architecture-03-data-flow.md)** - How data moves through the SDK
+- **[Service Layer](./04-REFERENCE/architecture/architecture-04-service-layer.md)** - Service organization and patterns
+- **[State Management](./04-REFERENCE/architecture/architecture-06-state-management.md)** - State tracking and duplicate prevention
+
+### 🎯 Scenarios & Patterns
+
+- **[Connector Scenarios](./03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md)** - Example connector scenarios
+- **[Integration Patterns](./03-PATTERN-GUIDES/integration-patterns/)** - Common patterns and practices
+- **[Orchestrators Guide](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md)** - Production orchestrators for inventory workflows
+
+### 🔄 Data Workflows
+
+- **[Ingestion Guide](./02-CORE-GUIDES/ingestion/)** - Complete guide for ingesting data into Fluent Commerce
+- **[Extraction Guide](./02-CORE-GUIDES/extraction/)** - Extract and transform data from Fluent Commerce
+- **[Auto-Pagination Guide](./02-CORE-GUIDES/auto-pagination/)** - 🌟 Automatic GraphQL pagination with zero boilerplate (modules + examples)
+
+### 🔄 Data Transformation
+
+- **[Universal Mapping Guide](./02-CORE-GUIDES/mapping/mapping-readme.md)** - Progressive learning path for field mapping and transformation
+- **[Resolver Guide](./02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md)** - Complete resolver development guide with modules and cookbook patterns
+- **[Resolver Signature](./04-REFERENCE/resolver-signature/resolver-signature-readme.md)** - Detailed resolver function signatures and contracts
+- **[GraphQL Mutation Mapping](./02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - Map XML/JSON to GraphQL mutations
+- **[Multiple Connections](./03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md)** - Handle multiple Fluent connections
+
+### 🌐 Platform Integration
+
+- **[Versori Platform APIs](../versori-apis/README.md)** - Complete Versori Platform API documentation
+  - Platform Management APIs (Control Plane)
+  - Workflow Runtime APIs (Data Plane)
+  - Postman collections for both API layers
+  - OpenAPI specifications
+  - SDK reference for `@versori/run`
+
+### 📄 Parser Learning Paths
+
+- **[CSV Parser](./02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md#csv-parser)** - Built-in CSV parsing with validation
+- **[Parser Guide](./02-CORE-GUIDES/parsers/parsers-readme.md)** - Complete learning path for JSON/JSONL and XML parsing with streaming support
+- **[Parquet Guide](./03-PATTERN-GUIDES/parquet/)** - Work with Parquet files for big data operations
+
+### 📁 Data Sources Learning Paths
+
+- **[Data Sources Guide](./02-CORE-GUIDES/data-sources/data-sources-readme.md)** - Complete learning path for S3 and SFTP integrations
+- **[SFTP Quick Reference](./02-CORE-GUIDES/data-sources/data-sources-quick-reference.md)** - Quick examples and recipes
+- **[File Operations Guide](./03-PATTERN-GUIDES/file-operations/file-operations-readme.md)** - Overview of all file operation capabilities
+
+### 🔒 Validation & Security
+
+- **[Webhook Validation Guide](./02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)** - Validate webhook signatures from Fluent Commerce
+- **[Error Handling Guide](./03-PATTERN-GUIDES/error-handling/error-handling-readme.md)** - Comprehensive error handling patterns and strategies
+- **[GraphQL Error Classification](./02-CORE-GUIDES/api-reference/graphql-error-classification.md)** - 🌟 Classify GraphQL errors (retryable vs non-retryable) with error codes
+- **[GraphQL Mapping Error Handling](./02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)** - Error handling for GraphQL operations
+- **[Testing Guide](./04-REFERENCE/testing/testing-readme.md)** - Test utilities and validation tools
+
+### 🌐 Platform Integration
+
+- **[Versori Platform](./04-REFERENCE/platforms/versori/)** - Complete Versori platform integration guide
+- **[Versori Webhook Response Patterns](./04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)** - ⚠️ **CRITICAL**: Returning XML/HTML/CSV from webhooks
+- **[Deno Compatibility](./04-REFERENCE/platforms/deno/)** - Deno runtime support and compatibility
+
+### 📚 Use Cases & Examples
+
+- **[Use Cases Index](./01-TEMPLATES/readme.md)** - Complete catalog of use cases and examples with decision tree
+
+#### Patterns (Reusable Components)
+
+- **[Custom Resolvers](./01-TEMPLATES/patterns/custom-resolvers.md)** - Custom transformation functions
+- **[Error Handling & Retry](./01-TEMPLATES/patterns/error-handling-retry.md)** - Circuit breakers, retries, fallbacks
+- **[Field Mapping Universal](./01-TEMPLATES/patterns/field-mapping-universal.md)** - Universal field transformation patterns
+- **[Pagination & Streaming](./01-TEMPLATES/patterns/pagination-streaming.md)** - Handle large datasets efficiently
+- **[State & Duplicate Prevention](./01-TEMPLATES/patterns/state-duplicate-prevention.md)** - Prevent duplicate processing
+- **[Large File Splitting](./01-TEMPLATES/patterns/large-file-splitting.md)** - Handle GB-sized files
+- **[Master Data ETL](./01-TEMPLATES/patterns/master-data-etl.md)** - Load locations, products, controls
+- **[CSV Schema Validation](./01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md)** - Validate and report CSV issues
+
+#### Standalone Scripts (Node.js/Deno)
+
+- **[S3 CSV → Batch API](./01-TEMPLATES/standalone/s3-csv-batch-api.md)** - Complete standalone S3 CSV ingestion
+- **[SFTP XML → GraphQL](./01-TEMPLATES/standalone/sftp-xml-graphql.md)** - SFTP XML order ingestion
+- **[GraphQL Query Export](./01-TEMPLATES/standalone/graphql-query-export.md)** - Export data via GraphQL queries
+- **[Multi-Source Aggregation](./01-TEMPLATES/standalone/multi-source-aggregation.md)** - Combine multiple data sources
+- **[S3 CSV Inventory Batch](./01-TEMPLATES/standalone/s3-csv-batch-api.md)** - CSV inventory processing
+- **[GraphQL → Parquet S3](./01-TEMPLATES/standalone/graphql-to-parquet-partitioned-s3.md)** - Export to partitioned Parquet
+- **[Multi-Channel Sync](./01-TEMPLATES/standalone/multi-channel-inventory-sync.md)** - Sync across channels
+- **[ASN Inbound Processing](./01-TEMPLATES/standalone/asn-inbound-processing.md)** - Process ASN/EDI 856 files
+
+#### Versori Platform Examples
+
+**Webhooks** (Real-time):
+- **[XML Order Ingestion](./01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)** - Process XML orders via webhooks
+- **[Payment Gateway Integration](./01-TEMPLATES/versori/webhooks/template-webhook-payment-gateway-integration.md)** - Adyen payment flows (Capture, Refund, Cancel, ReAuth)
+- **[Dropship Routing](./01-TEMPLATES/versori/webhooks/template-webhook-dropship-routing.md)** - Route dropship orders
+- **[Flash Sale Reserve](./01-TEMPLATES/versori/webhooks/template-webhook-flash-sale-reserve.md)** - Handle flash sale reservations
+- **[Generic XML Order](./01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md)** - Generic XML order processing
+- **[RMA Returns](./01-TEMPLATES/versori/webhooks/template-webhook-rma-returns-comprehensive.md)** - Comprehensive returns processing
+- **[ASN Purchase Order](./01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md)** - ASN webhook processing
+
+**Scheduled** (Batch):
+- **[Bulk Price Updates](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Schedule price updates
+- **[CSV Inventory Sync](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled CSV ingestion
+- **[Cycle Count Reconciliation](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Inventory counting
+- **[Master Data Adapter](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Master data loading
+- **[Multi-Channel Sync](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled multi-channel sync
+- **[SFTP CSV Ingestion](./01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)** - SFTP scheduled ingestion
+
+**Patterns** (Versori-specific):
+- **[Dual Workflow Connector](./01-TEMPLATES/versori/patterns/dual-workflow-connector.md)** - Webhook + scheduled combination
+- **[KV State Management](./01-TEMPLATES/versori/patterns/kv-state-management.md)** - Versori KV store patterns
+- **[XML Response Patterns](./01-TEMPLATES/versori/patterns/xml-response-patterns.md)** - Return XML from webhooks
+
+**Business Examples** (Complex workflows):
+- **[Dropship Order Routing](./01-TEMPLATES/versori/business-examples/dropship-order-routing.md)** - Complete dropship workflow
+- **[GraphQL Parquet Extraction](./01-TEMPLATES/versori/business-examples/graphql-parquet-extraction.md)** - Extract to Parquet format
+- **[Inter-Location Transfers](./01-TEMPLATES/versori/business-examples/inter-location-transfers.md)** - Transfer inventory between locations
+- **[Pre-Order Allocation](./01-TEMPLATES/versori/business-examples/pre-order-allocation.md)** - Pre-order reservation system
+
+---
+
+## 🔍 Find What You Need
+
+| **I Want To...** | **Start Here** | **Then See** |
+|---|---|---|
+| **Build a production connector** | 🌟 [Connector Scenarios](./03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md) | [Integration Patterns](./03-PATTERN-GUIDES/integration-patterns/) |
+| **Get started quickly** | [Getting Started](./00-START-HERE/getting-started.md) | [API Reference](./02-CORE-GUIDES/api-reference/api-reference-readme.md) |
+| **Configure retailerId (optional)** | [retailerId Configuration](./00-START-HERE/retailerid-configuration.md) | [Authentication](./02-CORE-GUIDES/api-reference/modules/api-reference-03-authentication.md) |
+| **Fetch ALL results (not just first page)** | ⚠️ [Auto-Pagination](./02-CORE-GUIDES/auto-pagination/) | [Quick Start](./02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md) |
+| **Set up inventory sync** | [Ingestion Guide](./02-CORE-GUIDES/ingestion/) | [Data Sources](./02-CORE-GUIDES/data-sources/data-sources-readme.md) |
+| **Use SFTP (no platform needed)** | 🌟 [Data Sources Guide](./02-CORE-GUIDES/data-sources/data-sources-readme.md) | [SFTP Quick Reference](./02-CORE-GUIDES/data-sources/data-sources-quick-reference.md) |
+| **Export data from Fluent** | [Extraction Guide](./02-CORE-GUIDES/extraction/) | [ExtractionOrchestrator Guide](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) |
+| **High-level extraction (auto-pagination)** | 🌟 [ExtractionOrchestrator](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [Extraction Guide](./02-CORE-GUIDES/extraction/) |
+| **Handle webhooks** | [Webhook Validation](./02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Webhook Examples](./01-TEMPLATES/versori/webhooks/) |
+| **Validate webhook signatures** | [Webhook Validation](./02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Quick Start Guide](./02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md) |
+| **Track job lifecycle** | [JobTracker Usage](./02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [State Management](./04-REFERENCE/architecture/architecture-06-state-management.md) |
+| **Retry partial batch failures** | [Batch Recovery Patterns](./03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [PartialBatchRecovery API](./02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md#partialbatchrecovery-new) |
+| **Pre-validate connector config** | [PreflightValidator Guide](./04-REFERENCE/testing/testing-readme.md) | [Testing Patterns](./04-REFERENCE/testing/) |
+| **Return XML/HTML from webhook** | ⚠️ [Webhook Response Patterns](./04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) | [Versori Platform](./04-REFERENCE/platforms/versori/) |
+| **Deploy on Versori** | [Versori Platform](./04-REFERENCE/platforms/versori/) | [Versori Examples](./01-TEMPLATES/versori/) |
+| **Look up API methods** | [API Reference](./02-CORE-GUIDES/api-reference/api-reference-readme.md) | [SDK Philosophy](./00-START-HERE/sdk-philosophy.md) |
+| **Transform data fields** | [Universal Mapping](./02-CORE-GUIDES/mapping/mapping-readme.md) | [Resolver Guide](./02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md) |
+| **Parse CSV data** | [API Reference](./02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md#csv-parser) | [CSV Validation Pattern](./01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md) |
+| **Parse XML/JSON data** | [Parser Guide](./02-CORE-GUIDES/parsers/parsers-readme.md) | [GraphQL Mutation Mapping](./02-CORE-GUIDES/mapping/graphql-mutation-mapping/) |
+| **Work with S3** | [Data Sources Guide](./02-CORE-GUIDES/data-sources/data-sources-readme.md) | [S3 Examples](./01-TEMPLATES/standalone/s3-csv-batch-api.md) |
+| **Debug issues** | [Error Handling Guide](./03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [Testing Guide](./04-REFERENCE/testing/testing-readme.md) |
+| **Prevent duplicates** | [State Management](./01-TEMPLATES/patterns/state-duplicate-prevention.md) | [Architecture](./04-REFERENCE/architecture/architecture-06-state-management.md) |
+| **Handle large files** | [Large File Splitting](./01-TEMPLATES/patterns/large-file-splitting.md) | [Pagination & Streaming](./01-TEMPLATES/patterns/pagination-streaming.md) |
+| **See complete examples** | [Use Cases Index](./01-TEMPLATES/readme.md) | [FAQ](./01-TEMPLATES/faq.md) |
+
+---
+
+## 📖 Documentation Structure
+
+**New 5-folder organization** for better AI context loading and navigation:
+
+```
+docs/
+├── readme.md (this file)
+├── template-loading-matrix.md (template selection guide)
+│
+├── 00-START-HERE/ (essential docs - read first)
+│   ├── getting-started.md (installation & setup)
+│   ├── decision-tree.md (which approach to use)
+│   ├── sdk-philosophy.md (design principles)
+│   └── troubleshooting-quick-reference.md (90% of issues)
+│
+├── 01-TEMPLATES/ (complete working examples)
+│   ├── readme.md (complete catalog with decision tree)
+│   ├── faq.md (troubleshooting guide)
+│   ├── patterns/ (9 reusable components)
+│   ├── standalone/ (9 Node.js/Deno scripts)
+│   └── versori/ (32 Versori platform examples)
+│       ├── webhooks/ (7 real-time)
+│       ├── scheduled/ (6 batch)
+│       ├── patterns/ (3 Versori-specific)
+│       └── business-examples/ (4 complex workflows)
+│
+├── 02-CORE-GUIDES/ (progressive learning paths)
+│   ├── api-reference/ (complete API docs)
+│   ├── ingestion/ (data into Fluent)
+│   ├── extraction/ (data from Fluent)
+│   ├── auto-pagination/ (7 modules - cursor pagination)
+│   ├── data-sources/ (S3, SFTP guides)
+│   ├── parsers/ (CSV, XML, JSON, Parquet)
+│   ├── webhook-validation/ (webhook security)
+│   └── mapping/ (field transformation)
+│       ├── modules/ (universal mapping)
+│       ├── resolvers/ (7 modules - custom functions)
+│       └── graphql-mutation-mapping/ (XML/JSON → GraphQL)
+│
+├── 03-PATTERN-GUIDES/ (reusable patterns)
+│   ├── error-handling/ (retry, circuit breakers)
+│   ├── file-operations/ (S3, SFTP patterns)
+│   ├── integration-patterns/ (common workflows)
+│   ├── multiple-connections/ (multi-tenant)
+│   ├── orchestrators/ (high-level workflows)
+│   ├── parquet/ (big data operations)
+│   └── [other patterns]
+│
+└── 04-REFERENCE/ (deep dives & platform docs)
+    ├── architecture/ (7 docs - system design)
+    ├── testing/ (test utilities)
+    ├── platforms/versori/ (Versori integration)
+    ├── schema/ (GraphQL schema docs)
+    └── troubleshooting/ (detailed debugging)
+```
+
+---
+
+## 🔗 External Resources
+
+- **[NPM Package](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)** - Install the SDK
+- **[GitHub Repository](https://github.com/fluentcommerce/fc-connect-sdk)** - Source code and issues
+- **[Fluent Commerce API Docs](https://docs.fluentcommerce.com)** - Fluent Commerce platform documentation
+- **[Versori Platform](https://versori.com)** - Versori integration platform
+
+---
+
+## 📝 Contributing
+
+Found an issue or want to improve the docs? Please see the main [readme.md](../readme.md) for contribution guidelines.
+
+**License:** MIT | **Current Version:** Latest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentcommerce/fc-connect-sdk",
-  "version": "0.1.48",
+  "version": "0.1.52",
   "description": "Fluent Commerce SDK - Deno & Node.js Compatible",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -70,7 +70,19 @@
     "validate:templates": "node scripts/validate-templates.cjs",
     "validate:exports": "node scripts/validate-exports.mjs",
     "test:cov": "jest --coverage --coverageReporters=json-summary --coverageReporters=lcov --coverageReporters=text --reporters=default --reporters=jest-junit",
-    "ai:queue": "node scripts/generate-ai-queue.cjs"
+    "ai:queue": "node scripts/generate-ai-queue.cjs",
+    "security:audit": "node security-audit/security-audit.cjs",
+    "security:audit:npm": "npm audit --audit-level=moderate",
+    "security:audit:json": "npm audit --json > artifacts/security-audit-$(date +%Y%m%d).json || true",
+    "security:check": "npm run security:audit:npm && npm run security:audit",
+    "security:snyk": "node security-audit/snyk-setup.cjs",
+    "security:snyk:test": "snyk test",
+    "security:snyk:monitor": "snyk monitor",
+    "security:snyk:report": "snyk test --json > artifacts/snyk-report-$(date +%Y%m%d).json",
+    "security:fix": "node security-audit/safe-fix.cjs",
+    "security:fix:critical": "node security-audit/safe-fix.cjs critical",
+    "security:fix:high": "node security-audit/safe-fix.cjs high",
+    "security:full": "npm run security:check && npm run security:snyk"
   },
   "jest-junit": {
     "outputDirectory": "artifacts",
@@ -97,7 +109,7 @@
     "@types/ssh2-sftp-client": "^9.0.5",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
-    "@versori/run": "^0.4.4",
+    "@versori/run": "^0.4.18",
     "chalk": "^4.1.2",
     "dotenv": "^17.2.2",
     "eslint": "^8.57.0",
@@ -107,8 +119,7 @@
     "highlight.js": "^11.11.1",
     "jest": "^29.7.0",
     "jest-junit": "^16.0.0",
-    "markdown-pdf": "^11.0.0",
-    "markdownlint-cli": "^0.45.0",
+    "markdownlint-cli": "^0.46.0",
     "marked": "^14.1.4",
     "ora": "^5.4.1",
     "p-limit": "^3.1.0",
@@ -124,11 +135,11 @@
     "@aws-sdk/client-s3": "^3.879.0",
     "@aws-sdk/credential-providers": "^3.879.0",
     "@aws-sdk/s3-request-presigner": "^3.886.0",
+    "@dsnp/parquetjs": "^1.8.7",
     "csv-parse": "^5.6.0",
     "fast-xml-parser": "^5.2.5",
     "graphql": "^16.9.0",
     "hyparquet": "^1.3.0",
-    "parquetjs": "^0.11.2",
     "ssh2": "^1.17.0",
     "ssh2-sftp-client": "^12.0.1"
   },

package/docs/versori-apis/ACTIVATIONS-AND-VARIABLES-GUIDE.md

@@ -1,60 +0,0 @@
-# Activations and Variables Guide
-
-This guide explains how to manage Activations and Dynamic Variables in the Versori Platform.
-
-## Concepts
-
-- **Activation**: A link between a User and an Environment. It stores configuration specific to that user in that environment.
-- **Dynamic Variables**: Key-value pairs stored on an Activation. These variables are defined by the Project's Variable Schema.
-
-## Updating Variables
-
-To update variables, you use the `PATCH` endpoint.
-
-**Endpoint**: `PATCH /o/{org_id}/environments/{env_id}/activations/{activation_id}/variables`
-
-### Important: Validation Rules
-
-The Versori Platform validates your variables against the Project's Schema on **every update**.
-
-**Critical Rule**: Even if you are only updating one variable (Partial Update), the **final state** of the variables must be valid.
-*   If your activation is missing **Required Variables**, you **MUST** provide them in your update request, even if you are not changing them.
-*   Once the activation is valid (has all required variables), you can perform partial updates freely.
-
-### Example
-
-**Scenario**: You want to update `detailedLogging` to `false`.
-**Problem**: Your activation is missing required variables: `gsiClientId`, `gsiCatalogId`.
-
-**Incorrect Request (Will Fail 400 Bad Request)**:
-```json
-{
-  "detailedLogging": "false"
-}
-```
-*Error: "missing properties: 'gsiClientId', 'gsiCatalogId'"*
-
-**Correct Request (Will Succeed)**:
-```json
-{
-  "detailedLogging": "false",
-  "gsiClientId": "YOUR_GSI_CLIENT_ID",
-  "gsiCatalogId": "YOUR_CATALOG_ID"
-}
-```
-
-## Finding Activations
-
-1.  **List Users**: Get the User ID.
-    `GET /o/{org_id}/users`
-2.  **List Activations**: Find the activation for that user.
-    `GET /o/{org_id}/activations` (Filter by `userId` in response)
-
-## Variable Schema
-
-To see which variables are required, check the Project's Variable Schema:
-
-`GET /o/{org_id}/projects/{project_id}/variables`
-
-Look for the `required` array in the response.
-