@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-05-transformation.md

@@ -1,494 +1,494 @@
-# Module 5: Data Transformation
-
-**Level:** Advanced
-**Estimated Time:** 25 minutes
-
-## Overview
-
-This module covers transforming extracted data using UniversalMapper, custom transformers, and advanced transformation patterns for converting Fluent data to external system formats.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Use UniversalMapper for declarative field mapping
-- ✅ Apply SDK resolvers for common transformations
-- ✅ Create custom resolvers for business logic
-- ✅ Build transformation pipelines
-- ✅ Handle complex nested structures
-- ✅ Flatten and aggregate data
-
-## UniversalMapper Basics
-
-### Simple Field Mapping
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'productRef', required: true },
-    warehouse: { source: 'locationRef', required: true },
-    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-    status: { source: 'status', resolver: 'sdk.lowercase' }
-  }
-});
-
-const result = await mapper.map(records);
-
-if (!result.success) {
-  console.error('Mapping errors:', result.errors);
-} else {
-  console.log(`Transformed ${result.data.length} records`);
-}
-```
-
-### SDK Resolvers
-
-Available built-in resolvers:
-
-| Resolver | Description | Example Input | Output |
-|----------|-------------|---------------|--------|
-| `sdk.toString` | Convert to string | 123 | "123" |
-| `sdk.parseInt` | Parse integer | "123" | 123 |
-| `sdk.parseFloat` | Parse float | "123.45" | 123.45 |
-| `sdk.number` | Convert to number | "123" | 123 |
-| `sdk.boolean` | Convert to boolean | "true" | true |
-| `sdk.uppercase` | Uppercase string | "hello" | "HELLO" |
-| `sdk.lowercase` | Lowercase string | "HELLO" | "hello" |
-| `sdk.trim` | Trim whitespace | " hello " | "hello" |
-| `sdk.formatDate` | Format ISO date | Date | "2025-01-15T10:00:00Z" |
-| `sdk.formatDateShort` | Short date | Date | "2025-01-15" |
-| `sdk.parseDate` | Parse date string | "2025-01-15" | Date |
-| `sdk.parseJson` | Parse JSON | '{"a":1}' | {a:1} |
-| `sdk.toJson` | Stringify JSON | {a:1} | '{"a":1}' |
-| `sdk.coalesce` | First non-null | [null, "a"] | "a" |
-| `sdk.identity` | Return as-is | "a" | "a" |
-
-### Nested Field Access
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'productRef' },
-    productName: { source: 'product.name' },  // Nested field
-    catalogueName: { source: 'product.catalogue.name' },  // Deep nesting
-    warehouseName: { source: 'location.name' }
-  }
-});
-```
-
-### Required vs Optional Fields
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'productRef', required: true },  // Must exist
-    quantity: { source: 'qty', required: true },
-    notes: { source: 'attributes.notes', required: false },  // Optional
-    description: { source: 'product.description' }  // Optional by default
-  }
-});
-
-const result = await mapper.map(records);
-
-// Check for errors
-if (!result.success) {
-  console.log('Missing required fields:', result.errors);
-}
-```
-
-## Custom Resolvers
-
-### Creating Custom Resolvers
-
-```typescript
-const mapper = new UniversalMapper(
-  {
-    fields: {
-      sku: { source: 'productRef' },
-      quantity: { source: 'qty', resolver: 'custom.ensurePositive' },
-      status: { source: 'status', resolver: 'custom.mapStatus' },
-      totalValue: { source: 'qty', resolver: 'custom.calculateValue' }
-    }
-  },
-  {
-    customResolvers: {
-      'custom.ensurePositive': (value) => {
-        const num = parseInt(value) || 0;
-        return Math.max(0, num);
-      },
-
-      'custom.mapStatus': (value) => {
-        const statusMap = {
-          'AVAILABLE': 'in_stock',
-          'OUT_OF_STOCK': 'out_of_stock',
-          'DISCONTINUED': 'discontinued'
-        };
-        return statusMap[value] || 'unknown';
-      },
-
-      'custom.calculateValue': (value, sourceData, helpers) => {
-        const qty = helpers.parseIntSafe(value, 0);
-        const price = helpers.parseFloatSafe(sourceData.price, 0);
-        return qty * price;
-      }
-    }
-  }
-);
-```
-
-### Resolver Helpers
-
-Available in resolver context:
-
-```typescript
-{
-  customResolvers: {
-    'custom.myResolver': (value, sourceData, helpers) => {
-      // helpers.parseIntSafe(value, defaultValue)
-      const qty = helpers.parseIntSafe(value, 0);
-
-      // helpers.parseFloatSafe(value, defaultValue)
-      const price = helpers.parseFloatSafe(sourceData.price, 0);
-
-      // helpers.parseDateSafe(value, defaultValue)
-      const date = helpers.parseDateSafe(sourceData.date, null);
-
-      // helpers.get(obj, path, defaultValue)
-      const name = helpers.get(sourceData, 'product.name', 'Unknown');
-
-      return /* transformed value */;
-    }
-  }
-}
-```
-
-## Transformation Pipelines
-
-### Chained Transformations
-
-```typescript
-class TransformationPipeline {
-  private transformers: Array<(data: any[]) => Promise<any[]>> = [];
-
-  addTransformer(transformer: (data: any[]) => Promise<any[]>): this {
-    this.transformers.push(transformer);
-    return this;
-  }
-
-  async transform(data: any[]): Promise<any[]> {
-    let result = data;
-
-    for (const transformer of this.transformers) {
-      result = await transformer(result);
-    }
-
-    return result;
-  }
-}
-
-// Usage
-const pipeline = new TransformationPipeline();
-
-pipeline
-  .addTransformer(async (data) => {
-    // Step 1: Field mapping
-    const mapper = new UniversalMapper(mappingConfig);
-    const result = await mapper.map(data);
-    return result.data;
-  })
-  .addTransformer(async (data) => {
-    // Step 2: Filter valid records
-    return data.filter(record => record.quantity > 0);
-  })
-  .addTransformer(async (data) => {
-    // Step 3: Add calculated fields
-    return data.map(record => ({
-      ...record,
-      totalValue: record.quantity * record.price,
-      lastProcessed: new Date().toISOString()
-    }));
-  });
-
-const transformed = await pipeline.transform(sourceData);
-```
-
-## Common Transformation Patterns
-
-### 1. Flattening Nested Structures
-
-```typescript
-class FlattenTransformer {
-  transform(records: any[]): any[] {
-    return records.map(record => this.flatten(record));
-  }
-
-  private flatten(obj: any, prefix = ''): any {
-    const flattened: any = {};
-
-    for (const key in obj) {
-      const value = obj[key];
-      const newKey = prefix ? `${prefix}.${key}` : key;
-
-      if (value === null || value === undefined) {
-        flattened[newKey] = null;
-      } else if (Array.isArray(value)) {
-        flattened[newKey] = JSON.stringify(value);
-        flattened[`${newKey}_count`] = value.length;
-      } else if (typeof value === 'object' && value !== null) {
-        Object.assign(flattened, this.flatten(value, newKey));
-      } else {
-        flattened[newKey] = value;
-      }
-    }
-
-    return flattened;
-  }
-}
-
-// Usage
-const transformer = new FlattenTransformer();
-const flat = transformer.transform([
-  {
-    ref: 'INV-001',
-    product: {
-      name: 'Mouse',
-      catalogue: { name: 'Electronics' }
-    }
-  }
-]);
-
-// Result:
-// {
-//   ref: 'INV-001',
-//   'product.name': 'Mouse',
-//   'product.catalogue.name': 'Electronics'
-// }
-```
-
-### 2. Aggregation
-
-```typescript
-class AggregateTransformer {
-  groupBy(records: any[], key: string): Map<string, any[]> {
-    const groups = new Map();
-
-    for (const record of records) {
-      const groupKey = record[key];
-
-      if (!groups.has(groupKey)) {
-        groups.set(groupKey, []);
-      }
-
-      groups.get(groupKey).push(record);
-    }
-
-    return groups;
-  }
-
-  sumBy(records: any[], field: string): number {
-    return records.reduce((sum, record) => {
-      return sum + (parseFloat(record[field]) || 0);
-    }, 0);
-  }
-
-  aggregateByWarehouse(inventory: any[]): any[] {
-    const groups = this.groupBy(inventory, 'locationRef');
-    const aggregated = [];
-
-    for (const [warehouse, items] of groups) {
-      aggregated.push({
-        warehouse,
-        totalQuantity: this.sumBy(items, 'quantity'),
-        skuCount: items.length,
-        totalValue: this.sumBy(items, 'totalValue')
-      });
-    }
-
-    return aggregated;
-  }
-}
-```
-
-### 3. External Format Conversion
-
-```typescript
-class ExternalFormatTransformer {
-  // To external system format
-  toExternalFormat(fluentRecords: any[]): any[] {
-    return fluentRecords.map(record => ({
-      // External field names
-      sku: record.productRef,
-      warehouse_code: record.locationRef,
-      available_qty: parseInt(record.qty) || 0,
-      item_status: this.mapStatus(record.status),
-      last_updated_timestamp: record.updatedOn,
-
-      // Metadata
-      metadata: {
-        fluent_id: record.id,
-        fluent_ref: record.ref,
-        sync_date: new Date().toISOString()
-      },
-
-      // Nested product info
-      product_info: {
-        name: record.product?.name || 'Unknown',
-        gtin: record.product?.gtin || '',
-        category: record.product?.catalogue?.name || 'Uncategorized'
-      }
-    }));
-  }
-
-  // From external back to Fluent format
-  fromExternalFormat(externalRecords: any[]): any[] {
-    return externalRecords.map(record => ({
-      productRef: record.sku,
-      locationRef: record.warehouse_code,
-      qty: record.available_qty,
-      status: this.reverseMapStatus(record.item_status)
-    }));
-  }
-
-  private mapStatus(status: string): string {
-    const map: Record<string, string> = {
-      'AVAILABLE': 'in_stock',
-      'OUT_OF_STOCK': 'out_of_stock',
-      'DISCONTINUED': 'discontinued'
-    };
-    return map[status] || 'unknown';
-  }
-
-  private reverseMapStatus(status: string): string {
-    const map: Record<string, string> = {
-      'in_stock': 'AVAILABLE',
-      'out_of_stock': 'OUT_OF_STOCK',
-      'discontinued': 'DISCONTINUED'
-    };
-    return map[status] || 'AVAILABLE';
-  }
-}
-```
-
-## Complete Workflow Example
-
-```typescript
-import {
-  createClient,
-  UniversalMapper,
-  S3DataSource
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function extractTransformExport() {
-  const client = await createClient({ config });
-  const s3 = new S3DataSource(s3Config);
-
-  // Step 1: Extract with enrichment
-  const result = await client.graphql({
-    query: `
-      query ExtractInventoryEnriched($first: Int!, $after: String) {
-        inventoryPositions(first: $first, after: $after) {
-          edges {
-            node {
-              ref
-              productRef
-              locationRef
-              qty
-              status
-              updatedOn
-              product {
-                name
-                gtin
-                catalogue { name }
-              }
-              location {
-                name
-                type
-              }
-            }
-            cursor
-          }
-          pageInfo { hasNextPage }
-        }
-      }
-    `,
-    variables: { first: 100 },
-    pagination: { maxRecords: 10000 }
-  });
-
-  const records = result.data.inventoryPositions.edges.map(e => e.node);
-
-  // Step 2: Transform with UniversalMapper
-  const mapper = new UniversalMapper(
-    {
-      fields: {
-        sku: { source: 'productRef', required: true },
-        productName: { source: 'product.name' },
-        productGtin: { source: 'product.gtin' },
-        category: { source: 'product.catalogue.name' },
-        warehouse: { source: 'locationRef', required: true },
-        warehouseName: { source: 'location.name' },
-        warehouseType: { source: 'location.type' },
-        quantity: { source: 'qty', resolver: 'custom.ensurePositive' },
-        status: { source: 'status', resolver: 'custom.mapStatus' },
-        lastUpdated: { source: 'updatedOn', resolver: 'sdk.formatDate' }
-      }
-    },
-    {
-      customResolvers: {
-        'custom.ensurePositive': (value) => Math.max(0, parseInt(value) || 0),
-        'custom.mapStatus': (value) => {
-          const map: Record<string, string> = {
-            'AVAILABLE': 'in_stock',
-            'OUT_OF_STOCK': 'out_of_stock'
-          };
-          return map[value] || 'unknown';
-        }
-      }
-    }
-  );
-
-  const mappingResult = await mapper.map(records);
-
-  if (!mappingResult.success) {
-    console.error('Mapping errors:', mappingResult.errors);
-    throw new Error('Transformation failed');
-  }
-
-  // Step 3: Export to S3
-  await s3.putObject(
-    'output-bucket',
-    `inventory_${new Date().toISOString()}.json`,
-    JSON.stringify(mappingResult.data, null, 2)
-  );
-
-  console.log(`Exported ${mappingResult.data.length} transformed records`);
-}
-```
-
-## Practice Exercise
-
-**Goal**: Transform inventory data to external warehouse system format
-
-**Requirements:**
-1. Map Fluent fields to external field names
-2. Convert status values to external codes
-3. Calculate total value (qty * price)
-4. Add metadata (sync timestamp, source system)
-5. Handle missing optional fields
-
-**Solution:** See complete example above
-
-## Key Takeaways
-
-- 🎯 Use UniversalMapper for declarative field mapping
-- 🎯 Leverage SDK resolvers for common transformations
-- 🎯 Create custom resolvers for business-specific logic
-- 🎯 Build transformation pipelines for complex workflows
-- 🎯 Flatten nested structures for BI/analytics tools
-- 🎯 Validate transformations and handle errors
-- 🎯 Document field mappings for maintainability
-
-## Next Steps
-
-Continue to [Module 6: Export Formats](./02-core-guides-extraction-06-export-formats.md) to learn how to export transformed data to various formats (JSON, CSV, XML, Parquet).
+# Module 5: Data Transformation
+
+**Level:** Advanced
+**Estimated Time:** 25 minutes
+
+## Overview
+
+This module covers transforming extracted data using UniversalMapper, custom transformers, and advanced transformation patterns for converting Fluent data to external system formats.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Use UniversalMapper for declarative field mapping
+- ✅ Apply SDK resolvers for common transformations
+- ✅ Create custom resolvers for business logic
+- ✅ Build transformation pipelines
+- ✅ Handle complex nested structures
+- ✅ Flatten and aggregate data
+
+## UniversalMapper Basics
+
+### Simple Field Mapping
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'productRef', required: true },
+    warehouse: { source: 'locationRef', required: true },
+    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+    status: { source: 'status', resolver: 'sdk.lowercase' }
+  }
+});
+
+const result = await mapper.map(records);
+
+if (!result.success) {
+  console.error('Mapping errors:', result.errors);
+} else {
+  console.log(`Transformed ${result.data.length} records`);
+}
+```
+
+### SDK Resolvers
+
+Available built-in resolvers:
+
+| Resolver | Description | Example Input | Output |
+|----------|-------------|---------------|--------|
+| `sdk.toString` | Convert to string | 123 | "123" |
+| `sdk.parseInt` | Parse integer | "123" | 123 |
+| `sdk.parseFloat` | Parse float | "123.45" | 123.45 |
+| `sdk.number` | Convert to number | "123" | 123 |
+| `sdk.boolean` | Convert to boolean | "true" | true |
+| `sdk.uppercase` | Uppercase string | "hello" | "HELLO" |
+| `sdk.lowercase` | Lowercase string | "HELLO" | "hello" |
+| `sdk.trim` | Trim whitespace | " hello " | "hello" |
+| `sdk.formatDate` | Format ISO date | Date | "2025-01-15T10:00:00Z" |
+| `sdk.formatDateShort` | Short date | Date | "2025-01-15" |
+| `sdk.parseDate` | Parse date string | "2025-01-15" | Date |
+| `sdk.parseJson` | Parse JSON | '{"a":1}' | {a:1} |
+| `sdk.toJson` | Stringify JSON | {a:1} | '{"a":1}' |
+| `sdk.coalesce` | First non-null | [null, "a"] | "a" |
+| `sdk.identity` | Return as-is | "a" | "a" |
+
+### Nested Field Access
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'productRef' },
+    productName: { source: 'product.name' },  // Nested field
+    catalogueName: { source: 'product.catalogue.name' },  // Deep nesting
+    warehouseName: { source: 'location.name' }
+  }
+});
+```
+
+### Required vs Optional Fields
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'productRef', required: true },  // Must exist
+    quantity: { source: 'qty', required: true },
+    notes: { source: 'attributes.notes', required: false },  // Optional
+    description: { source: 'product.description' }  // Optional by default
+  }
+});
+
+const result = await mapper.map(records);
+
+// Check for errors
+if (!result.success) {
+  console.log('Missing required fields:', result.errors);
+}
+```
+
+## Custom Resolvers
+
+### Creating Custom Resolvers
+
+```typescript
+const mapper = new UniversalMapper(
+  {
+    fields: {
+      sku: { source: 'productRef' },
+      quantity: { source: 'qty', resolver: 'custom.ensurePositive' },
+      status: { source: 'status', resolver: 'custom.mapStatus' },
+      totalValue: { source: 'qty', resolver: 'custom.calculateValue' }
+    }
+  },
+  {
+    customResolvers: {
+      'custom.ensurePositive': (value) => {
+        const num = parseInt(value) || 0;
+        return Math.max(0, num);
+      },
+
+      'custom.mapStatus': (value) => {
+        const statusMap = {
+          'AVAILABLE': 'in_stock',
+          'OUT_OF_STOCK': 'out_of_stock',
+          'DISCONTINUED': 'discontinued'
+        };
+        return statusMap[value] || 'unknown';
+      },
+
+      'custom.calculateValue': (value, sourceData, helpers) => {
+        const qty = helpers.parseIntSafe(value, 0);
+        const price = helpers.parseFloatSafe(sourceData.price, 0);
+        return qty * price;
+      }
+    }
+  }
+);
+```
+
+### Resolver Helpers
+
+Available in resolver context:
+
+```typescript
+{
+  customResolvers: {
+    'custom.myResolver': (value, sourceData, helpers) => {
+      // helpers.parseIntSafe(value, defaultValue)
+      const qty = helpers.parseIntSafe(value, 0);
+
+      // helpers.parseFloatSafe(value, defaultValue)
+      const price = helpers.parseFloatSafe(sourceData.price, 0);
+
+      // helpers.parseDateSafe(value, defaultValue)
+      const date = helpers.parseDateSafe(sourceData.date, null);
+
+      // helpers.get(obj, path, defaultValue)
+      const name = helpers.get(sourceData, 'product.name', 'Unknown');
+
+      return /* transformed value */;
+    }
+  }
+}
+```
+
+## Transformation Pipelines
+
+### Chained Transformations
+
+```typescript
+class TransformationPipeline {
+  private transformers: Array<(data: any[]) => Promise<any[]>> = [];
+
+  addTransformer(transformer: (data: any[]) => Promise<any[]>): this {
+    this.transformers.push(transformer);
+    return this;
+  }
+
+  async transform(data: any[]): Promise<any[]> {
+    let result = data;
+
+    for (const transformer of this.transformers) {
+      result = await transformer(result);
+    }
+
+    return result;
+  }
+}
+
+// Usage
+const pipeline = new TransformationPipeline();
+
+pipeline
+  .addTransformer(async (data) => {
+    // Step 1: Field mapping
+    const mapper = new UniversalMapper(mappingConfig);
+    const result = await mapper.map(data);
+    return result.data;
+  })
+  .addTransformer(async (data) => {
+    // Step 2: Filter valid records
+    return data.filter(record => record.quantity > 0);
+  })
+  .addTransformer(async (data) => {
+    // Step 3: Add calculated fields
+    return data.map(record => ({
+      ...record,
+      totalValue: record.quantity * record.price,
+      lastProcessed: new Date().toISOString()
+    }));
+  });
+
+const transformed = await pipeline.transform(sourceData);
+```
+
+## Common Transformation Patterns
+
+### 1. Flattening Nested Structures
+
+```typescript
+class FlattenTransformer {
+  transform(records: any[]): any[] {
+    return records.map(record => this.flatten(record));
+  }
+
+  private flatten(obj: any, prefix = ''): any {
+    const flattened: any = {};
+
+    for (const key in obj) {
+      const value = obj[key];
+      const newKey = prefix ? `${prefix}.${key}` : key;
+
+      if (value === null || value === undefined) {
+        flattened[newKey] = null;
+      } else if (Array.isArray(value)) {
+        flattened[newKey] = JSON.stringify(value);
+        flattened[`${newKey}_count`] = value.length;
+      } else if (typeof value === 'object' && value !== null) {
+        Object.assign(flattened, this.flatten(value, newKey));
+      } else {
+        flattened[newKey] = value;
+      }
+    }
+
+    return flattened;
+  }
+}
+
+// Usage
+const transformer = new FlattenTransformer();
+const flat = transformer.transform([
+  {
+    ref: 'INV-001',
+    product: {
+      name: 'Mouse',
+      catalogue: { name: 'Electronics' }
+    }
+  }
+]);
+
+// Result:
+// {
+//   ref: 'INV-001',
+//   'product.name': 'Mouse',
+//   'product.catalogue.name': 'Electronics'
+// }
+```
+
+### 2. Aggregation
+
+```typescript
+class AggregateTransformer {
+  groupBy(records: any[], key: string): Map<string, any[]> {
+    const groups = new Map();
+
+    for (const record of records) {
+      const groupKey = record[key];
+
+      if (!groups.has(groupKey)) {
+        groups.set(groupKey, []);
+      }
+
+      groups.get(groupKey).push(record);
+    }
+
+    return groups;
+  }
+
+  sumBy(records: any[], field: string): number {
+    return records.reduce((sum, record) => {
+      return sum + (parseFloat(record[field]) || 0);
+    }, 0);
+  }
+
+  aggregateByWarehouse(inventory: any[]): any[] {
+    const groups = this.groupBy(inventory, 'locationRef');
+    const aggregated = [];
+
+    for (const [warehouse, items] of groups) {
+      aggregated.push({
+        warehouse,
+        totalQuantity: this.sumBy(items, 'quantity'),
+        skuCount: items.length,
+        totalValue: this.sumBy(items, 'totalValue')
+      });
+    }
+
+    return aggregated;
+  }
+}
+```
+
+### 3. External Format Conversion
+
+```typescript
+class ExternalFormatTransformer {
+  // To external system format
+  toExternalFormat(fluentRecords: any[]): any[] {
+    return fluentRecords.map(record => ({
+      // External field names
+      sku: record.productRef,
+      warehouse_code: record.locationRef,
+      available_qty: parseInt(record.qty) || 0,
+      item_status: this.mapStatus(record.status),
+      last_updated_timestamp: record.updatedOn,
+
+      // Metadata
+      metadata: {
+        fluent_id: record.id,
+        fluent_ref: record.ref,
+        sync_date: new Date().toISOString()
+      },
+
+      // Nested product info
+      product_info: {
+        name: record.product?.name || 'Unknown',
+        gtin: record.product?.gtin || '',
+        category: record.product?.catalogue?.name || 'Uncategorized'
+      }
+    }));
+  }
+
+  // From external back to Fluent format
+  fromExternalFormat(externalRecords: any[]): any[] {
+    return externalRecords.map(record => ({
+      productRef: record.sku,
+      locationRef: record.warehouse_code,
+      qty: record.available_qty,
+      status: this.reverseMapStatus(record.item_status)
+    }));
+  }
+
+  private mapStatus(status: string): string {
+    const map: Record<string, string> = {
+      'AVAILABLE': 'in_stock',
+      'OUT_OF_STOCK': 'out_of_stock',
+      'DISCONTINUED': 'discontinued'
+    };
+    return map[status] || 'unknown';
+  }
+
+  private reverseMapStatus(status: string): string {
+    const map: Record<string, string> = {
+      'in_stock': 'AVAILABLE',
+      'out_of_stock': 'OUT_OF_STOCK',
+      'discontinued': 'DISCONTINUED'
+    };
+    return map[status] || 'AVAILABLE';
+  }
+}
+```
+
+## Complete Workflow Example
+
+```typescript
+import {
+  createClient,
+  UniversalMapper,
+  S3DataSource
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function extractTransformExport() {
+  const client = await createClient({ config });
+  const s3 = new S3DataSource(s3Config);
+
+  // Step 1: Extract with enrichment
+  const result = await client.graphql({
+    query: `
+      query ExtractInventoryEnriched($first: Int!, $after: String) {
+        inventoryPositions(first: $first, after: $after) {
+          edges {
+            node {
+              ref
+              productRef
+              locationRef
+              qty
+              status
+              updatedOn
+              product {
+                name
+                gtin
+                catalogue { name }
+              }
+              location {
+                name
+                type
+              }
+            }
+            cursor
+          }
+          pageInfo { hasNextPage }
+        }
+      }
+    `,
+    variables: { first: 100 },
+    pagination: { maxRecords: 10000 }
+  });
+
+  const records = result.data.inventoryPositions.edges.map(e => e.node);
+
+  // Step 2: Transform with UniversalMapper
+  const mapper = new UniversalMapper(
+    {
+      fields: {
+        sku: { source: 'productRef', required: true },
+        productName: { source: 'product.name' },
+        productGtin: { source: 'product.gtin' },
+        category: { source: 'product.catalogue.name' },
+        warehouse: { source: 'locationRef', required: true },
+        warehouseName: { source: 'location.name' },
+        warehouseType: { source: 'location.type' },
+        quantity: { source: 'qty', resolver: 'custom.ensurePositive' },
+        status: { source: 'status', resolver: 'custom.mapStatus' },
+        lastUpdated: { source: 'updatedOn', resolver: 'sdk.formatDate' }
+      }
+    },
+    {
+      customResolvers: {
+        'custom.ensurePositive': (value) => Math.max(0, parseInt(value) || 0),
+        'custom.mapStatus': (value) => {
+          const map: Record<string, string> = {
+            'AVAILABLE': 'in_stock',
+            'OUT_OF_STOCK': 'out_of_stock'
+          };
+          return map[value] || 'unknown';
+        }
+      }
+    }
+  );
+
+  const mappingResult = await mapper.map(records);
+
+  if (!mappingResult.success) {
+    console.error('Mapping errors:', mappingResult.errors);
+    throw new Error('Transformation failed');
+  }
+
+  // Step 3: Export to S3
+  await s3.putObject(
+    'output-bucket',
+    `inventory_${new Date().toISOString()}.json`,
+    JSON.stringify(mappingResult.data, null, 2)
+  );
+
+  console.log(`Exported ${mappingResult.data.length} transformed records`);
+}
+```
+
+## Practice Exercise
+
+**Goal**: Transform inventory data to external warehouse system format
+
+**Requirements:**
+1. Map Fluent fields to external field names
+2. Convert status values to external codes
+3. Calculate total value (qty * price)
+4. Add metadata (sync timestamp, source system)
+5. Handle missing optional fields
+
+**Solution:** See complete example above
+
+## Key Takeaways
+
+- 🎯 Use UniversalMapper for declarative field mapping
+- 🎯 Leverage SDK resolvers for common transformations
+- 🎯 Create custom resolvers for business-specific logic
+- 🎯 Build transformation pipelines for complex workflows
+- 🎯 Flatten nested structures for BI/analytics tools
+- 🎯 Validate transformations and handle errors
+- 🎯 Document field mappings for maintainability
+
+## Next Steps
+
+Continue to [Module 6: Export Formats](./02-core-guides-extraction-06-export-formats.md) to learn how to export transformed data to various formats (JSON, CSV, XML, Parquet).