npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (475) hide show

package/docs/02-CORE-GUIDES/parsers/parsers-quick-reference.md CHANGED Viewed

@@ -1,482 +1,482 @@
-# Parser Quick Reference
-One-page reference for all parser services in the Fluent Connect SDK.
-## Parser Comparison
-| Feature | CSV | JSON | XML | Parquet |
-|---------|-----|------|-----|---------|
-| **Format Type** | Tabular | Nested | Hierarchical | Columnar |
-| **Structure** | Rows & columns | Objects & arrays | Tags & attributes | Column-based |
-| **Human Readable** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ Binary |
-| **File Size** | Medium | Large | Large | Small (compressed) |
-| **Parsing Speed** | Fast | Fast | Medium | Fast (with streaming) |
-| **Nested Data** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
-| **Attributes** | ❌ No | N/A | ✅ Yes | N/A |
-| **Streaming** | ✅ Yes | ✅ JSONL | ✅ Yes | ✅ Yes |
-| **Best For** | Inventory feeds | APIs, webhooks | EDI, B2B | Analytics, extraction |
-| **Common Sources** | Warehouses, Excel | REST APIs | SFCC, EDI | Data warehouses |
-| **Compression** | None | None | None | ✅ Built-in (10:1) |
-## Quick Start Examples
-### CSV Parser
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-const csvParser = new CSVParserService();
-// Parse
-const records = await csvParser.parse(csvContent);
-// Stream large files
-for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
-  await processBatch(batch);
-}
-// Validate
-const validation = csvParser.validate(csvContent, {
-  requiredColumns: ['sku', 'qty']
-});
-```
-### JSON Parser
-```typescript
-import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
-const jsonParser = new JSONParserService();
-// Parse
-const data = await jsonParser.parse(jsonContent);
-// Extract nested data
-const items = await jsonParser.parse(jsonContent, {
-  dataPath: 'response.data.items'
-});
-// Parse JSONL
-for await (const item of jsonParser.parseStreaming(jsonlContent, {
-  jsonLines: true
-})) {
-  await processItem(item);
-}
-// Query data
-const value = jsonParser.query(data, 'store.inventory.items[0]');
-```
-### XML Parser
-```typescript
-import { XMLParserService, XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-const xmlParser = new XMLParserService();
-// Parse
-const parsed = await xmlParser.parse(xmlContent);
-// Access elements and attributes directly
-const orderId = parsed.order?.['@_id'];
-const items = parsed.order?.items?.item; // Array
-// ℹ️ For advanced path resolution with complex queries:
-// XMLPathResolver is part of the mapping services (NOT exported from parsers)
-// See GraphQLMutationMapper documentation
-// Generate XML
-import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-const builder = new XMLBuilder({
-  xmlDeclaration: true,
-  prettyPrint: true
-});
-const xml = builder.build({
-  Order: {
-    '@id': '12345',
-    Customer: { Name: 'John Doe' }
-  }
-});
-```
-### Parquet Parser
-```typescript
-import { ParquetParserService, createConsoleLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = createConsoleLogger();
-const parquetParser = new ParquetParserService(logger);
-// Parse
-const records = await parquetParser.parse(parquetBuffer);
-// Stream large files
-for await (const batch of parquetParser.parseStreaming(parquetBuffer, {
-  batchSize: 1000
-})) {
-  await processBatch(batch);
-}
-// Get column statistics
-const stats = await parquetParser.getColumnStatistics(parquetBuffer);
-```
-## API Reference
-### CSVParserService
-#### Methods
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `parse<T>()` | `csvContent: string, options?: CSVOptions` | `Promise<T[]>` | Parse CSV to array of objects |
-| `parseStreaming<T>()` | `csvContent: string, options?: CSVOptions, batchSize?: number` | `AsyncGenerator<T \| T[]>` | Stream CSV records |
-| `validate()` | `csvContent: string, schema: CSVValidationSchema` | `Promise<CSVValidationResult>` | Validate CSV structure |
-| `stringify()` | `records: any[], options?: StringifyOptions` | `string` | Convert objects to CSV string |
-#### CSVOptions
-```typescript
-interface CSVOptions {
-  columns?: boolean | string[];    // Column headers
-  delimiter?: string;               // Field delimiter (default: ',')
-  quote?: string;                   // Quote character (default: '"')
-  escape?: string;                  // Escape character (default: '"')
-  skip_empty_lines?: boolean;       // Skip empty lines
-  trim?: boolean;                   // Trim whitespace
-  from_line?: number;               // Start from line N
-  relax_column_count?: boolean;     // Allow variable columns
-}
-```
-#### StringifyOptions
-```typescript
-interface StringifyOptions {
-  headers?: boolean;        // Include header row (default: true)
-  delimiter?: string;       // Field delimiter (default: ',')
-  quote?: string;          // Quote character (default: '"')
-  escape?: string;         // Escape character (default: '"')
-}
-```
-#### CSV Stringify Example
-**Status:** ✅ Available as public method on `CSVParserService`
-```typescript
-const csvParser = new CSVParserService();
-const records = [
-  { name: 'Alice', age: 30, city: 'NYC' },
-  { name: 'Bob', age: 25, city: 'LA' }
-];
-const csvString = csvParser.stringify(records, {
-  headers: true,        // Include header row
-  delimiter: ',',       // Field delimiter
-  quote: '"',          // Quote character
-  escape: '"'          // Escape character
-});
-console.log(csvString);
-// Output:
-// name,age,city
-// Alice,30,NYC
-// Bob,25,LA
-```
-### JSONParserService
-#### Methods
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `parse<T>()` | `jsonContent: string, options?: JSONParseOptions` | `Promise<T>` | Parse JSON |
-| `parseStreaming<T>()` | `jsonContent: string \| Readable, options?: JSONStreamOptions` | `AsyncGenerator<T>` | Stream JSON/JSONL |
-| `validate()` | `jsonContent: string, options?: JSONParseOptions` | `JSONValidationResult` | Validate JSON |
-| `query()` | `data: any, path: string` | `any` | Query nested data |
-#### JSONParseOptions
-```typescript
-interface JSONParseOptions {
-  dataPath?: string;                // Extract nested path
-  parseDates?: boolean;             // Auto-parse dates
-  dateFormats?: string[];           // Date format patterns
-  validateSchema?: boolean;         // Validate against schema
-  schema?: object;                  // JSON schema
-  reviver?: (key: string, value: any) => any;  // Custom reviver
-  allowComments?: boolean;          // Allow // and /* */
-  allowTrailingCommas?: boolean;    // Allow trailing commas
-  maxDepth?: number;                // Max nesting depth
-}
-```
-#### JSONStreamOptions
-```typescript
-interface JSONStreamOptions {
-  batchSize?: number;               // Records per batch
-  jsonLines?: boolean;              // JSONL format
-  memoryLimit?: number;             // Memory limit in bytes
-  parseDates?: boolean;             // Auto-parse dates
-}
-```
-### XMLParserService
-#### Methods
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `parse()` | `xmlContent: string, options?: XMLParseOptions` | `Promise<Record<string, unknown>>` | Parse XML |
-| `parseSync()` | `xmlContent: string, options?: XMLParseOptions` | `Record<string, unknown>` | Parse XML synchronously |
-| `parseStreaming()` | `xmlContent: string, options?: XMLStreamOptions` | `AsyncGenerator<Record<string, unknown>>` | Stream XML elements |
-| `validate()` | `xmlContent: string` | `{ valid: boolean; errors: string[] }` | Validate XML |
-| `stringify()` | `data: any, options?: XMLStringifyOptions` | `string` | Convert object to XML |
-#### XMLParseOptions
-```typescript
-interface XMLParseOptions {
-  lowercaseKeys?: boolean;          // Lowercase element names
-  normalizeWhitespace?: boolean;    // Normalize whitespace
-  parseNumbers?: boolean;           // Auto-parse numbers
-  parseBooleans?: boolean;          // Auto-parse booleans
-  parseAttributeValues?: boolean;   // Auto-parse attribute values (numbers/booleans)
-  rootElement?: string;             // Start from element
-  arrayElements?: string[];         // Elements to treat as arrays
-  includeAttributes?: boolean;      // Include attributes
-  attributePrefix?: string;         // Attribute prefix (default: '@')
-  textKey?: string;                 // Text content key (default: '#text')
-  maxDepth?: number;                // Max nesting depth
-  removeNamespacePrefix?: boolean;  // Remove ns: prefixes
-}
-```
-### XML Path Resolution
-**Note:** `XMLPathResolver` is part of the mapping services layer (NOT exported from parsers). For simple parsing, access parsed structure directly using standard JavaScript property access. For complex mapping scenarios with advanced path queries, use `GraphQLMutationMapper` (see mapping documentation).
-### XMLBuilder
-**Status:** ✅ Exported from SDK (`@fluentcommerce/fc-connect-sdk`)
-#### Methods
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `build()` | `data: any, rootElement?: string` | `string` | Generate XML from object |
-#### XML Generation Patterns
-```typescript
-// Simple text
-{ "ItemId": "SKU001" }
-// → <ItemId>SKU001</ItemId>
-// Attribute only
-{ "Order": { "@id": "123" } }
-// → <Order id="123"/>
-// Attribute + text (use #text)
-{ "Color": { "@id": "9101", "#text": "Black" } }
-// → <Color id="9101">Black</Color>
-// Nested children
-{ "Customer": { "Name": { "FirstName": "John" } } }
-// → <Customer><Name><FirstName>John</FirstName></Name></Customer>
-// Arrays
-{ "Items": { "Item": [{ "Id": "1" }, { "Id": "2" }] } }
-// → <Items><Item><Id>1</Id></Item><Item><Id>2</Id></Item></Items>
-```
-### ParquetParserService
-#### Methods
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `parseSimple()` | `arrayBuffer: ArrayBuffer, fileName: string` | `Promise<ParquetDataRecord[]>` | Simple parse (easy mode) |
-| `parse()` | `arrayBuffer: ArrayBuffer, fileName: string, options?: Partial<ParquetParsingOptions>` | `Promise<{records: ParquetDataRecord[]; stats: ParquetParsingStats}>` | Parse with stats |
-| `parseStreaming()` | `arrayBuffer: ArrayBuffer, fileName: string, options?: Partial<ParquetParsingOptions>` | `Promise<ParquetStreamingResult>` | Stream Parquet |
-| `validateFile()` | `arrayBuffer: ArrayBuffer, fileName: string` | `Promise<ValidationResult>` | Validate Parquet |
-| `getPerformanceMetrics()` | none | `ParquetPerformanceMetrics` | Get performance stats |
-#### ParquetParsingOptions
-```typescript
-interface ParquetParsingOptions {
-  batchSize?: number;               // Records per batch
-  maxFileSize?: number;             // Max file size in bytes
-  enableStreaming?: boolean;        // Enable streaming mode
-  validation?: {
-    enabled?: boolean;              // Enable validation
-    requiredColumns?: string[];     // Required column names
-    columnTypes?: Record<string, ParquetDataType>;  // Expected types
-    allowAdditionalColumns?: boolean;  // Allow extra columns
-  };
-}
-```
-## Common Integration Patterns
-### Pattern 1: CSV → Transform → Fluent
-```typescript
-import { CSVParserService, UniversalMapper, createClient } from '@fluentcommerce/fc-connect-sdk';
-const csvParser = new CSVParserService();
-const records = await csvParser.parse(csvContent);
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: 'sku', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-    locationRef: { source: 'warehouse' }
-  }
-});
-const result = await mapper.map(records);
-const client = await createClient({ config });
-const job = await client.createJob({
-  name: 'inventory-ingestion',
-  retailerId: config.retailerId
-});
-await client.sendBatch(job.id, {
-  entityType: 'INVENTORY',
-  entities: result.data
-});
-```
-### Pattern 2: JSON Webhook → Fluent
-```typescript
-import { JSONParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
-const jsonParser = new JSONParserService();
-const order = await jsonParser.parse(webhookPayload, {
-  parseDates: true
-});
-const client = await createClient({ config });
-await client.graphql({
-  query: createOrderMutation,
-  variables: { input: order }
-});
-```
-### Pattern 3: XML → GraphQL Mutation
-```typescript
-import { XMLParserService, GraphQLMutationMapper, createClient } from '@fluentcommerce/fc-connect-sdk';
-const xmlParser = new XMLParserService();
-const parsed = await xmlParser.parse(xmlContent);
-const mapper = new GraphQLMutationMapper(mappingConfig);
-const mutation = await mapper.map(parsed);
-const client = await createClient({ config });
-await client.graphql({
-  query: mutation.query,
-  variables: mutation.variables
-});
-```
-### Pattern 4: Fluent → Parquet → S3
-```typescript
-import { createClient, ParquetParserService, S3DataSource, createConsoleLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = createConsoleLogger();
-const client = await createClient({ config });
-const result = await client.graphql({
-  query: extractionQuery,
-  pagination: { maxRecords: 1000000 }
-});
-const records = result.data.virtualPositions.edges.map(e => e.node);
-const parquetBuffer = await convertToParquet(records);
-const s3DataSource = new S3DataSource({
-  type: 'S3_PARQUET',
-  connectionId: 's3-parquet-extract',
-  name: 'S3 Parquet Extract',
-  s3Config: s3Config
-}, logger);
-await s3DataSource.uploadFile('data.parquet', parquetBuffer);
-```
-## Performance Guidelines
-| File Size | Parser Strategy | Batch Size | Notes |
-|-----------|----------------|------------|-------|
-| < 10MB | Direct parsing | N/A | Fast, load into memory |
-| 10-100MB | Streaming | 1000-5000 | Balance speed & memory |
-| 100MB-1GB | Streaming | 500-1000 | Smaller batches for safety |
-| > 1GB | Streaming + parallel | 100-500 | Process in parallel when possible |
-## Error Handling Checklist
-- ✅ Validate input before parsing
-- ✅ Use try-catch blocks
-- ✅ Log parsing errors with context
-- ✅ Implement retry logic for transient failures
-- ✅ Handle partial successes
-- ✅ Monitor parsing performance metrics
-## When to Use Each Parser
-**CSV Parser** - Choose when:
-- ✅ Data is tabular (rows and columns)
-- ✅ Source is warehouse feeds or spreadsheet exports
-- ✅ No nested data structures needed
-- ✅ Universal compatibility required
-**JSON Parser** - Choose when:
-- ✅ Data comes from REST APIs or webhooks
-- ✅ Need nested object/array structures
-- ✅ Working with modern systems
-- ✅ Type-aware data (strings, numbers, booleans)
-**XML Parser** - Choose when:
-- ✅ Integrating with EDI or B2B systems
-- ✅ Source is SFCC, Adobe Commerce, or B2B systems
-- ✅ Data has attributes and hierarchical structure
-- ✅ XML schema validation needed
-**Parquet Parser** - Choose when:
-- ✅ Extracting large datasets (1M+ records)
-- ✅ Need efficient compression (10:1 ratio)
-- ✅ Feeding data warehouses or analytics platforms
-- ✅ Working with columnar data
-## Quick Troubleshooting
-| Error | Likely Cause | Solution |
-|-------|--------------|----------|
-| "Invalid CSV format" | Wrong delimiter or malformed quotes | Try different delimiter, use relaxed options |
-| "Memory limit exceeded" | File too large | Use streaming with smaller batches |
-| "Unexpected token" (JSON) | Invalid JSON syntax | Try with `allowComments` and `allowTrailingCommas` |
-| "Mismatched tags" (XML) | Malformed XML | Validate XML first, check for unclosed tags |
-| "Cannot access attribute" (XML) | Wrong path syntax | Use XMLPathResolver with @ prefix for attributes |
-| "Invalid Parquet file" | Corrupted or wrong format | Check file magic bytes, validate before parsing |
-## See Also
-- [Parser Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md) - Detailed parser concepts
-- [CSV Parser Guide](./modules/02-core-guides-parsers-02-csv-parser.md) - Complete CSV documentation
-- [JSON Parser Guide](./modules/02-core-guides-parsers-03-json-parser.md) - Complete JSON documentation
-- [XML Parser Guide](./modules/02-core-guides-parsers-04-xml-parser.md) - Complete XML documentation
-- [Parquet Parser Guide](./modules/02-core-guides-parsers-05-parquet-parser.md) - Complete Parquet documentation
-- [Integration Patterns](./modules/02-core-guides-parsers-06-integration-patterns.md) - Real-world examples
-- [Troubleshooting](./modules/02-core-guides-parsers-07-troubleshooting.md) - Error handling and optimization
-- [Examples](./examples/) - Copy-paste ready code
+# Parser Quick Reference
+One-page reference for all parser services in the Fluent Connect SDK.
+## Parser Comparison
+| Feature | CSV | JSON | XML | Parquet |
+|---------|-----|------|-----|---------|
+| **Format Type** | Tabular | Nested | Hierarchical | Columnar |
+| **Structure** | Rows & columns | Objects & arrays | Tags & attributes | Column-based |
+| **Human Readable** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ Binary |
+| **File Size** | Medium | Large | Large | Small (compressed) |
+| **Parsing Speed** | Fast | Fast | Medium | Fast (with streaming) |
+| **Nested Data** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Attributes** | ❌ No | N/A | ✅ Yes | N/A |
+| **Streaming** | ✅ Yes | ✅ JSONL | ✅ Yes | ✅ Yes |
+| **Best For** | Inventory feeds | APIs, webhooks | EDI, B2B | Analytics, extraction |
+| **Common Sources** | Warehouses, Excel | REST APIs | SFCC, EDI | Data warehouses |
+| **Compression** | None | None | None | ✅ Built-in (10:1) |
+## Quick Start Examples
+### CSV Parser
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+const csvParser = new CSVParserService();
+// Parse
+const records = await csvParser.parse(csvContent);
+// Stream large files
+for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
+  await processBatch(batch);
+}
+// Validate
+const validation = csvParser.validate(csvContent, {
+  requiredColumns: ['sku', 'qty']
+});
+```
+### JSON Parser
+```typescript
+import { JSONParserService } from '@fluentcommerce/fc-connect-sdk';
+const jsonParser = new JSONParserService();
+// Parse
+const data = await jsonParser.parse(jsonContent);
+// Extract nested data
+const items = await jsonParser.parse(jsonContent, {
+  dataPath: 'response.data.items'
+});
+// Parse JSONL
+for await (const item of jsonParser.parseStreaming(jsonlContent, {
+  jsonLines: true
+})) {
+  await processItem(item);
+}
+// Query data
+const value = jsonParser.query(data, 'store.inventory.items[0]');
+```
+### XML Parser
+```typescript
+import { XMLParserService, XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+const xmlParser = new XMLParserService();
+// Parse
+const parsed = await xmlParser.parse(xmlContent);
+// Access elements and attributes directly
+const orderId = parsed.order?.['@_id'];
+const items = parsed.order?.items?.item; // Array
+// ℹ️ For advanced path resolution with complex queries:
+// XMLPathResolver is part of the mapping services (NOT exported from parsers)
+// See GraphQLMutationMapper documentation
+// Generate XML
+import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+const builder = new XMLBuilder({
+  xmlDeclaration: true,
+  prettyPrint: true
+});
+const xml = builder.build({
+  Order: {
+    '@id': '12345',
+    Customer: { Name: 'John Doe' }
+  }
+});
+```
+### Parquet Parser
+```typescript
+import { ParquetParserService, createConsoleLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = createConsoleLogger();
+const parquetParser = new ParquetParserService(logger);
+// Parse
+const records = await parquetParser.parse(parquetBuffer);
+// Stream large files
+for await (const batch of parquetParser.parseStreaming(parquetBuffer, {
+  batchSize: 1000
+})) {
+  await processBatch(batch);
+}
+// Get column statistics
+const stats = await parquetParser.getColumnStatistics(parquetBuffer);
+```
+## API Reference
+### CSVParserService
+#### Methods
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `parse<T>()` | `csvContent: string, options?: CSVOptions` | `Promise<T[]>` | Parse CSV to array of objects |
+| `parseStreaming<T>()` | `csvContent: string, options?: CSVOptions, batchSize?: number` | `AsyncGenerator<T \| T[]>` | Stream CSV records |
+| `validate()` | `csvContent: string, schema: CSVValidationSchema` | `Promise<CSVValidationResult>` | Validate CSV structure |
+| `stringify()` | `records: any[], options?: StringifyOptions` | `string` | Convert objects to CSV string |
+#### CSVOptions
+```typescript
+interface CSVOptions {
+  columns?: boolean | string[];    // Column headers
+  delimiter?: string;               // Field delimiter (default: ',')
+  quote?: string;                   // Quote character (default: '"')
+  escape?: string;                  // Escape character (default: '"')
+  skip_empty_lines?: boolean;       // Skip empty lines
+  trim?: boolean;                   // Trim whitespace
+  from_line?: number;               // Start from line N
+  relax_column_count?: boolean;     // Allow variable columns
+}
+```
+#### StringifyOptions
+```typescript
+interface StringifyOptions {
+  headers?: boolean;        // Include header row (default: true)
+  delimiter?: string;       // Field delimiter (default: ',')
+  quote?: string;          // Quote character (default: '"')
+  escape?: string;         // Escape character (default: '"')
+}
+```
+#### CSV Stringify Example
+**Status:** ✅ Available as public method on `CSVParserService`
+```typescript
+const csvParser = new CSVParserService();
+const records = [
+  { name: 'Alice', age: 30, city: 'NYC' },
+  { name: 'Bob', age: 25, city: 'LA' }
+];
+const csvString = csvParser.stringify(records, {
+  headers: true,        // Include header row
+  delimiter: ',',       // Field delimiter
+  quote: '"',          // Quote character
+  escape: '"'          // Escape character
+});
+console.log(csvString);
+// Output:
+// name,age,city
+// Alice,30,NYC
+// Bob,25,LA
+```
+### JSONParserService
+#### Methods
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `parse<T>()` | `jsonContent: string, options?: JSONParseOptions` | `Promise<T>` | Parse JSON |
+| `parseStreaming<T>()` | `jsonContent: string \| Readable, options?: JSONStreamOptions` | `AsyncGenerator<T>` | Stream JSON/JSONL |
+| `validate()` | `jsonContent: string, options?: JSONParseOptions` | `JSONValidationResult` | Validate JSON |
+| `query()` | `data: any, path: string` | `any` | Query nested data |
+#### JSONParseOptions
+```typescript
+interface JSONParseOptions {
+  dataPath?: string;                // Extract nested path
+  parseDates?: boolean;             // Auto-parse dates
+  dateFormats?: string[];           // Date format patterns
+  validateSchema?: boolean;         // Validate against schema
+  schema?: object;                  // JSON schema
+  reviver?: (key: string, value: any) => any;  // Custom reviver
+  allowComments?: boolean;          // Allow // and /* */
+  allowTrailingCommas?: boolean;    // Allow trailing commas
+  maxDepth?: number;                // Max nesting depth
+}
+```
+#### JSONStreamOptions
+```typescript
+interface JSONStreamOptions {
+  batchSize?: number;               // Records per batch
+  jsonLines?: boolean;              // JSONL format
+  memoryLimit?: number;             // Memory limit in bytes
+  parseDates?: boolean;             // Auto-parse dates
+}
+```
+### XMLParserService
+#### Methods
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `parse()` | `xmlContent: string, options?: XMLParseOptions` | `Promise<Record<string, unknown>>` | Parse XML |
+| `parseSync()` | `xmlContent: string, options?: XMLParseOptions` | `Record<string, unknown>` | Parse XML synchronously |
+| `parseStreaming()` | `xmlContent: string, options?: XMLStreamOptions` | `AsyncGenerator<Record<string, unknown>>` | Stream XML elements |
+| `validate()` | `xmlContent: string` | `{ valid: boolean; errors: string[] }` | Validate XML |
+| `stringify()` | `data: any, options?: XMLStringifyOptions` | `string` | Convert object to XML |
+#### XMLParseOptions
+```typescript
+interface XMLParseOptions {
+  lowercaseKeys?: boolean;          // Lowercase element names
+  normalizeWhitespace?: boolean;    // Normalize whitespace
+  parseNumbers?: boolean;           // Auto-parse numbers
+  parseBooleans?: boolean;          // Auto-parse booleans
+  parseAttributeValues?: boolean;   // Auto-parse attribute values (numbers/booleans)
+  rootElement?: string;             // Start from element
+  arrayElements?: string[];         // Elements to treat as arrays
+  includeAttributes?: boolean;      // Include attributes
+  attributePrefix?: string;         // Attribute prefix (default: '@')
+  textKey?: string;                 // Text content key (default: '#text')
+  maxDepth?: number;                // Max nesting depth
+  removeNamespacePrefix?: boolean;  // Remove ns: prefixes
+}
+```
+### XML Path Resolution
+**Note:** `XMLPathResolver` is part of the mapping services layer (NOT exported from parsers). For simple parsing, access parsed structure directly using standard JavaScript property access. For complex mapping scenarios with advanced path queries, use `GraphQLMutationMapper` (see mapping documentation).
+### XMLBuilder
+**Status:** ✅ Exported from SDK (`@fluentcommerce/fc-connect-sdk`)
+#### Methods
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `build()` | `data: any, rootElement?: string` | `string` | Generate XML from object |
+#### XML Generation Patterns
+```typescript
+// Simple text
+{ "ItemId": "SKU001" }
+// → <ItemId>SKU001</ItemId>
+// Attribute only
+{ "Order": { "@id": "123" } }
+// → <Order id="123"/>
+// Attribute + text (use #text)
+{ "Color": { "@id": "9101", "#text": "Black" } }
+// → <Color id="9101">Black</Color>
+// Nested children
+{ "Customer": { "Name": { "FirstName": "John" } } }
+// → <Customer><Name><FirstName>John</FirstName></Name></Customer>
+// Arrays
+{ "Items": { "Item": [{ "Id": "1" }, { "Id": "2" }] } }
+// → <Items><Item><Id>1</Id></Item><Item><Id>2</Id></Item></Items>
+```
+### ParquetParserService
+#### Methods
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `parseSimple()` | `arrayBuffer: ArrayBuffer, fileName: string` | `Promise<ParquetDataRecord[]>` | Simple parse (easy mode) |
+| `parse()` | `arrayBuffer: ArrayBuffer, fileName: string, options?: Partial<ParquetParsingOptions>` | `Promise<{records: ParquetDataRecord[]; stats: ParquetParsingStats}>` | Parse with stats |
+| `parseStreaming()` | `arrayBuffer: ArrayBuffer, fileName: string, options?: Partial<ParquetParsingOptions>` | `Promise<ParquetStreamingResult>` | Stream Parquet |
+| `validateFile()` | `arrayBuffer: ArrayBuffer, fileName: string` | `Promise<ValidationResult>` | Validate Parquet |
+| `getPerformanceMetrics()` | none | `ParquetPerformanceMetrics` | Get performance stats |
+#### ParquetParsingOptions
+```typescript
+interface ParquetParsingOptions {
+  batchSize?: number;               // Records per batch
+  maxFileSize?: number;             // Max file size in bytes
+  enableStreaming?: boolean;        // Enable streaming mode
+  validation?: {
+    enabled?: boolean;              // Enable validation
+    requiredColumns?: string[];     // Required column names
+    columnTypes?: Record<string, ParquetDataType>;  // Expected types
+    allowAdditionalColumns?: boolean;  // Allow extra columns
+  };
+}
+```
+## Common Integration Patterns
+### Pattern 1: CSV → Transform → Fluent
+```typescript
+import { CSVParserService, UniversalMapper, createClient } from '@fluentcommerce/fc-connect-sdk';
+const csvParser = new CSVParserService();
+const records = await csvParser.parse(csvContent);
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: 'sku', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+    locationRef: { source: 'warehouse' }
+  }
+});
+const result = await mapper.map(records);
+const client = await createClient({ config });
+const job = await client.createJob({
+  name: 'inventory-ingestion',
+  retailerId: config.retailerId
+});
+await client.sendBatch(job.id, {
+  entityType: 'INVENTORY',
+  entities: result.data
+});
+```
+### Pattern 2: JSON Webhook → Fluent
+```typescript
+import { JSONParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
+const jsonParser = new JSONParserService();
+const order = await jsonParser.parse(webhookPayload, {
+  parseDates: true
+});
+const client = await createClient({ config });
+await client.graphql({
+  query: createOrderMutation,
+  variables: { input: order }
+});
+```
+### Pattern 3: XML → GraphQL Mutation
+```typescript
+import { XMLParserService, GraphQLMutationMapper, createClient } from '@fluentcommerce/fc-connect-sdk';
+const xmlParser = new XMLParserService();
+const parsed = await xmlParser.parse(xmlContent);
+const mapper = new GraphQLMutationMapper(mappingConfig);
+const mutation = await mapper.map(parsed);
+const client = await createClient({ config });
+await client.graphql({
+  query: mutation.query,
+  variables: mutation.variables
+});
+```
+### Pattern 4: Fluent → Parquet → S3
+```typescript
+import { createClient, ParquetParserService, S3DataSource, createConsoleLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = createConsoleLogger();
+const client = await createClient({ config });
+const result = await client.graphql({
+  query: extractionQuery,
+  pagination: { maxRecords: 1000000 }
+});
+const records = result.data.virtualPositions.edges.map(e => e.node);
+const parquetBuffer = await convertToParquet(records);
+const s3DataSource = new S3DataSource({
+  type: 'S3_PARQUET',
+  connectionId: 's3-parquet-extract',
+  name: 'S3 Parquet Extract',
+  s3Config: s3Config
+}, logger);
+await s3DataSource.uploadFile('data.parquet', parquetBuffer);
+```
+## Performance Guidelines
+| File Size | Parser Strategy | Batch Size | Notes |
+|-----------|----------------|------------|-------|
+| < 10MB | Direct parsing | N/A | Fast, load into memory |
+| 10-100MB | Streaming | 1000-5000 | Balance speed & memory |
+| 100MB-1GB | Streaming | 500-1000 | Smaller batches for safety |
+| > 1GB | Streaming + parallel | 100-500 | Process in parallel when possible |
+## Error Handling Checklist
+- ✅ Validate input before parsing
+- ✅ Use try-catch blocks
+- ✅ Log parsing errors with context
+- ✅ Implement retry logic for transient failures
+- ✅ Handle partial successes
+- ✅ Monitor parsing performance metrics
+## When to Use Each Parser
+**CSV Parser** - Choose when:
+- ✅ Data is tabular (rows and columns)
+- ✅ Source is warehouse feeds or spreadsheet exports
+- ✅ No nested data structures needed
+- ✅ Universal compatibility required
+**JSON Parser** - Choose when:
+- ✅ Data comes from REST APIs or webhooks
+- ✅ Need nested object/array structures
+- ✅ Working with modern systems
+- ✅ Type-aware data (strings, numbers, booleans)
+**XML Parser** - Choose when:
+- ✅ Integrating with EDI or B2B systems
+- ✅ Source is SFCC, Adobe Commerce, or B2B systems
+- ✅ Data has attributes and hierarchical structure
+- ✅ XML schema validation needed
+**Parquet Parser** - Choose when:
+- ✅ Extracting large datasets (1M+ records)
+- ✅ Need efficient compression (10:1 ratio)
+- ✅ Feeding data warehouses or analytics platforms
+- ✅ Working with columnar data
+## Quick Troubleshooting
+| Error | Likely Cause | Solution |
+|-------|--------------|----------|
+| "Invalid CSV format" | Wrong delimiter or malformed quotes | Try different delimiter, use relaxed options |
+| "Memory limit exceeded" | File too large | Use streaming with smaller batches |
+| "Unexpected token" (JSON) | Invalid JSON syntax | Try with `allowComments` and `allowTrailingCommas` |
+| "Mismatched tags" (XML) | Malformed XML | Validate XML first, check for unclosed tags |
+| "Cannot access attribute" (XML) | Wrong path syntax | Use XMLPathResolver with @ prefix for attributes |
+| "Invalid Parquet file" | Corrupted or wrong format | Check file magic bytes, validate before parsing |
+## See Also
+- [Parser Foundations](../auto-pagination/modules/auto-pagination-01-foundations.md) - Detailed parser concepts
+- [CSV Parser Guide](./modules/02-core-guides-parsers-02-csv-parser.md) - Complete CSV documentation
+- [JSON Parser Guide](./modules/02-core-guides-parsers-03-json-parser.md) - Complete JSON documentation
+- [XML Parser Guide](./modules/02-core-guides-parsers-04-xml-parser.md) - Complete XML documentation
+- [Parquet Parser Guide](./modules/02-core-guides-parsers-05-parquet-parser.md) - Complete Parquet documentation
+- [Integration Patterns](./modules/02-core-guides-parsers-06-integration-patterns.md) - Real-world examples
+- [Troubleshooting](./modules/02-core-guides-parsers-07-troubleshooting.md) - Error handling and optimization
+- [Examples](./examples/) - Copy-paste ready code