@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/mapping-graphql-alias-batching-guide.md

@@ -1,820 +1,820 @@
-# GraphQL Alias Batching Guide
-
-**Last Updated:** 2025-01-24  
-**Status:** ✅ Production Ready
-
----
-
-## 📋 Table of Contents
-
-1. [Overview](#overview)
-2. [When to Use Alias Batching](#when-to-use-alias-batching)
-3. [How It Works](#how-it-works)
-4. [Configuration](#configuration)
-5. [Implementation Patterns](#implementation-patterns)
-6. [Response Parsing](#response-parsing)
-7. [Error Handling](#error-handling)
-8. [Performance Considerations](#performance-considerations)
-9. [Best Practices](#best-practices)
-10. [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-GraphQL alias batching allows you to execute multiple mutations in a single HTTP request by using GraphQL aliases. This reduces network overhead and can improve performance for high-volume ingestion scenarios.
-
-### What Are GraphQL Aliases?
-
-GraphQL aliases let you include multiple fields (or mutations) with the same name in a single query by giving each one a unique alias:
-
-```graphql
-mutation BatchCreateLocations($input1: CreateLocationInput!, $input2: CreateLocationInput!) {
-  createLocation1: createLocation(input: $input1) { id ref name }
-  createLocation2: createLocation(input: $input2) { id ref name }
-}
-```
-
-**Benefits:**
-- ✅ **Reduced Network Overhead:** One HTTP request instead of multiple
-- ✅ **Faster Execution:** Single round-trip to the server
-- ✅ **Better Throughput:** Process more mutations per second
-- ✅ **Server-Side Efficiency:** Server can optimize batch execution
-
-**Trade-offs:**
-- ⚠️ **Complex Error Handling:** Partial failures require parsing aliased responses
-- ⚠️ **Request Size Limits:** Large batches may hit payload limits
-- ⚠️ **Server Execution Control:** Server controls execution order (not client)
-
----
-
-## When to Use Alias Batching
-
-### ✅ Use Alias Batching When:
-
-1. **High-Volume Ingestion**
-   - Processing hundreds or thousands of records
-   - Network latency is a bottleneck
-   - Throughput is more important than latency
-
-2. **Sequential Processing is Acceptable**
-   - Records don't depend on each other
-   - Order doesn't matter
-   - You can handle partial failures gracefully
-
-3. **Rate Limiting Concerns**
-   - Want to reduce number of HTTP requests
-   - Server has strict rate limits
-   - Need to stay within quota
-
-### ❌ Don't Use Alias Batching When:
-
-1. **Low Volume (< 10 records)**
-   - Overhead doesn't justify complexity
-   - Separate requests are simpler
-
-2. **Strict Error Isolation Needed**
-   - Need to know exactly which mutation failed
-   - Can't tolerate partial failures
-   - Want to retry individual mutations
-
-3. **Dependent Mutations**
-   - Mutations depend on each other
-   - Need transaction-like behavior
-   - Order matters
-
-### Decision Matrix
-
-| Scenario | Separate Requests | Alias Batching |
-|---------|------------------|----------------|
-| < 10 records | ✅ Recommended | ❌ Overkill |
-| 10-100 records | ✅ Simple | ⚠️ Optional |
-| 100-1000 records | ⚠️ Slower | ✅ Recommended |
-| > 1000 records | ❌ Too slow | ✅ Recommended |
-| Need error isolation | ✅ Better | ⚠️ Complex |
-| Need throughput | ⚠️ Slower | ✅ Better |
-
----
-
-## How It Works
-
-### Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Client-Side Flow                         │
-└─────────────────────────────────────────────────────────────┘
-
-1. Map Items (GraphQLMutationMapper)
-   ├─ Transform each record to GraphQL input
-   └─ Store mapped inputs
-
-2. Batch Items (batchMap or manual)
-   ├─ Group items into batches (e.g., 5 per batch)
-   └─ Generate aliased query
-
-3. Execute Batches (Concurrency Control)
-   ├─ Send batch 1: mutationsPerAliasBatch=5
-   ├─ Send batch 2: mutationsPerAliasBatch=5
-   └─ Process concurrently (maxParallel=3)
-
-4. Parse Responses
-   ├─ Extract results by alias (createLocation1, createLocation2, ...)
-   ├─ Identify partial failures
-   └─ Aggregate success/failure counts
-```
-
-### SDK Methods
-
-#### 1. `GraphQLMutationMapper.batchMap()`
-
-The SDK provides a `batchMap()` method that generates aliased queries:
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-
-// Batch map multiple items
-const items = [
-  { ref: 'LOC-001', name: 'Location 1' },
-  { ref: 'LOC-002', name: 'Location 2' },
-  { ref: 'LOC-003', name: 'Location 3' },
-];
-
-const batch = await mapper.batchMap(items, { mutationsPerBatch: 3 });
-
-// Result:
-// {
-//   query: "mutation BatchCreateLocations($input1: CreateLocationInput!, ...) { createLocation1: createLocation(...) { id ref } ... }",
-//   variables: { input1: {...}, input2: {...}, input3: {...} }
-// }
-```
-
-#### 2. `buildAliasedMutationQuery()`
-
-For manual query generation:
-
-```typescript
-import { buildAliasedMutationQuery } from '@fluentcommerce/fc-connect-sdk';
-
-const query = buildAliasedMutationQuery(mappingConfig, batchSize);
-// Generates: mutation BatchCreateLocations($input1: ..., $input2: ...) { createLocation1: ... createLocation2: ... }
-```
-
----
-
-## Configuration
-
-### Template-Level Configuration
-
-Templates use activation variables to control alias batching:
-
-```typescript
-// Concurrency control (number of concurrent alias batch requests)
-const mutationBatchSize = parseInt(
-  activation?.getVariable('mutationBatchSize') || '1',  // Default: 1 (sequential)
-  10
-);
-
-// Alias batching (number of mutations per aliased request)
-const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch') 
-  ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10) 
-  : undefined;  // Default: undefined (disabled, use separate requests)
-```
-
-### Configuration Examples
-
-#### Example 1: Default (Sequential, No Aliases)
-```typescript
-mutationBatchSize: 1                    // Sequential processing
-mutationsPerAliasBatch: undefined       // Disabled (separate requests)
-```
-**Result:** Each mutation is sent as a separate request, executed sequentially.
-
-#### Example 2: Concurrent Requests (No Aliases)
-```typescript
-mutationBatchSize: 5                    // 5 concurrent requests
-mutationsPerAliasBatch: undefined       // Disabled (separate requests)
-```
-**Result:** 5 separate HTTP requests sent concurrently.
-
-#### Example 3: Alias Batching (Single Batch)
-```typescript
-mutationBatchSize: 1                    // Sequential batch processing
-mutationsPerAliasBatch: 5               // 5 mutations per aliased request
-```
-**Result:** Groups of 5 mutations bundled into single aliased requests, processed sequentially.
-
-#### Example 4: Concurrent Alias Batching
-```typescript
-mutationBatchSize: 3                    // 3 concurrent alias batch requests
-mutationsPerAliasBatch: 5               // 5 mutations per aliased request
-```
-**Result:** Groups of 5 mutations bundled into aliased requests, with 3 such requests sent concurrently.
-
-**Visual Example:**
-```
-100 locations, mutationsPerAliasBatch=5, mutationBatchSize=3
-
-Batch 1: [Loc1-5]   ──┐
-Batch 2: [Loc6-10]  ──┼─► Sent concurrently (3 batches)
-Batch 3: [Loc11-15] ──┘
-
-Batch 4: [Loc16-20] ──┐
-Batch 5: [Loc21-25] ──┼─► Sent concurrently (3 batches)
-Batch 6: [Loc26-30] ──┘
-
-... (continues until all 100 locations processed)
-```
-
-### Mapping Config (Optional)
-
-The `aliasBatching` config in `MappingConfig` is optional metadata. Templates use runtime parameters for flexibility:
-
-```json
-{
-  "mutation": "createLocation",
-  "sourceFormat": "json",
-  "aliasBatching": {
-    "enabled": true,
-    "mutationsPerBatch": 5,
-    "maxMutationsPerBatch": 20
-  },
-  "arguments": {
-    "input": {
-      "ref": { "source": "ref" },
-      "name": { "source": "name" }
-    }
-  }
-}
-```
-
-**Note:** Templates use `mutationsPerAliasBatch` activation variable instead of this config for runtime flexibility.
-
----
-
-## Implementation Patterns
-
-### Pattern 1: Template Helper Functions
-
-Templates include helper functions for alias batching:
-
-```typescript
-/**
- * Execute mutations using GraphQL aliases (batched requests)
- */
-async function executeMutationsWithAliases(
-  locations: Array<{ query: string; variables: any; input: any }>,
-  client: FluentClient,
-  mapper: GraphQLMutationMapper,
-  log: any,
-  retailerId: string,
-  maxParallel: number,          // Concurrency control
-  mutationsPerAliasBatch: number // Mutations per aliased request
-): Promise<MutationResult> {
-  // ... implementation
-}
-
-/**
- * Build aliased batch query and variables
- */
-function buildAliasedBatch(
-  batch: Array<{ query: string; variables: any; input: any }>,
-  mutationName: string,
-  retailerId: string
-): { query: string; variables: Record<string, any> } {
-  // ... implementation
-}
-
-/**
- * Parse aliased GraphQL response
- */
-function parseAliasResponse(
-  response: any,
-  batch: Array<{ query: string; variables: any; input: any }>,
-  mutationName: string
-): { executed: number; failed: number; errors: Array<{ locationRef: string; error: string }> } {
-  // ... implementation
-}
-```
-
-### Pattern 2: Using SDK batchMap()
-
-For custom implementations:
-
-```typescript
-import { GraphQLMutationMapper, FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-
-// Group items into batches
-const batchSize = 5;
-const batches: Array<typeof items> = [];
-for (let i = 0; i < items.length; i += batchSize) {
-  batches.push(items.slice(i, i + batchSize));
-}
-
-// Process batches
-for (const batch of batches) {
-  // Generate aliased query
-  const { query, variables } = await mapper.batchMap(batch, {
-    mutationsPerBatch: batch.length
-  });
-
-  // Execute
-  const response = await client.graphql({ query, variables });
-
-  // Parse response
-  const results = parseAliasResponse(response, batch, 'createLocation');
-  // ... handle results
-}
-```
-
-### Pattern 3: Dispatcher Pattern
-
-Templates use a dispatcher to choose between modes:
-
-```typescript
-async function executeMutations(
-  locations: Array<{ query: string; variables: any; input: any }>,
-  client: FluentClient,
-  mapper: GraphQLMutationMapper,
-  log: any,
-  retailerId: string,
-  batchSize: number = 1,
-  mutationsPerAliasBatch?: number
-): Promise<MutationResult> {
-  const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
-  
-  if (useAliases) {
-    return await executeMutationsWithAliases(
-      locations, client, mapper, log, retailerId,
-      batchSize, mutationsPerAliasBatch!
-    );
-  } else {
-    return await executeMutationsSeparate(
-      locations, client, mapper, log, retailerId, batchSize
-    );
-  }
-}
-```
-
----
-
-## Response Parsing
-
-### Response Structure
-
-Aliased GraphQL responses have this structure:
-
-```json
-{
-  "data": {
-    "createLocation1": { "id": "123", "ref": "LOC-001", "name": "Location 1" },
-    "createLocation2": { "id": "124", "ref": "LOC-002", "name": "Location 2" },
-    "createLocation3": null  // ← Partial failure
-  },
-  "errors": [
-    {
-      "message": "Location with ref 'LOC-003' already exists",
-      "path": ["createLocation3"],
-      "extensions": { "code": "DUPLICATE" }
-    }
-  ]
-}
-```
-
-### SDK Response Parser ✨ NEW
-
-**The SDK now provides a built-in response parser** (available in latest SDK):
-
-```typescript
-import {
-  parseAliasedMutationResponse,
-  formatErrorSummary,
-  getFailedMutations,
-  getSuccessfulMutations,
-  type AliasedMutationResult
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Execute aliased mutation
-const response = await client.graphql({ query, variables });
-
-// Parse response
-const result = parseAliasedMutationResponse(
-  response,
-  batchSize,         // Number of mutations in the batch
-  'createLocation',  // Base mutation name
-  inputs             // Optional: original input data for error tracking
-);
-
-// Check results
-console.log(`Executed: ${result.executed}, Failed: ${result.failed}`);
-console.log(`All succeeded: ${result.allSucceeded}`);
-
-if (!result.allSucceeded) {
-  console.error(formatErrorSummary(result));
-
-  // Get failed mutations
-  const failed = getFailedMutations(result);
-  failed.forEach(mutation => {
-    console.error(`${mutation.alias}: ${mutation.error?.message}`);
-  });
-}
-
-// Get successful mutations
-const successful = getSuccessfulMutations(result);
-console.log(`Created ${successful.length} locations successfully`);
-```
-
-### Result Structure
-
-The parser returns an `AliasedMutationResult` object:
-
-```typescript
-interface AliasedMutationResult {
-  executed: number;              // Total mutations that succeeded
-  failed: number;                // Total mutations that failed
-  allSucceeded: boolean;         // Whether all mutations succeeded
-  allFailed: boolean;            // Whether all mutations failed
-  results: MutationResult[];     // Individual mutation results
-  errors: MutationError[];       // Aggregated errors
-}
-
-interface MutationResult {
-  alias: string;                 // e.g., 'createLocation1'
-  index: number;                 // 0-based index in batch
-  success: boolean;              // Whether this mutation succeeded
-  data?: any;                    // Response data (if successful)
-  error?: MutationError;         // Error details (if failed)
-}
-
-interface MutationError {
-  alias: string;                 // e.g., 'createLocation2'
-  index: number;                 // 0-based index in batch
-  inputRef?: string;             // e.g., 'LOC-002' (from input data)
-  message: string;               // Error message
-  graphqlErrors?: GraphQLError[];// Full GraphQL error details
-  input?: any;                   // Original input data
-}
-```
-
-### Features
-
-**Automatic Error Correlation:**
-- Matches GraphQL errors to specific mutations via `path` arrays
-- Extracts error messages and details
-- Provides input reference tracking
-
-**Flexible Input Tracking:**
-```typescript
-// Default: extracts 'ref' or 'id' from input
-const result = parseAliasedMutationResponse(response, 3, 'createLocation', inputs);
-
-// Custom: extract custom reference field
-const result = parseAliasedMutationResponse(response, 3, 'createLocation', inputs, {
-  extractRef: (input: any) => input.customRef
-});
-```
-
-**Helper Functions:**
-- `getFailedMutations(result)` - Filter failed mutations
-- `getSuccessfulMutations(result)` - Filter successful mutations
-- `getErrorMessage(mutation)` - Extract error message
-- `formatErrorSummary(result)` - Format for logging
-
-### Alternative Template Parsing (Optional)
-
-For templates that need custom parsing logic:
-
-```typescript
-function parseAliasResponse(
-  response: any,
-  batch: Array<{ query: string; variables: any; input: any }>,
-  mutationName: string
-): { executed: number; failed: number; errors: Array<{ locationRef: string; error: string }> } {
-  const result = { executed: 0, failed: 0, errors: [] };
-
-  const data = response.data || {};
-  const errors = response.errors || [];
-
-  // Process each alias result
-  batch.forEach((item, index) => {
-    const alias = `${mutationName}${index + 1}`;
-    const aliasData = data[alias];
-    const aliasErrors = errors.filter((e: any) =>
-      e.path && Array.isArray(e.path) && e.path.includes(alias)
-    );
-
-    if (aliasData && !aliasErrors.length) {
-      result.executed++;
-    } else {
-      result.failed++;
-      const errorMsg = aliasErrors[0]?.message || 'Mutation failed';
-      const locationRef = item.input?.ref || 'unknown';
-      result.errors.push({
-        locationRef,
-        error: errorMsg,
-      });
-    }
-  });
-
-  return result;
-}
-```
-
-**Note:** The SDK parser provides more robust error handling and type safety. Use it unless you need custom parsing logic.
-
-### Alias Naming Pattern
-
-The SDK uses a simple naming pattern: `{mutationName}{index}`
-
-- `createLocation1`, `createLocation2`, `createLocation3`, ...
-- `updateProduct1`, `updateProduct2`, `updateProduct3`, ...
-- `deleteOrder1`, `deleteOrder2`, `deleteOrder3`, ...
-
-**Not configurable** - this keeps the implementation simple and predictable.
-
----
-
-## Error Handling
-
-### Partial Failures
-
-Aliased batches can have partial failures:
-
-```json
-{
-  "data": {
-    "createLocation1": { "id": "123", "ref": "LOC-001" },
-    "createLocation2": null,  // ← Failed
-    "createLocation3": { "id": "125", "ref": "LOC-003" }
-  },
-  "errors": [
-    {
-      "message": "Duplicate ref: LOC-002",
-      "path": ["createLocation2"]
-    }
-  ]
-}
-```
-
-**Best Practices:**
-1. ✅ Parse each alias result individually
-2. ✅ Track which mutations succeeded/failed
-3. ✅ Log partial failures for audit
-4. ✅ Continue processing remaining batches
-5. ✅ Don't retry entire batch if only one failed
-
-### Error Parsing
-
-```typescript
-// Extract errors for specific alias
-const aliasErrors = errors.filter((e: any) => 
-  e.path && Array.isArray(e.path) && e.path.includes(alias)
-);
-
-// Handle different error types
-if (aliasErrors.length > 0) {
-  const error = aliasErrors[0];
-  if (error.extensions?.code === 'DUPLICATE') {
-    // Handle duplicate
-  } else if (error.extensions?.code === 'VALIDATION_ERROR') {
-    // Handle validation error
-  } else {
-    // Handle generic error
-  }
-}
-```
-
-### Retry Strategy
-
-**Don't retry entire batch** - retry individual mutations:
-
-```typescript
-// ❌ BAD: Retry entire batch
-if (result.failed > 0) {
-  await retry(() => client.graphql({ query, variables }));
-}
-
-// ✅ GOOD: Retry individual mutations
-const failedItems = batch.filter((item, idx) => {
-  const alias = `${mutationName}${idx + 1}`;
-  return !response.data[alias];
-});
-
-for (const item of failedItems) {
-  await retry(() => executeSingleMutation(item));
-}
-```
-
----
-
-## Performance Considerations
-
-### Network Overhead
-
-**Separate Requests:**
-- 100 mutations = 100 HTTP requests
-- 100 × network latency = total time
-
-**Alias Batching:**
-- 100 mutations ÷ 5 per batch = 20 HTTP requests
-- 20 × network latency = total time
-
-**Savings:** ~80% reduction in network overhead
-
-### Optimal Batch Size
-
-**Factors to Consider:**
-
-1. **Payload Size**
-   - GraphQL requests have size limits
-   - Larger batches = larger payloads
-   - **Recommendation:** 5-10 mutations per batch
-
-2. **Error Isolation**
-   - Larger batches = more mutations affected by one failure
-   - **Recommendation:** 5-10 mutations per batch
-
-3. **Server Processing**
-   - Server may process batches sequentially
-   - Larger batches = longer wait for first result
-   - **Recommendation:** 5-10 mutations per batch
-
-**Default:** `mutationsPerAliasBatch: 5` (optimal balance)
-
-### Concurrency vs Batch Size
-
-**Trade-off:**
-- **High concurrency + small batches:** More requests, faster per-request
-- **Low concurrency + large batches:** Fewer requests, slower per-request
-
-**Recommendation:**
-- Start with `mutationBatchSize: 1`, `mutationsPerAliasBatch: 5`
-- If throughput is low, increase `mutationBatchSize` to 3-5
-- If errors increase, reduce `mutationsPerAliasBatch` to 3
-
----
-
-## Best Practices
-
-### ✅ DO
-
-1. **Use Aliases for High Volume**
-   - Process 100+ records
-   - Network latency is a bottleneck
-   - Throughput is priority
-
-2. **Keep Batch Sizes Reasonable**
-   - 5-10 mutations per batch
-   - Don't exceed payload limits
-   - Balance error isolation
-
-3. **Handle Partial Failures**
-   - Parse each alias result
-   - Track individual success/failure
-   - Log errors for audit
-
-4. **Monitor Performance**
-   - Track request count reduction
-   - Measure throughput improvement
-   - Watch for error rate changes
-
-5. **Use Concurrency Control**
-   - Start with `mutationBatchSize: 1`
-   - Increase gradually if needed
-   - Respect rate limits
-
-### ❌ DON'T
-
-1. **Don't Use for Low Volume**
-   - < 10 records: use separate requests
-   - Overhead doesn't justify complexity
-
-2. **Don't Make Batches Too Large**
-   - > 20 mutations per batch
-   - Risk hitting payload limits
-   - Poor error isolation
-
-3. **Don't Retry Entire Batches**
-   - Retry individual mutations
-   - Don't waste successful mutations
-
-4. **Don't Ignore Errors**
-   - Parse all alias results
-   - Log partial failures
-   - Track error patterns
-
-5. **Don't Skip Concurrency Control**
-   - Always set `mutationBatchSize`
-   - Respect rate limits
-   - Don't overwhelm server
-
----
-
-## Troubleshooting
-
-### Issue: Batch Size Too Large
-
-**Symptoms:**
-- `413 Payload Too Large` errors
-- Requests timing out
-- Server rejecting requests
-
-**Solution:**
-```typescript
-// Reduce batch size
-mutationsPerAliasBatch: 3  // Instead of 10
-```
-
-### Issue: Partial Failures Not Detected
-
-**Symptoms:**
-- Some mutations fail silently
-- Errors not logged
-- Incomplete data
-
-**Solution:**
-```typescript
-// Ensure parseAliasResponse checks all aliases
-batch.forEach((item, index) => {
-  const alias = `${mutationName}${index + 1}`;
-  const aliasData = data[alias];
-  const aliasErrors = errors.filter(e => e.path?.includes(alias));
-  
-  if (!aliasData || aliasErrors.length > 0) {
-    // Log error
-  }
-});
-```
-
-### Issue: Slow Performance
-
-**Symptoms:**
-- Batches take longer than separate requests
-- No throughput improvement
-
-**Solution:**
-```typescript
-// Increase concurrency
-mutationBatchSize: 5  // Instead of 1
-
-// Or reduce batch size
-mutationsPerAliasBatch: 3  // Instead of 10
-```
-
-### Issue: Wrong Alias Names
-
-**Symptoms:**
-- Can't find results in response
-- Alias names don't match
-
-**Solution:**
-```typescript
-// Ensure consistent naming pattern
-const alias = `${mutationName}${index + 1}`;  // Simple: createLocation1, createLocation2, etc.
-
-// Don't use custom naming patterns
-// ❌ const alias = `mut_${index}`;
-// ✅ const alias = `${mutationName}${index + 1}`;
-```
-
----
-
-## Related Documentation
-
-- [GraphQL Mutation Mapping Guide](graphql-mutation-mapping/graphql-mutation-mapping-readme.md)
-- [Mapping Format Decision Tree](mapping-format-decision-tree.md)
-- [Mapper Comparison Guide](mapping-mapper-comparison-guide.md)
-- [Implementation Plan](./mapping-graphql-alias-batching-guide.md) (see this guide)
-
----
-
-## Summary
-
-**GraphQL alias batching** reduces network overhead and improves throughput for high-volume ingestion scenarios. Use it when:
-
-- ✅ Processing 100+ records
-- ✅ Network latency is a bottleneck
-- ✅ Throughput is priority
-- ✅ Partial failures are acceptable
-
-**Configuration:**
-- `mutationBatchSize`: Concurrency control (default: 1)
-- `mutationsPerAliasBatch`: Mutations per aliased request (default: undefined = disabled)
-
-**Best Practices:**
-- Keep batch sizes reasonable (5-10 mutations)
-- Handle partial failures gracefully
-- Monitor performance and adjust as needed
-- Use concurrency control to respect rate limits
-
-The SDK provides complete alias batching support:
-- **Query Generation:** `batchMap()`, `buildAliasedMutationQuery()`
-- **Response Parsing:** `parseAliasedMutationResponse()` ✨ NEW
-- **Helper Functions:** `formatErrorSummary()`, `getFailedMutations()`, `getSuccessfulMutations()`
-
-Templates can use these SDK utilities or implement custom logic for specific requirements.
-
+# GraphQL Alias Batching Guide
+
+**Last Updated:** 2025-01-24  
+**Status:** ✅ Production Ready
+
+---
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [When to Use Alias Batching](#when-to-use-alias-batching)
+3. [How It Works](#how-it-works)
+4. [Configuration](#configuration)
+5. [Implementation Patterns](#implementation-patterns)
+6. [Response Parsing](#response-parsing)
+7. [Error Handling](#error-handling)
+8. [Performance Considerations](#performance-considerations)
+9. [Best Practices](#best-practices)
+10. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+GraphQL alias batching allows you to execute multiple mutations in a single HTTP request by using GraphQL aliases. This reduces network overhead and can improve performance for high-volume ingestion scenarios.
+
+### What Are GraphQL Aliases?
+
+GraphQL aliases let you include multiple fields (or mutations) with the same name in a single query by giving each one a unique alias:
+
+```graphql
+mutation BatchCreateLocations($input1: CreateLocationInput!, $input2: CreateLocationInput!) {
+  createLocation1: createLocation(input: $input1) { id ref name }
+  createLocation2: createLocation(input: $input2) { id ref name }
+}
+```
+
+**Benefits:**
+- ✅ **Reduced Network Overhead:** One HTTP request instead of multiple
+- ✅ **Faster Execution:** Single round-trip to the server
+- ✅ **Better Throughput:** Process more mutations per second
+- ✅ **Server-Side Efficiency:** Server can optimize batch execution
+
+**Trade-offs:**
+- ⚠️ **Complex Error Handling:** Partial failures require parsing aliased responses
+- ⚠️ **Request Size Limits:** Large batches may hit payload limits
+- ⚠️ **Server Execution Control:** Server controls execution order (not client)
+
+---
+
+## When to Use Alias Batching
+
+### ✅ Use Alias Batching When:
+
+1. **High-Volume Ingestion**
+   - Processing hundreds or thousands of records
+   - Network latency is a bottleneck
+   - Throughput is more important than latency
+
+2. **Sequential Processing is Acceptable**
+   - Records don't depend on each other
+   - Order doesn't matter
+   - You can handle partial failures gracefully
+
+3. **Rate Limiting Concerns**
+   - Want to reduce number of HTTP requests
+   - Server has strict rate limits
+   - Need to stay within quota
+
+### ❌ Don't Use Alias Batching When:
+
+1. **Low Volume (< 10 records)**
+   - Overhead doesn't justify complexity
+   - Separate requests are simpler
+
+2. **Strict Error Isolation Needed**
+   - Need to know exactly which mutation failed
+   - Can't tolerate partial failures
+   - Want to retry individual mutations
+
+3. **Dependent Mutations**
+   - Mutations depend on each other
+   - Need transaction-like behavior
+   - Order matters
+
+### Decision Matrix
+
+| Scenario | Separate Requests | Alias Batching |
+|---------|------------------|----------------|
+| < 10 records | ✅ Recommended | ❌ Overkill |
+| 10-100 records | ✅ Simple | ⚠️ Optional |
+| 100-1000 records | ⚠️ Slower | ✅ Recommended |
+| > 1000 records | ❌ Too slow | ✅ Recommended |
+| Need error isolation | ✅ Better | ⚠️ Complex |
+| Need throughput | ⚠️ Slower | ✅ Better |
+
+---
+
+## How It Works
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Client-Side Flow                         │
+└─────────────────────────────────────────────────────────────┘
+
+1. Map Items (GraphQLMutationMapper)
+   ├─ Transform each record to GraphQL input
+   └─ Store mapped inputs
+
+2. Batch Items (batchMap or manual)
+   ├─ Group items into batches (e.g., 5 per batch)
+   └─ Generate aliased query
+
+3. Execute Batches (Concurrency Control)
+   ├─ Send batch 1: mutationsPerAliasBatch=5
+   ├─ Send batch 2: mutationsPerAliasBatch=5
+   └─ Process concurrently (maxParallel=3)
+
+4. Parse Responses
+   ├─ Extract results by alias (createLocation1, createLocation2, ...)
+   ├─ Identify partial failures
+   └─ Aggregate success/failure counts
+```
+
+### SDK Methods
+
+#### 1. `GraphQLMutationMapper.batchMap()`
+
+The SDK provides a `batchMap()` method that generates aliased queries:
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+
+// Batch map multiple items
+const items = [
+  { ref: 'LOC-001', name: 'Location 1' },
+  { ref: 'LOC-002', name: 'Location 2' },
+  { ref: 'LOC-003', name: 'Location 3' },
+];
+
+const batch = await mapper.batchMap(items, { mutationsPerBatch: 3 });
+
+// Result:
+// {
+//   query: "mutation BatchCreateLocations($input1: CreateLocationInput!, ...) { createLocation1: createLocation(...) { id ref } ... }",
+//   variables: { input1: {...}, input2: {...}, input3: {...} }
+// }
+```
+
+#### 2. `buildAliasedMutationQuery()`
+
+For manual query generation:
+
+```typescript
+import { buildAliasedMutationQuery } from '@fluentcommerce/fc-connect-sdk';
+
+const query = buildAliasedMutationQuery(mappingConfig, batchSize);
+// Generates: mutation BatchCreateLocations($input1: ..., $input2: ...) { createLocation1: ... createLocation2: ... }
+```
+
+---
+
+## Configuration
+
+### Template-Level Configuration
+
+Templates use activation variables to control alias batching:
+
+```typescript
+// Concurrency control (number of concurrent alias batch requests)
+const mutationBatchSize = parseInt(
+  activation?.getVariable('mutationBatchSize') || '1',  // Default: 1 (sequential)
+  10
+);
+
+// Alias batching (number of mutations per aliased request)
+const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch') 
+  ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10) 
+  : undefined;  // Default: undefined (disabled, use separate requests)
+```
+
+### Configuration Examples
+
+#### Example 1: Default (Sequential, No Aliases)
+```typescript
+mutationBatchSize: 1                    // Sequential processing
+mutationsPerAliasBatch: undefined       // Disabled (separate requests)
+```
+**Result:** Each mutation is sent as a separate request, executed sequentially.
+
+#### Example 2: Concurrent Requests (No Aliases)
+```typescript
+mutationBatchSize: 5                    // 5 concurrent requests
+mutationsPerAliasBatch: undefined       // Disabled (separate requests)
+```
+**Result:** 5 separate HTTP requests sent concurrently.
+
+#### Example 3: Alias Batching (Single Batch)
+```typescript
+mutationBatchSize: 1                    // Sequential batch processing
+mutationsPerAliasBatch: 5               // 5 mutations per aliased request
+```
+**Result:** Groups of 5 mutations bundled into single aliased requests, processed sequentially.
+
+#### Example 4: Concurrent Alias Batching
+```typescript
+mutationBatchSize: 3                    // 3 concurrent alias batch requests
+mutationsPerAliasBatch: 5               // 5 mutations per aliased request
+```
+**Result:** Groups of 5 mutations bundled into aliased requests, with 3 such requests sent concurrently.
+
+**Visual Example:**
+```
+100 locations, mutationsPerAliasBatch=5, mutationBatchSize=3
+
+Batch 1: [Loc1-5]   ──┐
+Batch 2: [Loc6-10]  ──┼─► Sent concurrently (3 batches)
+Batch 3: [Loc11-15] ──┘
+
+Batch 4: [Loc16-20] ──┐
+Batch 5: [Loc21-25] ──┼─► Sent concurrently (3 batches)
+Batch 6: [Loc26-30] ──┘
+
+... (continues until all 100 locations processed)
+```
+
+### Mapping Config (Optional)
+
+The `aliasBatching` config in `MappingConfig` is optional metadata. Templates use runtime parameters for flexibility:
+
+```json
+{
+  "mutation": "createLocation",
+  "sourceFormat": "json",
+  "aliasBatching": {
+    "enabled": true,
+    "mutationsPerBatch": 5,
+    "maxMutationsPerBatch": 20
+  },
+  "arguments": {
+    "input": {
+      "ref": { "source": "ref" },
+      "name": { "source": "name" }
+    }
+  }
+}
+```
+
+**Note:** Templates use `mutationsPerAliasBatch` activation variable instead of this config for runtime flexibility.
+
+---
+
+## Implementation Patterns
+
+### Pattern 1: Template Helper Functions
+
+Templates include helper functions for alias batching:
+
+```typescript
+/**
+ * Execute mutations using GraphQL aliases (batched requests)
+ */
+async function executeMutationsWithAliases(
+  locations: Array<{ query: string; variables: any; input: any }>,
+  client: FluentClient,
+  mapper: GraphQLMutationMapper,
+  log: any,
+  retailerId: string,
+  maxParallel: number,          // Concurrency control
+  mutationsPerAliasBatch: number // Mutations per aliased request
+): Promise<MutationResult> {
+  // ... implementation
+}
+
+/**
+ * Build aliased batch query and variables
+ */
+function buildAliasedBatch(
+  batch: Array<{ query: string; variables: any; input: any }>,
+  mutationName: string,
+  retailerId: string
+): { query: string; variables: Record<string, any> } {
+  // ... implementation
+}
+
+/**
+ * Parse aliased GraphQL response
+ */
+function parseAliasResponse(
+  response: any,
+  batch: Array<{ query: string; variables: any; input: any }>,
+  mutationName: string
+): { executed: number; failed: number; errors: Array<{ locationRef: string; error: string }> } {
+  // ... implementation
+}
+```
+
+### Pattern 2: Using SDK batchMap()
+
+For custom implementations:
+
+```typescript
+import { GraphQLMutationMapper, FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+
+// Group items into batches
+const batchSize = 5;
+const batches: Array<typeof items> = [];
+for (let i = 0; i < items.length; i += batchSize) {
+  batches.push(items.slice(i, i + batchSize));
+}
+
+// Process batches
+for (const batch of batches) {
+  // Generate aliased query
+  const { query, variables } = await mapper.batchMap(batch, {
+    mutationsPerBatch: batch.length
+  });
+
+  // Execute
+  const response = await client.graphql({ query, variables });
+
+  // Parse response
+  const results = parseAliasResponse(response, batch, 'createLocation');
+  // ... handle results
+}
+```
+
+### Pattern 3: Dispatcher Pattern
+
+Templates use a dispatcher to choose between modes:
+
+```typescript
+async function executeMutations(
+  locations: Array<{ query: string; variables: any; input: any }>,
+  client: FluentClient,
+  mapper: GraphQLMutationMapper,
+  log: any,
+  retailerId: string,
+  batchSize: number = 1,
+  mutationsPerAliasBatch?: number
+): Promise<MutationResult> {
+  const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
+  
+  if (useAliases) {
+    return await executeMutationsWithAliases(
+      locations, client, mapper, log, retailerId,
+      batchSize, mutationsPerAliasBatch!
+    );
+  } else {
+    return await executeMutationsSeparate(
+      locations, client, mapper, log, retailerId, batchSize
+    );
+  }
+}
+```
+
+---
+
+## Response Parsing
+
+### Response Structure
+
+Aliased GraphQL responses have this structure:
+
+```json
+{
+  "data": {
+    "createLocation1": { "id": "123", "ref": "LOC-001", "name": "Location 1" },
+    "createLocation2": { "id": "124", "ref": "LOC-002", "name": "Location 2" },
+    "createLocation3": null  // ← Partial failure
+  },
+  "errors": [
+    {
+      "message": "Location with ref 'LOC-003' already exists",
+      "path": ["createLocation3"],
+      "extensions": { "code": "DUPLICATE" }
+    }
+  ]
+}
+```
+
+### SDK Response Parser ✨ NEW
+
+**The SDK now provides a built-in response parser** (available in latest SDK):
+
+```typescript
+import {
+  parseAliasedMutationResponse,
+  formatErrorSummary,
+  getFailedMutations,
+  getSuccessfulMutations,
+  type AliasedMutationResult
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Execute aliased mutation
+const response = await client.graphql({ query, variables });
+
+// Parse response
+const result = parseAliasedMutationResponse(
+  response,
+  batchSize,         // Number of mutations in the batch
+  'createLocation',  // Base mutation name
+  inputs             // Optional: original input data for error tracking
+);
+
+// Check results
+console.log(`Executed: ${result.executed}, Failed: ${result.failed}`);
+console.log(`All succeeded: ${result.allSucceeded}`);
+
+if (!result.allSucceeded) {
+  console.error(formatErrorSummary(result));
+
+  // Get failed mutations
+  const failed = getFailedMutations(result);
+  failed.forEach(mutation => {
+    console.error(`${mutation.alias}: ${mutation.error?.message}`);
+  });
+}
+
+// Get successful mutations
+const successful = getSuccessfulMutations(result);
+console.log(`Created ${successful.length} locations successfully`);
+```
+
+### Result Structure
+
+The parser returns an `AliasedMutationResult` object:
+
+```typescript
+interface AliasedMutationResult {
+  executed: number;              // Total mutations that succeeded
+  failed: number;                // Total mutations that failed
+  allSucceeded: boolean;         // Whether all mutations succeeded
+  allFailed: boolean;            // Whether all mutations failed
+  results: MutationResult[];     // Individual mutation results
+  errors: MutationError[];       // Aggregated errors
+}
+
+interface MutationResult {
+  alias: string;                 // e.g., 'createLocation1'
+  index: number;                 // 0-based index in batch
+  success: boolean;              // Whether this mutation succeeded
+  data?: any;                    // Response data (if successful)
+  error?: MutationError;         // Error details (if failed)
+}
+
+interface MutationError {
+  alias: string;                 // e.g., 'createLocation2'
+  index: number;                 // 0-based index in batch
+  inputRef?: string;             // e.g., 'LOC-002' (from input data)
+  message: string;               // Error message
+  graphqlErrors?: GraphQLError[];// Full GraphQL error details
+  input?: any;                   // Original input data
+}
+```
+
+### Features
+
+**Automatic Error Correlation:**
+- Matches GraphQL errors to specific mutations via `path` arrays
+- Extracts error messages and details
+- Provides input reference tracking
+
+**Flexible Input Tracking:**
+```typescript
+// Default: extracts 'ref' or 'id' from input
+const result = parseAliasedMutationResponse(response, 3, 'createLocation', inputs);
+
+// Custom: extract custom reference field
+const result = parseAliasedMutationResponse(response, 3, 'createLocation', inputs, {
+  extractRef: (input: any) => input.customRef
+});
+```
+
+**Helper Functions:**
+- `getFailedMutations(result)` - Filter failed mutations
+- `getSuccessfulMutations(result)` - Filter successful mutations
+- `getErrorMessage(mutation)` - Extract error message
+- `formatErrorSummary(result)` - Format for logging
+
+### Alternative Template Parsing (Optional)
+
+For templates that need custom parsing logic:
+
+```typescript
+function parseAliasResponse(
+  response: any,
+  batch: Array<{ query: string; variables: any; input: any }>,
+  mutationName: string
+): { executed: number; failed: number; errors: Array<{ locationRef: string; error: string }> } {
+  const result = { executed: 0, failed: 0, errors: [] };
+
+  const data = response.data || {};
+  const errors = response.errors || [];
+
+  // Process each alias result
+  batch.forEach((item, index) => {
+    const alias = `${mutationName}${index + 1}`;
+    const aliasData = data[alias];
+    const aliasErrors = errors.filter((e: any) =>
+      e.path && Array.isArray(e.path) && e.path.includes(alias)
+    );
+
+    if (aliasData && !aliasErrors.length) {
+      result.executed++;
+    } else {
+      result.failed++;
+      const errorMsg = aliasErrors[0]?.message || 'Mutation failed';
+      const locationRef = item.input?.ref || 'unknown';
+      result.errors.push({
+        locationRef,
+        error: errorMsg,
+      });
+    }
+  });
+
+  return result;
+}
+```
+
+**Note:** The SDK parser provides more robust error handling and type safety. Use it unless you need custom parsing logic.
+
+### Alias Naming Pattern
+
+The SDK uses a simple naming pattern: `{mutationName}{index}`
+
+- `createLocation1`, `createLocation2`, `createLocation3`, ...
+- `updateProduct1`, `updateProduct2`, `updateProduct3`, ...
+- `deleteOrder1`, `deleteOrder2`, `deleteOrder3`, ...
+
+**Not configurable** - this keeps the implementation simple and predictable.
+
+---
+
+## Error Handling
+
+### Partial Failures
+
+Aliased batches can have partial failures:
+
+```json
+{
+  "data": {
+    "createLocation1": { "id": "123", "ref": "LOC-001" },
+    "createLocation2": null,  // ← Failed
+    "createLocation3": { "id": "125", "ref": "LOC-003" }
+  },
+  "errors": [
+    {
+      "message": "Duplicate ref: LOC-002",
+      "path": ["createLocation2"]
+    }
+  ]
+}
+```
+
+**Best Practices:**
+1. ✅ Parse each alias result individually
+2. ✅ Track which mutations succeeded/failed
+3. ✅ Log partial failures for audit
+4. ✅ Continue processing remaining batches
+5. ✅ Don't retry entire batch if only one failed
+
+### Error Parsing
+
+```typescript
+// Extract errors for specific alias
+const aliasErrors = errors.filter((e: any) => 
+  e.path && Array.isArray(e.path) && e.path.includes(alias)
+);
+
+// Handle different error types
+if (aliasErrors.length > 0) {
+  const error = aliasErrors[0];
+  if (error.extensions?.code === 'DUPLICATE') {
+    // Handle duplicate
+  } else if (error.extensions?.code === 'VALIDATION_ERROR') {
+    // Handle validation error
+  } else {
+    // Handle generic error
+  }
+}
+```
+
+### Retry Strategy
+
+**Don't retry entire batch** - retry individual mutations:
+
+```typescript
+// ❌ BAD: Retry entire batch
+if (result.failed > 0) {
+  await retry(() => client.graphql({ query, variables }));
+}
+
+// ✅ GOOD: Retry individual mutations
+const failedItems = batch.filter((item, idx) => {
+  const alias = `${mutationName}${idx + 1}`;
+  return !response.data[alias];
+});
+
+for (const item of failedItems) {
+  await retry(() => executeSingleMutation(item));
+}
+```
+
+---
+
+## Performance Considerations
+
+### Network Overhead
+
+**Separate Requests:**
+- 100 mutations = 100 HTTP requests
+- 100 × network latency = total time
+
+**Alias Batching:**
+- 100 mutations ÷ 5 per batch = 20 HTTP requests
+- 20 × network latency = total time
+
+**Savings:** ~80% reduction in network overhead
+
+### Optimal Batch Size
+
+**Factors to Consider:**
+
+1. **Payload Size**
+   - GraphQL requests have size limits
+   - Larger batches = larger payloads
+   - **Recommendation:** 5-10 mutations per batch
+
+2. **Error Isolation**
+   - Larger batches = more mutations affected by one failure
+   - **Recommendation:** 5-10 mutations per batch
+
+3. **Server Processing**
+   - Server may process batches sequentially
+   - Larger batches = longer wait for first result
+   - **Recommendation:** 5-10 mutations per batch
+
+**Default:** `mutationsPerAliasBatch: 5` (optimal balance)
+
+### Concurrency vs Batch Size
+
+**Trade-off:**
+- **High concurrency + small batches:** More requests, faster per-request
+- **Low concurrency + large batches:** Fewer requests, slower per-request
+
+**Recommendation:**
+- Start with `mutationBatchSize: 1`, `mutationsPerAliasBatch: 5`
+- If throughput is low, increase `mutationBatchSize` to 3-5
+- If errors increase, reduce `mutationsPerAliasBatch` to 3
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+1. **Use Aliases for High Volume**
+   - Process 100+ records
+   - Network latency is a bottleneck
+   - Throughput is priority
+
+2. **Keep Batch Sizes Reasonable**
+   - 5-10 mutations per batch
+   - Don't exceed payload limits
+   - Balance error isolation
+
+3. **Handle Partial Failures**
+   - Parse each alias result
+   - Track individual success/failure
+   - Log errors for audit
+
+4. **Monitor Performance**
+   - Track request count reduction
+   - Measure throughput improvement
+   - Watch for error rate changes
+
+5. **Use Concurrency Control**
+   - Start with `mutationBatchSize: 1`
+   - Increase gradually if needed
+   - Respect rate limits
+
+### ❌ DON'T
+
+1. **Don't Use for Low Volume**
+   - < 10 records: use separate requests
+   - Overhead doesn't justify complexity
+
+2. **Don't Make Batches Too Large**
+   - > 20 mutations per batch
+   - Risk hitting payload limits
+   - Poor error isolation
+
+3. **Don't Retry Entire Batches**
+   - Retry individual mutations
+   - Don't waste successful mutations
+
+4. **Don't Ignore Errors**
+   - Parse all alias results
+   - Log partial failures
+   - Track error patterns
+
+5. **Don't Skip Concurrency Control**
+   - Always set `mutationBatchSize`
+   - Respect rate limits
+   - Don't overwhelm server
+
+---
+
+## Troubleshooting
+
+### Issue: Batch Size Too Large
+
+**Symptoms:**
+- `413 Payload Too Large` errors
+- Requests timing out
+- Server rejecting requests
+
+**Solution:**
+```typescript
+// Reduce batch size
+mutationsPerAliasBatch: 3  // Instead of 10
+```
+
+### Issue: Partial Failures Not Detected
+
+**Symptoms:**
+- Some mutations fail silently
+- Errors not logged
+- Incomplete data
+
+**Solution:**
+```typescript
+// Ensure parseAliasResponse checks all aliases
+batch.forEach((item, index) => {
+  const alias = `${mutationName}${index + 1}`;
+  const aliasData = data[alias];
+  const aliasErrors = errors.filter(e => e.path?.includes(alias));
+  
+  if (!aliasData || aliasErrors.length > 0) {
+    // Log error
+  }
+});
+```
+
+### Issue: Slow Performance
+
+**Symptoms:**
+- Batches take longer than separate requests
+- No throughput improvement
+
+**Solution:**
+```typescript
+// Increase concurrency
+mutationBatchSize: 5  // Instead of 1
+
+// Or reduce batch size
+mutationsPerAliasBatch: 3  // Instead of 10
+```
+
+### Issue: Wrong Alias Names
+
+**Symptoms:**
+- Can't find results in response
+- Alias names don't match
+
+**Solution:**
+```typescript
+// Ensure consistent naming pattern
+const alias = `${mutationName}${index + 1}`;  // Simple: createLocation1, createLocation2, etc.
+
+// Don't use custom naming patterns
+// ❌ const alias = `mut_${index}`;
+// ✅ const alias = `${mutationName}${index + 1}`;
+```
+
+---
+
+## Related Documentation
+
+- [GraphQL Mutation Mapping Guide](graphql-mutation-mapping/graphql-mutation-mapping-readme.md)
+- [Mapping Format Decision Tree](mapping-format-decision-tree.md)
+- [Mapper Comparison Guide](mapping-mapper-comparison-guide.md)
+- [Implementation Plan](./mapping-graphql-alias-batching-guide.md) (see this guide)
+
+---
+
+## Summary
+
+**GraphQL alias batching** reduces network overhead and improves throughput for high-volume ingestion scenarios. Use it when:
+
+- ✅ Processing 100+ records
+- ✅ Network latency is a bottleneck
+- ✅ Throughput is priority
+- ✅ Partial failures are acceptable
+
+**Configuration:**
+- `mutationBatchSize`: Concurrency control (default: 1)
+- `mutationsPerAliasBatch`: Mutations per aliased request (default: undefined = disabled)
+
+**Best Practices:**
+- Keep batch sizes reasonable (5-10 mutations)
+- Handle partial failures gracefully
+- Monitor performance and adjust as needed
+- Use concurrency control to respect rate limits
+
+The SDK provides complete alias batching support:
+- **Query Generation:** `batchMap()`, `buildAliasedMutationQuery()`
+- **Response Parsing:** `parseAliasedMutationResponse()` ✨ NEW
+- **Helper Functions:** `formatErrorSummary()`, `getFailedMutations()`, `getSuccessfulMutations()`
+
+Templates can use these SDK utilities or implement custom logic for specific requirements.
+