@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,75 +1,75 @@
-# Custom Resolvers
-
-> **Build custom transformation functions for complex business logic**
-> Extend mapping capabilities with TypeScript/JavaScript functions
-
-For complete documentation, see [mapping-resolvers-readme.md](./mapping-resolvers-readme.md)
-
-## Quick Start
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-// Define custom resolver
-const customResolvers = {
-  calculateDiscount: (value, context, helpers) => {
-    const price = parseFloat(value);
-    return context.data.isVIP ? price * 0.8 : price * 0.9;
-  }
-};
-
-// Use in mapping
-const mapper = new UniversalMapper({
-  fields: {
-    discountedPrice: {
-      source: 'originalPrice',
-      resolver: 'custom.calculateDiscount'
-    }
-  }
-}, customResolvers);
-```
-
-## Navigation
-
-- [Complete Documentation](./mapping-resolvers-readme.md) - Full guide
-- [Resolver Guide](./mapping-resolvers-resolver-guide.md) - Comprehensive guide
-- [API Reference](./mapping-resolvers-resolver-api-reference.md) - Complete API
-- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) - Function signatures
-- [Helpers Reference](./mapping-resolvers-resolver-helpers-reference.md) - Helper functions
-- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Common patterns
-- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues
-- [Examples](./examples/) - Code examples
-
-## SDK Built-in Resolvers
-
-The SDK provides these resolvers out-of-the-box:
-
-**String Transformations**
-- `sdk.trim` - Remove whitespace
-- `sdk.uppercase` - Convert to uppercase
-- `sdk.lowercase` - Convert to lowercase
-
-**Type Conversions**
-- `sdk.parseInt` - Convert to integer
-- `sdk.parseFloat` - Convert to float
-- `sdk.parseBoolean` - Convert to boolean
-
-**Date/Time**
-- `sdk.formatDate` - Format date strings
-- `sdk.parseDate` - Parse date strings
-
-**Advanced**
-- `sdk.split` - Split strings into arrays
-- `sdk.join` - Join arrays into strings
-- `sdk.default` - Provide default values
-
-## When to Use Custom Resolvers
-
-Use custom resolvers when you need:
-- Complex business logic transformations
-- API lookups during mapping
-- Async data enrichment
-- Multi-field conditional transformations
-- Custom data validation
-
-See [mapping-resolvers-readme.md](./mapping-resolvers-readme.md) for complete details.
+# Custom Resolvers
+
+> **Build custom transformation functions for complex business logic**
+> Extend mapping capabilities with TypeScript/JavaScript functions
+
+For complete documentation, see [mapping-resolvers-readme.md](./mapping-resolvers-readme.md)
+
+## Quick Start
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+// Define custom resolver
+const customResolvers = {
+  calculateDiscount: (value, context, helpers) => {
+    const price = parseFloat(value);
+    return context.data.isVIP ? price * 0.8 : price * 0.9;
+  }
+};
+
+// Use in mapping
+const mapper = new UniversalMapper({
+  fields: {
+    discountedPrice: {
+      source: 'originalPrice',
+      resolver: 'custom.calculateDiscount'
+    }
+  }
+}, customResolvers);
+```
+
+## Navigation
+
+- [Complete Documentation](./mapping-resolvers-readme.md) - Full guide
+- [Resolver Guide](./mapping-resolvers-resolver-guide.md) - Comprehensive guide
+- [API Reference](./mapping-resolvers-resolver-api-reference.md) - Complete API
+- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) - Function signatures
+- [Helpers Reference](./mapping-resolvers-resolver-helpers-reference.md) - Helper functions
+- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Common patterns
+- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues
+- [Examples](./examples/) - Code examples
+
+## SDK Built-in Resolvers
+
+The SDK provides these resolvers out-of-the-box:
+
+**String Transformations**
+- `sdk.trim` - Remove whitespace
+- `sdk.uppercase` - Convert to uppercase
+- `sdk.lowercase` - Convert to lowercase
+
+**Type Conversions**
+- `sdk.parseInt` - Convert to integer
+- `sdk.parseFloat` - Convert to float
+- `sdk.parseBoolean` - Convert to boolean
+
+**Date/Time**
+- `sdk.formatDate` - Format date strings
+- `sdk.parseDate` - Parse date strings
+
+**Advanced**
+- `sdk.split` - Split strings into arrays
+- `sdk.join` - Join arrays into strings
+- `sdk.default` - Provide default values
+
+## When to Use Custom Resolvers
+
+Use custom resolvers when you need:
+- Complex business logic transformations
+- API lookups during mapping
+- Async data enrichment
+- Multi-field conditional transformations
+- Custom data validation
+
+See [mapping-resolvers-readme.md](./mapping-resolvers-readme.md) for complete details.

