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

@fluentcommerce/fc-connect-sdk 0.1.53 → 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 (495) hide show

package/docs/00-START-HERE/cli-analyze-source-structure-guide.md CHANGED Viewed

@@ -1,655 +1,655 @@
-# Analyze Source Structure CLI Tool - User Guide
-**Tool:** `fc-connect analyze-source-structure`
-**Purpose:** Analyze data files (XML, JSON, CSV, Parquet) and generate mapping templates for Fluent Commerce integrations
----
-## Table of Contents
-1. [What Is This Tool?](#what-is-this-tool)
-2. [Why Use It?](#why-use-it)
-3. [Getting Started](#getting-started)
-4. [Quick Start Examples](#quick-start-examples)
-5. [Common Workflows](#common-workflows)
-6. [Understanding the Output](#understanding-the-output)
-7. [Best Practices](#best-practices)
-8. [Advanced Usage](#advanced-usage)
-9. [Troubleshooting](#troubleshooting)
-10. [FAQ](#faq)
----
-## What Is This Tool?
-The `analyze-source-structure` CLI tool helps you understand how data files are structured and automatically generates mapping configurations for the Fluent Connect SDK.
-**What it does:**
-- ✅ Parses your data files (XML, JSON, CSV, Parquet)
-- ✅ Shows you exactly how the SDK sees your data
-- ✅ Lists all available fields and paths for mapping
-- ✅ Detects arrays, nested objects, and XML attributes
-- ✅ Generates ready-to-use mapping templates
-- ✅ Suggests appropriate data type resolvers (parseFloat, trim, etc.)
-- ✅ Creates shareable documentation for your team
-**What it doesn't do:**
-- ❌ Doesn't modify your source files
-- ❌ Doesn't connect to APIs
-- ❌ Doesn't execute mappings (use the SDK for that)
----
-## Why Use It?
-### Problem: Manual Mapping Discovery is Time-Consuming
-Without this tool, you'd need to:
-1. Manually inspect your XML/JSON files
-2. Figure out how the SDK parsers interpret the data
-3. Manually write field paths (prone to errors)
-4. Guess which resolvers to use (sdk.parseFloat vs sdk.parseInt?)
-5. Trial-and-error to find the correct array structures
-### Solution: Automated Analysis
-With this tool, you get:
-- **Instant visibility** - See all available fields in seconds
-- **Accurate paths** - No typos or wrong paths
-- **Smart suggestions** - Automatic resolver detection based on field names and data
-- **Team collaboration** - Generate markdown docs to share with colleagues
-- **Faster onboarding** - New developers understand data structure immediately
----
-## Getting Started
-### Installation
-```bash
-# The tool is included with the SDK
-npm install @fluentcommerce/fc-connect-sdk
-```
-### Basic Command
-```bash
-npx fc-connect analyze-source-structure --file <path-to-your-file>
-```
-That's it! The tool will:
-1. Auto-detect the file format (XML, JSON, CSV, Parquet)
-2. Parse the file using SDK parsers
-3. Display all available mapping paths
-4. Show structure insights (arrays, attributes)
----
-## Quick Start Examples
-### Example 1: Analyze an XML File
-```bash
-npx fc-connect analyze-source-structure --file ./vendor-products.xml
-```
-**Output:**
-```
-📂 Parsing XML file: vendor-products.xml
-🔍 Available Mapping Paths:
-  🏷️  Product.@sku
-  📄 Product.Name
-  📄 Product.Price
-  📋 Product.Variants.Variant[] (array)
-  🏷️  Product.Variants.Variant.@id
-  📄 Product.Variants.Variant.Size
-📋 Structure Insights:
-  Root Element(s): Product
-  Arrays Detected: 1
-    - Product.Variants.Variant[] (array)
-  Attributes Detected: 2 (XML only)
-    - Product.@sku
-    - Product.Variants.Variant.@id
-```
-### Example 2: Generate Mapping Template
-```bash
-npx fc-connect analyze-source-structure \
-  --file ./vendor-products.xml \
-  --output ./product-mapping.json
-```
-**Creates:** `product-mapping.json`
-```json
-{
-  "version": "1.0.0",
-  "description": "Generated mapping template from XML analysis",
-  "fields": {
-    "sku": {
-      "source": "Product.@sku",
-      "resolver": "sdk.trim",
-      "comment": "SKU field detected - preserves format"
-    },
-    "name": {
-      "source": "Product.Name",
-      "resolver": "sdk.trim"
-    },
-    "price": {
-      "source": "Product.Price",
-      "resolver": "sdk.parseFloat",
-      "comment": "Price field detected - converts to number"
-    },
-    "Variant": {
-      "source": "Product.Variants.Variant[]",
-      "isArray": true,
-      "fields": {
-        "id": {
-          "source": "@id",
-          "comment": "Array item field - item is already context"
-        },
-        "size": {
-          "source": "Size"
-        }
-      }
-    }
-  }
-}
-```
-### Example 3: Generate Documentation
-```bash
-npx fc-connect analyze-source-structure \
-  --file ./vendor-products.xml \
-  --markdown ./docs/vendor-analysis.md
-```
-**Creates:** Complete documentation including:
-- Input file sample (first 50 lines)
-- CLI command used (reproducible)
-- Parsed structure (JavaScript object)
-- All mapping paths with visual indicators
-- Complete mapping template
-- Next steps guidance
----
-## Common Workflows
-### Workflow 1: New Integration - Understanding Source Data
-**Scenario:** You've received XML files from a new vendor and need to understand their structure.
-```bash
-# Step 1: Analyze the structure
-npx fc-connect analyze-source-structure \
-  --file ./vendor-order-sample.xml \
-  --markdown ./docs/vendor-order-analysis.md
-# Step 2: Review the documentation
-# Open ./docs/vendor-order-analysis.md and review:
-# - What fields are available?
-# - What are the array structures?
-# - Are there XML attributes?
-# Step 3: Generate starting template
-npx fc-connect analyze-source-structure \
-  --file ./vendor-order-sample.xml \
-  --output ./config/vendor-order-mapping.json \
-  --direction ingest \
-  --mapper graphql
-```
-**What you get:**
-- ✅ Complete understanding of vendor data structure
-- ✅ Documentation you can share with your team
-- ✅ Working mapping template ready to customize
-### Workflow 2: CSV Data Migration
-**Scenario:** Migrating inventory data from CSV to Fluent Commerce.
-```bash
-# Step 1: Analyze CSV structure
-npx fc-connect analyze-source-structure \
-  --file ./inventory.csv \
-  --output ./migration-mapping.json \
-  --direction extract \
-  --mapper universal
-# Step 2: Review the generated mapping
-# The tool detected columns and suggested resolvers:
-# - "sku" → sdk.trim (preserves SKU format)
-# - "price" → sdk.parseFloat (converts to number)
-# - "quantity" → sdk.parseInt (converts to integer)
-# Step 3: Customize field names to match Fluent schema
-# Edit migration-mapping.json:
-# - Rename "sku" to "skuRef"
-# - Add "required: true" where needed
-# - Adjust resolvers if necessary
-# Step 4: Use in your migration script
-```
-### Workflow 3: Debugging Mapping Issues
-**Scenario:** Your mapping isn't working as expected. Fields aren't being extracted correctly.
-```bash
-# Problem: Field "Order.Items.Item.SKU" isn't mapping
-# Solution: See how SDK actually parses your file
-npx fc-connect analyze-source-structure \
-  --file ./problematic-order.xml \
-  --show-json
-# Output shows the actual JavaScript object structure
-# You discover: SDK stores it as "@sku" (XML attribute), not "SKU"
-# Fix your mapping: "source": "@sku"
-```
-### Workflow 4: Team Collaboration
-**Scenario:** Your team needs to understand a complex data source for a new integration.
-```bash
-# Generate comprehensive documentation
-npx fc-connect analyze-source-structure \
-  --file ./sfcc-order-export.xml \
-  --output ./config/sfcc-order-mapping.json \
-  --markdown ./docs/sfcc-order-structure.md \
-  --direction ingest \
-  --mapper graphql
-# Share ./docs/sfcc-order-structure.md with:
-# - Developers (see the exact structure)
-# - QA (understand test data requirements)
-# - Product managers (review data fields)
-```
----
-## Understanding the Output
-### Console Output Explained
-```
-📂 Parsing XML file: inventory.xml
-```
-Confirms the file and format detected.
-```
-🔍 Available Mapping Paths:
-  🏷️  InventoryFeed.Items.Item.@sku
-  📄 InventoryFeed.Items.Item.ProductName
-  📋 InventoryFeed.Items.Item[] (array)
-```
-**Icons:**
-- 🏷️ = XML attribute (use @ prefix in mapping)
-- 📄 = Regular scalar field
-- 📋 = Array field (needs `isArray: true`)
-### Mapping Template Structure
-```json
-{
-  "version": "1.0.0",
-  "fields": {
-    "fieldName": {
-      "source": "path.to.field",     // ← Where to get data from
-      "resolver": "sdk.trim",         // ← How to transform it
-      "required": true,               // ← Validation (optional)
-      "comment": "Description"        // ← For documentation
-    }
-  }
-}
-```
-### Smart Resolver Detection
-The tool analyzes field names and values to suggest appropriate resolvers:
-| Field Name Contains | Sample Value | Suggested Resolver | Why? |
-|-------------------|--------------|-------------------|------|
-| `sku`, `code`, `barcode` | `"SKU-001"` | `sdk.trim` | Preserves format (leading zeros, hyphens) |
-| `price`, `amount`, `cost` | `"19.99"` | `sdk.parseFloat` | Converts to decimal number |
-| `quantity`, `count`, `id` | `"100"` | `sdk.parseInt` | Converts to integer |
-| `email`, `mail` | `"USER@EXAMPLE.COM"` | `sdk.lowercase` | Normalizes email addresses |
-| `date`, `timestamp` | `"2024-01-15"` | `sdk.parseDate` | Converts to date object |
-| `version`, `build`, `tag` | `"2024-01-15"` | `sdk.trim` | Preserves version strings |
-**Important:** These are suggestions! Always review and adjust based on your specific requirements.
----
-## Best Practices
-### 1. Always Use Markdown for Complex Files
-```bash
-# ✅ GOOD - Creates shareable documentation
-npx fc-connect analyze-source-structure \
-  --file ./complex-order.xml \
-  --markdown ./docs/order-analysis.md
-# ❌ LESS IDEAL - Console output only (hard to review later)
-npx fc-connect analyze-source-structure \
-  --file ./complex-order.xml
-```
-### 2. Specify Mapper Type for Better Templates
-```bash
-# For XML/JSON → GraphQL ingestion
-npx fc-connect analyze-source-structure \
-  --file ./order.xml \
-  --mapper graphql \
-  --direction ingest
-# For CSV → Batch API
-npx fc-connect analyze-source-structure \
-  --file ./inventory.csv \
-  --mapper universal \
-  --direction extract
-```
-### 3. Review and Customize Generated Templates
-Generated templates are a **starting point**, not the final solution:
-```json
-// Generated template
-{
-  "sku": {
-    "source": "@sku",
-    "resolver": "sdk.trim"
-  }
-}
-// Customize for your needs
-{
-  "skuRef": {                    // ← Rename to match Fluent schema
-    "source": "@sku",
-    "resolver": "sdk.trim",
-    "required": true,             // ← Add validation
-    "comment": "Product SKU"      // ← Update comment
-  }
-}
-```
-### 4. Use Sample Files for Analysis
-```bash
-# ✅ GOOD - Small representative sample
-npx fc-connect analyze-source-structure --file ./order-sample.xml
-# ❌ AVOID - Huge production file (slower, same results)
-npx fc-connect analyze-source-structure --file ./orders-full-10gb.xml
-```
-The tool samples data intelligently:
-- CSV/Parquet: First 100 rows
-- XML/JSON: Full file (but docs show first 50 lines)
-### 5. Version Control Your Mappings
-```bash
-# Generate mapping template
-npx fc-connect analyze-source-structure \
-  --file ./vendor-products.xml \
-  --output ./config/vendor-mapping.json
-# Commit to version control
-git add ./config/vendor-mapping.json
-git commit -m "feat: add vendor product mapping template"
-```
----
-## Advanced Usage
-### Option 1: Show Parsed Structure
-```bash
-# See exactly how SDK parsers interpret your file
-npx fc-connect analyze-source-structure \
-  --file ./order.xml \
-  --show-json
-```
-**Use when:**
-- Debugging why a field isn't mapping
-- Understanding nested object structures
-- Verifying array structures
-### Option 2: Multiple Output Formats
-```bash
-# Generate both mapping template AND documentation
-npx fc-connect analyze-source-structure \
-  --file ./products.xml \
-  --output ./config/product-mapping.json \
-  --markdown ./docs/product-analysis.md \
-  --direction ingest \
-  --mapper graphql
-```
-### Option 3: Parquet Analysis
-```bash
-# Analyze Parquet files (first 100 records)
-npx fc-connect analyze-source-structure \
-  --file ./events.parquet \
-  --format parquet \
-  --output ./event-mapping.json
-```
-### Option 4: Custom Markdown Path
-```bash
-# Specify custom documentation path
-npx fc-connect analyze-source-structure \
-  --file ./inventory.csv \
-  --markdown ./team-docs/inventory-structure.md
-```
----
-## Troubleshooting
-### Problem: "Cannot find module"
-```bash
-# Error: Cannot find module '@fluentcommerce/fc-connect-sdk'
-# Solution: Install the SDK
-npm install @fluentcommerce/fc-connect-sdk
-```
-### Problem: "File not found"
-```bash
-# Error: ENOENT: no such file or directory
-# Solution: Use absolute or correct relative path
-npx fc-connect analyze-source-structure --file ./correct-path/file.xml
-# Or use absolute path
-npx fc-connect analyze-source-structure --file /full/path/to/file.xml
-```
-### Problem: "Format not detected"
-```bash
-# Error: Could not detect format
-# Solution: Specify format explicitly
-npx fc-connect analyze-source-structure \
-  --file ./myfile.dat \
-  --format xml
-```
-### Problem: XML Attributes Not Showing
-```bash
-# Issue: XML attributes like 'id="123"' not in output
-# Check: Make sure your XML has attributes
-# The tool automatically includes attributes with @ prefix
-# If you don't see attributes, they might not exist in your XML
-```
-### Problem: Array Fields Not Detected
-```bash
-# Issue: Tool shows field but not as array
-# Cause: Your sample file might have only one item
-# Solution: Provide a sample with multiple items in the array
-# Example:
-# ❌ Single item (tool can't detect it's an array)
-<Items>
-  <Item>Product 1</Item>
-</Items>
-# ✅ Multiple items (tool detects array)
-<Items>
-  <Item>Product 1</Item>
-  <Item>Product 2</Item>
-</Items>
-```
-### Problem: Resolver Suggestions Incorrect
-```bash
-# Issue: Field "productCode" suggested as parseInt, should be trim
-# Cause: Value "12345" looks numeric
-# Solution: This is now FIXED in latest SDK version
-# Code/SKU fields are detected BEFORE numeric detection
-# If you still see issues, customize the generated template:
-{
-  "productCode": {
-    "source": "code",
-    "resolver": "sdk.trim"  // ← Override suggestion
-  }
-}
-```
----
-## FAQ
-### Q: What file formats are supported?
-**A:** XML, JSON, CSV, and Parquet files.
-### Q: Does this tool connect to the Fluent API?
-**A:** No, it only analyzes local files. It uses the same parsers as the SDK, so the output matches runtime behavior.
-### Q: Can I use this on production data?
-**A:** Yes! The tool only reads files, never modifies them. However, use sample files when possible (faster analysis, same results).
-### Q: How do I use the generated mapping template?
-**A:** Import it in your connector code:
-```typescript
-import mappingConfig from './product-mapping.json' with { type: 'json' };
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-const mapper = new UniversalMapper(mappingConfig);
-const result = await mapper.map(sourceData);
-```
-### Q: Can I customize the resolver suggestions?
-**A:** Yes! The suggestions are just a starting point. Edit the generated JSON file to match your needs.
-### Q: What's the difference between `--mapper universal` and `--mapper graphql`?
-**A:**
-- `universal`: For CSV/Parquet → Batch API (uses item-relative paths like `"source": "sku"`)
-- `graphql`: For XML/JSON → GraphQL mutations (uses `$.` prefix like `"source": "$.sku"`)
-Choose based on your integration pattern.
-### Q: How do I handle huge files?
-**A:** The tool samples data intelligently:
-- CSV/Parquet: First 100 rows
-- XML/JSON: Full file (but analysis is fast)
-You don't need to provide the entire dataset—a representative sample is enough.
-### Q: Can I use this for Versori connectors?
-**A:** Yes! The tool works for both standalone Node.js apps and Versori connectors. The mapping format is the same.
-### Q: What if my field paths are incorrect?
-**A:** Use `--show-json` to see exactly how the SDK parses your file:
-```bash
-npx fc-connect analyze-source-structure \
-  --file ./your-file.xml \
-  --show-json
-```
-This shows the actual JavaScript object structure, making it easy to identify correct paths.
-### Q: How do I share analysis with my team?
-**A:** Generate markdown documentation:
-```bash
-npx fc-connect analyze-source-structure \
-  --file ./data.xml \
-  --markdown ./docs/analysis.md
-```
-Share the markdown file—it's self-contained and includes everything your team needs.
----
-## Next Steps
-1. **Try it yourself**: Run the tool on one of your data files
-2. **Generate a template**: Create your first mapping configuration
-3. **Customize**: Edit the template to match your Fluent schema
-4. **Use in SDK**: Load the mapping in your connector code
-5. **Share**: Generate documentation for your team
-**Need more help?**
-- See [SDK Documentation](../02-CORE-GUIDES/mapping/modules/) for mapping guides
-- Check [Templates](../01-TEMPLATES/) for complete integration examples
-- Review [CLI Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for all available options
----
-**Pro Tip:** Save time by generating both mapping and documentation in one command:
-```bash
-npx fc-connect analyze-source-structure \
-  --file ./your-data.xml \
-  --output ./config/mapping.json \
-  --markdown ./docs/analysis.md \
-  --direction ingest \
-  --mapper graphql
-```
-Now you have:
-✅ Mapping template ready to use
-✅ Documentation to share with your team
-✅ Complete understanding of your data structure
+# Analyze Source Structure CLI Tool - User Guide
+**Tool:** `fc-connect analyze-source-structure`
+**Purpose:** Analyze data files (XML, JSON, CSV, Parquet) and generate mapping templates for Fluent Commerce integrations
+---
+## Table of Contents
+1. [What Is This Tool?](#what-is-this-tool)
+2. [Why Use It?](#why-use-it)
+3. [Getting Started](#getting-started)
+4. [Quick Start Examples](#quick-start-examples)
+5. [Common Workflows](#common-workflows)
+6. [Understanding the Output](#understanding-the-output)
+7. [Best Practices](#best-practices)
+8. [Advanced Usage](#advanced-usage)
+9. [Troubleshooting](#troubleshooting)
+10. [FAQ](#faq)
+---
+## What Is This Tool?
+The `analyze-source-structure` CLI tool helps you understand how data files are structured and automatically generates mapping configurations for the Fluent Connect SDK.
+**What it does:**
+- ✅ Parses your data files (XML, JSON, CSV, Parquet)
+- ✅ Shows you exactly how the SDK sees your data
+- ✅ Lists all available fields and paths for mapping
+- ✅ Detects arrays, nested objects, and XML attributes
+- ✅ Generates ready-to-use mapping templates
+- ✅ Suggests appropriate data type resolvers (parseFloat, trim, etc.)
+- ✅ Creates shareable documentation for your team
+**What it doesn't do:**
+- ❌ Doesn't modify your source files
+- ❌ Doesn't connect to APIs
+- ❌ Doesn't execute mappings (use the SDK for that)
+---
+## Why Use It?
+### Problem: Manual Mapping Discovery is Time-Consuming
+Without this tool, you'd need to:
+1. Manually inspect your XML/JSON files
+2. Figure out how the SDK parsers interpret the data
+3. Manually write field paths (prone to errors)
+4. Guess which resolvers to use (sdk.parseFloat vs sdk.parseInt?)
+5. Trial-and-error to find the correct array structures
+### Solution: Automated Analysis
+With this tool, you get:
+- **Instant visibility** - See all available fields in seconds
+- **Accurate paths** - No typos or wrong paths
+- **Smart suggestions** - Automatic resolver detection based on field names and data
+- **Team collaboration** - Generate markdown docs to share with colleagues
+- **Faster onboarding** - New developers understand data structure immediately
+---
+## Getting Started
+### Installation
+```bash
+# The tool is included with the SDK
+npm install @fluentcommerce/fc-connect-sdk
+```
+### Basic Command
+```bash
+npx fc-connect analyze-source-structure --file <path-to-your-file>
+```
+That's it! The tool will:
+1. Auto-detect the file format (XML, JSON, CSV, Parquet)
+2. Parse the file using SDK parsers
+3. Display all available mapping paths
+4. Show structure insights (arrays, attributes)
+---
+## Quick Start Examples
+### Example 1: Analyze an XML File
+```bash
+npx fc-connect analyze-source-structure --file ./vendor-products.xml
+```
+**Output:**
+```
+📂 Parsing XML file: vendor-products.xml
+🔍 Available Mapping Paths:
+  🏷️  Product.@sku
+  📄 Product.Name
+  📄 Product.Price
+  📋 Product.Variants.Variant[] (array)
+  🏷️  Product.Variants.Variant.@id
+  📄 Product.Variants.Variant.Size
+📋 Structure Insights:
+  Root Element(s): Product
+  Arrays Detected: 1
+    - Product.Variants.Variant[] (array)
+  Attributes Detected: 2 (XML only)
+    - Product.@sku
+    - Product.Variants.Variant.@id
+```
+### Example 2: Generate Mapping Template
+```bash
+npx fc-connect analyze-source-structure \
+  --file ./vendor-products.xml \
+  --output ./product-mapping.json
+```
+**Creates:** `product-mapping.json`
+```json
+{
+  "version": "1.0.0",
+  "description": "Generated mapping template from XML analysis",
+  "fields": {
+    "sku": {
+      "source": "Product.@sku",
+      "resolver": "sdk.trim",
+      "comment": "SKU field detected - preserves format"
+    },
+    "name": {
+      "source": "Product.Name",
+      "resolver": "sdk.trim"
+    },
+    "price": {
+      "source": "Product.Price",
+      "resolver": "sdk.parseFloat",
+      "comment": "Price field detected - converts to number"
+    },
+    "Variant": {
+      "source": "Product.Variants.Variant[]",
+      "isArray": true,
+      "fields": {
+        "id": {
+          "source": "@id",
+          "comment": "Array item field - item is already context"
+        },
+        "size": {
+          "source": "Size"
+        }
+      }
+    }
+  }
+}
+```
+### Example 3: Generate Documentation
+```bash
+npx fc-connect analyze-source-structure \
+  --file ./vendor-products.xml \
+  --markdown ./docs/vendor-analysis.md
+```
+**Creates:** Complete documentation including:
+- Input file sample (first 50 lines)
+- CLI command used (reproducible)
+- Parsed structure (JavaScript object)
+- All mapping paths with visual indicators
+- Complete mapping template
+- Next steps guidance
+---
+## Common Workflows
+### Workflow 1: New Integration - Understanding Source Data
+**Scenario:** You've received XML files from a new vendor and need to understand their structure.
+```bash
+# Step 1: Analyze the structure
+npx fc-connect analyze-source-structure \
+  --file ./vendor-order-sample.xml \
+  --markdown ./docs/vendor-order-analysis.md
+# Step 2: Review the documentation
+# Open ./docs/vendor-order-analysis.md and review:
+# - What fields are available?
+# - What are the array structures?
+# - Are there XML attributes?
+# Step 3: Generate starting template
+npx fc-connect analyze-source-structure \
+  --file ./vendor-order-sample.xml \
+  --output ./config/vendor-order-mapping.json \
+  --direction ingest \
+  --mapper graphql
+```
+**What you get:**
+- ✅ Complete understanding of vendor data structure
+- ✅ Documentation you can share with your team
+- ✅ Working mapping template ready to customize
+### Workflow 2: CSV Data Migration
+**Scenario:** Migrating inventory data from CSV to Fluent Commerce.
+```bash
+# Step 1: Analyze CSV structure
+npx fc-connect analyze-source-structure \
+  --file ./inventory.csv \
+  --output ./migration-mapping.json \
+  --direction extract \
+  --mapper universal
+# Step 2: Review the generated mapping
+# The tool detected columns and suggested resolvers:
+# - "sku" → sdk.trim (preserves SKU format)
+# - "price" → sdk.parseFloat (converts to number)
+# - "quantity" → sdk.parseInt (converts to integer)
+# Step 3: Customize field names to match Fluent schema
+# Edit migration-mapping.json:
+# - Rename "sku" to "skuRef"
+# - Add "required: true" where needed
+# - Adjust resolvers if necessary
+# Step 4: Use in your migration script
+```
+### Workflow 3: Debugging Mapping Issues
+**Scenario:** Your mapping isn't working as expected. Fields aren't being extracted correctly.
+```bash
+# Problem: Field "Order.Items.Item.SKU" isn't mapping
+# Solution: See how SDK actually parses your file
+npx fc-connect analyze-source-structure \
+  --file ./problematic-order.xml \
+  --show-json
+# Output shows the actual JavaScript object structure
+# You discover: SDK stores it as "@sku" (XML attribute), not "SKU"
+# Fix your mapping: "source": "@sku"
+```
+### Workflow 4: Team Collaboration
+**Scenario:** Your team needs to understand a complex data source for a new integration.
+```bash
+# Generate comprehensive documentation
+npx fc-connect analyze-source-structure \
+  --file ./sfcc-order-export.xml \
+  --output ./config/sfcc-order-mapping.json \
+  --markdown ./docs/sfcc-order-structure.md \
+  --direction ingest \
+  --mapper graphql
+# Share ./docs/sfcc-order-structure.md with:
+# - Developers (see the exact structure)
+# - QA (understand test data requirements)
+# - Product managers (review data fields)
+```
+---
+## Understanding the Output
+### Console Output Explained
+```
+📂 Parsing XML file: inventory.xml
+```
+Confirms the file and format detected.
+```
+🔍 Available Mapping Paths:
+  🏷️  InventoryFeed.Items.Item.@sku
+  📄 InventoryFeed.Items.Item.ProductName
+  📋 InventoryFeed.Items.Item[] (array)
+```
+**Icons:**
+- 🏷️ = XML attribute (use @ prefix in mapping)
+- 📄 = Regular scalar field
+- 📋 = Array field (needs `isArray: true`)
+### Mapping Template Structure
+```json
+{
+  "version": "1.0.0",
+  "fields": {
+    "fieldName": {
+      "source": "path.to.field",     // ← Where to get data from
+      "resolver": "sdk.trim",         // ← How to transform it
+      "required": true,               // ← Validation (optional)
+      "comment": "Description"        // ← For documentation
+    }
+  }
+}
+```
+### Smart Resolver Detection
+The tool analyzes field names and values to suggest appropriate resolvers:
+| Field Name Contains | Sample Value | Suggested Resolver | Why? |
+|-------------------|--------------|-------------------|------|
+| `sku`, `code`, `barcode` | `"SKU-001"` | `sdk.trim` | Preserves format (leading zeros, hyphens) |
+| `price`, `amount`, `cost` | `"19.99"` | `sdk.parseFloat` | Converts to decimal number |
+| `quantity`, `count`, `id` | `"100"` | `sdk.parseInt` | Converts to integer |
+| `email`, `mail` | `"USER@EXAMPLE.COM"` | `sdk.lowercase` | Normalizes email addresses |
+| `date`, `timestamp` | `"2024-01-15"` | `sdk.parseDate` | Converts to date object |
+| `version`, `build`, `tag` | `"2024-01-15"` | `sdk.trim` | Preserves version strings |
+**Important:** These are suggestions! Always review and adjust based on your specific requirements.
+---
+## Best Practices
+### 1. Always Use Markdown for Complex Files
+```bash
+# ✅ GOOD - Creates shareable documentation
+npx fc-connect analyze-source-structure \
+  --file ./complex-order.xml \
+  --markdown ./docs/order-analysis.md
+# ❌ LESS IDEAL - Console output only (hard to review later)
+npx fc-connect analyze-source-structure \
+  --file ./complex-order.xml
+```
+### 2. Specify Mapper Type for Better Templates
+```bash
+# For XML/JSON → GraphQL ingestion
+npx fc-connect analyze-source-structure \
+  --file ./order.xml \
+  --mapper graphql \
+  --direction ingest
+# For CSV → Batch API
+npx fc-connect analyze-source-structure \
+  --file ./inventory.csv \
+  --mapper universal \
+  --direction extract
+```
+### 3. Review and Customize Generated Templates
+Generated templates are a **starting point**, not the final solution:
+```json
+// Generated template
+{
+  "sku": {
+    "source": "@sku",
+    "resolver": "sdk.trim"
+  }
+}
+// Customize for your needs
+{
+  "skuRef": {                    // ← Rename to match Fluent schema
+    "source": "@sku",
+    "resolver": "sdk.trim",
+    "required": true,             // ← Add validation
+    "comment": "Product SKU"      // ← Update comment
+  }
+}
+```
+### 4. Use Sample Files for Analysis
+```bash
+# ✅ GOOD - Small representative sample
+npx fc-connect analyze-source-structure --file ./order-sample.xml
+# ❌ AVOID - Huge production file (slower, same results)
+npx fc-connect analyze-source-structure --file ./orders-full-10gb.xml
+```
+The tool samples data intelligently:
+- CSV/Parquet: First 100 rows
+- XML/JSON: Full file (but docs show first 50 lines)
+### 5. Version Control Your Mappings
+```bash
+# Generate mapping template
+npx fc-connect analyze-source-structure \
+  --file ./vendor-products.xml \
+  --output ./config/vendor-mapping.json
+# Commit to version control
+git add ./config/vendor-mapping.json
+git commit -m "feat: add vendor product mapping template"
+```
+---
+## Advanced Usage
+### Option 1: Show Parsed Structure
+```bash
+# See exactly how SDK parsers interpret your file
+npx fc-connect analyze-source-structure \
+  --file ./order.xml \
+  --show-json
+```
+**Use when:**
+- Debugging why a field isn't mapping
+- Understanding nested object structures
+- Verifying array structures
+### Option 2: Multiple Output Formats
+```bash
+# Generate both mapping template AND documentation
+npx fc-connect analyze-source-structure \
+  --file ./products.xml \
+  --output ./config/product-mapping.json \
+  --markdown ./docs/product-analysis.md \
+  --direction ingest \
+  --mapper graphql
+```
+### Option 3: Parquet Analysis
+```bash
+# Analyze Parquet files (first 100 records)
+npx fc-connect analyze-source-structure \
+  --file ./events.parquet \
+  --format parquet \
+  --output ./event-mapping.json
+```
+### Option 4: Custom Markdown Path
+```bash
+# Specify custom documentation path
+npx fc-connect analyze-source-structure \
+  --file ./inventory.csv \
+  --markdown ./team-docs/inventory-structure.md
+```
+---
+## Troubleshooting
+### Problem: "Cannot find module"
+```bash
+# Error: Cannot find module '@fluentcommerce/fc-connect-sdk'
+# Solution: Install the SDK
+npm install @fluentcommerce/fc-connect-sdk
+```
+### Problem: "File not found"
+```bash
+# Error: ENOENT: no such file or directory
+# Solution: Use absolute or correct relative path
+npx fc-connect analyze-source-structure --file ./correct-path/file.xml
+# Or use absolute path
+npx fc-connect analyze-source-structure --file /full/path/to/file.xml
+```
+### Problem: "Format not detected"
+```bash
+# Error: Could not detect format
+# Solution: Specify format explicitly
+npx fc-connect analyze-source-structure \
+  --file ./myfile.dat \
+  --format xml
+```
+### Problem: XML Attributes Not Showing
+```bash
+# Issue: XML attributes like 'id="123"' not in output
+# Check: Make sure your XML has attributes
+# The tool automatically includes attributes with @ prefix
+# If you don't see attributes, they might not exist in your XML
+```
+### Problem: Array Fields Not Detected
+```bash
+# Issue: Tool shows field but not as array
+# Cause: Your sample file might have only one item
+# Solution: Provide a sample with multiple items in the array
+# Example:
+# ❌ Single item (tool can't detect it's an array)
+<Items>
+  <Item>Product 1</Item>
+</Items>
+# ✅ Multiple items (tool detects array)
+<Items>
+  <Item>Product 1</Item>
+  <Item>Product 2</Item>
+</Items>
+```
+### Problem: Resolver Suggestions Incorrect
+```bash
+# Issue: Field "productCode" suggested as parseInt, should be trim
+# Cause: Value "12345" looks numeric
+# Solution: This is now FIXED in latest SDK version
+# Code/SKU fields are detected BEFORE numeric detection
+# If you still see issues, customize the generated template:
+{
+  "productCode": {
+    "source": "code",
+    "resolver": "sdk.trim"  // ← Override suggestion
+  }
+}
+```
+---
+## FAQ
+### Q: What file formats are supported?
+**A:** XML, JSON, CSV, and Parquet files.
+### Q: Does this tool connect to the Fluent API?
+**A:** No, it only analyzes local files. It uses the same parsers as the SDK, so the output matches runtime behavior.
+### Q: Can I use this on production data?
+**A:** Yes! The tool only reads files, never modifies them. However, use sample files when possible (faster analysis, same results).
+### Q: How do I use the generated mapping template?
+**A:** Import it in your connector code:
+```typescript
+import mappingConfig from './product-mapping.json' with { type: 'json' };
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+const mapper = new UniversalMapper(mappingConfig);
+const result = await mapper.map(sourceData);
+```
+### Q: Can I customize the resolver suggestions?
+**A:** Yes! The suggestions are just a starting point. Edit the generated JSON file to match your needs.
+### Q: What's the difference between `--mapper universal` and `--mapper graphql`?
+**A:**
+- `universal`: For CSV/Parquet → Batch API (uses item-relative paths like `"source": "sku"`)
+- `graphql`: For XML/JSON → GraphQL mutations (uses `$.` prefix like `"source": "$.sku"`)
+Choose based on your integration pattern.
+### Q: How do I handle huge files?
+**A:** The tool samples data intelligently:
+- CSV/Parquet: First 100 rows
+- XML/JSON: Full file (but analysis is fast)
+You don't need to provide the entire dataset—a representative sample is enough.
+### Q: Can I use this for Versori connectors?
+**A:** Yes! The tool works for both standalone Node.js apps and Versori connectors. The mapping format is the same.
+### Q: What if my field paths are incorrect?
+**A:** Use `--show-json` to see exactly how the SDK parses your file:
+```bash
+npx fc-connect analyze-source-structure \
+  --file ./your-file.xml \
+  --show-json
+```
+This shows the actual JavaScript object structure, making it easy to identify correct paths.
+### Q: How do I share analysis with my team?
+**A:** Generate markdown documentation:
+```bash
+npx fc-connect analyze-source-structure \
+  --file ./data.xml \
+  --markdown ./docs/analysis.md
+```
+Share the markdown file—it's self-contained and includes everything your team needs.
+---
+## Next Steps
+1. **Try it yourself**: Run the tool on one of your data files
+2. **Generate a template**: Create your first mapping configuration
+3. **Customize**: Edit the template to match your Fluent schema
+4. **Use in SDK**: Load the mapping in your connector code
+5. **Share**: Generate documentation for your team
+**Need more help?**
+- See [SDK Documentation](../02-CORE-GUIDES/mapping/modules/) for mapping guides
+- Check [Templates](../01-TEMPLATES/) for complete integration examples
+- Review [CLI Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for all available options
+---
+**Pro Tip:** Save time by generating both mapping and documentation in one command:
+```bash
+npx fc-connect analyze-source-structure \
+  --file ./your-data.xml \
+  --output ./config/mapping.json \
+  --markdown ./docs/analysis.md \
+  --direction ingest \
+  --mapper graphql
+```
+Now you have:
+✅ Mapping template ready to use
+✅ Documentation to share with your team
+✅ Complete understanding of your data structure