@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/00-START-HERE/mapper-quick-decision-guide.md

@@ -1,235 +1,235 @@
-# Mapper Quick Decision Guide
-
-**⏱️ Read Time:** 2 minutes | **When:** Before starting any integration
-
----
-
-## 🎯 The Core Difference (One Sentence)
-
-**GraphQLMutationMapper:** Both `map()` and `mapWithNodes()` return query + variables (ready to execute)  
-**UniversalMapper:** Only generates the variables (plain JavaScript objects) - you write the query manually
-
-> ✅ **Fixed:** `mapWithNodes()` now returns `{ success, data, query, context, errors }` - consistent with `map()`! Both GraphQLMutationMapper methods return query + variables automatically.
-
----
-
-## 📊 Complete Comparison Table
-
-| Feature | GraphQLMutationMapper.map() | GraphQLMutationMapper.mapWithNodes() | UniversalMapper.map() |
-|---------|----------------------------|-------------------------------------|----------------------|
-| **Returns Query?** | ✅ Yes (auto-generated) | ✅ Yes (auto-generated) | ❌ No (you write it) |
-| **Returns Variables?** | ✅ Yes (in `variables`) | ✅ Yes (in `data`) | ✅ Yes (in `data`) |
-| **Custom Resolvers?** | ❌ No | ✅ Yes (primary use case) | ✅ Yes |
-| **XML Nodes?** | ❌ No | ✅ Yes (extract nested XML) | ❌ No |
-| **Steps to Execute** | 1 step: `await client.graphql(result)` | 1 step: `await client.graphql({ query: result.query, variables: result.variables })` | 2 steps: write query + `graphql()` |
-| **Real-World Usage** | Simple JSON → GraphQL | ⚠️ **Most templates use this!** | CSV/Parquet → Any API |
-| **Best For** | Simple transformations | Complex XML + custom logic | Maximum flexibility |
-
----
-
-## 📊 Quick Decision Table
-
-| Your Scenario | Use This | Why |
-|--------------|----------|-----|
-| **XML/JSON webhooks** (SFCC orders, EDI) → Fluent with custom resolvers | `GraphQLMutationMapper.mapWithNodes()` | Custom resolvers, XML nodes, context passing (returns query automatically) |
-| **Simple JSON → GraphQL** (no custom resolvers) | `GraphQLMutationMapper.map()` | One-step execution, auto-generated query |
-| **CSV/Parquet files** → Fluent (any API) | `UniversalMapper` | Flexible, works with GraphQL, Event API, or Batch API |
-| **Bulk inventory** (CSV/Parquet) → Batch API | `UniversalMapper` + Batch API | Only way to use Batch API (inventory only) |
-| **Need to trigger workflows** → Event API | `UniversalMapper` + Event API | Event API doesn't use GraphQL queries |
-| **Simple field transforms** (rename, convert types) | `UniversalMapper` | Lightweight, no GraphQL needed |
-
----
-
-## 🔍 What They Return
-
-### GraphQLMutationMapper - Method 1: `map()` (Simple Pattern)
-```typescript
-const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
-const result = await mapper.map(sourceData);
-
-// result = {
-//   query: `mutation CreateOrder($input: CreateOrderInput!) { ... }`,  // ✅ Auto-generated!
-//   variables: { input: { ref: "ORD-123", ... } }
-// }
-
-await client.graphql(result);  // ✅ Ready to execute! (result has query + variables)
-```
-
-**Limitations:** No custom resolvers, no XML nodes extraction
-
----
-
-### GraphQLMutationMapper - Method 2: `mapWithNodes()` (Advanced Pattern)
-**⚠️ This is what templates actually use!**
-
-```typescript
-const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
-const result = await mapper.mapWithNodes(xmlData, customResolvers, context);
-
-// result = {
-//   success: true,
-//   data: { input: { ref: "ORD-123", ... } },  // ✅ GraphQL variables
-//   query: `mutation CreateOrder(...) { ... }`, // ✅ Auto-generated query!
-//   context: { /* parsed nodes */ },
-//   errors: []
-// }
-
-// Execute directly (one step - consistent with map()!)
-await client.graphql({
-  query: result.query,       // ← From mapWithNodes()
-  variables: result.variables  // ← From mapWithNodes() (wrapped if fields pattern)
-});
-```
-
-**Why templates use this:** Custom resolvers, XML node extraction, context passing
-
----
-
-### UniversalMapper
-```typescript
-const mapper = new UniversalMapper(config);
-const result = await mapper.map(sourceData);
-
-// result = {
-//   success: true,
-//   data: { ref: "ORD-123", ... },  // ✅ Just the data
-//   errors: []
-// }
-
-// YOU write the GraphQL query
-const mutation = `mutation CreateOrder($input: CreateOrderInput!) { ... }`;
-await client.graphql({ 
-  query: mutation, 
-  variables: result.variables  // Already wrapped: { input: { ... } }
-});
-```
-
----
-
-## ✅ When to Use GraphQLMutationMapper
-
-### Use `map()` when:
-- ✅ Simple JSON → GraphQL (no custom resolvers needed)
-- ✅ Want **auto-generated GraphQL queries** (one-step execution)
-- ✅ No XML nodes extraction needed
-
-### Use `mapWithNodes()` when (⚠️ **Most templates use this!**):
-- ✅ Processing **complex XML/JSON** (SFCC orders, EDI files, nested structures)
-- ✅ Need **custom resolvers** (business logic, API calls)
-- ✅ Need **XML node extraction** (nested/escaped XML segments)
-- ✅ Need **context passing** (FluentClient, config, helpers)
-- ✅ **Returns query automatically** (consistent with `map()` - 1 step!)
-
-**Example use cases:**
-- SFCC order ingestion (complex nested XML + custom resolvers)
-- EDI 850 purchase orders → GraphQL (with custom validation)
-- Complex JSON webhook payloads → GraphQL (with business logic)
-
----
-
-## ✅ When to Use UniversalMapper
-
-Use when:
-- ✅ Processing **CSV or simple JSON** (inventory, products, locations)
-- ✅ Want to **write your own GraphQL queries** (more control)
-- ✅ Need to use **Event API** (trigger Rubix workflows)
-- ✅ Need to use **Batch API** (bulk inventory updates)
-- ✅ Want **flexibility** to use mapped data with multiple APIs
-
-**Example use cases:**
-- CSV inventory updates → Batch API
-- CSV product catalog → Event API (triggers workflows)
-- JSON location data → GraphQL mutations (your own queries)
-- Parquet data warehouse → Any API
-
----
-
-## 🚀 Key Insight: UniversalMapper is MORE Flexible
-
-UniversalMapper can be used with **3 different APIs**, not just GraphQL:
-
-```typescript
-const mapper = new UniversalMapper(config);
-const result = await mapper.map(csvRow);
-
-// Option 1: GraphQL Mutations
-await client.graphql({
-  query: yourMutation,
-  variables: result.variables  // Already wrapped: { input: { ... } }
-});
-
-// Option 2: Event API (triggers Rubix workflows)
-await client.sendEvent({
-  name: 'UPSERT_LOCATION',
-  attributes: result.data,  // ✅ Same mapped data!
-}, 'async');
-
-// Option 3: Batch API (inventory only)
-await client.sendBatch(jobId, {
-  entityType: 'INVENTORY',
-  entities: [result.data],  // ✅ Same mapped data!
-});
-```
-
-**GraphQLMutationMapper can ONLY be used with GraphQL mutations** (the query string is pre-built).
-
----
-
-## 📝 Decision Flow
-
-```
-START: What are you building?
-│
-├─ XML/JSON webhook → Fluent?
-│  └─ YES → Use GraphQLMutationMapper ✅
-│
-├─ CSV/Parquet → Fluent?
-│  ├─ Need Batch API (inventory)? → UniversalMapper + Batch API ✅
-│  ├─ Need Event API (workflows)? → UniversalMapper + Event API ✅
-│  └─ Need GraphQL? → UniversalMapper + Manual GraphQL ✅
-│
-└─ Simple field transforms?
-   └─ YES → UniversalMapper ✅
-```
-
----
-
-## 🔑 The Bottom Line
-
-| Mapper Method | Returns Query? | Returns Variables? | Steps to Execute |
-|--------------|----------------|-------------------|------------------|
-| **GraphQLMutationMapper.map()** | ✅ Yes (auto-generated) | ✅ Yes (in `variables`) | 1 step: `await client.graphql(result)` |
-| **GraphQLMutationMapper.mapWithNodes()** | ✅ Yes (auto-generated) | ✅ Yes (in `variables`, unwrapped in `data`) | 1 step: `await client.graphql({ query: result.query, variables: result.variables })` |
-| **UniversalMapper.map()** | ❌ No (you write it) | ✅ Yes (in `data`) | 2 steps: write query + `graphql()` |
-
-**Key Insight:** Both `map()` and `mapWithNodes()` now return query + variables (consistent API!) - only UniversalMapper requires you to write the query manually.
-
-**Analogy:**
-- **GraphQLMutationMapper.map()** = Ordering a complete meal (ready to eat)
-- **GraphQLMutationMapper.mapWithNodes()** = Ordering a complete meal with custom ingredients (ready to eat, but more complex)
-- **UniversalMapper** = Getting ingredients from a grocery store (you cook everything yourself, maximum flexibility)
-
----
-
-## 📚 Need More Details?
-
-- **Complete Comparison:** [Mapper Comparison Guide](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) - Real-world scenario with code examples
-- **GraphQLMutationMapper Guide:** [GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)
-- **UniversalMapper Guide:** [Universal Mapping](../02-CORE-GUIDES/mapping/)
-
----
-
-## 💡 Pro Tip
-
-**If you're starting fresh:**
-1. Use **UniversalMapper** for maximum flexibility
-2. Write simple GraphQL mutation strings
-3. Switch to **GraphQLMutationMapper.mapWithNodes()** if:
-   - You need custom resolvers with context (FluentClient, config)
-   - You need XML node extraction
-   - You want auto-generated queries (now consistent with `map()`!)
-
-**Important:** `mapWithNodes()` now returns the query automatically - making it consistent with `map()`! Both methods are now 1-step execution.
-
-**Most SDK users prefer UniversalMapper + manual GraphQL** because it's easier to understand and debug!
-
+# Mapper Quick Decision Guide
+
+**⏱️ Read Time:** 2 minutes | **When:** Before starting any integration
+
+---
+
+## 🎯 The Core Difference (One Sentence)
+
+**GraphQLMutationMapper:** Both `map()` and `mapWithNodes()` return query + variables (ready to execute)  
+**UniversalMapper:** Only generates the variables (plain JavaScript objects) - you write the query manually
+
+> ✅ **Fixed:** `mapWithNodes()` now returns `{ success, data, query, context, errors }` - consistent with `map()`! Both GraphQLMutationMapper methods return query + variables automatically.
+
+---
+
+## 📊 Complete Comparison Table
+
+| Feature | GraphQLMutationMapper.map() | GraphQLMutationMapper.mapWithNodes() | UniversalMapper.map() |
+|---------|----------------------------|-------------------------------------|----------------------|
+| **Returns Query?** | ✅ Yes (auto-generated) | ✅ Yes (auto-generated) | ❌ No (you write it) |
+| **Returns Variables?** | ✅ Yes (in `variables`) | ✅ Yes (in `data`) | ✅ Yes (in `data`) |
+| **Custom Resolvers?** | ❌ No | ✅ Yes (primary use case) | ✅ Yes |
+| **XML Nodes?** | ❌ No | ✅ Yes (extract nested XML) | ❌ No |
+| **Steps to Execute** | 1 step: `await client.graphql(result)` | 1 step: `await client.graphql({ query: result.query, variables: result.variables })` | 2 steps: write query + `graphql()` |
+| **Real-World Usage** | Simple JSON → GraphQL | ⚠️ **Most templates use this!** | CSV/Parquet → Any API |
+| **Best For** | Simple transformations | Complex XML + custom logic | Maximum flexibility |
+
+---
+
+## 📊 Quick Decision Table
+
+| Your Scenario | Use This | Why |
+|--------------|----------|-----|
+| **XML/JSON webhooks** (SFCC orders, EDI) → Fluent with custom resolvers | `GraphQLMutationMapper.mapWithNodes()` | Custom resolvers, XML nodes, context passing (returns query automatically) |
+| **Simple JSON → GraphQL** (no custom resolvers) | `GraphQLMutationMapper.map()` | One-step execution, auto-generated query |
+| **CSV/Parquet files** → Fluent (any API) | `UniversalMapper` | Flexible, works with GraphQL, Event API, or Batch API |
+| **Bulk inventory** (CSV/Parquet) → Batch API | `UniversalMapper` + Batch API | Only way to use Batch API (inventory only) |
+| **Need to trigger workflows** → Event API | `UniversalMapper` + Event API | Event API doesn't use GraphQL queries |
+| **Simple field transforms** (rename, convert types) | `UniversalMapper` | Lightweight, no GraphQL needed |
+
+---
+
+## 🔍 What They Return
+
+### GraphQLMutationMapper - Method 1: `map()` (Simple Pattern)
+```typescript
+const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
+const result = await mapper.map(sourceData);
+
+// result = {
+//   query: `mutation CreateOrder($input: CreateOrderInput!) { ... }`,  // ✅ Auto-generated!
+//   variables: { input: { ref: "ORD-123", ... } }
+// }
+
+await client.graphql(result);  // ✅ Ready to execute! (result has query + variables)
+```
+
+**Limitations:** No custom resolvers, no XML nodes extraction
+
+---
+
+### GraphQLMutationMapper - Method 2: `mapWithNodes()` (Advanced Pattern)
+**⚠️ This is what templates actually use!**
+
+```typescript
+const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
+const result = await mapper.mapWithNodes(xmlData, customResolvers, context);
+
+// result = {
+//   success: true,
+//   data: { input: { ref: "ORD-123", ... } },  // ✅ GraphQL variables
+//   query: `mutation CreateOrder(...) { ... }`, // ✅ Auto-generated query!
+//   context: { /* parsed nodes */ },
+//   errors: []
+// }
+
+// Execute directly (one step - consistent with map()!)
+await client.graphql({
+  query: result.query,       // ← From mapWithNodes()
+  variables: result.variables  // ← From mapWithNodes() (wrapped if fields pattern)
+});
+```
+
+**Why templates use this:** Custom resolvers, XML node extraction, context passing
+
+---
+
+### UniversalMapper
+```typescript
+const mapper = new UniversalMapper(config);
+const result = await mapper.map(sourceData);
+
+// result = {
+//   success: true,
+//   data: { ref: "ORD-123", ... },  // ✅ Just the data
+//   errors: []
+// }
+
+// YOU write the GraphQL query
+const mutation = `mutation CreateOrder($input: CreateOrderInput!) { ... }`;
+await client.graphql({ 
+  query: mutation, 
+  variables: result.variables  // Already wrapped: { input: { ... } }
+});
+```
+
+---
+
+## ✅ When to Use GraphQLMutationMapper
+
+### Use `map()` when:
+- ✅ Simple JSON → GraphQL (no custom resolvers needed)
+- ✅ Want **auto-generated GraphQL queries** (one-step execution)
+- ✅ No XML nodes extraction needed
+
+### Use `mapWithNodes()` when (⚠️ **Most templates use this!**):
+- ✅ Processing **complex XML/JSON** (SFCC orders, EDI files, nested structures)
+- ✅ Need **custom resolvers** (business logic, API calls)
+- ✅ Need **XML node extraction** (nested/escaped XML segments)
+- ✅ Need **context passing** (FluentClient, config, helpers)
+- ✅ **Returns query automatically** (consistent with `map()` - 1 step!)
+
+**Example use cases:**
+- SFCC order ingestion (complex nested XML + custom resolvers)
+- EDI 850 purchase orders → GraphQL (with custom validation)
+- Complex JSON webhook payloads → GraphQL (with business logic)
+
+---
+
+## ✅ When to Use UniversalMapper
+
+Use when:
+- ✅ Processing **CSV or simple JSON** (inventory, products, locations)
+- ✅ Want to **write your own GraphQL queries** (more control)
+- ✅ Need to use **Event API** (trigger Rubix workflows)
+- ✅ Need to use **Batch API** (bulk inventory updates)
+- ✅ Want **flexibility** to use mapped data with multiple APIs
+
+**Example use cases:**
+- CSV inventory updates → Batch API
+- CSV product catalog → Event API (triggers workflows)
+- JSON location data → GraphQL mutations (your own queries)
+- Parquet data warehouse → Any API
+
+---
+
+## 🚀 Key Insight: UniversalMapper is MORE Flexible
+
+UniversalMapper can be used with **3 different APIs**, not just GraphQL:
+
+```typescript
+const mapper = new UniversalMapper(config);
+const result = await mapper.map(csvRow);
+
+// Option 1: GraphQL Mutations
+await client.graphql({
+  query: yourMutation,
+  variables: result.variables  // Already wrapped: { input: { ... } }
+});
+
+// Option 2: Event API (triggers Rubix workflows)
+await client.sendEvent({
+  name: 'UPSERT_LOCATION',
+  attributes: result.data,  // ✅ Same mapped data!
+}, 'async');
+
+// Option 3: Batch API (inventory only)
+await client.sendBatch(jobId, {
+  entityType: 'INVENTORY',
+  entities: [result.data],  // ✅ Same mapped data!
+});
+```
+
+**GraphQLMutationMapper can ONLY be used with GraphQL mutations** (the query string is pre-built).
+
+---
+
+## 📝 Decision Flow
+
+```
+START: What are you building?
+│
+├─ XML/JSON webhook → Fluent?
+│  └─ YES → Use GraphQLMutationMapper ✅
+│
+├─ CSV/Parquet → Fluent?
+│  ├─ Need Batch API (inventory)? → UniversalMapper + Batch API ✅
+│  ├─ Need Event API (workflows)? → UniversalMapper + Event API ✅
+│  └─ Need GraphQL? → UniversalMapper + Manual GraphQL ✅
+│
+└─ Simple field transforms?
+   └─ YES → UniversalMapper ✅
+```
+
+---
+
+## 🔑 The Bottom Line
+
+| Mapper Method | Returns Query? | Returns Variables? | Steps to Execute |
+|--------------|----------------|-------------------|------------------|
+| **GraphQLMutationMapper.map()** | ✅ Yes (auto-generated) | ✅ Yes (in `variables`) | 1 step: `await client.graphql(result)` |
+| **GraphQLMutationMapper.mapWithNodes()** | ✅ Yes (auto-generated) | ✅ Yes (in `variables`, unwrapped in `data`) | 1 step: `await client.graphql({ query: result.query, variables: result.variables })` |
+| **UniversalMapper.map()** | ❌ No (you write it) | ✅ Yes (in `data`) | 2 steps: write query + `graphql()` |
+
+**Key Insight:** Both `map()` and `mapWithNodes()` now return query + variables (consistent API!) - only UniversalMapper requires you to write the query manually.
+
+**Analogy:**
+- **GraphQLMutationMapper.map()** = Ordering a complete meal (ready to eat)
+- **GraphQLMutationMapper.mapWithNodes()** = Ordering a complete meal with custom ingredients (ready to eat, but more complex)
+- **UniversalMapper** = Getting ingredients from a grocery store (you cook everything yourself, maximum flexibility)
+
+---
+
+## 📚 Need More Details?
+
+- **Complete Comparison:** [Mapper Comparison Guide](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) - Real-world scenario with code examples
+- **GraphQLMutationMapper Guide:** [GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)
+- **UniversalMapper Guide:** [Universal Mapping](../02-CORE-GUIDES/mapping/)
+
+---
+
+## 💡 Pro Tip
+
+**If you're starting fresh:**
+1. Use **UniversalMapper** for maximum flexibility
+2. Write simple GraphQL mutation strings
+3. Switch to **GraphQLMutationMapper.mapWithNodes()** if:
+   - You need custom resolvers with context (FluentClient, config)
+   - You need XML node extraction
+   - You want auto-generated queries (now consistent with `map()`!)
+
+**Important:** `mapWithNodes()` now returns the query automatically - making it consistent with `map()`! Both methods are now 1-step execution.
+
+**Most SDK users prefer UniversalMapper + manual GraphQL** because it's easier to understand and debug!
+