@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,258 +1,258 @@
-# Parser Services Learning Path
-
-> **Complete guide to data parsing in the Fluent Connect SDK**
-> Progressive learning modules covering CSV, JSON, XML, and Parquet parsers with real examples
-
-## 📚 What You'll Learn
-
-This guide teaches you how to parse and transform data from various formats using the SDK's parser services. By the end, you'll understand:
-
-- ✅ How to choose the right parser for your data format
-- ✅ How to parse CSV, JSON, XML, and Parquet files efficiently
-- ✅ How to handle large files with streaming and batching
-- ✅ How to validate data structure and apply transformations
-- ✅ How to integrate parsers with SDK mapping and ingestion services
-- ✅ How to troubleshoot common parsing issues
-
-## 🎯 Learning Path Overview
-
-This guide is organized into **7 progressive modules**. Follow them in order for the best learning experience:
-
-| Module | Topic | Level |
-|--------|-------|-------|
-| [Module 1](../auto-pagination/modules/auto-pagination-01-foundations.md) | **Foundations** - Parser overview, format comparison, selection guide | Beginner |
-| [Module 2](./modules/02-core-guides-parsers-02-csv-parser.md) | **CSV Parser** - Tabular data, streaming, validation | Beginner |
-| [Module 3](./modules/02-core-guides-parsers-03-json-parser.md) | **JSON Parser** - JSON/JSONL, nested data, path queries | Beginner |
-| [Module 4](./modules/02-core-guides-parsers-04-xml-parser.md) | **XML Parser** - XML parsing, attributes, path resolution, generation | Intermediate |
-| [Module 5](./modules/02-core-guides-parsers-05-parquet-parser.md) | **Parquet Parser** - Columnar data, compression, performance | Advanced |
-| [Module 6](./modules/02-core-guides-parsers-06-integration-patterns.md) | **Integration Patterns** - Combining parsers with SDK services | Advanced |
-| [Module 7](./modules/02-core-guides-parsers-07-troubleshooting.md) | **Troubleshooting** - Common errors, optimization, edge cases | Intermediate |
-
-## 🚀 Quick Navigation
-
-### By Use Case
-
-- **First time parsing data?** → Start with [Module 1: Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md)
-- **Need to parse CSV inventory files?** → Jump to [Module 2: CSV Parser](./modules/02-core-guides-parsers-02-csv-parser.md)
-- **Processing API responses?** → See [Module 3: JSON Parser](./modules/02-core-guides-parsers-03-json-parser.md)
-- **Integrating with EDI/B2B systems?** → Check [Module 4: XML Parser](./modules/02-core-guides-parsers-04-xml-parser.md)
-- **Handling large datasets?** → Explore [Module 5: Parquet Parser](./modules/02-core-guides-parsers-05-parquet-parser.md)
-- **Want code examples?** → Browse [Examples Directory](./examples/)
-
-### By Data Format
-
-Different data formats require different parsing strategies:
-
-| Format | Parser | Common Use Cases | Complexity | Example |
-|--------|--------|------------------|------------|---------|
-| **CSV** | CSVParserService | Inventory feeds, exports, spreadsheets | Simple | [Example](./examples/csv-parser-examples.ts) |
-| **JSON** | JSONParserService | API responses, webhooks, configs | Simple | [Example](./examples/json-parser-examples.ts) |
-| **JSONL** | JSONParserService | Streaming logs, bulk data | Simple | [Example](./examples/json-parser-examples.ts) |
-| **XML** | XMLParserService | EDI, B2B systems, SOAP APIs | Medium | [Example](./examples/xml-parser-examples.ts) |
-| **Parquet** | ParquetParserService | Data warehouses, analytics, large extracts | Advanced | [Example](./examples/parquet-parser-examples.ts) |
-
-### By Integration Type
-
-| Integration | Best Parser | Recommended Approach | Example |
-|-------------|-------------|----------------------|---------|
-| S3 CSV Inventory | CSVParserService | Streaming with batching | [CSV Examples](./examples/csv-parser-examples.ts) |
-| API Webhooks | JSONParserService | Standard parsing with validation | [JSON Examples](./examples/json-parser-examples.ts) |
-| SFCC Orders | XMLParserService | Path resolution + mutation mapping | [XML Examples](./examples/xml-parser-examples.ts) |
-| Data Extraction | ParquetParserService | Columnar format for efficiency | [Parquet Examples](./examples/parquet-parser-examples.ts) |
-| Multi-format ETL | All parsers | Format detection + routing | [See Parser Examples](./examples/) |
-
-## 📖 Quick Reference
-
-For quick lookups, see:
-- [Parser Comparison Table](../advanced-services/advanced-services-quick-reference.md#parser-comparison) - Feature matrix
-- [Parser Examples](./examples/) - Complete code examples for all parsers
-- [Troubleshooting Guide](./modules/02-core-guides-parsers-07-troubleshooting.md#common-errors) - Error messages and fixes
-- [API Reference](../advanced-services/advanced-services-quick-reference.md#api-reference) - All parser methods and options
-
-## 🎓 Prerequisites
-
-Before starting this guide, you should:
-
-1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk`
-2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
-3. ✅ Understand basic data structures (arrays, objects, types)
-4. ✅ Be familiar with the SDK's `createClient()` usage
-
-**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
-
-## 🔍 Key Concepts at a Glance
-
-### Parser Selection Decision Tree
-
-```
-What format is your data?
-├─ Tabular/Spreadsheet (rows + columns)
-│  └─ CSV Parser → Simple, fast, universal support
-│
-├─ Nested/Hierarchical structures
-│  ├─ From APIs/Modern systems
-│  │  └─ JSON Parser → Standard parsing, JSONL streaming
-│  │
-│  └─ From EDI/B2B systems
-│     └─ XML Parser → Path resolution, attribute support
-│
-└─ Large analytical datasets
-   └─ Parquet Parser → Columnar, compressed, efficient
-```
-
-### When to Use Each Parser
-
-**CSV Parser** - Best for:
-- ✅ Inventory feeds from warehouses
-- ✅ Spreadsheet exports (Excel → CSV)
-- ✅ Simple tabular data
-- ✅ Universal compatibility
-
-**JSON Parser** - Best for:
-- ✅ REST API responses
-- ✅ Webhook payloads
-- ✅ Configuration files
-- ✅ Nested data structures
-
-**XML Parser** - Best for:
-- ✅ EDI/B2B integrations
-- ✅ System exports
-- ✅ SOAP API responses
-- ✅ SFCC/Adobe Commerce orders
-
-**Parquet Parser** - Best for:
-- ✅ Large-scale data extraction
-- ✅ Analytics and reporting
-- ✅ Data warehouse ingestion
-- ✅ Memory-efficient processing
-
-## 🛠️ Complete Example
-
-Here's a real-world example showing parser integration:
-
-```typescript
-import {
-  createClient,
-  CSVParserService,
-  UniversalMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Create client (works in Node.js, Deno, and Versori)
-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!
-  }
-});
-
-// Sample CSV data (from warehouse feed)
-const csvData = `sku,qty,location,updated_date
-SKU001,100,WH-01,2025-01-15
-SKU002,50,WH-01,2025-01-15
-SKU003,75,WH-02,2025-01-15`;
-
-// Step 1: Parse CSV
-const csvParser = new CSVParserService();
-const records = await csvParser.parse(csvData);
-console.log(`Parsed ${records.length} records`);
-
-// Step 2: Transform with UniversalMapper
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: 'sku', required: true },
-    qty: { source: 'qty', resolver: 'sdk.parseInt' },
-    locationRef: { source: 'location' },
-    updatedOn: { source: 'updated_date', resolver: 'sdk.formatDate' }
-  }
-});
-
-const result = await mapper.map(records);
-
-if (!result.success) {
-  console.error('Mapping errors:', result.errors);
-  throw new Error('Transformation failed');
-}
-
-// Step 3: Send to Fluent Commerce (Batch API for INVENTORY only)
-const job = await client.createJob({
-  name: 'csv-inventory-update',
-  retailerId: process.env.FLUENT_RETAILER_ID!
-});
-
-await client.sendBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  source: 'CSV_IMPORT',
-  event: 'INVENTORY_UPDATE',
-  entities: result.data
-});
-
-console.log(`✅ Successfully ingested ${result.data.length} inventory positions`);
-```
-
-**What this does:**
-1. Parses CSV data into structured records
-2. Transforms records to Fluent format using field mappings
-3. Sends transformed data to Fluent Commerce Batch API
-
-## 📂 Repository Structure
-
-```
-docs/guides/parsers/
-├── readme.md                          # This file - main index
-├── quick-reference.md                 # Parser comparison and API reference
-│
-├── modules/                           # Learning modules
-│   ├── 01-foundations.md              # Parser overview and selection
-│   ├── 02-csv-parser.md               # CSV parsing guide
-│   ├── 03-json-parser.md              # JSON/JSONL parsing guide
-│   ├── 04-xml-parser.md               # XML parsing and generation
-│   ├── 05-parquet-parser.md           # Parquet columnar data
-│   ├── 06-integration-patterns.md     # SDK service integration
-│   └── 07-troubleshooting.md          # Error handling and optimization
-│
-└── examples/                          # Verified code examples
-    ├── readme.md                      # Examples index
-    ├── common-patterns.ts             # Copy-paste ready patterns
-    ├── csv-basic.ts                   # Basic CSV parsing
-    ├── csv-streaming.ts               # Large CSV with streaming
-    ├── json-basic.ts                  # Basic JSON parsing
-    ├── jsonl-streaming.ts             # JSONL streaming
-    ├── xml-basic.ts                   # Basic XML parsing
-    ├── xml-generation.ts              # XML generation
-    ├── parquet-basic.ts               # Basic Parquet parsing
-    ├── s3-csv-ingestion.ts            # Complete S3 CSV workflow
-    ├── webhook-json.ts                # JSON webhook processing
-    ├── sfcc-xml-order.ts              # SFCC XML order integration
-    ├── parquet-extraction.ts          # Parquet extraction workflow
-    └── multi-format-etl.ts            # Multi-format ETL pipeline
-```
-
-## 🔗 Related Documentation
-
-- [Universal Mapping Guide](../mapping/mapping-readme.md) - Transform parsed data
-- [Auto-Pagination Guide](../auto-pagination/) - Fetch large datasets
-- [Resolver Development Guide](../mapping/resolvers/mapping-resolvers-readme.md) - Custom transformations
-- [Versori Platform Integration](../../04-REFERENCE/platforms/versori/) - Deploy to Versori
-
-## 💡 Tips for Best Results
-
-1. **Choose the right parser** - Match parser to data format and use case
-2. **Use streaming for large files** - Prevent memory issues with batch processing
-3. **Validate early** - Use parser validation before transformation
-4. **Combine with UniversalMapper** - Standard pattern for data transformation
-5. **Test with sample data** - Validate parsing logic before production
-
-## 🚦 Getting Started
-
-Ready to begin? Start with [Module 1: Foundations →](../auto-pagination/modules/auto-pagination-01-foundations.md)
-
----
-
-**Need Help?**
-- 📖 Browse [Examples](./examples/)
-- 🔍 Check [Troubleshooting](./modules/02-core-guides-parsers-07-troubleshooting.md)
-- 📧 Contact support@fluentcommerce.com
-- 🐛 Report issues at [GitHub](https://github.com/fluentcommerce/fc-connect-sdk/issues)
+# Parser Services Learning Path
+
+> **Complete guide to data parsing in the Fluent Connect SDK**
+> Progressive learning modules covering CSV, JSON, XML, and Parquet parsers with real examples
+
+## 📚 What You'll Learn
+
+This guide teaches you how to parse and transform data from various formats using the SDK's parser services. By the end, you'll understand:
+
+- ✅ How to choose the right parser for your data format
+- ✅ How to parse CSV, JSON, XML, and Parquet files efficiently
+- ✅ How to handle large files with streaming and batching
+- ✅ How to validate data structure and apply transformations
+- ✅ How to integrate parsers with SDK mapping and ingestion services
+- ✅ How to troubleshoot common parsing issues
+
+## 🎯 Learning Path Overview
+
+This guide is organized into **7 progressive modules**. Follow them in order for the best learning experience:
+
+| Module | Topic | Level |
+|--------|-------|-------|
+| [Module 1](../auto-pagination/modules/auto-pagination-01-foundations.md) | **Foundations** - Parser overview, format comparison, selection guide | Beginner |
+| [Module 2](./modules/02-core-guides-parsers-02-csv-parser.md) | **CSV Parser** - Tabular data, streaming, validation | Beginner |
+| [Module 3](./modules/02-core-guides-parsers-03-json-parser.md) | **JSON Parser** - JSON/JSONL, nested data, path queries | Beginner |
+| [Module 4](./modules/02-core-guides-parsers-04-xml-parser.md) | **XML Parser** - XML parsing, attributes, path resolution, generation | Intermediate |
+| [Module 5](./modules/02-core-guides-parsers-05-parquet-parser.md) | **Parquet Parser** - Columnar data, compression, performance | Advanced |
+| [Module 6](./modules/02-core-guides-parsers-06-integration-patterns.md) | **Integration Patterns** - Combining parsers with SDK services | Advanced |
+| [Module 7](./modules/02-core-guides-parsers-07-troubleshooting.md) | **Troubleshooting** - Common errors, optimization, edge cases | Intermediate |
+
+## 🚀 Quick Navigation
+
+### By Use Case
+
+- **First time parsing data?** → Start with [Module 1: Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md)
+- **Need to parse CSV inventory files?** → Jump to [Module 2: CSV Parser](./modules/02-core-guides-parsers-02-csv-parser.md)
+- **Processing API responses?** → See [Module 3: JSON Parser](./modules/02-core-guides-parsers-03-json-parser.md)
+- **Integrating with EDI/B2B systems?** → Check [Module 4: XML Parser](./modules/02-core-guides-parsers-04-xml-parser.md)
+- **Handling large datasets?** → Explore [Module 5: Parquet Parser](./modules/02-core-guides-parsers-05-parquet-parser.md)
+- **Want code examples?** → Browse [Examples Directory](./examples/)
+
+### By Data Format
+
+Different data formats require different parsing strategies:
+
+| Format | Parser | Common Use Cases | Complexity | Example |
+|--------|--------|------------------|------------|---------|
+| **CSV** | CSVParserService | Inventory feeds, exports, spreadsheets | Simple | [Example](./examples/csv-parser-examples.ts) |
+| **JSON** | JSONParserService | API responses, webhooks, configs | Simple | [Example](./examples/json-parser-examples.ts) |
+| **JSONL** | JSONParserService | Streaming logs, bulk data | Simple | [Example](./examples/json-parser-examples.ts) |
+| **XML** | XMLParserService | EDI, B2B systems, SOAP APIs | Medium | [Example](./examples/xml-parser-examples.ts) |
+| **Parquet** | ParquetParserService | Data warehouses, analytics, large extracts | Advanced | [Example](./examples/parquet-parser-examples.ts) |
+
+### By Integration Type
+
+| Integration | Best Parser | Recommended Approach | Example |
+|-------------|-------------|----------------------|---------|
+| S3 CSV Inventory | CSVParserService | Streaming with batching | [CSV Examples](./examples/csv-parser-examples.ts) |
+| API Webhooks | JSONParserService | Standard parsing with validation | [JSON Examples](./examples/json-parser-examples.ts) |
+| SFCC Orders | XMLParserService | Path resolution + mutation mapping | [XML Examples](./examples/xml-parser-examples.ts) |
+| Data Extraction | ParquetParserService | Columnar format for efficiency | [Parquet Examples](./examples/parquet-parser-examples.ts) |
+| Multi-format ETL | All parsers | Format detection + routing | [See Parser Examples](./examples/) |
+
+## 📖 Quick Reference
+
+For quick lookups, see:
+- [Parser Comparison Table](../advanced-services/advanced-services-quick-reference.md#parser-comparison) - Feature matrix
+- [Parser Examples](./examples/) - Complete code examples for all parsers
+- [Troubleshooting Guide](./modules/02-core-guides-parsers-07-troubleshooting.md#common-errors) - Error messages and fixes
+- [API Reference](../advanced-services/advanced-services-quick-reference.md#api-reference) - All parser methods and options
+
+## 🎓 Prerequisites
+
+Before starting this guide, you should:
+
+1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk`
+2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
+3. ✅ Understand basic data structures (arrays, objects, types)
+4. ✅ Be familiar with the SDK's `createClient()` usage
+
+**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
+
+## 🔍 Key Concepts at a Glance
+
+### Parser Selection Decision Tree
+
+```
+What format is your data?
+├─ Tabular/Spreadsheet (rows + columns)
+│  └─ CSV Parser → Simple, fast, universal support
+│
+├─ Nested/Hierarchical structures
+│  ├─ From APIs/Modern systems
+│  │  └─ JSON Parser → Standard parsing, JSONL streaming
+│  │
+│  └─ From EDI/B2B systems
+│     └─ XML Parser → Path resolution, attribute support
+│
+└─ Large analytical datasets
+   └─ Parquet Parser → Columnar, compressed, efficient
+```
+
+### When to Use Each Parser
+
+**CSV Parser** - Best for:
+- ✅ Inventory feeds from warehouses
+- ✅ Spreadsheet exports (Excel → CSV)
+- ✅ Simple tabular data
+- ✅ Universal compatibility
+
+**JSON Parser** - Best for:
+- ✅ REST API responses
+- ✅ Webhook payloads
+- ✅ Configuration files
+- ✅ Nested data structures
+
+**XML Parser** - Best for:
+- ✅ EDI/B2B integrations
+- ✅ System exports
+- ✅ SOAP API responses
+- ✅ SFCC/Adobe Commerce orders
+
+**Parquet Parser** - Best for:
+- ✅ Large-scale data extraction
+- ✅ Analytics and reporting
+- ✅ Data warehouse ingestion
+- ✅ Memory-efficient processing
+
+## 🛠️ Complete Example
+
+Here's a real-world example showing parser integration:
+
+```typescript
+import {
+  createClient,
+  CSVParserService,
+  UniversalMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Create client (works in Node.js, Deno, and Versori)
+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!
+  }
+});
+
+// Sample CSV data (from warehouse feed)
+const csvData = `sku,qty,location,updated_date
+SKU001,100,WH-01,2025-01-15
+SKU002,50,WH-01,2025-01-15
+SKU003,75,WH-02,2025-01-15`;
+
+// Step 1: Parse CSV
+const csvParser = new CSVParserService();
+const records = await csvParser.parse(csvData);
+console.log(`Parsed ${records.length} records`);
+
+// Step 2: Transform with UniversalMapper
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: 'sku', required: true },
+    qty: { source: 'qty', resolver: 'sdk.parseInt' },
+    locationRef: { source: 'location' },
+    updatedOn: { source: 'updated_date', resolver: 'sdk.formatDate' }
+  }
+});
+
+const result = await mapper.map(records);
+
+if (!result.success) {
+  console.error('Mapping errors:', result.errors);
+  throw new Error('Transformation failed');
+}
+
+// Step 3: Send to Fluent Commerce (Batch API for INVENTORY only)
+const job = await client.createJob({
+  name: 'csv-inventory-update',
+  retailerId: process.env.FLUENT_RETAILER_ID!
+});
+
+await client.sendBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  source: 'CSV_IMPORT',
+  event: 'INVENTORY_UPDATE',
+  entities: result.data
+});
+
+console.log(`✅ Successfully ingested ${result.data.length} inventory positions`);
+```
+
+**What this does:**
+1. Parses CSV data into structured records
+2. Transforms records to Fluent format using field mappings
+3. Sends transformed data to Fluent Commerce Batch API
+
+## 📂 Repository Structure
+
+```
+docs/guides/parsers/
+├── readme.md                          # This file - main index
+├── quick-reference.md                 # Parser comparison and API reference
+│
+├── modules/                           # Learning modules
+│   ├── 01-foundations.md              # Parser overview and selection
+│   ├── 02-csv-parser.md               # CSV parsing guide
+│   ├── 03-json-parser.md              # JSON/JSONL parsing guide
+│   ├── 04-xml-parser.md               # XML parsing and generation
+│   ├── 05-parquet-parser.md           # Parquet columnar data
+│   ├── 06-integration-patterns.md     # SDK service integration
+│   └── 07-troubleshooting.md          # Error handling and optimization
+│
+└── examples/                          # Verified code examples
+    ├── readme.md                      # Examples index
+    ├── common-patterns.ts             # Copy-paste ready patterns
+    ├── csv-basic.ts                   # Basic CSV parsing
+    ├── csv-streaming.ts               # Large CSV with streaming
+    ├── json-basic.ts                  # Basic JSON parsing
+    ├── jsonl-streaming.ts             # JSONL streaming
+    ├── xml-basic.ts                   # Basic XML parsing
+    ├── xml-generation.ts              # XML generation
+    ├── parquet-basic.ts               # Basic Parquet parsing
+    ├── s3-csv-ingestion.ts            # Complete S3 CSV workflow
+    ├── webhook-json.ts                # JSON webhook processing
+    ├── sfcc-xml-order.ts              # SFCC XML order integration
+    ├── parquet-extraction.ts          # Parquet extraction workflow
+    └── multi-format-etl.ts            # Multi-format ETL pipeline
+```
+
+## 🔗 Related Documentation
+
+- [Universal Mapping Guide](../mapping/mapping-readme.md) - Transform parsed data
+- [Auto-Pagination Guide](../auto-pagination/) - Fetch large datasets
+- [Resolver Development Guide](../mapping/resolvers/mapping-resolvers-readme.md) - Custom transformations
+- [Versori Platform Integration](../../04-REFERENCE/platforms/versori/) - Deploy to Versori
+
+## 💡 Tips for Best Results
+
+1. **Choose the right parser** - Match parser to data format and use case
+2. **Use streaming for large files** - Prevent memory issues with batch processing
+3. **Validate early** - Use parser validation before transformation
+4. **Combine with UniversalMapper** - Standard pattern for data transformation
+5. **Test with sample data** - Validate parsing logic before production
+
+## 🚦 Getting Started
+
+Ready to begin? Start with [Module 1: Foundations →](../auto-pagination/modules/auto-pagination-01-foundations.md)
+
+---
+
+**Need Help?**
+- 📖 Browse [Examples](./examples/)
+- 🔍 Check [Troubleshooting](./modules/02-core-guides-parsers-07-troubleshooting.md)
+- 📧 Contact support@fluentcommerce.com
+- 🐛 Report issues at [GitHub](https://github.com/fluentcommerce/fc-connect-sdk/issues)

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

@@ -1,65 +1,65 @@
-# Parsers Guide
-
-> **Parse CSV, XML, JSON, and Parquet files with the FC Connect SDK**
-> Streaming, memory-efficient parsing for all data formats
-
-For complete documentation, see [parsers-readme.md](./parsers-readme.md)
-
-## Quick Start
-
-```typescript
-import { CSVParserService, XMLParserService, JSONParserService, ParquetParserService } from '@fluentcommerce/fc-connect-sdk';
-
-// CSV Parsing
-const csvParser = new CSVParserService(logger);
-const csvData = await csvParser.parse(csvString);
-
-// XML Parsing
-const xmlParser = new XMLParserService(logger);
-const xmlDoc = await xmlParser.parseToDocument(xmlString);
-
-// JSON Parsing
-const jsonParser = new JSONParserService(logger);
-const jsonData = await jsonParser.parse(jsonString);
-
-// Parquet Parsing
-const parquetParser = new ParquetParserService(logger);
-const parquetData = await parquetParser.parse(buffer);
-```
-
-## Navigation
-
-- [Complete Documentation](./parsers-readme.md) - Full guide
-- [Quick Reference](./parsers-quick-reference.md) - Cheat sheet
-- [Modules](./modules/) - Progressive learning modules
-- [Examples](./examples/) - Code examples
-
-## Supported Formats
-
-| Format | Parser | Use Case | Complexity |
-|--------|--------|----------|------------|
-| **CSV** | CSVParserService | Inventory feeds, product catalogs | Simple |
-| **XML** | XMLParserService | Order imports, SFCC integrations | Medium |
-| **JSON** | JSONParserService | API responses, webhooks | Simple |
-| **Parquet** | ParquetParserService | Analytics, data lakes | Medium |
-
-## Learning Path
-
-| Module | Topic | Level |
-|--------|-------|-------|
-| [Module 1](./modules/02-core-guides-parsers-01-foundations.md) | Foundations | Beginner |
-| [Module 2](./modules/02-core-guides-parsers-02-csv-parser.md) | CSV Parser | Beginner |
-| [Module 3](./modules/02-core-guides-parsers-03-json-parser.md) | JSON Parser | Beginner |
-| [Module 4](./modules/02-core-guides-parsers-04-xml-parser.md) | XML Parser | Intermediate |
-| [Module 5](./modules/02-core-guides-parsers-05-parquet-parser.md) | Parquet Parser | Intermediate |
-| [Module 6](./modules/02-core-guides-parsers-06-integration-patterns.md) | Integration Patterns | Intermediate |
-| [Module 7](./modules/02-core-guides-parsers-07-troubleshooting.md) | Troubleshooting | All Levels |
-
-## Key Features
-
-- **Streaming** - Memory-efficient for large files
-- **Validation** - Built-in schema validation
-- **Error Handling** - Graceful error recovery
-- **Type Safety** - Full TypeScript support
-
-See [parsers-readme.md](./parsers-readme.md) for complete details.
+# Parsers Guide
+
+> **Parse CSV, XML, JSON, and Parquet files with the FC Connect SDK**
+> Streaming, memory-efficient parsing for all data formats
+
+For complete documentation, see [parsers-readme.md](./parsers-readme.md)
+
+## Quick Start
+
+```typescript
+import { CSVParserService, XMLParserService, JSONParserService, ParquetParserService } from '@fluentcommerce/fc-connect-sdk';
+
+// CSV Parsing
+const csvParser = new CSVParserService(logger);
+const csvData = await csvParser.parse(csvString);
+
+// XML Parsing
+const xmlParser = new XMLParserService(logger);
+const xmlDoc = await xmlParser.parseToDocument(xmlString);
+
+// JSON Parsing
+const jsonParser = new JSONParserService(logger);
+const jsonData = await jsonParser.parse(jsonString);
+
+// Parquet Parsing
+const parquetParser = new ParquetParserService(logger);
+const parquetData = await parquetParser.parse(buffer);
+```
+
+## Navigation
+
+- [Complete Documentation](./parsers-readme.md) - Full guide
+- [Quick Reference](./parsers-quick-reference.md) - Cheat sheet
+- [Modules](./modules/) - Progressive learning modules
+- [Examples](./examples/) - Code examples
+
+## Supported Formats
+
+| Format | Parser | Use Case | Complexity |
+|--------|--------|----------|------------|
+| **CSV** | CSVParserService | Inventory feeds, product catalogs | Simple |
+| **XML** | XMLParserService | Order imports, SFCC integrations | Medium |
+| **JSON** | JSONParserService | API responses, webhooks | Simple |
+| **Parquet** | ParquetParserService | Analytics, data lakes | Medium |
+
+## Learning Path
+
+| Module | Topic | Level |
+|--------|-------|-------|
+| [Module 1](./modules/02-core-guides-parsers-01-foundations.md) | Foundations | Beginner |
+| [Module 2](./modules/02-core-guides-parsers-02-csv-parser.md) | CSV Parser | Beginner |
+| [Module 3](./modules/02-core-guides-parsers-03-json-parser.md) | JSON Parser | Beginner |
+| [Module 4](./modules/02-core-guides-parsers-04-xml-parser.md) | XML Parser | Intermediate |
+| [Module 5](./modules/02-core-guides-parsers-05-parquet-parser.md) | Parquet Parser | Intermediate |
+| [Module 6](./modules/02-core-guides-parsers-06-integration-patterns.md) | Integration Patterns | Intermediate |
+| [Module 7](./modules/02-core-guides-parsers-07-troubleshooting.md) | Troubleshooting | All Levels |
+
+## Key Features
+
+- **Streaming** - Memory-efficient for large files
+- **Validation** - Built-in schema validation
+- **Error Handling** - Graceful error recovery
+- **Type Safety** - Full TypeScript support
+
+See [parsers-readme.md](./parsers-readme.md) for complete details.