package/docs/02-CORE-GUIDES/parsers/examples/02-core-guides-parsers-readme.md

@@ -1,161 +1,161 @@
-# Parser Examples
-
-This directory contains verified, runnable code examples for all parser services.
-
-## Quick Links
-
-- [CSV Parser Examples](./csv-parser-examples.ts) - Complete CSV parsing examples
-- [JSON Parser Examples](./json-parser-examples.ts) - Complete JSON parsing examples
-- [XML Parser Examples](./xml-parser-examples.ts) - Complete XML parsing examples
-- [Parquet Parser Examples](./parquet-parser-examples.ts) - Complete Parquet parsing examples
-
-## CSV Examples
-
-All CSV parsing examples are consolidated in [csv-parser-examples.ts](./csv-parser-examples.ts), including:
-- Basic CSV parsing
-- Large file streaming
-- Transformation workflows
-- S3 CSV ingestion
-
-## JSON Examples
-
-All JSON parsing examples are consolidated in [json-parser-examples.ts](./json-parser-examples.ts), including:
-- Basic JSON parsing
-- JSONL streaming
-- Webhook processing
-- Shopify integration patterns
-
-## XML Examples
-
-All XML parsing examples are consolidated in [xml-parser-examples.ts](./xml-parser-examples.ts), including:
-- Basic XML parsing
-- XML generation
-- SFCC order transformation
-- Complete SFCC integration
-
-## Parquet Examples
-
-All Parquet parsing examples are consolidated in [parquet-parser-examples.ts](./parquet-parser-examples.ts), including:
-- Basic Parquet parsing
-- Extraction to Parquet
-- Virtual positions extraction
-
-## Common Patterns
-
-See the parser example files above for quick copy-paste snippets:
-
-### CSV Parsing Pattern
-```typescript
-import { CSVParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const csvParser = new CSVParserService();
-const records = await csvParser.parse(csvContent);
-
-const mapper = new UniversalMapper(mappingConfig);
-const result = await mapper.map(records);
-```
-
-### JSON Webhook Pattern
-```typescript
-import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const jsonParser = new JSONParserService();
-const data = await jsonParser.parse(webhookPayload, {
-  parseDates: true,
-  dataPath: 'data.items'
-});
-```
-
-### XML Parsing Pattern
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent);
-
-// Access parsed structure directly
-const orderId = parsed.order?.['@_id'];
-const items = parsed.order?.items?.item; // Array of items
-
-// For advanced path resolution, use XMLPathResolver from mapping services
-// See GraphQLMutationMapper documentation
-```
-
-### Streaming Pattern
-```typescript
-const csvParser = new CSVParserService();
-
-for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
-  const result = await mapper.map(batch);
-  await sendToFluent(result.data);
-}
-```
-
-## Running Examples
-
-All examples are written in TypeScript and can be run directly:
-
-```bash
-# Install dependencies
-npm install @fluentcommerce/fc-connect-sdk
-
-# Set environment variables
-export FLUENT_BASE_URL="https://api.fluentcommerce.com"
-export FLUENT_CLIENT_ID="your-client-id"
-export FLUENT_CLIENT_SECRET="your-client-secret"
-export FLUENT_RETAILER_ID="1"
-
-# Run an example
-npx tsx examples/csv-parser-examples.ts
-```
-
-## Example Template
-
-When creating new examples, follow this template:
-
-```typescript
-/**
- * Example: [Name]
- * Description: [What this example demonstrates]
- * Complexity: [Beginner/Intermediate/Advanced]
- */
-
-import { createClient, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-async function exampleFunction() {
-  // 1. Setup
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    }
-  });
-
-  // 2. Parse data
-  const csvParser = new CSVParserService();
-  const records = await csvParser.parse(csvContent);
-
-  // 3. Transform (if needed)
-  // ... transformation logic
-
-  // 4. Send to Fluent (if applicable)
-  // ... Fluent API calls
-
-  console.log('✅ Example complete');
-}
-
-// Run if main module
-if (require.main === module) {
-  exampleFunction().catch(console.error);
-}
-
-export { exampleFunction };
-```
-
-## Need Help?
-
-- See [Module 7: Troubleshooting](../modules/02-core-guides-parsers-07-troubleshooting.md) for error handling
-- Check [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) for API documentation
-- Review [Integration Patterns](../modules/02-core-guides-parsers-06-integration-patterns.md) for complete workflows
+# Parser Examples
+
+This directory contains verified, runnable code examples for all parser services.
+
+## Quick Links
+
+- [CSV Parser Examples](./csv-parser-examples.ts) - Complete CSV parsing examples
+- [JSON Parser Examples](./json-parser-examples.ts) - Complete JSON parsing examples
+- [XML Parser Examples](./xml-parser-examples.ts) - Complete XML parsing examples
+- [Parquet Parser Examples](./parquet-parser-examples.ts) - Complete Parquet parsing examples
+
+## CSV Examples
+
+All CSV parsing examples are consolidated in [csv-parser-examples.ts](./csv-parser-examples.ts), including:
+- Basic CSV parsing
+- Large file streaming
+- Transformation workflows
+- S3 CSV ingestion
+
+## JSON Examples
+
+All JSON parsing examples are consolidated in [json-parser-examples.ts](./json-parser-examples.ts), including:
+- Basic JSON parsing
+- JSONL streaming
+- Webhook processing
+- Shopify integration patterns
+
+## XML Examples
+
+All XML parsing examples are consolidated in [xml-parser-examples.ts](./xml-parser-examples.ts), including:
+- Basic XML parsing
+- XML generation
+- SFCC order transformation
+- Complete SFCC integration
+
+## Parquet Examples
+
+All Parquet parsing examples are consolidated in [parquet-parser-examples.ts](./parquet-parser-examples.ts), including:
+- Basic Parquet parsing
+- Extraction to Parquet
+- Virtual positions extraction
+
+## Common Patterns
+
+See the parser example files above for quick copy-paste snippets:
+
+### CSV Parsing Pattern
+```typescript
+import { CSVParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const csvParser = new CSVParserService();
+const records = await csvParser.parse(csvContent);
+
+const mapper = new UniversalMapper(mappingConfig);
+const result = await mapper.map(records);
+```
+
+### JSON Webhook Pattern
+```typescript
+import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const jsonParser = new JSONParserService();
+const data = await jsonParser.parse(webhookPayload, {
+  parseDates: true,
+  dataPath: 'data.items'
+});
+```
+
+### XML Parsing Pattern
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent);
+
+// Access parsed structure directly
+const orderId = parsed.order?.['@_id'];
+const items = parsed.order?.items?.item; // Array of items
+
+// For advanced path resolution, use XMLPathResolver from mapping services
+// See GraphQLMutationMapper documentation
+```
+
+### Streaming Pattern
+```typescript
+const csvParser = new CSVParserService();
+
+for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
+  const result = await mapper.map(batch);
+  await sendToFluent(result.data);
+}
+```
+
+## Running Examples
+
+All examples are written in TypeScript and can be run directly:
+
+```bash
+# Install dependencies
+npm install @fluentcommerce/fc-connect-sdk
+
+# Set environment variables
+export FLUENT_BASE_URL="https://api.fluentcommerce.com"
+export FLUENT_CLIENT_ID="your-client-id"
+export FLUENT_CLIENT_SECRET="your-client-secret"
+export FLUENT_RETAILER_ID="1"
+
+# Run an example
+npx tsx examples/csv-parser-examples.ts
+```
+
+## Example Template
+
+When creating new examples, follow this template:
+
+```typescript
+/**
+ * Example: [Name]
+ * Description: [What this example demonstrates]
+ * Complexity: [Beginner/Intermediate/Advanced]
+ */
+
+import { createClient, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+async function exampleFunction() {
+  // 1. Setup
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    }
+  });
+
+  // 2. Parse data
+  const csvParser = new CSVParserService();
+  const records = await csvParser.parse(csvContent);
+
+  // 3. Transform (if needed)
+  // ... transformation logic
+
+  // 4. Send to Fluent (if applicable)
+  // ... Fluent API calls
+
+  console.log('✅ Example complete');
+}
+
+// Run if main module
+if (require.main === module) {
+  exampleFunction().catch(console.error);
+}
+
+export { exampleFunction };
+```
+
+## Need Help?
+
+- See [Module 7: Troubleshooting](../modules/02-core-guides-parsers-07-troubleshooting.md) for error handling
+- Check [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) for API documentation
+- Review [Integration Patterns](../modules/02-core-guides-parsers-06-integration-patterns.md) for complete workflows