@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/mapping-format-decision-tree.md

@@ -1,480 +1,480 @@
-# Mapping Configuration Format Decision Tree
-
-**FC Connect SDK - Choosing the Right Mapping Pattern**
-
----
-
-## Quick Decision Tree
-
-```
-START: I need to configure field mappings
-│
-├─ Is this a tutorial, example, or proof-of-concept?
-│  └─ YES → ✅ Use INLINE MAPPING (simple object)
-│
-├─ Is this a webhook with dynamic transformation logic?
-│  └─ YES → ✅ Use INLINE MAPPING (programmatic)
-│
-├─ Is this a production template with <10 simple fields?
-│  └─ YES → ✅ Use INLINE MAPPING (acceptable)
-│
-└─ Is this a production template with 10+ fields OR reusable config?
-   └─ YES → ✅ Use EXTERNAL JSON FILE
-```
-
----
-
-## Three Valid Patterns
-
-### ✅ Pattern 1: External JSON File (Production Standard)
-
-**When to use:**
-- Production templates with 10+ fields
-- Reusable configurations across multiple workflows
-- Multi-environment deployments (dev, staging, prod)
-- Complex mappings requiring maintenance
-- Team collaboration (non-developers can edit JSON)
-
-**Syntax:**
-```typescript
-import mappingConfig from './config/inventory.batch.json' with { type: 'json' };
-
-const mapper = new UniversalMapper(mappingConfig);
-```
-
-**File structure:**
-```
-src/
-├── workflows/
-│   └── inventory-ingestion.ts          # Workflow code
-└── config/
-    └── inventory.batch.json             # Mapping configuration
-```
-
-**Example JSON:**
-```json
-{
-  "version": "1.0.0",
-  "fields": {
-    "skuRef": {
-      "source": "sku_id",
-      "required": true
-    },
-    "qty": {
-      "source": "quantity",
-      "resolver": "sdk.parseInt"
-    },
-    "expectedOn": {
-      "source": "expected_date",
-      "resolver": "sdk.formatDate"
-    }
-  }
-}
-```
-
-**Benefits:**
-- ✅ Clean separation of code and configuration
-- ✅ Easy to maintain and update without code changes
-- ✅ Non-developers can modify mappings
-- ✅ Supports environment-specific configs
-- ✅ Better for version control (clear diffs)
-
-**Drawbacks:**
-- ❌ Requires separate file
-- ❌ No TypeScript validation at compile time
-
----
-
-### ✅ Pattern 2: Inline Mapping (Examples & Simple Cases)
-
-**When to use:**
-- Documentation examples and tutorials
-- Proof-of-concepts and quick prototypes
-- Simple mappings with <10 fields
-- Webhooks with dynamic transformation logic
-- One-off scripts or tests
-
-**Syntax:**
-```typescript
-const mapper = new UniversalMapper({
-  version: '1.0.0',
-  fields: {
-    skuRef: { source: 'sku_id', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-    expectedOn: { source: 'expected_date', resolver: 'sdk.formatDate' }
-  }
-});
-```
-
-**Benefits:**
-- ✅ Everything in one file (self-contained)
-- ✅ Quick to write and iterate
-- ✅ Good for learning and examples
-- ✅ TypeScript type checking for structure
-
-**Drawbacks:**
-- ❌ Harder to maintain for large configs
-- ❌ Code changes required for mapping updates
-- ❌ Mixes configuration with business logic
-
-**Valid use cases:**
-1. **Documentation/Tutorials**: Teaching SDK usage
-```typescript
-// Example: Quick CSV ingestion tutorial
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'product_code' },
-    qty: { source: 'stock_level', resolver: 'sdk.parseInt' }
-  }
-});
-```
-
-2. **Dynamic Webhooks**: Logic-based transformations
-```typescript
-// Example: Webhook with conditional logic
-export const orderWebhook = webhook('order-created', async (ctx) => {
-  const { data } = ctx;
-
-  // Dynamic mapping based on order type
-  const fields = data.type === 'WHOLESALE'
-    ? { discount: { source: 'wholesale_discount' } }
-    : { discount: { source: 'retail_discount' } };
-
-  const mapper = new UniversalMapper({ fields });
-  return mapper.map(data);
-});
-```
-
-3. **Simple One-Off Scripts**: Quick data transformations
-```typescript
-// Example: One-time data migration
-const mapper = new UniversalMapper({
-  fields: {
-    id: { source: 'old_id' },
-    name: { source: 'product_name' }
-  }
-});
-```
-
----
-
-### ❌ Pattern 3: TypeScript Config Import (Non-Standard)
-
-**Status:** ⚠️ **NOT RECOMMENDED** - Older pattern being phased out
-
-**What it looks like:**
-```typescript
-// ❌ WRONG - TypeScript module import (no 'with' clause)
-import { inventoryMapping } from './config/inventory-mapping.config';
-
-// ❌ WRONG - Old assert syntax
-import mappingConfig from './config/inventory.json' assert { type: 'json' };
-
-// ❌ WRONG - TypeScript file extension
-import mappingConfig from './config/inventory.config.ts';
-```
-
-**Why not to use:**
-- ❌ Not a standard JavaScript pattern
-- ❌ Inconsistent with SDK conventions
-- ❌ Requires TypeScript transpilation (breaks Deno)
-- ❌ Harder for non-developers to maintain
-- ❌ Mixes configuration with code structure
-
-**Migration path:**
-```typescript
-// BEFORE (TypeScript config import)
-import { inventoryMapping } from './config/inventory-mapping.config';
-const mapper = new UniversalMapper(inventoryMapping);
-
-// AFTER (External JSON)
-import inventoryMapping from './config/inventory.batch.json' with { type: 'json' };
-const mapper = new UniversalMapper(inventoryMapping);
-```
-
----
-
-## Decision Matrix
-
-| Scenario | Recommended Pattern | Reasoning |
-|----------|-------------------|-----------|
-| **Production inventory ingestion** | External JSON | 50+ fields, reusable across environments |
-| **Production order extraction** | External JSON | Complex nested structure, team maintenance |
-| **Tutorial: "Your First Ingestion"** | Inline | Self-contained example, <10 fields |
-| **Webhook: Order created event** | Inline | Dynamic logic based on payload |
-| **Prototype: Testing new data source** | Inline | Quick iteration, proof-of-concept |
-| **Multi-tenant connector** | External JSON | Environment-specific configs (dev/prod) |
-| **GraphQL mutation template** | External JSON | Reusable across multiple mutations |
-| **Test fixture generation** | Inline | Test-specific, isolated data |
-| **Documentation pattern guide** | Inline | Teaching concept, self-contained |
-| **Enterprise production workflow** | External JSON | Governance, change management, auditing |
-
----
-
-## Template Categories Analysis
-
-**Verified Statistics (2025-10-31):**
-
-| Pattern | Count | Percentage | Primary Use |
-|---------|-------|------------|-------------|
-| ✅ External JSON | 20 | 40.0% | Production ingestion/extraction |
-| ⚠️ TypeScript Import | 7 | 14.0% | Older approach (being migrated) |
-| ✅ Inline Mapping | 17 | 34.0% | Examples, webhooks, simple cases |
-| ℹ️ No Mapping | 6 | 12.0% | Architecture guides, non-mapping patterns |
-| **Total** | **50** | **100%** | All Versori production templates |
-
----
-
-## Best Practices
-
-### For External JSON Files
-
-1. **Use descriptive filenames:**
-   ```
-   ✅ inventory.batch.json
-   ✅ products.export.csv.json
-   ✅ orders.import.xml.json
-
-   ❌ mapping.json
-   ❌ config.json
-   ❌ data.json
-   ```
-
-2. **Include version and metadata:**
-   ```json
-   {
-     "version": "1.0.0",
-     "description": "Inventory batch ingestion mapping",
-     "lastUpdated": "2025-10-31",
-     "fields": { ... }
-   }
-   ```
-
-3. **Use consistent structure:**
-   ```json
-   {
-     "version": "1.0.0",
-     "fields": {
-       "fieldName": {
-         "source": "source_path",
-         "required": true|false,
-         "resolver": "sdk.resolverName",
-         "defaultValue": "value"
-       }
-     }
-   }
-   ```
-
-4. **Document custom resolvers:**
-   ```json
-   {
-     "version": "1.0.0",
-     "customResolvers": [
-       "custom.calculateTax",
-       "custom.formatAddress"
-     ],
-     "fields": { ... }
-   }
-   ```
-
-### For Inline Mappings
-
-1. **Keep it simple (<10 fields):**
-   ```typescript
-   // ✅ GOOD - Simple, readable
-   const mapper = new UniversalMapper({
-     fields: {
-       sku: { source: 'product_code' },
-       qty: { source: 'stock', resolver: 'sdk.parseInt' }
-     }
-   });
-
-   // ❌ BAD - Too complex for inline
-   const mapper = new UniversalMapper({
-     fields: {
-       // 50 fields here...
-     }
-   });
-   ```
-
-2. **Add comments for clarity:**
-   ```typescript
-   const mapper = new UniversalMapper({
-     fields: {
-       // Primary identifier from source system
-       skuRef: { source: 'sku_id', required: true },
-
-       // Stock quantity (parse as integer)
-       qty: { source: 'quantity', resolver: 'sdk.parseInt' }
-     }
-   });
-   ```
-
-3. **Extract to variable for reusability:**
-   ```typescript
-   // ✅ GOOD - Reusable within file
-   const inventoryFields = {
-     skuRef: { source: 'sku_id' },
-     qty: { source: 'quantity', resolver: 'sdk.parseInt' }
-   };
-
-   const mapper1 = new UniversalMapper({ fields: inventoryFields });
-   const mapper2 = new UniversalMapper({ fields: inventoryFields });
-   ```
-
----
-
-## Environment-Specific Configurations
-
-### External JSON Pattern
-
-**Directory structure:**
-```
-config/
-├── dev/
-│   ├── inventory.batch.json
-│   └── products.export.json
-├── staging/
-│   ├── inventory.batch.json
-│   └── products.export.json
-└── prod/
-    ├── inventory.batch.json
-    └── products.export.json
-```
-
-**Dynamic import:**
-```typescript
-import { activation } from '@versori/run';
-
-// Load environment-specific config
-const env = activation.environment || 'dev';
-const mappingConfig = await import(`./config/${env}/inventory.batch.json`, {
-  with: { type: 'json' }
-});
-
-const mapper = new UniversalMapper(mappingConfig.default);
-```
-
----
-
-## Migration Guide
-
-### Migrating from TypeScript Import to External JSON
-
-**Step 1: Extract TypeScript config to JSON**
-```typescript
-// OLD: config/inventory-mapping.config.ts
-export const inventoryMapping = {
-  version: '1.0.0',
-  fields: {
-    skuRef: { source: 'sku_id', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' }
-  }
-};
-```
-
-**Step 2: Create JSON file**
-```json
-// NEW: config/inventory.batch.json
-{
-  "version": "1.0.0",
-  "fields": {
-    "skuRef": { "source": "sku_id", "required": true },
-    "qty": { "source": "quantity", "resolver": "sdk.parseInt" }
-  }
-}
-```
-
-**Step 3: Update import statement**
-```typescript
-// OLD
-import { inventoryMapping } from './config/inventory-mapping.config';
-const mapper = new UniversalMapper(inventoryMapping);
-
-// NEW
-import inventoryMapping from './config/inventory.batch.json' with { type: 'json' };
-const mapper = new UniversalMapper(inventoryMapping);
-```
-
-**Step 4: Delete old TypeScript config file**
-```bash
-rm config/inventory-mapping.config.ts
-```
-
----
-
-## Common Pitfalls
-
-### ❌ Pitfall 1: Using TypeScript for production configs
-```typescript
-// ❌ WRONG
-import { config } from './inventory.config';
-
-// ✅ CORRECT
-import config from './inventory.batch.json' with { type: 'json' };
-```
-
-### ❌ Pitfall 2: Inline mappings with 50+ fields
-```typescript
-// ❌ WRONG - Too large for inline
-const mapper = new UniversalMapper({
-  fields: {
-    field1: { ... },
-    field2: { ... },
-    // 48 more fields...
-  }
-});
-
-// ✅ CORRECT - Use external JSON
-import mappingConfig from './config/large-mapping.json' with { type: 'json' };
-const mapper = new UniversalMapper(mappingConfig);
-```
-
-### ❌ Pitfall 3: Missing 'with { type: 'json' }' clause
-```typescript
-// ❌ WRONG - TypeScript import
-import mappingConfig from './config/mapping.json';
-
-// ❌ WRONG - Old assert syntax
-import mappingConfig from './config/mapping.json' assert { type: 'json' };
-
-// ✅ CORRECT - Standard JSON import
-import mappingConfig from './config/mapping.json' with { type: 'json' };
-```
-
----
-
-## Related Documentation
-
-- [Universal Mapping Guide](mapping-readme.md) - Complete mapping patterns
-- [SDK Resolvers](./resolvers/mapping-resolvers-readme.md) - Built-in field transformations
-- [GraphQL Mutation Mapping](./graphql-mutation-mapping/graphql-mutation-mapping-readme.md) - XML/JSON → GraphQL
-- [Template Loading Matrix](../../template-loading-matrix.md) - Template selection guide
-
----
-
-## FAQ
-
-**Q: Can I use inline mappings in production?**
-A: Yes, for simple cases (<10 fields) or webhooks with dynamic logic. For larger configs, use external JSON.
-
-**Q: Why not use TypeScript for type safety?**
-A: External JSON files are easier for non-developers to maintain and support runtime configuration changes without code deployment.
-
-**Q: What's the difference between `assert` and `with`?**
-A: `assert { type: 'json' }` is older syntax. Use `with { type: 'json' }` for current JavaScript/TypeScript standards.
-
-**Q: Can I have both inline and external mappings?**
-A: Yes! Use external for large/reusable configs and inline for dynamic logic or simple examples.
-
-**Q: How do I validate my JSON mapping file?**
-A: Use the SDK's validation tools:
-```bash
-npx fc-connect validate-schema --mapping config/inventory.batch.json
-```
-
----
-
-**Last Updated:** 2025-10-31
-**SDK Version:** ≥0.1.31
-**Verified Against:** 50 production Versori templates
+# Mapping Configuration Format Decision Tree
+
+**FC Connect SDK - Choosing the Right Mapping Pattern**
+
+---
+
+## Quick Decision Tree
+
+```
+START: I need to configure field mappings
+│
+├─ Is this a tutorial, example, or proof-of-concept?
+│  └─ YES → ✅ Use INLINE MAPPING (simple object)
+│
+├─ Is this a webhook with dynamic transformation logic?
+│  └─ YES → ✅ Use INLINE MAPPING (programmatic)
+│
+├─ Is this a production template with <10 simple fields?
+│  └─ YES → ✅ Use INLINE MAPPING (acceptable)
+│
+└─ Is this a production template with 10+ fields OR reusable config?
+   └─ YES → ✅ Use EXTERNAL JSON FILE
+```
+
+---
+
+## Three Valid Patterns
+
+### ✅ Pattern 1: External JSON File (Production Standard)
+
+**When to use:**
+- Production templates with 10+ fields
+- Reusable configurations across multiple workflows
+- Multi-environment deployments (dev, staging, prod)
+- Complex mappings requiring maintenance
+- Team collaboration (non-developers can edit JSON)
+
+**Syntax:**
+```typescript
+import mappingConfig from './config/inventory.batch.json' with { type: 'json' };
+
+const mapper = new UniversalMapper(mappingConfig);
+```
+
+**File structure:**
+```
+src/
+├── workflows/
+│   └── inventory-ingestion.ts          # Workflow code
+└── config/
+    └── inventory.batch.json             # Mapping configuration
+```
+
+**Example JSON:**
+```json
+{
+  "version": "1.0.0",
+  "fields": {
+    "skuRef": {
+      "source": "sku_id",
+      "required": true
+    },
+    "qty": {
+      "source": "quantity",
+      "resolver": "sdk.parseInt"
+    },
+    "expectedOn": {
+      "source": "expected_date",
+      "resolver": "sdk.formatDate"
+    }
+  }
+}
+```
+
+**Benefits:**
+- ✅ Clean separation of code and configuration
+- ✅ Easy to maintain and update without code changes
+- ✅ Non-developers can modify mappings
+- ✅ Supports environment-specific configs
+- ✅ Better for version control (clear diffs)
+
+**Drawbacks:**
+- ❌ Requires separate file
+- ❌ No TypeScript validation at compile time
+
+---
+
+### ✅ Pattern 2: Inline Mapping (Examples & Simple Cases)
+
+**When to use:**
+- Documentation examples and tutorials
+- Proof-of-concepts and quick prototypes
+- Simple mappings with <10 fields
+- Webhooks with dynamic transformation logic
+- One-off scripts or tests
+
+**Syntax:**
+```typescript
+const mapper = new UniversalMapper({
+  version: '1.0.0',
+  fields: {
+    skuRef: { source: 'sku_id', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+    expectedOn: { source: 'expected_date', resolver: 'sdk.formatDate' }
+  }
+});
+```
+
+**Benefits:**
+- ✅ Everything in one file (self-contained)
+- ✅ Quick to write and iterate
+- ✅ Good for learning and examples
+- ✅ TypeScript type checking for structure
+
+**Drawbacks:**
+- ❌ Harder to maintain for large configs
+- ❌ Code changes required for mapping updates
+- ❌ Mixes configuration with business logic
+
+**Valid use cases:**
+1. **Documentation/Tutorials**: Teaching SDK usage
+```typescript
+// Example: Quick CSV ingestion tutorial
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'product_code' },
+    qty: { source: 'stock_level', resolver: 'sdk.parseInt' }
+  }
+});
+```
+
+2. **Dynamic Webhooks**: Logic-based transformations
+```typescript
+// Example: Webhook with conditional logic
+export const orderWebhook = webhook('order-created', async (ctx) => {
+  const { data } = ctx;
+
+  // Dynamic mapping based on order type
+  const fields = data.type === 'WHOLESALE'
+    ? { discount: { source: 'wholesale_discount' } }
+    : { discount: { source: 'retail_discount' } };
+
+  const mapper = new UniversalMapper({ fields });
+  return mapper.map(data);
+});
+```
+
+3. **Simple One-Off Scripts**: Quick data transformations
+```typescript
+// Example: One-time data migration
+const mapper = new UniversalMapper({
+  fields: {
+    id: { source: 'old_id' },
+    name: { source: 'product_name' }
+  }
+});
+```
+
+---
+
+### ❌ Pattern 3: TypeScript Config Import (Non-Standard)
+
+**Status:** ⚠️ **NOT RECOMMENDED** - Older pattern being phased out
+
+**What it looks like:**
+```typescript
+// ❌ WRONG - TypeScript module import (no 'with' clause)
+import { inventoryMapping } from './config/inventory-mapping.config';
+
+// ❌ WRONG - Old assert syntax
+import mappingConfig from './config/inventory.json' assert { type: 'json' };
+
+// ❌ WRONG - TypeScript file extension
+import mappingConfig from './config/inventory.config.ts';
+```
+
+**Why not to use:**
+- ❌ Not a standard JavaScript pattern
+- ❌ Inconsistent with SDK conventions
+- ❌ Requires TypeScript transpilation (breaks Deno)
+- ❌ Harder for non-developers to maintain
+- ❌ Mixes configuration with code structure
+
+**Migration path:**
+```typescript
+// BEFORE (TypeScript config import)
+import { inventoryMapping } from './config/inventory-mapping.config';
+const mapper = new UniversalMapper(inventoryMapping);
+
+// AFTER (External JSON)
+import inventoryMapping from './config/inventory.batch.json' with { type: 'json' };
+const mapper = new UniversalMapper(inventoryMapping);
+```
+
+---
+
+## Decision Matrix
+
+| Scenario | Recommended Pattern | Reasoning |
+|----------|-------------------|-----------|
+| **Production inventory ingestion** | External JSON | 50+ fields, reusable across environments |
+| **Production order extraction** | External JSON | Complex nested structure, team maintenance |
+| **Tutorial: "Your First Ingestion"** | Inline | Self-contained example, <10 fields |
+| **Webhook: Order created event** | Inline | Dynamic logic based on payload |
+| **Prototype: Testing new data source** | Inline | Quick iteration, proof-of-concept |
+| **Multi-tenant connector** | External JSON | Environment-specific configs (dev/prod) |
+| **GraphQL mutation template** | External JSON | Reusable across multiple mutations |
+| **Test fixture generation** | Inline | Test-specific, isolated data |
+| **Documentation pattern guide** | Inline | Teaching concept, self-contained |
+| **Enterprise production workflow** | External JSON | Governance, change management, auditing |
+
+---
+
+## Template Categories Analysis
+
+**Verified Statistics (2025-10-31):**
+
+| Pattern | Count | Percentage | Primary Use |
+|---------|-------|------------|-------------|
+| ✅ External JSON | 20 | 40.0% | Production ingestion/extraction |
+| ⚠️ TypeScript Import | 7 | 14.0% | Older approach (being migrated) |
+| ✅ Inline Mapping | 17 | 34.0% | Examples, webhooks, simple cases |
+| ℹ️ No Mapping | 6 | 12.0% | Architecture guides, non-mapping patterns |
+| **Total** | **50** | **100%** | All Versori production templates |
+
+---
+
+## Best Practices
+
+### For External JSON Files
+
+1. **Use descriptive filenames:**
+   ```
+   ✅ inventory.batch.json
+   ✅ products.export.csv.json
+   ✅ orders.import.xml.json
+
+   ❌ mapping.json
+   ❌ config.json
+   ❌ data.json
+   ```
+
+2. **Include version and metadata:**
+   ```json
+   {
+     "version": "1.0.0",
+     "description": "Inventory batch ingestion mapping",
+     "lastUpdated": "2025-10-31",
+     "fields": { ... }
+   }
+   ```
+
+3. **Use consistent structure:**
+   ```json
+   {
+     "version": "1.0.0",
+     "fields": {
+       "fieldName": {
+         "source": "source_path",
+         "required": true|false,
+         "resolver": "sdk.resolverName",
+         "defaultValue": "value"
+       }
+     }
+   }
+   ```
+
+4. **Document custom resolvers:**
+   ```json
+   {
+     "version": "1.0.0",
+     "customResolvers": [
+       "custom.calculateTax",
+       "custom.formatAddress"
+     ],
+     "fields": { ... }
+   }
+   ```
+
+### For Inline Mappings
+
+1. **Keep it simple (<10 fields):**
+   ```typescript
+   // ✅ GOOD - Simple, readable
+   const mapper = new UniversalMapper({
+     fields: {
+       sku: { source: 'product_code' },
+       qty: { source: 'stock', resolver: 'sdk.parseInt' }
+     }
+   });
+
+   // ❌ BAD - Too complex for inline
+   const mapper = new UniversalMapper({
+     fields: {
+       // 50 fields here...
+     }
+   });
+   ```
+
+2. **Add comments for clarity:**
+   ```typescript
+   const mapper = new UniversalMapper({
+     fields: {
+       // Primary identifier from source system
+       skuRef: { source: 'sku_id', required: true },
+
+       // Stock quantity (parse as integer)
+       qty: { source: 'quantity', resolver: 'sdk.parseInt' }
+     }
+   });
+   ```
+
+3. **Extract to variable for reusability:**
+   ```typescript
+   // ✅ GOOD - Reusable within file
+   const inventoryFields = {
+     skuRef: { source: 'sku_id' },
+     qty: { source: 'quantity', resolver: 'sdk.parseInt' }
+   };
+
+   const mapper1 = new UniversalMapper({ fields: inventoryFields });
+   const mapper2 = new UniversalMapper({ fields: inventoryFields });
+   ```
+
+---
+
+## Environment-Specific Configurations
+
+### External JSON Pattern
+
+**Directory structure:**
+```
+config/
+├── dev/
+│   ├── inventory.batch.json
+│   └── products.export.json
+├── staging/
+│   ├── inventory.batch.json
+│   └── products.export.json
+└── prod/
+    ├── inventory.batch.json
+    └── products.export.json
+```
+
+**Dynamic import:**
+```typescript
+import { activation } from '@versori/run';
+
+// Load environment-specific config
+const env = activation.environment || 'dev';
+const mappingConfig = await import(`./config/${env}/inventory.batch.json`, {
+  with: { type: 'json' }
+});
+
+const mapper = new UniversalMapper(mappingConfig.default);
+```
+
+---
+
+## Migration Guide
+
+### Migrating from TypeScript Import to External JSON
+
+**Step 1: Extract TypeScript config to JSON**
+```typescript
+// OLD: config/inventory-mapping.config.ts
+export const inventoryMapping = {
+  version: '1.0.0',
+  fields: {
+    skuRef: { source: 'sku_id', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' }
+  }
+};
+```
+
+**Step 2: Create JSON file**
+```json
+// NEW: config/inventory.batch.json
+{
+  "version": "1.0.0",
+  "fields": {
+    "skuRef": { "source": "sku_id", "required": true },
+    "qty": { "source": "quantity", "resolver": "sdk.parseInt" }
+  }
+}
+```
+
+**Step 3: Update import statement**
+```typescript
+// OLD
+import { inventoryMapping } from './config/inventory-mapping.config';
+const mapper = new UniversalMapper(inventoryMapping);
+
+// NEW
+import inventoryMapping from './config/inventory.batch.json' with { type: 'json' };
+const mapper = new UniversalMapper(inventoryMapping);
+```
+
+**Step 4: Delete old TypeScript config file**
+```bash
+rm config/inventory-mapping.config.ts
+```
+
+---
+
+## Common Pitfalls
+
+### ❌ Pitfall 1: Using TypeScript for production configs
+```typescript
+// ❌ WRONG
+import { config } from './inventory.config';
+
+// ✅ CORRECT
+import config from './inventory.batch.json' with { type: 'json' };
+```
+
+### ❌ Pitfall 2: Inline mappings with 50+ fields
+```typescript
+// ❌ WRONG - Too large for inline
+const mapper = new UniversalMapper({
+  fields: {
+    field1: { ... },
+    field2: { ... },
+    // 48 more fields...
+  }
+});
+
+// ✅ CORRECT - Use external JSON
+import mappingConfig from './config/large-mapping.json' with { type: 'json' };
+const mapper = new UniversalMapper(mappingConfig);
+```
+
+### ❌ Pitfall 3: Missing 'with { type: 'json' }' clause
+```typescript
+// ❌ WRONG - TypeScript import
+import mappingConfig from './config/mapping.json';
+
+// ❌ WRONG - Old assert syntax
+import mappingConfig from './config/mapping.json' assert { type: 'json' };
+
+// ✅ CORRECT - Standard JSON import
+import mappingConfig from './config/mapping.json' with { type: 'json' };
+```
+
+---
+
+## Related Documentation
+
+- [Universal Mapping Guide](mapping-readme.md) - Complete mapping patterns
+- [SDK Resolvers](./resolvers/mapping-resolvers-readme.md) - Built-in field transformations
+- [GraphQL Mutation Mapping](./graphql-mutation-mapping/graphql-mutation-mapping-readme.md) - XML/JSON → GraphQL
+- [Template Loading Matrix](../../template-loading-matrix.md) - Template selection guide
+
+---
+
+## FAQ
+
+**Q: Can I use inline mappings in production?**
+A: Yes, for simple cases (<10 fields) or webhooks with dynamic logic. For larger configs, use external JSON.
+
+**Q: Why not use TypeScript for type safety?**
+A: External JSON files are easier for non-developers to maintain and support runtime configuration changes without code deployment.
+
+**Q: What's the difference between `assert` and `with`?**
+A: `assert { type: 'json' }` is older syntax. Use `with { type: 'json' }` for current JavaScript/TypeScript standards.
+
+**Q: Can I have both inline and external mappings?**
+A: Yes! Use external for large/reusable configs and inline for dynamic logic or simple examples.
+
+**Q: How do I validate my JSON mapping file?**
+A: Use the SDK's validation tools:
+```bash
+npx fc-connect validate-schema --mapping config/inventory.batch.json
+```
+
+---
+
+**Last Updated:** 2025-10-31
+**SDK Version:** ≥0.1.31
+**Verified Against:** 50 production Versori templates