@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

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

@@ -1,279 +1,279 @@
-# FC Connect SDK - API Reference
-
-**Complete API documentation for the Fluent Commerce Connect SDK**
-
-This reference provides comprehensive documentation for all public APIs, types, and utilities in the SDK.
-
-## Quick Start
-
-```typescript
-import {
-  createClient,           // Client factory (auto-detects runtime)
-  FluentClient,           // Core API client
-  BatchAPIClient,         // Batch API operations
-  UniversalMapper,        // Field mapping
-  S3DataSource,          // S3 operations
-  SftpDataSource,        // SFTP operations
-  CSVParserService,      // CSV parsing
-  XMLParserService,      // XML parsing
-  ExtractionOrchestrator // High-level extraction
-} from '@fluentcommerce/fc-connect-sdk';
-```
-
-## Quick Navigation
-
-### By Component Type
-
-| Component            | Description                                | Module                                               |
-| -------------------- | ------------------------------------------ | ---------------------------------------------------- |
-| **Client & Factory** | Client creation and core operations        | [Client API](./modules/api-reference-01-client-api.md)             |
-| **Authentication**   | OAuth2 and auth providers                  | [Authentication](./modules/api-reference-03-authentication.md)     |
-| **GraphQL Mapping**  | XML/JSON to GraphQL transformation         | [GraphQL Mapping](./modules/api-reference-04-graphql-mapping.md)   |
-| **Services**         | Core services (mapping, state, extraction) | [Services](./modules/api-reference-05-services.md)                 |
-| **Data Sources**     | S3 and SFTP data sources                   | [Data Sources](./modules/api-reference-06-data-sources.md)         |
-| **Parsers**          | CSV, JSON, XML, Parquet parsers            | [Parsers](./modules/api-reference-07-parsers.md)                   |
-| **Types**            | TypeScript type definitions                | [Types](./modules/api-reference-08-types.md)                       |
-| **Error Handling**   | Error classes and handling                 | [Error Handling](./modules/api-reference-09-error-handling.md)     |
-| **Utilities**        | Helper functions and utilities             | [Utilities](./modules/api-reference-10-utilities.md)               |
-| **CLI Tools**        | Command-line utilities                     | [CLI Tools](./modules/api-reference-11-cli-tools.md)               |
-| **Testing**          | Testing utilities and mocks                | [Testing](./modules/api-reference-12-testing.md)                   |
-| **Resolver Builder** | GraphQL query builder                      | [Resolver Builder](./modules/api-reference-13-resolver-builder.md) |
-
-### By Use Case
-
-| Use Case                    | Start Here                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| **First time using SDK**    | [Client API](./modules/api-reference-01-client-api.md) → [Examples](./examples/)                                           |
-| **Building data ingestion** | [Data Sources](./modules/api-reference-06-data-sources.md) → [Services](./modules/api-reference-05-services.md)                          |
-| **XML/JSON to GraphQL**     | [GraphQL Mapping](./modules/api-reference-04-graphql-mapping.md) → [Parsers](./modules/api-reference-07-parsers.md)                      |
-| **Extracting data**         | [Services](./modules/api-reference-05-services.md#extractionorchestrator) → [Examples](./examples/)                            |
-| **Webhook handling**        | [Services](./modules/api-reference-05-services.md#webhook-validation-service) → [Utilities](./modules/api-reference-10-utilities.md)     |
-| **Custom transformations**  | [Services](./modules/api-reference-05-services.md#universal-mapper) → [Resolver Builder](./modules/api-reference-13-resolver-builder.md) |
-| **Testing integrations**    | [Testing](./modules/api-reference-12-testing.md) → [Error Handling](./modules/api-reference-09-error-handling.md)                        |
-
-### Quick References
-
-- **[Event API Input/Output Reference](./event-api-input-output-reference.md)** - ⭐ NEW: Complete Event API request/response structures with live examples
-- **[Quick Reference Cheat Sheet](../advanced-services/advanced-services-quick-reference.md)** - All common APIs on one page
-- **[Code Examples](./examples/)** - Copy-paste ready examples
-- **[Type Definitions](./modules/api-reference-08-types.md)** - Complete TypeScript types
-
----
-
-## Module Guide
-
-### Module 1: Client API
-
-**Level:** Beginner | **Category:** Core
-
-The main entry point for SDK operations. Learn how to create clients, execute GraphQL operations, send events, and manage batch jobs.
-
-**Key APIs:** `createClient()`, `FluentClient`, `graphql(payload)`, `sendEvent()`, `getEvents()`, `getEventById()`, `createJob()`, `sendBatch()`
-
-[View Module →](./modules/api-reference-01-client-api.md)
-
----
-
-### Module 2: Authentication
-
-**Level:** Intermediate | **Category:** Security
-
-Authentication providers for OAuth2, bearer tokens, and Versori platform connections.
-
-**Key APIs:** `OAuth2AuthProvider`, `BearerTokenAuthProvider`, `AuthManager`
-
-[View Module →](./modules/api-reference-03-authentication.md)
-
----
-
-### Module 3: GraphQL Mutation Mapping
-
-**Level:** Advanced | **Category:** Data Transformation
-
-Schema-driven transformation of XML/JSON data into GraphQL mutations with full validation.
-
-**Key APIs:** `GraphQLMutationMapper`, `XMLPathResolver`, `JSONPathResolver`, `GraphQLIntrospectionService`
-
-[View Module →](./modules/api-reference-04-graphql-mapping.md)
-
----
-
-### Module 4: Services
-
-**Level:** Intermediate | **Category:** Core Services
-
-Comprehensive services for data transformation, state management, extraction, logging, and S3 operations.
-
-**Key APIs:** `UniversalMapper`, `StateService`, `WebhookValidationService`, `S3Service`
-
-[View Module →](./modules/api-reference-05-services.md)
-
----
-
-### Module 5: Data Sources
-
-**Level:** Intermediate | **Category:** Data Access
-
-Read and write data from S3 buckets and SFTP servers with streaming support.
-
-**Key APIs:** `S3DataSource`, `SftpDataSource`, `InventoryDataSource`
-
-[View Module →](./modules/api-reference-06-data-sources.md)
-
----
-
-### Module 6: Parsers
-
-**Level:** Intermediate | **Category:** Data Parsing
-
-Parse CSV, JSON, XML, and Parquet files with validation and streaming support.
-
-**Key APIs:** `CSVParserService`, `JSONParserService`, `XMLParserService`, `ParquetParserService`
-
-[View Module →](./modules/api-reference-07-parsers.md)
-
----
-
-### Module 7: Types
-
-**Level:** Reference | **Category:** TypeScript
-
-Complete TypeScript type definitions for all SDK interfaces, enums, and types.
-
-**Key Types:** `FluentConfig`, `BatchAction`, `EntityType`, `JobStrategy`, `MappingConfig`, `FieldConfig`
-
-[View Module →](./modules/api-reference-08-types.md)
-
----
-
-### Module 8: Error Handling
-
-**Level:** Intermediate | **Category:** Reliability
-
-Error classes, error codes, and best practices for handling failures.
-
-**Key APIs:** `FluentError`, `AuthenticationError`, `ValidationError`, `MappingError`, `S3ServiceError`
-
-[View Module →](./modules/api-reference-09-error-handling.md)
-
----
-
-### Module 9: Utilities
-
-**Level:** Intermediate | **Category:** Helpers
-
-Helper functions for webhook parsing, event validation, field mapping, and more.
-
-**Key Functions:** `parseWebhookRequest()`, `validateFluentEvent()`, `generateFileName()`, SDK resolvers
-
-[View Module →](./modules/api-reference-10-utilities.md)
-
----
-
-### Module 10: CLI Tools
-
-**Level:** Advanced | **Category:** Development Tools
-
-Command-line utilities for schema introspection, mapping generation, and validation.
-
-**Key Tools:** `introspect-schema`, `generate-mutation-mapping`, `generate-query-mapping`, `validate-schema`, `analyze-coverage`
-
-[View Module →](./modules/api-reference-11-cli-tools.md)
-
----
-
-### Module 11: Testing
-
-**Level:** Intermediate | **Category:** Quality Assurance
-
-Testing utilities, mocks, and helpers for integration testing.
-
-**Key APIs:** `S3Tester`, `FluentConnectionTester`, `MockFluentClient`
-
-[View Module →](./modules/api-reference-12-testing.md)
-
----
-
-### Module 12: Resolver Builder
-
-**Level:** Advanced | **Category:** GraphQL
-
-Build complex GraphQL queries with automatic pagination and field resolution.
-
-**Key APIs:** `ResolverBuilder`, `QueryBuilder`, `FieldResolver`
-
-[View Module →](./modules/api-reference-13-resolver-builder.md)
-
----
-
-## Getting Started
-
-### Installation
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk
-```
-
-### Basic Usage
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Create client
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    username: process.env.FLUENT_USERNAME,
-    password: process.env.FLUENT_PASSWORD,
-  },
-});
-
-// Query data
-const result = await client.graphql({
-  query: `
-    query GetProducts($first: Int) {
-      products(first: $first) {
-        edges {
-          node {
-            id
-            ref
-            name
-          }
-        }
-      }
-    }
-  `,
-  variables: { first: 10 },
-});
-
-console.log(result);
-```
-
-## Documentation Versions
-
-This API reference is for the latest version of the SDK. For version-specific documentation:
-
-- **Latest Version:** [Check npm](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) for current version
-- **Changelog:** See [CHANGELOG.md](../../../CHANGELOG.md) for version history (at repository root)
-
-## Additional Resources
-
-- **[Getting Started Guide](../../00-START-HERE/getting-started.md)** - Setup and first integration
-- **[Comprehensive Guides](../)** - Progressive learning modules
-  - [Auto-Pagination Guide](../auto-pagination/) - Master cursor-based pagination
-  - [Resolver Development Guide](../mapping/resolvers/) - Build custom data transformers
-  - [Universal Mapping Guide](../mapping/) - One config for all formats
-- **[Use Case Examples](../../01-TEMPLATES/readme.md)** - Complete working examples organized by deployment context
-- **[Versori Platform Integration](../../04-REFERENCE/platforms/versori/platforms-versori-readme.md)** - Deploy to Versori
-
-## Support
-
-- **Issues:** Report bugs or request features on GitHub
-- **Documentation:** Browse the complete documentation in the `docs/` directory
-- **Examples:** Check the `examples/` directory for working code samples
-
----
-
-**Ready to dive in?** Start with [Module 1: Client API](./modules/api-reference-01-client-api.md) or browse the [Quick Reference](../advanced-services/advanced-services-quick-reference.md) for common patterns.
+# FC Connect SDK - API Reference
+
+**Complete API documentation for the Fluent Commerce Connect SDK**
+
+This reference provides comprehensive documentation for all public APIs, types, and utilities in the SDK.
+
+## Quick Start
+
+```typescript
+import {
+  createClient,           // Client factory (auto-detects runtime)
+  FluentClient,           // Core API client
+  BatchAPIClient,         // Batch API operations
+  UniversalMapper,        // Field mapping
+  S3DataSource,          // S3 operations
+  SftpDataSource,        // SFTP operations
+  CSVParserService,      // CSV parsing
+  XMLParserService,      // XML parsing
+  ExtractionOrchestrator // High-level extraction
+} from '@fluentcommerce/fc-connect-sdk';
+```
+
+## Quick Navigation
+
+### By Component Type
+
+| Component            | Description                                | Module                                               |
+| -------------------- | ------------------------------------------ | ---------------------------------------------------- |
+| **Client & Factory** | Client creation and core operations        | [Client API](./modules/api-reference-01-client-api.md)             |
+| **Authentication**   | OAuth2 and auth providers                  | [Authentication](./modules/api-reference-03-authentication.md)     |
+| **GraphQL Mapping**  | XML/JSON to GraphQL transformation         | [GraphQL Mapping](./modules/api-reference-04-graphql-mapping.md)   |
+| **Services**         | Core services (mapping, state, extraction) | [Services](./modules/api-reference-05-services.md)                 |
+| **Data Sources**     | S3 and SFTP data sources                   | [Data Sources](./modules/api-reference-06-data-sources.md)         |
+| **Parsers**          | CSV, JSON, XML, Parquet parsers            | [Parsers](./modules/api-reference-07-parsers.md)                   |
+| **Types**            | TypeScript type definitions                | [Types](./modules/api-reference-08-types.md)                       |
+| **Error Handling**   | Error classes and handling                 | [Error Handling](./modules/api-reference-09-error-handling.md)     |
+| **Utilities**        | Helper functions and utilities             | [Utilities](./modules/api-reference-10-utilities.md)               |
+| **CLI Tools**        | Command-line utilities                     | [CLI Tools](./modules/api-reference-11-cli-tools.md)               |
+| **Testing**          | Testing utilities and mocks                | [Testing](./modules/api-reference-12-testing.md)                   |
+| **Resolver Builder** | GraphQL query builder                      | [Resolver Builder](./modules/api-reference-13-resolver-builder.md) |
+
+### By Use Case
+
+| Use Case                    | Start Here                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **First time using SDK**    | [Client API](./modules/api-reference-01-client-api.md) → [Examples](./examples/)                                           |
+| **Building data ingestion** | [Data Sources](./modules/api-reference-06-data-sources.md) → [Services](./modules/api-reference-05-services.md)                          |
+| **XML/JSON to GraphQL**     | [GraphQL Mapping](./modules/api-reference-04-graphql-mapping.md) → [Parsers](./modules/api-reference-07-parsers.md)                      |
+| **Extracting data**         | [Services](./modules/api-reference-05-services.md#extractionorchestrator) → [Examples](./examples/)                            |
+| **Webhook handling**        | [Services](./modules/api-reference-05-services.md#webhook-validation-service) → [Utilities](./modules/api-reference-10-utilities.md)     |
+| **Custom transformations**  | [Services](./modules/api-reference-05-services.md#universal-mapper) → [Resolver Builder](./modules/api-reference-13-resolver-builder.md) |
+| **Testing integrations**    | [Testing](./modules/api-reference-12-testing.md) → [Error Handling](./modules/api-reference-09-error-handling.md)                        |
+
+### Quick References
+
+- **[Event API Input/Output Reference](./event-api-input-output-reference.md)** - ⭐ NEW: Complete Event API request/response structures with live examples
+- **[Quick Reference Cheat Sheet](../advanced-services/advanced-services-quick-reference.md)** - All common APIs on one page
+- **[Code Examples](./examples/)** - Copy-paste ready examples
+- **[Type Definitions](./modules/api-reference-08-types.md)** - Complete TypeScript types
+
+---
+
+## Module Guide
+
+### Module 1: Client API
+
+**Level:** Beginner | **Category:** Core
+
+The main entry point for SDK operations. Learn how to create clients, execute GraphQL operations, send events, and manage batch jobs.
+
+**Key APIs:** `createClient()`, `FluentClient`, `graphql(payload)`, `sendEvent()`, `createJob()`, `sendBatch()`
+
+[View Module →](./modules/api-reference-01-client-api.md)
+
+---
+
+### Module 2: Authentication
+
+**Level:** Intermediate | **Category:** Security
+
+Authentication providers for OAuth2, bearer tokens, and Versori platform connections.
+
+**Key APIs:** `OAuth2AuthProvider`, `BearerTokenAuthProvider`, `AuthManager`
+
+[View Module →](./modules/api-reference-03-authentication.md)
+
+---
+
+### Module 3: GraphQL Mutation Mapping
+
+**Level:** Advanced | **Category:** Data Transformation
+
+Schema-driven transformation of XML/JSON data into GraphQL mutations with full validation.
+
+**Key APIs:** `GraphQLMutationMapper`, `XMLPathResolver`, `JSONPathResolver`, `GraphQLIntrospectionService`
+
+[View Module →](./modules/api-reference-04-graphql-mapping.md)
+
+---
+
+### Module 4: Services
+
+**Level:** Intermediate | **Category:** Core Services
+
+Comprehensive services for data transformation, state management, extraction, logging, and S3 operations.
+
+**Key APIs:** `UniversalMapper`, `StateService`, `WebhookValidationService`, `S3Service`
+
+[View Module →](./modules/api-reference-05-services.md)
+
+---
+
+### Module 5: Data Sources
+
+**Level:** Intermediate | **Category:** Data Access
+
+Read and write data from S3 buckets and SFTP servers with streaming support.
+
+**Key APIs:** `S3DataSource`, `SftpDataSource`, `InventoryDataSource`
+
+[View Module →](./modules/api-reference-06-data-sources.md)
+
+---
+
+### Module 6: Parsers
+
+**Level:** Intermediate | **Category:** Data Parsing
+
+Parse CSV, JSON, XML, and Parquet files with validation and streaming support.
+
+**Key APIs:** `CSVParserService`, `JSONParserService`, `XMLParserService`, `ParquetParserService`
+
+[View Module →](./modules/api-reference-07-parsers.md)
+
+---
+
+### Module 7: Types
+
+**Level:** Reference | **Category:** TypeScript
+
+Complete TypeScript type definitions for all SDK interfaces, enums, and types.
+
+**Key Types:** `FluentConfig`, `BatchAction`, `EntityType`, `JobStrategy`, `MappingConfig`, `FieldConfig`
+
+[View Module →](./modules/api-reference-08-types.md)
+
+---
+
+### Module 8: Error Handling
+
+**Level:** Intermediate | **Category:** Reliability
+
+Error classes, error codes, and best practices for handling failures.
+
+**Key APIs:** `FluentError`, `AuthenticationError`, `ValidationError`, `MappingError`, `S3ServiceError`
+
+[View Module →](./modules/api-reference-09-error-handling.md)
+
+---
+
+### Module 9: Utilities
+
+**Level:** Intermediate | **Category:** Helpers
+
+Helper functions for webhook parsing, event validation, field mapping, and more.
+
+**Key Functions:** `parseWebhookRequest()`, `validateFluentEvent()`, `generateFileName()`, SDK resolvers
+
+[View Module →](./modules/api-reference-10-utilities.md)
+
+---
+
+### Module 10: CLI Tools
+
+**Level:** Advanced | **Category:** Development Tools
+
+Command-line utilities for schema introspection, mapping generation, and validation.
+
+**Key Tools:** `introspect-schema`, `generate-mutation-mapping`, `generate-query-mapping`, `validate-schema`, `analyze-coverage`
+
+[View Module →](./modules/api-reference-11-cli-tools.md)
+
+---
+
+### Module 11: Testing
+
+**Level:** Intermediate | **Category:** Quality Assurance
+
+Testing utilities, mocks, and helpers for integration testing.
+
+**Key APIs:** `S3Tester`, `FluentConnectionTester`, `MockFluentClient`
+
+[View Module →](./modules/api-reference-12-testing.md)
+
+---
+
+### Module 12: Resolver Builder
+
+**Level:** Advanced | **Category:** GraphQL
+
+Build complex GraphQL queries with automatic pagination and field resolution.
+
+**Key APIs:** `ResolverBuilder`, `QueryBuilder`, `FieldResolver`
+
+[View Module →](./modules/api-reference-13-resolver-builder.md)
+
+---
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk
+```
+
+### Basic Usage
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Create client
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    username: process.env.FLUENT_USERNAME,
+    password: process.env.FLUENT_PASSWORD,
+  },
+});
+
+// Query data
+const result = await client.graphql({
+  query: `
+    query GetProducts($first: Int) {
+      products(first: $first) {
+        edges {
+          node {
+            id
+            ref
+            name
+          }
+        }
+      }
+    }
+  `,
+  variables: { first: 10 },
+});
+
+console.log(result);
+```
+
+## Documentation Versions
+
+This API reference is for the latest version of the SDK. For version-specific documentation:
+
+- **Latest Version:** [Check npm](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) for current version
+- **Changelog:** See [CHANGELOG.md](../../../CHANGELOG.md) for version history (at repository root)
+
+## Additional Resources
+
+- **[Getting Started Guide](../../00-START-HERE/getting-started.md)** - Setup and first integration
+- **[Comprehensive Guides](../)** - Progressive learning modules
+  - [Auto-Pagination Guide](../auto-pagination/) - Master cursor-based pagination
+  - [Resolver Development Guide](../mapping/resolvers/) - Build custom data transformers
+  - [Universal Mapping Guide](../mapping/) - One config for all formats
+- **[Use Case Examples](../../01-TEMPLATES/readme.md)** - Complete working examples organized by deployment context
+- **[Versori Platform Integration](../../04-REFERENCE/platforms/versori/platforms-versori-readme.md)** - Deploy to Versori
+
+## Support
+
+- **Issues:** Report bugs or request features on GitHub
+- **Documentation:** Browse the complete documentation in the `docs/` directory
+- **Examples:** Check the `examples/` directory for working code samples
+
+---
+
+**Ready to dive in?** Start with [Module 1: Client API](./modules/api-reference-01-client-api.md) or browse the [Quick Reference](../advanced-services/advanced-services-quick-reference.md) for common patterns.