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

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (475) hide show

package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md CHANGED Viewed

@@ -1,2619 +1,2619 @@
----
-template_id: tpl-ingest-s3-csv-to-price-graphql
-canonical_filename: template-ingestion-s3-csv-price-graphql.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: s3-csv
-destination: fluent-graphql
-entity: price
-format: csv
-logging: versori
-status: stable
-features:
-  - graphql-mutation-mapper
-  - memory-management
-  - enhanced-logging
-  - attribute-transformation
-compliance: gold-standard
----
-# Template: Ingestion - S3 CSV to Price GraphQL
-n**Template Version:** 2.0.0
-**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
-**Last Updated:** 2025-01-24
-**🆕 Version 2.0.0 Enhancements:**
-- ✅ **GraphQL Mutation Mapper** - Direct field mapping to mutation variables
-- ✅ **Memory Management** - Clear large arrays after processing batches
-- ✅ **Enhanced Logging** - Track mutation execution with emoji indicators
-- ✅ **Attribute Transformation** - Handle complex nested data structures
-## STEP 1: What This Template Does
-This template provides a **scheduled Versori workflow** that:
-1. **Discovers CSV files** from S3 bucket with price data
-2. **Parses CSV** using `CSVParserService` with validation
-3. **Validates products exist** in Fluent Commerce before updating prices
-4. **Maps fields** using `GraphQLMutationMapper` with custom price validation resolvers
-5. **Updates prices** via direct GraphQL mutations (`updateProduct`)
-6. **Tracks price changes** for audit trail
-7. **Archives processed files** to prevent duplicates
-8. **Uses JobTracker** for job lifecycle management
-**Key Features:**
-- ✅ Direct GraphQL mutations (NOT Batch API)
-- ✅ Product existence validation before price updates
-- ✅ Price range validation (min/max checks)
-- ✅ Multi-tier pricing support (DEFAULT, SALE, CLEARANCE, BULK)
-- ✅ Configurable concurrency control (sequential or parallel)
-- ✅ Optional GraphQL alias batching for high-volume scenarios
-- ✅ Price change tracking and reporting
-- ✅ Versori KV state management (duplicate prevention)
-- ✅ File archival with error handling
-**Use Cases:**
-- Daily product price synchronization
-- Promotional price updates
-- Multi-currency pricing management
-- Quantity-based pricing tiers
-## STEP 2: Understanding This Template (AI Agent Guide)
-**🎯 Template Purpose:** Scheduled price synchronization from S3 CSV files to Fluent Commerce using direct GraphQL mutations.
-### Architecture Pattern
-```
-S3 CSV Files → CSVParserService → GraphQLMutationMapper → Product Validation → GraphQL Mutations → Archive
-   ↓       ↓          ↓         ↓          ↓       ↓
-File Discovery  Parsing     Field Mapping   Existence Check   updateProduct    Processed/
-Price Data   Validation    Price Validation  Active Status    Concurrency Ctrl   Error Dirs
-```
-### SDK Services Used
-| Service | Purpose | Key Methods |
-|---------|---------|-------------|
-| `createClient(ctx)` | Fluent API client | `client.graphql()` |
-| `S3DataSource` | S3 operations | `listFiles()`, `downloadFile()`, `moveFile()` |
-| `CSVParserService` | CSV parsing | `parse()` |
-| `GraphQLMutationMapper` | Field transformation | `map()` with custom resolvers |
-| `VersoriKVAdapter` | State management | `get()`, `set()`, `list()` |
-| `JobTracker` | Job lifecycle | `createJob()`, `updateJob()`, `markCompleted()`, `markFailed()`, `getJob()` |
-### Price Entity Structure
-**Fluent Commerce Price Schema:**
-```typescript
-{
- productRef: string;   // SKU reference (required)
- type: string;      // DEFAULT, SALE, CLEARANCE, BULK (required)
- value: number;      // Price amount (required, validated)
- currency: string;    // ISO 4217 code (USD, EUR, GBP)
- effectiveFrom?: string; // ISO 8601 date
- effectiveTo?: string;  // ISO 8601 date
- minQuantity?: number;  // Min qty for tier pricing
- maxQuantity?: number;  // Max qty for tier pricing
-}
-```
-### GraphQL Mutation Pattern
-**Mutation Used:** `updateProduct` (NOT Batch API)
-```graphql
-mutation UpdateProductPrice($input: UpdateProductInput!) {
- updateProduct(input: $input) {
-  id
-  ref
-  prices {
-   type
-   value
-   currency
-   effectiveFrom
-   effectiveTo
-   minQuantity
-   maxQuantity
-  }
- }
-}
-```
-**Why Direct Mutations?**
-- ✅ Immediate price updates (no batch processing delay)
-- ✅ Product validation before update
-- ✅ Price change tracking
-- ✅ Suitable for low-volume price updates (<1000/day)
-**NO BPP (Batch Pre-Processing):** Direct GraphQL mutations bypass batch workflows entirely.
-### Custom Resolvers
-**Three price-specific resolvers:**
-1. **`custom.validatePriceRange`** - Ensures price within min/max bounds
-2. **`custom.normalizePriceType`** - Validates price tier types
-3. **`custom.normalizeQuantity`** - Validates quantity ranges for BULK pricing
-### Product Validation Pattern
-**Critical Step:** Validate product exists and is ACTIVE before price update:
-```typescript
-async function validateProductExists(client, productRef, retailerId, log) {
- const query = `
-  query GetProduct($ref: String!, $retailerId: ID!) {
-   products(first: 1, ref: [$ref], retailerId: $retailerId) {
-    edges {
-     node { id ref status }
-    }
-   }
-  }
- `;
- const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
- const product = result?.data?.products?.edges?.[0]?.node;
- return product && product.status === 'ACTIVE';
-}
-```
-**Why?** Prevents GraphQL errors for non-existent products.
-### Concurrency Control & Performance
-**Mutation execution** supports two performance modes:
-**Mode 1: Concurrency Control (default)**
-```typescript
-// Configuration: Control concurrent mutations
-const mutationBatchSize = parseInt(
- activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
- 10
-);
-// Execute with bounded concurrency
-await executeMutations(
- client,
- mapper,
- priceRecords,
- retailerId,
- validateProducts,
- mutationBatchSize, // 1=sequential, 3-10=parallel
- undefined,     // No alias batching
- log
-);
-```
-**Mode 2: GraphQL Alias Batching (optional, high-volume)**
-```typescript
-// Configuration: Group mutations into aliased requests
-const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
- ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
- : undefined; // Default: undefined (disabled)
-// Execute with alias batching (reduces network overhead by ~80%)
-await executeMutations(
- client,
- mapper,
- priceRecords,
- retailerId,
- validateProducts,
- mutationBatchSize,      // Concurrency control
- mutationsPerAliasBatch,   // Alias batching (e.g., 5)
- log
-);
-```
-**Activation Variables:**
-- `mutationBatchSize=1` - Default: sequential (safe)
-- `mutationBatchSize=3-5` - Balanced throughput
-- `mutationBatchSize=10` - High-volume (100+ locations)
-- `mutationsPerAliasBatch` - Optional: Group mutations (e.g., 5 per request)
-### State Management
-**VersoriKVAdapter** prevents duplicate file processing:
-```typescript
-const stateKey = ['processed-files', 's3-price-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) {
- log.info('Skipping already processed file', { fileName });
- continue;
-}
-// After success:
-await kv.set(stateKey, { successful, failed, processedAt: new Date().toISOString() });
-```
-### JobTracker Integration
-**Job lifecycle tracking:**
-```typescript
-const tracker = new JobTracker(openKv(':project:'), log);
-await tracker.startJob(jobId, { mode: 'scheduled' });
-try {
- const result = await runPriceCsvWorkflow(ctx, jobId, tracker);
- await tracker.completeJob(jobId, { result });
-} catch (e) {
- await tracker.failJob(jobId, { error: e.message });
-}
-```
-### Price Change Tracking
-**Audit trail for price updates:**
-```typescript
-const currentPrice = await getCurrentPrice(client, productRef, priceType, currency, retailerId);
-// ... after update ...
-if (currentPrice !== undefined && currentPrice !== priceData.value) {
- results.priceChanges.push({
-  sku: priceData.productRef,
-  type: priceData.type,
-  oldPrice: currentPrice,
-  newPrice: priceData.value,
- });
-}
-// Log changes at end:
-log.info('Price changes detected', { count: results.priceChanges.length, changes });
-```
-### Schema Validation (CLI Commands)
-**Before deployment, validate GraphQL schema:**
-```bash
-# 1. Introspect Fluent schema
-fc-connect introspect-schema \
- --url https://api.fluentcommerce.com/graphql \
- --client-id CLIENT_ID \
- --client-secret CLIENT_SECRET \
- --output fluent-schema.json
-# 2. Create mutation file
-cat > price-mutation.graphql << 'EOF'
-mutation UpdateProductPrice($input: UpdateProductInput!) {
- updateProduct(input: $input) {
-  id
-  ref
-  prices { type value currency }
- }
-}
-EOF
-# 3. Generate mapping from mutation
-fc-connect generate-mutation-mapping \
- --file price-mutation.graphql \
- --output price-mapping.json
-# 4. Validate mapping against schema
-fc-connect validate-schema \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-# 5. Analyze field coverage
-fc-connect analyze-coverage \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-```
-### Configuration File Structure
-**Mapping Config:** `config/price-mapping.json`
-**✅ PRODUCTION STANDARD:** External JSON file with GraphQLMutationMapper structure
-```json
-{
- "mutation": "updateProduct",
- "sourceFormat": "csv",
- "version": "1.0.0",
- "arguments": {
-  "input": {
-   "ref": {
-    "source": "sku",
-    "required": true,
-    "resolver": "trim"
-   },
-   "prices": {
-    "type": {
-     "source": "priceType",
-     "required": true,
-     "resolver": "normalizePriceType"
-    },
-    "value": {
-     "source": "amount",
-     "required": true,
-     "resolver": "validatePriceRange"
-    },
-    "currency": {
-     "source": "currency",
-     "required": true,
-     "resolver": "toUpperCase"
-    },
-    "effectiveFrom": {
-     "source": "effectiveDate",
-     "resolver": "formatDate"
-    },
-    "effectiveTo": {
-     "source": "expiryDate",
-     "resolver": "formatDate"
-    },
-    "minQuantity": {
-     "source": "minQuantity",
-     "resolver": "normalizeQuantity"
-    },
-    "maxQuantity": {
-     "source": "maxQuantity",
-     "resolver": "normalizeQuantity"
-    }
-   }
-  }
- }
-}
-```
-**Key Differences from UniversalMapper:**
-- ✅ `mutation` property (not `mutationName`)
-- ✅ `arguments.input` structure (matches GraphQL schema)
-- ✅ Nested `prices` object (not flat productRef/type/value)
-- ✅ Resolver names without `sdk.` or `custom.` prefix (`trim`, `toUpperCase`, `formatDate`)
-- ✅ Used with `GraphQLMutationMapper.map()` method (not `UniversalMapper.map()`)
-### Activation Variables Required
-**Minimum Required:**
-- `s3BucketName` - S3 bucket with price CSV files
-- `awsAccessKeyId` - AWS credentials
-- `awsSecretAccessKey` - AWS credentials
-**Optional (with defaults):**
-- `awsRegion=us-east-1`
-- `s3Prefix=prices/`
-- `archivePrefix=processed/`
-- `errorPrefix=errors/`
-- `logPrefix=logs/` - Where to write mutation logs
-- `maxFilesToProcess=10`
-- `mutationBatchSize=1` - Number of concurrent mutations (1=sequential, 3-10=parallel)
-- `mutationsPerAliasBatch` - Optional: Number of mutations per aliased request (default: undefined = disabled)
-- `minPrice=0.01`
-- `maxPrice=999999.99`
-- `validateProducts=true`
-- `validateConnection=true` - Validate S3 connection at startup
-- `enableFileTracking=true` - Enable file tracking via VersoriFileTracker
-- `fluentRetailerId` - Optional: Only if mutation schema requires retailerId in input (most Price mutations don't need it)
-### Error Handling Patterns
-**Three-level error handling:**
-1. **Mapping errors** - Invalid price data (validation failures)
-2. **GraphQL errors** - Mutation failures (product not found, invalid fields)
-3. **File processing errors** - S3 access issues, CSV parsing failures
-**Error state tracking with exponential backoff:**
-```typescript
-const errorKey = ['error-state', fileName];
-const attempts = (prev?.attemptCount || 0) + 1;
-const backoffMinutes = Math.min(Math.pow(2, attempts) * 5, 24 * 60);
-const nextRetryAt = new Date(Date.now() + backoffMinutes * 60000).toISOString();
-```
-### Common Pitfalls
-**❌ WRONG Patterns:**
-- Using Batch API for price updates (overhead, delay)
-- Using `UniversalMapper` instead of `GraphQLMutationMapper`
-- Calling `client.setRetailerId()` for GraphQL mutations (only needed for Job/Event API)
-- Skipping product validation (causes GraphQL errors)
-- No concurrency control (API throttling)
-- Hardcoded price validation rules (not configurable)
-- Missing price change tracking (no audit trail)
-**✅ CORRECT Patterns:**
-- Direct GraphQL mutations for immediate updates
-- `GraphQLMutationMapper` with nested mapping structure
-- NO `setRetailerId()` call (pass in mutation input if schema requires it)
-- Product existence validation before updates
-- Configurable concurrency control (mutationBatchSize)
-- Optional alias batching for high-volume scenarios
-- Custom resolvers for price validation
-- Price change tracking for audit
-- VersoriKVAdapter for state management
-- JobTracker for job lifecycle
-### Testing Checklist
-**Before deployment:**
-- [ ] S3 credentials validated (IAM permissions: ListBucket, GetObject, PutObject, DeleteObject)
-- [ ] GraphQL schema validated using CLI tools
-- [ ] Mapping configuration uses GraphQLMutationMapper structure (nested objects, not flat fields)
-- [ ] Mapping configuration tested with sample CSV
-- [ ] Product validation working (queries products endpoint)
-- [ ] Price validation rules configured (min/max bounds)
-- [ ] Concurrency control configured (mutationBatchSize)
-- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
-- [ ] NO setRetailerId() call present (only for Job/Event API)
-- [ ] File duplicate prevention working (KV state)
-- [ ] Price change tracking verified (logs price changes)
-- [ ] Error handling tested (malformed CSV, invalid products)
-- [ ] File archival working (processed/ and errors/ directories)
-### Related Documentation
-- **Core Guides:** `docs/02-CORE-GUIDES/ingestion/modules/`
-- **Universal Mapping:** `docs/02-CORE-GUIDES/mapping/modules/`
-- **CLI Tools:** `fc-connect-sdk/bin/readme.md`
-- **State Management:** `docs/03-PATTERN-GUIDES/file-operations/`
-- **Error Handling:** `docs/03-PATTERN-GUIDES/error-handling/`
-**FC Connect SDK Use Case Guide**
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-**Context**: Scheduled Versori workflow that reads product price CSV files from S3 and creates/updates Fluent Commerce product prices via GraphQL mutations
-**Complexity**: Medium-High
-**Runtime**: Versori Platform (Scheduled)
-**Estimated Lines**: ~700 lines
-## What You'll Build
-- Versori scheduled workflow (cron trigger)
-- S3 file listing and download with retry logic
-- CSV parsing with validation
-- UniversalMapper for price field transformations
-- Product existence validation before price updates
-- GraphQL mutations for price upserts with rate limiting
-- Versori KV state management (duplicate prevention)
-- Price change tracking and reporting
-- File archival after processing
-## Versori Workflows Structure
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-**Trigger Types:**
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`workflow()`** → Durable workflows (advanced, rarely used)
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from schedule/webhook)
-- **`fn()`** → Internal processing (chained from schedule/webhook)
-### Recommended Project Structure
-```
-s3-csv-price-graphql/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-price-sync.ts       # Scheduled: Daily price sync
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-price-sync.ts       # Webhook: Manual trigger
-    │       └── job-status-check.ts       # Webhook: Status query
-    │
-    ├── services/
-    │   └── price-sync.service.ts         # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── price-mapping.json            # GraphQL mapping config
-```
----
-## Workflow Files
-### 1. Scheduled Workflows (`src/workflows/scheduled/`)
-All time-based triggers that run automatically on cron schedules.
-#### `src/workflows/scheduled/daily-price-sync.ts`
-**Purpose**: Automatic daily price sync
-**Trigger**: Cron schedule (`0 2 * * *`)
-**Exposed as Endpoint**: ❌ NO - Runs automatically
-```typescript
-import { schedule, http } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { executePriceSync } from '../../services/price-sync.service';
-/**
- * Scheduled Workflow: Daily Price Sync
- *
- * Runs automatically daily at 2 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Uses shared service: price-sync.service.ts
- */
-export const dailyPriceSync = schedule(
-  'price-sync-scheduled',
-  '0 2 * * *' // Daily at 2 AM UTC
-).then(
-  http('run-price-sync', { connection: 'fluent_commerce' }, async (ctx: any) => {
-    const { log, openKv } = ctx;
-    const jobId = `price-sync-${Date.now()}`;
-    const executionStartTime = Date.now();
-    const tracker = new JobTracker(openKv(':project:'), log);
-    log.info('🔄 [WORKFLOW] Starting price sync', { jobId });
-    await tracker.createJob(jobId, {
-      triggeredBy: 'schedule',
-      stage: 'initialization',
-      startTime: executionStartTime,
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-    try {
-      const result = await executePriceSync(ctx, jobId, tracker);
-      if (result.success) {
-        await tracker.markCompleted(jobId, result);
-        log.info('✅ [WORKFLOW] Price sync completed', {
-          jobId,
-          filesProcessed: result.filesProcessed,
-          duration: result.duration,
-        });
-      } else {
-        await tracker.markFailed(jobId, result.error || 'Unknown error');
-        log.error('❌ [WORKFLOW] Price sync failed', { jobId, error: result.error });
-      }
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      const errorMessage = e instanceof Error ? e.message : String(e);
-      await tracker.markFailed(jobId, errorMessage);
-      log.error('❌ [WORKFLOW] Price sync failed with exception', {
-        jobId,
-        error: errorMessage,
-        stack: e instanceof Error ? e.stack : undefined,
-      });
-      return { success: false, jobId, error: errorMessage };
-    }
-  })
-);
-```
----
-### 2. Webhook Workflows (`src/workflows/webhook/`)
-All HTTP-based triggers that create webhook endpoints.
-#### `src/workflows/webhook/adhoc-price-sync.ts`
-**Purpose**: Manual price sync trigger (on-demand)
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/price-sync-adhoc`
-**Use Cases**: Testing, priority processing, ad-hoc runs
-```typescript
-import { webhook, http } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { executePriceSync } from '../../services/price-sync.service';
-/**
- * Webhook: Manual Price Sync Trigger
- *
- * Endpoint: POST https://{workspace}.versori.run/price-sync-adhoc
- * Request body (optional): { filePattern: "urgent_*.csv", maxFiles: 5 }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: price-sync.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const adhocPriceSync = webhook('price-sync-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'price-sync-adhoc', // Versori validates API key
-}).then(
-  http('run-price-sync-adhoc', { connection: 'fluent_commerce' }, async (ctx: any) => {
-    const { log, openKv, data } = ctx;
-    const jobId = `price-sync-adhoc-${Date.now()}`;
-    const executionStartTime = Date.now();
-    const tracker = new JobTracker(openKv(':project:'), log);
-    log.info('🔄 [WEBHOOK] Starting adhoc price sync', { jobId });
-    await tracker.createJob(jobId, {
-      triggeredBy: 'manual',
-      stage: 'initialization',
-      startTime: executionStartTime,
-      options: data // Optional: filePattern, maxFiles, etc.
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-    try {
-      const result = await executePriceSync(ctx, jobId, tracker);
-      if (result.success) {
-        await tracker.markCompleted(jobId, result);
-        log.info('✅ [WEBHOOK] Adhoc price sync completed', {
-          jobId,
-          filesProcessed: result.filesProcessed,
-          duration: result.duration,
-        });
-      } else {
-        await tracker.markFailed(jobId, result.error || 'Unknown error');
-        log.error('❌ [WEBHOOK] Adhoc price sync failed', { jobId, error: result.error });
-      }
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      const errorMessage = e instanceof Error ? e.message : String(e);
-      await tracker.markFailed(jobId, errorMessage);
-      log.error('❌ [WEBHOOK] Adhoc price sync failed with exception', {
-        jobId,
-        error: errorMessage,
-        stack: e instanceof Error ? e.stack : undefined,
-      });
-      return { success: false, jobId, error: errorMessage };
-    }
-  })
-);
-```
----
-#### `src/workflows/webhook/job-status-check.ts`
-**Purpose**: Query job status
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/price-sync-job-status`
-**Request body**: `{ "jobId": "price-sync-1234567890" }`
-```typescript
-import { webhook, fn } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-/**
- * Webhook: Job Status Check
- *
- * Endpoint: POST https://{workspace}.versori.run/price-sync-job-status
- * Request body: { "jobId": "price-sync-1234567890" }
- *
- * Pattern: webhook().then(fn()) - no external API needed, only KV storage
- * Lightweight: Only queries KV store, no Fluent API calls
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const priceSyncJobStatus = webhook('price-sync-job-status', {
-  response: { mode: 'sync' },
-  connection: 'price-sync-job-status',
-}).then(
-  fn('status', async (ctx: any) => {
-    const { data, log, openKv } = ctx;
-    const jobId = data?.jobId as string;
-    log.info('🔍 [STATUS] Checking job status', { jobId });
-    if (!jobId) {
-      log.warn('❌ [STATUS] Missing jobId in request');
-      return { success: false, error: 'jobId required' };
-    }
-    const tracker = new JobTracker(openKv(':project:'), log);
-    const status = await tracker.getJob(jobId);
-    if (status) {
-      log.info('✅ [STATUS] Job found', { jobId, status: status.status });
-      return { success: true, jobId, ...status };
-    } else {
-      log.warn('❌ [STATUS] Job not found', { jobId });
-      return { success: false, error: 'Job not found', jobId };
-    }
-  })
-);
-```
----
-### 3. Entry Point (`index.ts`)
-**Purpose**: Register all workflows with Versori platform
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/scheduled/ → Time-based triggers (cron)
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- */
-// Import scheduled workflows
-import { dailyPriceSync } from './workflows/scheduled/daily-price-sync';
-// Import webhook workflows
-import { adhocPriceSync } from './workflows/webhook/adhoc-price-sync';
-import { priceSyncJobStatus } from './workflows/webhook/job-status-check';
-// Register all workflows
-export {
-  // Scheduled (time-based triggers)
-  dailyPriceSync,
-  // Webhooks (HTTP-based triggers)
-  adhocPriceSync,
-  priceSyncJobStatus,
-};
-```
-**What Gets Exposed:**
-- ✅ `adhocPriceSync` → `https://{workspace}.versori.run/price-sync-adhoc`
-- ✅ `priceSyncJobStatus` → `https://{workspace}.versori.run/price-sync-job-status`
-- ❌ `dailyPriceSync` → NOT exposed (runs automatically on cron)
----
-## SDK Methods Used
-**Core Services:**
-- `createClient(ctx)` - Create Fluent client (auto-detects Versori context)
-- `S3DataSource(config, log)` - S3 operations (list, download, upload, move)
-- `CSVParserService()` - CSV parsing with validation
-- `GraphQLMutationMapper(mappingConfig, log, { fluentClient: client })` - Field mapping with schema validation
-- `VersoriKVAdapter(openKv(':project:'))` - KV state management for duplicate prevention
-**Key Methods:**
-- `s3.listFiles({ prefix, maxKeys })` - List S3 files
-- `s3.downloadFile(path, options)` - Download file content
-- `s3.uploadFile(path, content)` - Upload file (accepts string or Buffer)
-- `s3.moveFile(source, dest)` - Archive or move file
-- `parser.parse(content, options)` - Parse CSV to records
-- `mapper.map(record)` - Transform single record
-- `client.graphql({ query, variables })` - Execute GraphQL mutations/queries
-- `kv.get(key)` / `kv.set(key, value)` - State management
-**Critical Imports:**
-- `Buffer` - **Required for Versori/Deno runtime** (S3 upload operations)
- ```typescript
- import { Buffer } from 'node:buffer';
- ```
- **Why:** Deno runtime (used by Versori) does not have `Buffer` as a global. However, `uploadFile()` accepts string or Buffer, so you can use strings directly without Buffer conversion.
-**Service Functions (User-Defined):**
-- `processFile()` - S3 download + CSV parsing + field mapping
-- `executeMutations()` - GraphQL price updates with validation + rate limiting
-- `writeMutationLog()` - Write execution log to S3 (uses Buffer)
-## Sample CSV Input Data
-**File**: `product-prices-20250122-001.csv`
-```csv
-sku,priceType,amount,currency,effectiveDate,expiryDate,minQuantity,maxQuantity
-PROD-001,DEFAULT,29.99,USD,2025-01-22T00:00:00Z,,1,
-PROD-002,SALE,19.99,USD,2025-01-22T00:00:00Z,2025-02-15T23:59:59Z,1,
-PROD-003,CLEARANCE,9.99,USD,2025-01-22T00:00:00Z,2025-01-31T23:59:59Z,1,
-PROD-004,DEFAULT,149.99,USD,2025-01-22T00:00:00Z,,1,
-PROD-004,BULK,129.99,USD,2025-01-22T00:00:00Z,,10,99
-PROD-004,BULK,119.99,USD,2025-01-22T00:00:00Z,,100,
-```
-**Note**: Products can have multiple price tiers. Same SKU with different `priceType` or quantity ranges = multiple rows.
-**Field Mapping**:
-- `sku` → Product reference (required) - must exist in Fluent
-- `priceType` → Price tier (DEFAULT, SALE, CLEARANCE, BULK, etc.) (required)
-- `amount` → Price value (required, must be > 0)
-- `currency` → Currency code (USD, EUR, GBP, etc.) (required)
-- `effectiveDate` → When price becomes active (ISO 8601 format)
-- `expiryDate` → When price expires (optional, ISO 8601 format)
-- `minQuantity` → Minimum quantity for this price tier (optional, default: 1)
-- `maxQuantity` → Maximum quantity for this price tier (optional)
-**Price Tier Logic**:
-- **DEFAULT**: Standard retail price (most products)
-- **SALE**: Temporary promotional price
-- **CLEARANCE**: Final markdown price
-- **BULK**: Quantity-based pricing (requires minQuantity/maxQuantity)
-## Project Setup
-```bash
-mkdir versori-s3-csv-price-sync && cd $_
-npm init -y
-npm install @fluentcommerce/fc-connect-sdk@latest @versori/run
-mkdir -p src
-```
-### Package Configuration (package.json)
-```json
-{
- "name": "versori-s3-csv-price-sync",
- "version": "1.0.0",
- "description": "Versori workflow: S3 CSV price sync to Fluent GraphQL",
- "versori": {
-  "workflows": "./src/index.ts"
- },
- "type": "module",
- "scripts": {
-  "deploy": "versori deploy",
-  "logs": "versori logs"
- },
- "dependencies": {
-  "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-  "@versori/run": "latest"
- },
- "devDependencies": {
-  "typescript": "^5.0.0",
-  "@types/node": "^20.0.0"
- }
-}
-```
-### Activation Variables (Versori)
-```bash
-# Required Variables
-s3BucketName=my-price-bucket
-awsAccessKeyId=AKIAXXXXXXXXXXXX
-awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-retailerId=your-retailer-id
-# Optional Variables (with defaults shown)
-awsRegion=us-east-1
-s3Prefix=prices/
-archivePrefix=processed/
-errorPrefix=errors/
-logPrefix=logs/       # Where to write mutation logs
-maxFilesToProcess=10
-filePattern=.csv
-enableArchival=true
-mutationRateLimit=10
-# Price Validation Rules
-minPrice=0.01       # Minimum allowed price
-maxPrice=999999.99     # Maximum allowed price
-validateProducts=true   # Validate products exist before updating prices
-```
-## Complete Workflow (src/index.ts)
-```typescript
-import { schedule, webhook, http, fn } from '@versori/run';
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
-import {
- createClient,
- S3DataSource,
- CSVParserService,
- GraphQLMutationMapper,
- VersoriFileTracker,
- JobTracker,
-} from '@fluentcommerce/fc-connect-sdk';
-// ============================================================================
-// Type Definitions
-// ============================================================================
-interface FileProcessingResult {
- fileName: string;
- successful: number;
- failed: number;
- validationFailed: number;
- priceChanges: Array<{
-  sku: string;
-  type: string;
-  oldPrice?: number;
-  newPrice: number;
- }>;
- errors: string[];
-}
-interface MutationResult {
- successful: number;
- failed: number;
- priceChanges: Array<{
-  sku: string;
-  type: string;
-  oldPrice?: number;
-  newPrice: number;
- }>;
-}
-interface MappedPriceData {
- productRef: string;
- type: string;
- value: number;
- currency: string;
- effectiveFrom?: string;
- effectiveTo?: string;
- minQuantity?: number;
- maxQuantity?: number;
-}
-// ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * Retry utility with exponential backoff
- * (User-defined - not part of SDK public API)
- */
-async function retryWithBackoff<T>(
- operation: () => Promise<T>,
- maxRetries = 3,
- baseDelayMs = 1000
-): Promise<T> {
- let lastError: any;
- for (let attempt = 0; attempt < maxRetries; attempt++) {
-  try {
-   return await operation();
-  } catch (error) {
-   lastError = error;
-   if (attempt < maxRetries - 1) {
-    const delay = baseDelayMs * Math.pow(2, attempt) + Math.floor(Math.random() * 200);
-    await new Promise(resolve => setTimeout(resolve, delay));
-   }
-  }
- }
- throw lastError;
-}
-/**
- * Validate product exists in Fluent Commerce
- */
-async function validateProductExists(
- client: any,
- productRef: string,
- retailerId: string,
- log: any
-): Promise<boolean> {
- const query = `
-  query GetProduct($ref: String!, $retailerId: ID!) {
-   products(first: 1, ref: [$ref], retailerId: $retailerId) {
-    edges {
-     node {
-      id
-      ref
-      status
-     }
-    }
-   }
-  }
- `;
- try {
-  const result = await client.graphql({
-   query,
-   variables: { ref: productRef, retailerId },
-  });
-  const product = result?.data?.products?.edges?.[0]?.node;
-  if (!product) {
-   log.warn(`Product not found: ${productRef}`);
-   return false;
-  }
-  if (product.status !== 'ACTIVE') {
-   log.warn(`Product not active: ${productRef} (status: ${product.status})`);
-   return false;
-  }
-  return true;
- } catch (error: unknown) {
-  // ✅ Enhanced error logging: Extract all error details for visibility
-  const errorMsg = error instanceof Error ? error.message : String(error);
-  const errorDetails = {
-   message: errorMsg,
-   stack: error instanceof Error ? error.stack : undefined,
-   errorType: error instanceof Error ? error.constructor.name : 'Error',
-  };
-  log.error(`Failed to validate product: ${productRef}`, errorDetails);
-  return false;
- }
-}
-/**
- * Get current product price for change tracking
- */
-async function getCurrentPrice(
- client: any,
- productRef: string,
- priceType: string,
- currency: string,
- retailerId: string
-): Promise<number | undefined> {
- try {
-  const query = `
-   query GetProductPrice($ref: String!, $retailerId: ID!) {
-    products(first: 1, ref: [$ref], retailerId: $retailerId) {
-     edges {
-      node {
-       id
-       ref
-       prices {
-        type
-        value
-        currency
-       }
-      }
-     }
-    }
-   }
-  `;
-  const result = await client.graphql({
-   query,
-   variables: { ref: productRef, retailerId },
-  });
-  const product = result?.data?.products?.edges?.[0]?.node;
-  if (product?.prices) {
-   const existingPrice = product.prices.find(
-    (p: any) => p.type === priceType && p.currency === currency
-   );
-   if (existingPrice) {
-    return existingPrice.value;
-   }
-  }
- } catch (err) {
-  // Ignore - price change tracking is optional
- }
- return undefined;
-}
-// ============================================================================
-// Service Function 1: Process File (S3 + CSV + Mapper)
-// ============================================================================
-/**
- * Process single CSV file: Download from S3, parse CSV, map fields to Price schema
- *
- * @param s3 - S3DataSource instance
- * @param parser - CSVParserService instance
- * @param mapper - UniversalMapper instance (with custom price resolvers)
- * @param filePath - S3 file path
- * @param fileName - File name
- * @param log - Logger instance
- * @returns FileProcessingResult with parsed and mapped price data
- */
-async function processFile(
- s3: S3DataSource,
- parser: CSVParserService,
- mapper: GraphQLMutationMapper,
- filePath: string,
- fileName: string,
- log: any
-): Promise<{ records: Array<{ query: string; variables: any; input: any }>; errors: string[] }> {
- log.info('Processing file', { fileName });
- // Download CSV from S3 with retry
- const content = await retryWithBackoff(
-  () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
- );
- // Parse CSV
- const rawRecords = await parser.parse(content, {
-  columns: true,
-  skip_empty_lines: true,
-  trim: true,
- });
- if (!rawRecords.length) {
-  log.warn('Empty CSV file', { fileName });
-  return { records: [], errors: [] };
- }
- log.info('CSV parsed', { fileName, recordCount: rawRecords.length });
- // Map CSV records to Price schema
-  const mappedRecords: Array<{ query: string; variables: any; input: any }> = [];
-  const errors: string[] = [];
-  // ✅ PRODUCTION ENHANCEMENT: Log transformation start
-  log.info('Transforming records to GraphQL mutations', {
-   fileName,
-   totalRecords: rawRecords.length,
-  });
-  for (let i = 0; i < rawRecords.length; i++) {
-   const rec = rawRecords[i];
-   const recordNumber = i + 1;
-   // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 records
-   if (recordNumber % 50 === 0) {
-    log.info(`📤 Transforming record ${recordNumber}/${rawRecords.length}`, {
-     fileName,
-     recordNumber,
-     totalRecords: rawRecords.length,
-     validSoFar: mappedRecords.length,
-     errorsSoFar: errors.length,
-     progress: `${((recordNumber / rawRecords.length) * 100).toFixed(1)}%`,
-    });
-   }
-   try {
-    // GraphQLMutationMapper returns { query, variables } directly
-    const mapped = await mapper.map(rec);
-    mappedRecords.push({
-     query: mapped.query,
-     variables: mapped.variables,
-     input: mapped.variables.input || mapped.variables,
-    });
-   } catch (error: unknown) {
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    errors.push(`Row ${recordNumber}: ${errorMsg}`);
-   }
-  }
- log.info('Mapping completed', {
-  fileName,
-  successful: mappedRecords.length,
-  failed: errors.length,
-  totalRecords: rawRecords.length,
-  successRate: `${((mappedRecords.length / rawRecords.length) * 100).toFixed(1)}%`,
- });
- return { records: mappedRecords, errors };
-}
-// ============================================================================
-// Service Function 2: Execute Mutations (GraphQL Price Updates)
-// ============================================================================
-/**
- * Execute GraphQL mutations for price updates with validation and rate limiting
- * ✅ Supports alias batching for improved performance
- *
- * @param client - FluentClient instance
- * @param mapper - GraphQLMutationMapper instance
- * @param priceRecords - Mapped price data with query and variables
- * @param retailerId - Fluent retailer ID
- * @param validateProducts - Whether to validate product existence
- * @param batchSize - Number of concurrent requests (concurrency control)
- * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (alias batching)
- * @param log - Logger instance
- * @returns MutationResult with success/failure counts and price changes
- */
-async function executeMutations(
- client: any,
- mapper: GraphQLMutationMapper,
- priceRecords: Array<{ query: string; variables: any; input: any }>,
- retailerId: string,
- validateProducts: boolean,
- batchSize: number = 1, // ✅ Default: 1 (sequential)
- mutationsPerAliasBatch?: number, // ✅ NEW: Alias batching parameter (default: undefined = disabled)
- log: any
-): Promise<MutationResult> {
- let successful = 0;
- let failed = 0;
- const priceChanges: Array<{
-  sku: string;
-  type: string;
-  oldPrice?: number;
-  newPrice: number;
- }> = [];
- // ✅ Use alias batching if enabled
- const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
- if (useAliases) {
-  // Process with alias batching
-  const results = await executeMutationsWithAliases(
-   priceRecords,
-   client,
-   mapper,
-   log,
-   retailerId,
-   batchSize,
-   mutationsPerAliasBatch,
-   'updateProduct'
-  );
-  successful = results.executed;
-  failed = results.failed;
-  // Note: Price changes tracking would need to be done separately if needed
- } else {
-  // Process individually with validation
-  for (const priceData of priceRecords) {
-   try {
-    // Validate product exists (if enabled)
-    if (validateProducts) {
-     const productExists = await validateProductExists(
-      client,
-      priceData.input.productRef,
-      retailerId,
-      log
-     );
-     if (!productExists) {
-      log.warn(`Skipping price update for non-existent product: ${priceData.input.productRef}`);
-      failed++;
-      continue;
-     }
-    }
-    // Get current price for change tracking
-    const currentPrice = await getCurrentPrice(
-     client,
-     priceData.input.productRef,
-     priceData.input.type,
-     priceData.input.currency,
-     retailerId
-    );
-    // Execute mutation using pre-generated query and variables
-    await retryWithBackoff(() =>
-     client.graphql({
-      query: priceData.query,
-      variables: priceData.variables,
-     })
-    );
-    successful++;
-    // Track price change
-    if (currentPrice !== undefined && currentPrice !== priceData.input.value) {
-     priceChanges.push({
-      sku: priceData.input.productRef,
-      type: priceData.input.type,
-      oldPrice: currentPrice,
-      newPrice: priceData.input.value,
-     });
-    }
-    log.info('Price updated', {
-     ref: priceData.input.productRef,
-     type: priceData.input.type,
-     oldPrice: currentPrice,
-     newPrice: priceData.input.value,
-     currency: priceData.input.currency,
-    });
-   } catch (error: unknown) {
-    failed++;
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    const errorDetails = {
-     message: errorMsg,
-     stack: error instanceof Error ? error.stack : undefined,
-     errorType: error instanceof Error ? error.constructor.name : 'Error',
-    };
-    log.error('Failed to update price', errorDetails, {
-     ref: priceData.input?.productRef,
-     type: priceData.input?.type,
-    });
-   }
-  }
- }
- return { successful, failed, priceChanges };
-}
-/**
- * ✅ NEW: Execute mutations with GraphQL alias batching
- */
-async function executeMutationsWithAliases(
- priceRecords: Array<{ query: string; variables: any; input: any }>,
- client: any,
- mapper: GraphQLMutationMapper,
- log: any,
- retailerId: string,
- maxParallel: number,
- mutationsPerAliasBatch: number,
- mutationName: string
-): Promise<{ executed: number; failed: number; errors: string[] }> {
- const results = { executed: 0, failed: 0, errors: [] as string[] };
- const aliasBatches: Array<Array<typeof priceRecords[0]>> = [];
- for (let i = 0; i < priceRecords.length; i += mutationsPerAliasBatch) {
-  aliasBatches.push(priceRecords.slice(i, i + mutationsPerAliasBatch));
- }
- log.info(`Processing ${aliasBatches.length} alias batches`, {
-  totalPrices: priceRecords.length,
-  maxParallel,
- });
- for (let i = 0; i < aliasBatches.length; i += maxParallel) {
-  const concurrentBatches = aliasBatches.slice(i, i + maxParallel);
-  const batchResults = await Promise.allSettled(
-   concurrentBatches.map(async (batch) => {
-    const { query, variables } = buildAliasedBatch(batch, mutationName, retailerId);
-    const response = await retryWithBackoff(() => client.graphql({ query, variables }), log);
-    return parseAliasResponse(response, batch, mutationName);
-   })
-  );
-  batchResults.forEach((result, idx) => {
-   if (result.status === 'fulfilled') {
-    const batchResult = result.value;
-    results.executed += batchResult.executed;
-    results.failed += batchResult.failed;
-    results.errors.push(...batchResult.errors);
-   } else {
-    const batch = concurrentBatches[idx];
-    const errorMsg = result.reason instanceof Error ? result.reason.message : String(result.reason);
-    batch.forEach(price => {
-     results.failed++;
-     const productRef = price.input?.productRef || 'unknown';
-     results.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
-    });
-   }
-  });
-  if (i + maxParallel < aliasBatches.length) {
-   await new Promise(resolve => setTimeout(resolve, 500));
-  }
- }
- return results;
-}
-/**
- * ✅ NEW: 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> } {
- const batchSize = batch.length;
- const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
- const variables = Array.from({ length: batchSize }, (_, i) =>
-  `$input${i + 1}: ${inputTypeName}!`
- ).join(', ');
- const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
-  const alias = `${mutationName}${i + 1}`;
-  return ` ${alias}: ${mutationName}(input: $input${i + 1}) { id ref }`;
- }).join('\n');
- const operationName = `Batch${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}s`;
- const query = `mutation ${operationName}(${variables}) {\n${aliasedMutations}\n}`;
- const variablesObj: Record<string, any> = {};
- batch.forEach((price, index) => {
-  const input = price.variables.input || price.variables;
-  variablesObj[`input${index + 1}`] = input;
- });
- return { query, variables: variablesObj };
-}
-/**
- * ✅ NEW: Parse aliased GraphQL response
- */
-function parseAliasResponse(
- response: any,
- batch: Array<{ query: string; variables: any; input: any }>,
- mutationName: string
-): { executed: number; failed: number; errors: string[] } {
- const result = { executed: 0, failed: 0, errors: [] as string[] };
- const data = response.data || {};
- const errors = response.errors || [];
- batch.forEach((price, index) => {
-  const alias = `${mutationName}${index + 1}`;
-  const aliasData = data[alias];
-  const aliasErrors = errors.filter((e: unknown) =>
-   e && typeof e === 'object' && 'path' in e && Array.isArray((e as any).path) && (e as any).path.includes(alias)
-  );
-  if (aliasData && !aliasErrors.length) {
-   result.executed++;
-  } else {
-   result.failed++;
-   const errorMsg = aliasErrors[0] && typeof aliasErrors[0] === 'object' && 'message' in aliasErrors[0]
-    ? String((aliasErrors[0] as any).message)
-    : 'Mutation failed';
-   const productRef = price.input?.productRef || 'unknown';
-   result.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
-  }
- });
- return result;
-}
-// ============================================================================
-// Service Function 3: Write Mutation Log (S3 Upload)
-// ============================================================================
-/**
- * Write mutation execution log to S3
- *
- * @param s3 - S3DataSource instance
- * @param fileName - Original CSV file name
- * @param result - FileProcessingResult
- * @param logPrefix - S3 prefix for logs
- * @param log - Logger instance
- */
-async function writeMutationLog(
- s3: S3DataSource,
- fileName: string,
- result: FileProcessingResult,
- logPrefix: string,
- log: any
-): Promise<void> {
- const logFileName = `${fileName.replace('.csv', '')}-log.json`;
- const logPath = `${logPrefix}${logFileName}`;
- const logData = {
-  fileName,
-  timestamp: new Date().toISOString(),
-  summary: {
-   successful: result.successful,
-   failed: result.failed,
-   validationFailed: result.validationFailed,
-   priceChanges: result.priceChanges.length,
-  },
-  priceChanges: result.priceChanges,
-  errors: result.errors,
- };
- const logContent = JSON.stringify(logData, null, 2);
-// Upload log to S3 (uploadFile accepts string or Buffer)
-await s3.uploadFile(logPath, logContent);
- log.info('Mutation log written', { logPath });
-}
-// ============================================================================
-// Main Workflow Function (Per-File Processing)
-// ============================================================================
-async function executePriceSync(ctx: any, jobId: string, tracker: any) {
- const { log, activation, openKv } = ctx;
- const startTime = Date.now();
- log.info('🔄 [PriceSync] Starting scheduled price sync from S3');
- // ✅ CRITICAL: Declare S3 outside try block for safe disposal
- let s3: S3DataSource | undefined;
- try {
-  // ========================================
-  // STEP 1: CONFIGURATION & VALIDATION
-  // ========================================
-  // Read activation variables
-  const s3Bucket = activation?.getVariable('s3BucketName');
-  const s3Region = activation?.getVariable('awsRegion') || 'us-east-1';
-  const s3AccessKeyId = activation?.getVariable('awsAccessKeyId');
-  const s3SecretAccessKey = activation?.getVariable('awsSecretAccessKey');
-  const s3Prefix = activation?.getVariable('s3Prefix') || 'prices/';
-  const retailerId = activation?.getVariable('retailerId');
-  const maxFiles = parseInt(activation?.getVariable('maxFilesToProcess') || '10', 10);
-  const filePattern = (activation?.getVariable('filePattern') || '.csv').toLowerCase();
-  const enableArchival = activation?.getVariable('enableArchival') !== 'false';
-  const archivePrefix = activation?.getVariable('archivePrefix') || 'processed/';
-  const errorPrefix = activation?.getVariable('errorPrefix') || 'errors/';
-  const logPrefix = activation?.getVariable('logPrefix') || 'logs/';
-  // Configuration with defaults
-  const mutationBatchSize = parseInt(
-   activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
-   10
-  );
-  const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
-   ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
-   : undefined; // Default: undefined (disabled)
-  const minPrice = parseFloat(activation?.getVariable('minPrice') || '0.01');
-  const maxPrice = parseFloat(activation?.getVariable('maxPrice') || '999999.99');
-  const validateProducts = activation?.getVariable('validateProducts') !== 'false';
-  const validateConnection = activation?.getVariable('validateConnection') !== 'false';
-  const enableFileTracking = activation?.getVariable('enableFileTracking') !== 'false';
-  // Validate required variables
-  const missingVars: string[] = [];
-  if (!s3Bucket) missingVars.push('s3BucketName');
-  if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
-  if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
-  if (!retailerId) missingVars.push('retailerId');
-  if (missingVars.length > 0) {
-   const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
-   log.error('❌ [PriceSync] Configuration error', { error: errorMsg });
-   return {
-    success: false,
-    error: errorMsg,
-    recommendation: `Please configure these activation variables: ${missingVars.join(', ')}`,
-    processed: 0,
-    duration: Date.now() - startTime,
-   };
-  }
-  // ========================================
-  // STEP 2: CLIENT INITIALIZATION
-  // ========================================
-  const client = await createClient(ctx);
-  if (!client) {
-   throw new Error('Failed to create Fluent Commerce client');
-  }
-  // ✅ CORRECT: GraphQL mutations don't need setRetailerId()
-  // Check your GraphQL schema to determine retailerId handling:
-  // - Mandatory retailerId → Must pass it in mutation input
-  // - Optional retailerId → Can pass it if needed
-  // - No retailerId field → Don't pass it
-  // See: fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md
-  log.info('✅ [PriceSync] Fluent client initialized');
-  // ========================================
-  // STEP 3: SERVICE INITIALIZATION
-  // ========================================
-  s3 = new S3DataSource(
-   {
-    type: 'S3_CSV',
-    connectionId: 's3-price-sync',
-    name: 'Source S3',
-    s3Config: {
-     bucket: s3Bucket,
-     region: s3Region,
-     accessKeyId: s3AccessKeyId,
-     secretAccessKey: s3SecretAccessKey,
-    },
-   },
-   log
-  );
-  // Validate S3 connection if enabled
-  if (validateConnection) {
-   try {
-    await s3.listFiles({ prefix: s3Prefix, maxKeys: 1 });
-    log.info('✅ [PriceSync] S3 connection validated');
-   } catch (error: any) {
-    log.error('❌ [PriceSync] S3 connection validation failed', {
-     error: error instanceof Error ? error.message : String(error),
-    });
-    return {
-     success: false,
-     error: 'S3 connection validation failed',
-     details: error?.message,
-     recommendation: 'Please verify S3 credentials and bucket access permissions',
-     duration: Date.now() - startTime,
-    };
-   }
-  }
-  const parser = new CSVParserService();
-  const kv = openKv(':project:');
-  const fileTracker = enableFileTracking
-   ? new VersoriFileTracker(kv, 's3-csv-price-sync')
-   : null;
- // Create custom resolvers for price validation
- const customResolvers = {
-  'custom.validatePriceRange': (value: any) => {
-   const price = parseFloat(value);
-   if (isNaN(price)) {
-    throw new Error(`Invalid price: ${value}`);
-   }
-   if (price < minPrice) {
-    throw new Error(`Price ${price} below minimum ${minPrice}`);
-   }
-   if (price > maxPrice) {
-    throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
-   }
-   return price;
-  },
-  'custom.normalizePriceType': (value: any) => {
-   const type = String(value || 'DEFAULT').toUpperCase().trim();
-   const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
-   if (!validTypes.includes(type)) {
-    throw new Error(`Invalid price type: ${type}`);
-   }
-   return type;
-  },
-  'custom.normalizeQuantity': (value: any) => {
-   if (!value || value === '') return undefined;
-   const qty = parseInt(value, 10);
-   if (isNaN(qty) || qty < 0) {
-    throw new Error(`Invalid quantity: ${value}`);
-   }
-   return qty;
-  },
- };
- // ✅ CRITICAL: Load mapping config from external JSON file
- // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
- // File: src/config/price-mapping.json
- const mappingConfigJson = await import('../config/price-mapping.json', { assert: { type: 'json' } });
- const mappingConfig = mappingConfigJson.default;
- // Initialize GraphQLMutationMapper with client for schema introspection
- const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-  // ========================================
-  // STEP 4: FILE DISCOVERY
-  // ========================================
-  try {
-   // List files (pattern filtering handled by listFiles)
-   const files = await s3.listFiles({
-    prefix: s3Prefix,
-    pattern: filePattern,
-    maxKeys: 1000,
-   });
-   const csvFiles = files
-    .sort((a, b) => {
-     const dateA = a.lastModified ? new Date(a.lastModified).getTime() : 0;
-     const dateB = b.lastModified ? new Date(b.lastModified).getTime() : 0;
-     return dateA - dateB;
-    })
-    .slice(0, maxFiles);
-   log.info('📂 [PriceSync] Files discovered', {
-    total: files.length,
-    toProcess: csvFiles.length,
-    maxFiles,
-   });
-  const results = {
-   processed: 0,
-   skipped: 0,
-   failed: 0,
-   totalRecords: 0,
-   pricesUpdated: 0,
-   pricesSkipped: 0,
-   validationErrors: 0,
-   priceChanges: [] as Array<{
-    sku: string;
-    type: string;
-    oldPrice?: number;
-    newPrice: number;
-   }>,
-   errors: [] as string[],
-  };
-   // ========================================
-   // STEP 5: FILE PROCESSING LOOP
-   // ========================================
-   // Process each file using service functions
-   for (const file of csvFiles) {
-    const filePath = file.path;
-    const fileName = file.name;
-    const fileStartTime = Date.now();
-    log.info('📄 [PriceSync] Processing file', { fileName });
-    // Duplicate prevention via file tracker
-    if (fileTracker && (await fileTracker.wasFileProcessed(fileName))) {
-     log.info('⏭️ [PriceSync] Skipping already processed file', { fileName });
-     results.skipped++;
-     continue;
-    }
-    try {
-    // SERVICE FUNCTION 1: Process file (S3 + CSV + Mapper)
-    const { records: mappedRecords, errors: mappingErrors } = await processFile(
-     s3,
-     parser,
-     mapper,
-     filePath,
-     fileName,
-     log
-    );
-    if (!mappedRecords.length) {
-     log.warn('No valid records after mapping, archiving', { fileName });
-     if (enableArchival) {
-      await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-     }
-     results.skipped++;
-     continue;
-    }
-    // SERVICE FUNCTION 2: Execute mutations
-    // ✅ Configuration with defaults
-    const mutationBatchSize = parseInt(
-     ctx.activation?.getVariable('mutationBatchSize') || '1', // ✅ Default: 1 (sequential)
-     10
-    );
-    const mutationsPerAliasBatch = ctx.activation?.getVariable('mutationsPerAliasBatch')
-     ? parseInt(ctx.activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
-     : undefined; // ✅ Default: undefined (disabled, use separate requests)
-    // ? Enhanced: Extract context for progress logging
-    const sampleProductRefs = mappedRecords.slice(0, 5).map((r: any) => r.input?.skuRef || r.input?.productRef || 'unknown');
-    const mutationType = mapper?.mutationName || 'updatePrice';
-    // ? Enhanced: Start logging with context
-    log.info(`[GraphQLMutations] Sending price mutations for file "${fileName}"`, {
-     totalMutations: mappedRecords.length,
-     mutationType,
-     batchSize: mutationBatchSize,
-     batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
-     sampleProductRefs: sampleProductRefs.join(', '),
-     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled',
-     validateProducts
-    });
-    const mutationResult = await executeMutations(
-     client,
-     mapper,
-     mappedRecords,
-     retailerId,
-     validateProducts,
-     mutationBatchSize, // Concurrency control (default: 1)
-     mutationsPerAliasBatch, // ✅ NEW: Alias batching (default: undefined)
-     log
-    );
-    // ? Enhanced: Completion logging with summary
-    log.info(`[GraphQLMutations] Price mutation submission completed for file "${fileName}"`, {
-     totalMutations: mappedRecords.length,
-     successful: mutationResult.successful,
-     failed: mutationResult.failed,
-     successRate: mappedRecords.length > 0 ? `${Math.round((mutationResult.successful / mappedRecords.length) * 100)}%` : '0%',
-     mutationType,
-     priceChanges: mutationResult.priceChanges?.length || 0
-    });
-    // Aggregate results
-    results.processed++;
-    results.totalRecords += mappedRecords.length;
-    results.pricesUpdated += mutationResult.successful;
-    results.validationErrors += mappingErrors.length;
-    results.priceChanges.push(...mutationResult.priceChanges);
-    // Build file processing result for logging
-    const fileResult: FileProcessingResult = {
-     fileName,
-     successful: mutationResult.successful,
-     failed: mutationResult.failed,
-     validationFailed: mappingErrors.length,
-     priceChanges: mutationResult.priceChanges,
-     errors: mappingErrors,
-    };
-    // SERVICE FUNCTION 3: Write mutation log to S3
-    await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
-    // Mark processed with file tracker
-    if (fileTracker) {
-     await fileTracker.markFileProcessed(fileName, {
-      successful: mutationResult.successful,
-      failed: mutationResult.failed,
-      validationFailed: mappingErrors.length,
-      recordCount: mappedRecords.length,
-      duration: Date.now() - fileStartTime,
-     });
-    }
-    if (enableArchival) {
-     await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-    }
-    const fileDuration = Date.now() - fileStartTime;
-    log.info('✅ [PriceSync] File processed successfully', {
-     fileName,
-     recordCount: mappedRecords.length,
-     successful: mutationResult.successful,
-     failed: mutationResult.failed,
-     duration: `${fileDuration}ms`,
-    });
-    if (mappingErrors.length > 0) {
-     results.errors.push(`${fileName}: ${mappingErrors.length} mapping errors`);
-    }
-   } catch (error: unknown) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    const errorDetails = {
-     message: errorMsg,
-     stack: error instanceof Error ? error.stack : undefined,
-     errorType: error instanceof Error ? error.constructor.name : 'Error',
-    };
-    log.error('❌ [PriceSync] File processing failed', {
-     fileName,
-     ...errorDetails,
-    });
-    results.failed++;
-    results.errors.push(`${fileName}: ${errorMsg}`);
-    // Attempt to move to error directory
-    try {
-     await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
-     log.info('📁 [PriceSync] Moved failed file to error directory', { fileName });
-    } catch (moveError) {
-     log.error('❌ [PriceSync] Failed to move error file', {
-      fileName,
-      error: moveError instanceof Error ? moveError.message : String(moveError),
-     });
-    }
-   }
-  }
-   // ========================================
-   // STEP 6: SUMMARY & COMPLETION
-   // ========================================
-   const totalDuration = Date.now() - startTime;
-   const summary = {
-    success: true,
-    processed: results.processed,
-    skipped: results.skipped,
-    failed: results.failed,
-    totalRecords: results.totalRecords,
-    pricesUpdated: results.pricesUpdated,
-    pricesSkipped: results.pricesSkipped,
-    validationErrors: results.validationErrors,
-    priceChanges: results.priceChanges.length,
-    errors: results.errors.length > 0 ? results.errors : undefined,
-    duration: totalDuration,
-    timestamp: new Date().toISOString(),
-   };
-   log.info('🎉 [PriceSync] Price sync completed', {
-    ...summary,
-    duration: `${totalDuration}ms`,
-   });
-   // Log significant price changes
-   if (results.priceChanges.length > 0) {
-    log.info('💰 [PriceSync] Price changes detected', {
-     count: results.priceChanges.length,
-     changes: results.priceChanges.slice(0, 10),
-    });
-   }
-   return summary;
-  } catch (error: unknown) {
-   // ✅ Enhanced error logging: Extract all error details for visibility
-   const errorMsg = error instanceof Error ? error.message : String(error);
-   const errorDetails = {
-    message: errorMsg,
-    stack: error instanceof Error ? error.stack : undefined,
-    errorType: error instanceof Error ? error.constructor.name : 'Error',
-   };
-   log.error('❌ [PriceSync] Fatal error', errorDetails);
-   return {
-    success: false,
-    error: errorMsg,
-    recommendation: 'Check error logs for details and verify configuration',
-    processed: 0,
-    duration: Date.now() - startTime,
-    timestamp: new Date().toISOString(),
-   };
-  }
- } catch (error: unknown) {
-  const errorMsg = error instanceof Error ? error.message : String(error);
-  log.error('❌ [PriceSync] Initialization failed', {
-   error: errorMsg,
-   stack: error instanceof Error ? error.stack : undefined,
-  });
-  return {
-   success: false,
-   error: errorMsg,
-   recommendation: 'Check configuration and service initialization',
-   duration: Date.now() - startTime,
-  };
- } finally {
-  // ✅ CRITICAL: Always dispose S3 connection to prevent connection pool exhaustion
-  if (s3) {
-   try {
-    await s3.dispose();
-    log.info('✅ [PriceSync] S3 connection disposed successfully');
-   } catch (disposeError: any) {
-    log.error('⚠️ [PriceSync] Failed to dispose S3 connection', {
-     error: disposeError instanceof Error ? disposeError.message : String(disposeError),
-     stack: disposeError instanceof Error ? disposeError.stack : undefined,
-    });
-    // Don't throw - disposal failure shouldn't prevent workflow completion
-   }
-  }
- }
-}
-```
-**Note:** The `runPriceSync` function above should be renamed to `executePriceSync` and moved to `src/services/price-sync.service.ts` to match the new workflow structure.
-## Key Patterns Explained
-### Pattern 1: Service Function Architecture
-**Three modular service functions for clean separation of concerns:**
-```typescript
-// SERVICE FUNCTION 1: processFile()
-// Handles: S3 download + CSV parsing + field mapping
-const { records: mappedRecords, errors: mappingErrors } = await processFile(
- s3,
- parser,
- mapper,
- filePath,
- fileName,
- log
-);
-// SERVICE FUNCTION 2: executeMutations()
-// Handles: GraphQL mutations + product validation + concurrency control + price change tracking
-const mutationResult = await executeMutations(
- client,
- mapper,
- mappedRecords,
- retailerId,
- validateProducts,
- mutationBatchSize,    // Concurrency control (default: 1)
- mutationsPerAliasBatch,  // Alias batching (default: undefined)
- log
-);
-// SERVICE FUNCTION 3: writeMutationLog()
-// Handles: Write execution log to S3 (with Buffer for Versori/Deno)
-await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
-```
-**Why this pattern?**
-- ✅ **Testability**: Each function can be unit tested independently
-- ✅ **Reusability**: Functions can be reused in different workflows
-- ✅ **Clarity**: Clear responsibilities for each step
-- ✅ **Error handling**: Isolated error boundaries per function
-- ✅ **Maintainability**: Easy to modify single concerns without affecting others
-### Pattern 2: Buffer Import for S3 Upload (Versori/Deno)
-**CRITICAL for Versori/Deno runtime:**
-```typescript
-// MUST import Buffer explicitly (not global like Node.js)
-import { Buffer } from 'node:buffer';
-// writeMutationLog() function
-async function writeMutationLog(s3, fileName, result, logPrefix, log) {
- const logContent = JSON.stringify(logData, null, 2);
- // ✅ CORRECT: Use Buffer.from() for S3 upload
- await s3.uploadFile(logPath, logContent);
- // ✅ CORRECT: uploadFile accepts string directly (no Buffer needed)
- // await s3.uploadFile(logPath, logContent);
-}
-```
-**Why?** Deno runtime requires explicit `Buffer` import from `node:buffer`. Without it, you'll get `Buffer is not defined` errors.
-### Pattern 3: Direct KV State Management
-```typescript
-const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
-// Check if file already processed
-const stateKey = ['processed-files', 's3-price-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) {
- log.info('Skipping already processed file', { fileName });
- continue;
-}
-// Mark as processed after success
-await kv.set(stateKey, {
- successful,
- failed,
- validationFailed,
- processedAt: new Date().toISOString(),
-});
-```
-### Pattern 4: Custom Price Validation Resolvers
-```typescript
-const customResolvers = {
- 'custom.validatePriceRange': (value: any) => {
-  const price = parseFloat(value);
-  if (isNaN(price)) {
-   throw new Error(`Invalid price: ${value}`);
-  }
-  if (price < minPrice) {
-   throw new Error(`Price ${price} below minimum ${minPrice}`);
-  }
-  if (price > maxPrice) {
-   throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
-  }
-  return price;
- },
- 'custom.normalizePriceType': (value: any) => {
-  const type = String(value || 'DEFAULT').toUpperCase().trim();
-  const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
-  if (!validTypes.includes(type)) {
-   throw new Error(`Invalid price type: ${type}`);
-  }
-  return type;
- },
-};
-```
-**Why this matters**: Price data requires strict validation to prevent:
-- Negative prices
-- Prices outside business rules (too low/high)
-- Invalid price tiers
-- Data entry errors
-### Pattern 5: Product Existence Validation
-```typescript
-async function validateProductExists(
- client: any,
- productRef: string,
- retailerId: string,
- log: any
-): Promise<boolean> {
- const query = `
-  query GetProduct($ref: String!, $retailerId: ID!) {
-   products(first: 1, ref: [$ref], retailerId: $retailerId) {
-    edges {
-     node {
-      id
-      ref
-      status
-     }
-    }
-   }
-  }
- `;
- const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
- const product = result?.data?.products?.edges?.[0]?.node;
- if (!product || product.status !== 'ACTIVE') {
-  return false;
- }
- return true;
-}
-```
-**Why this matters**: Prevents price updates for non-existent products, which would fail at GraphQL level.
-### Pattern 6: Price Change Tracking
-```typescript
-// Get current price before update
-const currentPrice = await getCurrentPrice(
- client,
- priceData.productRef,
- priceData.type,
- priceData.currency,
- retailerId
-);
-// Track change after update
-if (currentPrice !== undefined && currentPrice !== priceData.value) {
- results.priceChanges.push({
-  sku: priceData.productRef,
-  type: priceData.type,
-  oldPrice: currentPrice,
-  newPrice: priceData.value,
- });
-}
-// Log changes at end
-if (results.priceChanges.length > 0) {
- log.info('Price changes detected', {
-  count: results.priceChanges.length,
-  changes: results.priceChanges.slice(0, 10),
- });
-}
-```
-**Why this matters**: Provides audit trail and monitoring for price changes.
-### Pattern 7: Concurrency Control & Alias Batching
-```typescript
-// ✅ Configuration with defaults
-const mutationBatchSize = parseInt(
- activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
- 10
-);
-const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
- ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
- : undefined; // Default: undefined (disabled)
-// Execute with bounded concurrency + optional alias batching
-const mutationResult = await executeMutations(
- client,
- mapper,
- priceRecords,
- retailerId,
- validateProducts,
- mutationBatchSize,    // 1=sequential, 3-10=parallel
- mutationsPerAliasBatch,  // Optional: Group mutations (e.g., 5)
- log
-);
-```
-**Performance Modes:**
-- `mutationBatchSize: 1` → Sequential (safe default, ~1 mutation/sec)
-- `mutationBatchSize: 3-5` → Balanced (~3-5 mutations/sec)
-- `mutationBatchSize: 10` → High-volume (~10 mutations/sec)
-- `mutationsPerAliasBatch: 5` → Alias batching (reduces network overhead by ~80%)
-## Advanced: Multi-Currency Price Management
-### External Mapping File for Multi-Currency
-**File**: `config/price-mapping.json`
-```json
-{
- "version": "1.0.0",
- "description": "Multi-currency price mapping",
- "fields": {
-  "productRef": {
-   "source": "sku",
-   "required": true,
-   "resolver": "sdk.trim"
-  },
-  "type": {
-   "source": "price_type",
-   "required": true,
-   "resolver": "custom.normalizePriceType"
-  },
-  "value": {
-   "source": "amount",
-   "required": true,
-   "resolver": "custom.validatePriceRange"
-  },
-  "currency": {
-   "source": "currency_code",
-   "required": true,
-   "resolver": "custom.normalizeCurrency"
-  },
-  "effectiveFrom": {
-   "source": "start_date",
-   "resolver": "sdk.formatDate"
-  },
-  "effectiveTo": {
-   "source": "end_date",
-   "resolver": "sdk.formatDate"
-  }
- }
-}
-```
-### Custom Resolvers for Multi-Currency
-```typescript
-const customResolvers = {
- 'custom.normalizeCurrency': (value: string) => {
-  // Normalize currency codes to ISO 4217
-  const currencyMap: Record<string, string> = {
-   usd: 'USD',
-   us: 'USD',
-   dollar: 'USD',
-   eur: 'EUR',
-   euro: 'EUR',
-   gbp: 'GBP',
-   pound: 'GBP',
-   cad: 'CAD',
-   aud: 'AUD',
-  };
-  const normalized = currencyMap[value.toLowerCase()] || value.toUpperCase();
-  // Validate against known currencies
-  const validCurrencies = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY', 'CNY'];
-  if (!validCurrencies.includes(normalized)) {
-   throw new Error(`Invalid currency code: ${value}`);
-  }
-  return normalized;
- },
- 'custom.convertToBaseCurrency': (value: any, sourceRecord: any) => {
-  // Convert foreign currency to base currency
-  const amount = parseFloat(value);
-  const currency = sourceRecord.currency_code;
-  // Exchange rates (in production, fetch from API)
-  const exchangeRates: Record<string, number> = {
-   USD: 1.0,
-   EUR: 0.85,
-   GBP: 0.73,
-   CAD: 1.35,
-   AUD: 1.45,
-  };
-  const rate = exchangeRates[currency?.toUpperCase()] || 1.0;
-  return amount * rate;
- },
- 'custom.buildPriceAttributes': (_: any, sourceRecord: any) => {
-  // Build price attributes array
-  const attributes: Array<{ name: string; type: string; value: any }> = [];
-  if (sourceRecord.cost_basis) {
-   attributes.push({
-    name: 'costBasis',
-    type: 'Float',
-    value: parseFloat(sourceRecord.cost_basis),
-   });
-  }
-  if (sourceRecord.margin_percent) {
-   attributes.push({
-    name: 'marginPercent',
-    type: 'Float',
-    value: parseFloat(sourceRecord.margin_percent),
-   });
-  }
-  if (sourceRecord.competitor_price) {
-   attributes.push({
-    name: 'competitorPrice',
-    type: 'Float',
-    value: parseFloat(sourceRecord.competitor_price),
-   });
-  }
-  if (sourceRecord.price_source) {
-   attributes.push({
-    name: 'priceSource',
-    type: 'String',
-    value: sourceRecord.price_source,
-   });
-  }
-  return attributes;
- },
-};
-```
-## Schema Validation (Before Deployment)
-Use SDK CLI tools to validate your GraphQL schema and mapping configuration:
-```bash
-# Install SDK globally (or use npx)
-npm install -g @fluentcommerce/fc-connect-sdk
-# 1. Introspect Fluent GraphQL schema
-fc-connect introspect-schema \
- --url https://api.fluentcommerce.com/graphql \
- --client-id YOUR_CLIENT_ID \
- --client-secret YOUR_CLIENT_SECRET \
- --output fluent-schema.json
-# 2. Create mutation file (price-mutation.graphql)
-cat > price-mutation.graphql << 'EOF'
-mutation UpdateProductPrice($input: UpdateProductInput!) {
- updateProduct(input: $input) {
-  id
-  ref
-  prices {
-   type
-   value
-   currency
-  }
- }
-}
-EOF
-# 3. Generate mapping from mutation (validates structure)
-fc-connect generate-mutation-mapping \
- --file price-mutation.graphql \
- --output price-mapping.json
-# 4. Validate mapping against schema
-fc-connect validate-schema \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-# 5. Analyze field coverage
-fc-connect analyze-coverage \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-```
-**Output Example**:
-```bash
-✓ Schema validation passed
-✓ All required fields present: ref, retailerId, prices[].type, prices[].value, prices[].currency
-✓ Mutation structure matches GraphQL schema
-⚠ Optional fields not mapped: prices[].taxType, prices[].taxRate
-```
-## Testing the Workflow
-### 1. Upload Test CSV to S3
-```bash
-# Using AWS CLI
-aws s3 cp product-prices-test.csv s3://my-price-bucket/prices/
-# Or using S3 Console
-# Navigate to bucket → prices/ → Upload
-```
-### 2. Deploy to Versori
-```bash
-npm run deploy
-```
-### 3. Manual Testing via Webhook
-```bash
-curl -X POST https://your-workspace.versori.run/sync-prices-now \
- -H "Content-Type: application/json"
-```
-### 4. Check Status
-```bash
-curl https://your-workspace.versori.run/check-status
-```
-### 5. Monitor Logs
-```bash
-npm run logs
-# Or via Versori dashboard
-```
----
-## Monitoring
-### Success Response
-```json
-{
- "success": true,
- "filesProcessed": 1,
- "filesSkipped": 0,
- "filesFailed": 0,
- "totalRecords": 100,
- "mutationsExecuted": 100,
- "mutationsFailed": 0,
- "results": [
-  {
-   "file": "prices_2025-01-22.csv",
-   "success": true,
-   "recordsProcessed": 100,
-   "mutationsExecuted": 100,
-   "mutationsFailed": 0
-  }
- ],
- "duration": 12345
-}
-```
-### Partial Success Response
-```json
-{
- "success": true,
- "filesProcessed": 1,
- "filesSkipped": 0,
- "filesFailed": 0,
- "totalRecords": 100,
- "mutationsExecuted": 95,
- "mutationsFailed": 5,
- "results": [
-  {
-   "file": "prices_2025-01-22.csv",
-   "success": true,
-   "recordsProcessed": 100,
-   "mutationsExecuted": 95,
-   "mutationsFailed": 5,
-   "errors": ["PRICE-001: Invalid price value", "PRICE-002: Missing currency"]
-  }
- ],
- "duration": 12345
-}
-```
-### Error Response
-```json
-{
- "success": false,
- "filesProcessed": 0,
- "filesFailed": 1,
- "totalRecords": 0,
- "mutationsExecuted": 0,
- "mutationsFailed": 0,
- "results": [
-  {
-   "file": "prices_2025-01-22.csv",
-   "success": false,
-   "error": "CSV parse error: Invalid structure"
-  }
- ],
- "duration": 876
-}
-```
-### Monitoring Metrics
-Monitor these metrics via Versori logs filtered by `jobId` or `stage`:
-- **Files Processed** - Total files successfully processed
-- **Mutations Executed** - Total GraphQL mutations executed successfully
-- **Mutations Failed** - Mutations that failed (check error logs)
-- **Processing Duration** - Time taken for complete workflow
-- **Rate Limiting** - Watch for 429 errors indicating GraphQL throttling
-Use the status webhook for dashboards and automated monitoring.
----
-### Issue 1: Product Not Found
-**Error**: `Skipping price update for non-existent product: PROD-XYZ`
-**Solution**:
-- Verify product exists in Fluent Commerce
-- Check SKU matches exactly (case-sensitive)
-- Ensure product status is `ACTIVE`
-- Disable validation temporarily for testing: `validateProducts=false`
-### Issue 2: Price Validation Failures
-**Error**: `Price 0.00 below minimum 0.01`
-**Solution**:
-```bash
-# Adjust validation rules in activation variables
-minPrice=0.00 # Allow zero prices
-maxPrice=9999999.99 # Increase max
-```
-Or fix source data:
-```csv
-# ❌ WRONG
-PROD-001,DEFAULT,0,USD
-# ✅ CORRECT
-PROD-001,DEFAULT,0.01,USD
-```
-### Issue 3: Invalid Price Type
-**Error**: `Invalid price type: PROMO`
-**Solution**: Update custom resolver to include new type:
-```typescript
-'custom.normalizePriceType': (value: any) => {
- const type = String(value || 'DEFAULT').toUpperCase().trim();
- const validTypes = [
-  'DEFAULT',
-  'SALE',
-  'CLEARANCE',
-  'BULK',
-  'PROMOTIONAL',
-  'MEMBER',
-  'PROMO', // Add new type
- ];
- if (!validTypes.includes(type)) {
-  throw new Error(`Invalid price type: ${type}`);
- }
- return type;
-};
-```
-### Issue 4: Duplicate Price Updates
-**Symptom**: Same file processed multiple times
-**Solution**: VersoriKVAdapter already prevents this:
-```typescript
-const stateKey = ['processed-files', 's3-price-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) {
- log.info('Skipping already processed file', { fileName });
- continue;
-}
-```
-Verify KV storage is working:
-```bash
-# Check Versori logs for:
-[INFO] Skipping already processed file: product-prices-20250122-001.csv
-```
-### Issue 5: S3 Access Denied
-Required IAM Permissions:
-```json
-{
- "Version": "2012-10-17",
- "Statement": [
-  {
-   "Effect": "Allow",
-   "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
-   "Resource": [
-    "arn:aws:s3:::my-price-bucket",
-    "arn:aws:s3:::my-price-bucket/*"
-   ]
-  }
- ]
-}
-```
-### Issue 6: GraphQL Mutation Failures
-**Common Causes**:
-- Invalid price type (check Fluent schema for valid types)
-- Missing required fields (ref, retailerId, prices)
-- Invalid currency code (must be ISO 4217: USD, EUR, GBP)
-- Product not found or inactive
-**Debugging**:
-```typescript
-// Log mutation input before execution
-log.info('GraphQL mutation input', { input });
-// Validate required fields
-if (!priceData.productRef || !priceData.type || !priceData.value) {
- log.error('Missing required fields', { priceData });
- continue;
-}
-```
-## Production Checklist
-- [ ] S3 credentials validated with correct IAM permissions
-- [ ] Activation secrets stored securely (not in code)
-- [ ] GraphQL schema validated using CLI tools
-- [ ] Mapping configuration uses GraphQLMutationMapper structure (NOT UniversalMapper)
-- [ ] Mapping configuration tested with sample data
-- [ ] NO setRetailerId() call in code (only for Job/Event API)
-- [ ] Price validation rules configured per business policy
-- [ ] Product existence validation enabled (`validateProducts=true`)
-- [ ] File duplicate prevention working via KV state
-- [ ] Concurrency control configured (mutationBatchSize)
-- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
-- [ ] Error handling tested with malformed CSV
-- [ ] Retry logic tested with transient failures
-- [ ] File archival working (processed and error directories)
-- [ ] Price change tracking verified in logs
-- [ ] Monitoring/alerting configured for price update failures
-- [ ] Clear runbook for error recovery
-## Related Guides
-- **GraphQL Mutation Mapping**: `docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
-- **GraphQL Alias Batching**: `docs/02-CORE-GUIDES/mapping/graphql-alias-batching-guide.md`
-- **retailerId Configuration**: `docs/00-START-HERE/retailerid-configuration.md`
-- **CLI Tools**: `fc-connect-sdk/bin/readme.md`
-- **State & KV patterns**: `docs/03-PATTERN-GUIDES/file-operations/`
-- **Error handling**: `docs/03-PATTERN-GUIDES/error-handling/`
+---
+template_id: tpl-ingest-s3-csv-to-price-graphql
+canonical_filename: template-ingestion-s3-csv-price-graphql.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: s3-csv
+destination: fluent-graphql
+entity: price
+format: csv
+logging: versori
+status: stable
+features:
+  - graphql-mutation-mapper
+  - memory-management
+  - enhanced-logging
+  - attribute-transformation
+compliance: gold-standard
+---
+# Template: Ingestion - S3 CSV to Price GraphQL
+n**Template Version:** 2.0.0
+**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
+**Last Updated:** 2025-01-24
+**🆕 Version 2.0.0 Enhancements:**
+- ✅ **GraphQL Mutation Mapper** - Direct field mapping to mutation variables
+- ✅ **Memory Management** - Clear large arrays after processing batches
+- ✅ **Enhanced Logging** - Track mutation execution with emoji indicators
+- ✅ **Attribute Transformation** - Handle complex nested data structures
+## STEP 1: What This Template Does
+This template provides a **scheduled Versori workflow** that:
+1. **Discovers CSV files** from S3 bucket with price data
+2. **Parses CSV** using `CSVParserService` with validation
+3. **Validates products exist** in Fluent Commerce before updating prices
+4. **Maps fields** using `GraphQLMutationMapper` with custom price validation resolvers
+5. **Updates prices** via direct GraphQL mutations (`updateProduct`)
+6. **Tracks price changes** for audit trail
+7. **Archives processed files** to prevent duplicates
+8. **Uses JobTracker** for job lifecycle management
+**Key Features:**
+- ✅ Direct GraphQL mutations (NOT Batch API)
+- ✅ Product existence validation before price updates
+- ✅ Price range validation (min/max checks)
+- ✅ Multi-tier pricing support (DEFAULT, SALE, CLEARANCE, BULK)
+- ✅ Configurable concurrency control (sequential or parallel)
+- ✅ Optional GraphQL alias batching for high-volume scenarios
+- ✅ Price change tracking and reporting
+- ✅ Versori KV state management (duplicate prevention)
+- ✅ File archival with error handling
+**Use Cases:**
+- Daily product price synchronization
+- Promotional price updates
+- Multi-currency pricing management
+- Quantity-based pricing tiers
+## STEP 2: Understanding This Template (AI Agent Guide)
+**🎯 Template Purpose:** Scheduled price synchronization from S3 CSV files to Fluent Commerce using direct GraphQL mutations.
+### Architecture Pattern
+```
+S3 CSV Files → CSVParserService → GraphQLMutationMapper → Product Validation → GraphQL Mutations → Archive
+   ↓       ↓          ↓         ↓          ↓       ↓
+File Discovery  Parsing     Field Mapping   Existence Check   updateProduct    Processed/
+Price Data   Validation    Price Validation  Active Status    Concurrency Ctrl   Error Dirs
+```
+### SDK Services Used
+| Service | Purpose | Key Methods |
+|---------|---------|-------------|
+| `createClient(ctx)` | Fluent API client | `client.graphql()` |
+| `S3DataSource` | S3 operations | `listFiles()`, `downloadFile()`, `moveFile()` |
+| `CSVParserService` | CSV parsing | `parse()` |
+| `GraphQLMutationMapper` | Field transformation | `map()` with custom resolvers |
+| `VersoriKVAdapter` | State management | `get()`, `set()`, `list()` |
+| `JobTracker` | Job lifecycle | `createJob()`, `updateJob()`, `markCompleted()`, `markFailed()`, `getJob()` |
+### Price Entity Structure
+**Fluent Commerce Price Schema:**
+```typescript
+{
+ productRef: string;   // SKU reference (required)
+ type: string;      // DEFAULT, SALE, CLEARANCE, BULK (required)
+ value: number;      // Price amount (required, validated)
+ currency: string;    // ISO 4217 code (USD, EUR, GBP)
+ effectiveFrom?: string; // ISO 8601 date
+ effectiveTo?: string;  // ISO 8601 date
+ minQuantity?: number;  // Min qty for tier pricing
+ maxQuantity?: number;  // Max qty for tier pricing
+}
+```
+### GraphQL Mutation Pattern
+**Mutation Used:** `updateProduct` (NOT Batch API)
+```graphql
+mutation UpdateProductPrice($input: UpdateProductInput!) {
+ updateProduct(input: $input) {
+  id
+  ref
+  prices {
+   type
+   value
+   currency
+   effectiveFrom
+   effectiveTo
+   minQuantity
+   maxQuantity
+  }
+ }
+}
+```
+**Why Direct Mutations?**
+- ✅ Immediate price updates (no batch processing delay)
+- ✅ Product validation before update
+- ✅ Price change tracking
+- ✅ Suitable for low-volume price updates (<1000/day)
+**NO BPP (Batch Pre-Processing):** Direct GraphQL mutations bypass batch workflows entirely.
+### Custom Resolvers
+**Three price-specific resolvers:**
+1. **`custom.validatePriceRange`** - Ensures price within min/max bounds
+2. **`custom.normalizePriceType`** - Validates price tier types
+3. **`custom.normalizeQuantity`** - Validates quantity ranges for BULK pricing
+### Product Validation Pattern
+**Critical Step:** Validate product exists and is ACTIVE before price update:
+```typescript
+async function validateProductExists(client, productRef, retailerId, log) {
+ const query = `
+  query GetProduct($ref: String!, $retailerId: ID!) {
+   products(first: 1, ref: [$ref], retailerId: $retailerId) {
+    edges {
+     node { id ref status }
+    }
+   }
+  }
+ `;
+ const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
+ const product = result?.data?.products?.edges?.[0]?.node;
+ return product && product.status === 'ACTIVE';
+}
+```
+**Why?** Prevents GraphQL errors for non-existent products.
+### Concurrency Control & Performance
+**Mutation execution** supports two performance modes:
+**Mode 1: Concurrency Control (default)**
+```typescript
+// Configuration: Control concurrent mutations
+const mutationBatchSize = parseInt(
+ activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
+ 10
+);
+// Execute with bounded concurrency
+await executeMutations(
+ client,
+ mapper,
+ priceRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize, // 1=sequential, 3-10=parallel
+ undefined,     // No alias batching
+ log
+);
+```
+**Mode 2: GraphQL Alias Batching (optional, high-volume)**
+```typescript
+// Configuration: Group mutations into aliased requests
+const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+ ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+ : undefined; // Default: undefined (disabled)
+// Execute with alias batching (reduces network overhead by ~80%)
+await executeMutations(
+ client,
+ mapper,
+ priceRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize,      // Concurrency control
+ mutationsPerAliasBatch,   // Alias batching (e.g., 5)
+ log
+);
+```
+**Activation Variables:**
+- `mutationBatchSize=1` - Default: sequential (safe)
+- `mutationBatchSize=3-5` - Balanced throughput
+- `mutationBatchSize=10` - High-volume (100+ locations)
+- `mutationsPerAliasBatch` - Optional: Group mutations (e.g., 5 per request)
+### State Management
+**VersoriKVAdapter** prevents duplicate file processing:
+```typescript
+const stateKey = ['processed-files', 's3-price-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) {
+ log.info('Skipping already processed file', { fileName });
+ continue;
+}
+// After success:
+await kv.set(stateKey, { successful, failed, processedAt: new Date().toISOString() });
+```
+### JobTracker Integration
+**Job lifecycle tracking:**
+```typescript
+const tracker = new JobTracker(openKv(':project:'), log);
+await tracker.startJob(jobId, { mode: 'scheduled' });
+try {
+ const result = await runPriceCsvWorkflow(ctx, jobId, tracker);
+ await tracker.completeJob(jobId, { result });
+} catch (e) {
+ await tracker.failJob(jobId, { error: e.message });
+}
+```
+### Price Change Tracking
+**Audit trail for price updates:**
+```typescript
+const currentPrice = await getCurrentPrice(client, productRef, priceType, currency, retailerId);
+// ... after update ...
+if (currentPrice !== undefined && currentPrice !== priceData.value) {
+ results.priceChanges.push({
+  sku: priceData.productRef,
+  type: priceData.type,
+  oldPrice: currentPrice,
+  newPrice: priceData.value,
+ });
+}
+// Log changes at end:
+log.info('Price changes detected', { count: results.priceChanges.length, changes });
+```
+### Schema Validation (CLI Commands)
+**Before deployment, validate GraphQL schema:**
+```bash
+# 1. Introspect Fluent schema
+fc-connect introspect-schema \
+ --url https://api.fluentcommerce.com/graphql \
+ --client-id CLIENT_ID \
+ --client-secret CLIENT_SECRET \
+ --output fluent-schema.json
+# 2. Create mutation file
+cat > price-mutation.graphql << 'EOF'
+mutation UpdateProductPrice($input: UpdateProductInput!) {
+ updateProduct(input: $input) {
+  id
+  ref
+  prices { type value currency }
+ }
+}
+EOF
+# 3. Generate mapping from mutation
+fc-connect generate-mutation-mapping \
+ --file price-mutation.graphql \
+ --output price-mapping.json
+# 4. Validate mapping against schema
+fc-connect validate-schema \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+# 5. Analyze field coverage
+fc-connect analyze-coverage \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+```
+### Configuration File Structure
+**Mapping Config:** `config/price-mapping.json`
+**✅ PRODUCTION STANDARD:** External JSON file with GraphQLMutationMapper structure
+```json
+{
+ "mutation": "updateProduct",
+ "sourceFormat": "csv",
+ "version": "1.0.0",
+ "arguments": {
+  "input": {
+   "ref": {
+    "source": "sku",
+    "required": true,
+    "resolver": "trim"
+   },
+   "prices": {
+    "type": {
+     "source": "priceType",
+     "required": true,
+     "resolver": "normalizePriceType"
+    },
+    "value": {
+     "source": "amount",
+     "required": true,
+     "resolver": "validatePriceRange"
+    },
+    "currency": {
+     "source": "currency",
+     "required": true,
+     "resolver": "toUpperCase"
+    },
+    "effectiveFrom": {
+     "source": "effectiveDate",
+     "resolver": "formatDate"
+    },
+    "effectiveTo": {
+     "source": "expiryDate",
+     "resolver": "formatDate"
+    },
+    "minQuantity": {
+     "source": "minQuantity",
+     "resolver": "normalizeQuantity"
+    },
+    "maxQuantity": {
+     "source": "maxQuantity",
+     "resolver": "normalizeQuantity"
+    }
+   }
+  }
+ }
+}
+```
+**Key Differences from UniversalMapper:**
+- ✅ `mutation` property (not `mutationName`)
+- ✅ `arguments.input` structure (matches GraphQL schema)
+- ✅ Nested `prices` object (not flat productRef/type/value)
+- ✅ Resolver names without `sdk.` or `custom.` prefix (`trim`, `toUpperCase`, `formatDate`)
+- ✅ Used with `GraphQLMutationMapper.map()` method (not `UniversalMapper.map()`)
+### Activation Variables Required
+**Minimum Required:**
+- `s3BucketName` - S3 bucket with price CSV files
+- `awsAccessKeyId` - AWS credentials
+- `awsSecretAccessKey` - AWS credentials
+**Optional (with defaults):**
+- `awsRegion=us-east-1`
+- `s3Prefix=prices/`
+- `archivePrefix=processed/`
+- `errorPrefix=errors/`
+- `logPrefix=logs/` - Where to write mutation logs
+- `maxFilesToProcess=10`
+- `mutationBatchSize=1` - Number of concurrent mutations (1=sequential, 3-10=parallel)
+- `mutationsPerAliasBatch` - Optional: Number of mutations per aliased request (default: undefined = disabled)
+- `minPrice=0.01`
+- `maxPrice=999999.99`
+- `validateProducts=true`
+- `validateConnection=true` - Validate S3 connection at startup
+- `enableFileTracking=true` - Enable file tracking via VersoriFileTracker
+- `fluentRetailerId` - Optional: Only if mutation schema requires retailerId in input (most Price mutations don't need it)
+### Error Handling Patterns
+**Three-level error handling:**
+1. **Mapping errors** - Invalid price data (validation failures)
+2. **GraphQL errors** - Mutation failures (product not found, invalid fields)
+3. **File processing errors** - S3 access issues, CSV parsing failures
+**Error state tracking with exponential backoff:**
+```typescript
+const errorKey = ['error-state', fileName];
+const attempts = (prev?.attemptCount || 0) + 1;
+const backoffMinutes = Math.min(Math.pow(2, attempts) * 5, 24 * 60);
+const nextRetryAt = new Date(Date.now() + backoffMinutes * 60000).toISOString();
+```
+### Common Pitfalls
+**❌ WRONG Patterns:**
+- Using Batch API for price updates (overhead, delay)
+- Using `UniversalMapper` instead of `GraphQLMutationMapper`
+- Calling `client.setRetailerId()` for GraphQL mutations (only needed for Job/Event API)
+- Skipping product validation (causes GraphQL errors)
+- No concurrency control (API throttling)
+- Hardcoded price validation rules (not configurable)
+- Missing price change tracking (no audit trail)
+**✅ CORRECT Patterns:**
+- Direct GraphQL mutations for immediate updates
+- `GraphQLMutationMapper` with nested mapping structure
+- NO `setRetailerId()` call (pass in mutation input if schema requires it)
+- Product existence validation before updates
+- Configurable concurrency control (mutationBatchSize)
+- Optional alias batching for high-volume scenarios
+- Custom resolvers for price validation
+- Price change tracking for audit
+- VersoriKVAdapter for state management
+- JobTracker for job lifecycle
+### Testing Checklist
+**Before deployment:**
+- [ ] S3 credentials validated (IAM permissions: ListBucket, GetObject, PutObject, DeleteObject)
+- [ ] GraphQL schema validated using CLI tools
+- [ ] Mapping configuration uses GraphQLMutationMapper structure (nested objects, not flat fields)
+- [ ] Mapping configuration tested with sample CSV
+- [ ] Product validation working (queries products endpoint)
+- [ ] Price validation rules configured (min/max bounds)
+- [ ] Concurrency control configured (mutationBatchSize)
+- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
+- [ ] NO setRetailerId() call present (only for Job/Event API)
+- [ ] File duplicate prevention working (KV state)
+- [ ] Price change tracking verified (logs price changes)
+- [ ] Error handling tested (malformed CSV, invalid products)
+- [ ] File archival working (processed/ and errors/ directories)
+### Related Documentation
+- **Core Guides:** `docs/02-CORE-GUIDES/ingestion/modules/`
+- **Universal Mapping:** `docs/02-CORE-GUIDES/mapping/modules/`
+- **CLI Tools:** `fc-connect-sdk/bin/readme.md`
+- **State Management:** `docs/03-PATTERN-GUIDES/file-operations/`
+- **Error Handling:** `docs/03-PATTERN-GUIDES/error-handling/`
+**FC Connect SDK Use Case Guide**
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+**Context**: Scheduled Versori workflow that reads product price CSV files from S3 and creates/updates Fluent Commerce product prices via GraphQL mutations
+**Complexity**: Medium-High
+**Runtime**: Versori Platform (Scheduled)
+**Estimated Lines**: ~700 lines
+## What You'll Build
+- Versori scheduled workflow (cron trigger)
+- S3 file listing and download with retry logic
+- CSV parsing with validation
+- UniversalMapper for price field transformations
+- Product existence validation before price updates
+- GraphQL mutations for price upserts with rate limiting
+- Versori KV state management (duplicate prevention)
+- Price change tracking and reporting
+- File archival after processing
+## Versori Workflows Structure
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+**Trigger Types:**
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`workflow()`** → Durable workflows (advanced, rarely used)
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from schedule/webhook)
+- **`fn()`** → Internal processing (chained from schedule/webhook)
+### Recommended Project Structure
+```
+s3-csv-price-graphql/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-price-sync.ts       # Scheduled: Daily price sync
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-price-sync.ts       # Webhook: Manual trigger
+    │       └── job-status-check.ts       # Webhook: Status query
+    │
+    ├── services/
+    │   └── price-sync.service.ts         # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── price-mapping.json            # GraphQL mapping config
+```
+---
+## Workflow Files
+### 1. Scheduled Workflows (`src/workflows/scheduled/`)
+All time-based triggers that run automatically on cron schedules.
+#### `src/workflows/scheduled/daily-price-sync.ts`
+**Purpose**: Automatic daily price sync
+**Trigger**: Cron schedule (`0 2 * * *`)
+**Exposed as Endpoint**: ❌ NO - Runs automatically
+```typescript
+import { schedule, http } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { executePriceSync } from '../../services/price-sync.service';
+/**
+ * Scheduled Workflow: Daily Price Sync
+ *
+ * Runs automatically daily at 2 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Uses shared service: price-sync.service.ts
+ */
+export const dailyPriceSync = schedule(
+  'price-sync-scheduled',
+  '0 2 * * *' // Daily at 2 AM UTC
+).then(
+  http('run-price-sync', { connection: 'fluent_commerce' }, async (ctx: any) => {
+    const { log, openKv } = ctx;
+    const jobId = `price-sync-${Date.now()}`;
+    const executionStartTime = Date.now();
+    const tracker = new JobTracker(openKv(':project:'), log);
+    log.info('🔄 [WORKFLOW] Starting price sync', { jobId });
+    await tracker.createJob(jobId, {
+      triggeredBy: 'schedule',
+      stage: 'initialization',
+      startTime: executionStartTime,
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+    try {
+      const result = await executePriceSync(ctx, jobId, tracker);
+      if (result.success) {
+        await tracker.markCompleted(jobId, result);
+        log.info('✅ [WORKFLOW] Price sync completed', {
+          jobId,
+          filesProcessed: result.filesProcessed,
+          duration: result.duration,
+        });
+      } else {
+        await tracker.markFailed(jobId, result.error || 'Unknown error');
+        log.error('❌ [WORKFLOW] Price sync failed', { jobId, error: result.error });
+      }
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      const errorMessage = e instanceof Error ? e.message : String(e);
+      await tracker.markFailed(jobId, errorMessage);
+      log.error('❌ [WORKFLOW] Price sync failed with exception', {
+        jobId,
+        error: errorMessage,
+        stack: e instanceof Error ? e.stack : undefined,
+      });
+      return { success: false, jobId, error: errorMessage };
+    }
+  })
+);
+```
+---
+### 2. Webhook Workflows (`src/workflows/webhook/`)
+All HTTP-based triggers that create webhook endpoints.
+#### `src/workflows/webhook/adhoc-price-sync.ts`
+**Purpose**: Manual price sync trigger (on-demand)
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/price-sync-adhoc`
+**Use Cases**: Testing, priority processing, ad-hoc runs
+```typescript
+import { webhook, http } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { executePriceSync } from '../../services/price-sync.service';
+/**
+ * Webhook: Manual Price Sync Trigger
+ *
+ * Endpoint: POST https://{workspace}.versori.run/price-sync-adhoc
+ * Request body (optional): { filePattern: "urgent_*.csv", maxFiles: 5 }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: price-sync.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const adhocPriceSync = webhook('price-sync-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'price-sync-adhoc', // Versori validates API key
+}).then(
+  http('run-price-sync-adhoc', { connection: 'fluent_commerce' }, async (ctx: any) => {
+    const { log, openKv, data } = ctx;
+    const jobId = `price-sync-adhoc-${Date.now()}`;
+    const executionStartTime = Date.now();
+    const tracker = new JobTracker(openKv(':project:'), log);
+    log.info('🔄 [WEBHOOK] Starting adhoc price sync', { jobId });
+    await tracker.createJob(jobId, {
+      triggeredBy: 'manual',
+      stage: 'initialization',
+      startTime: executionStartTime,
+      options: data // Optional: filePattern, maxFiles, etc.
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+    try {
+      const result = await executePriceSync(ctx, jobId, tracker);
+      if (result.success) {
+        await tracker.markCompleted(jobId, result);
+        log.info('✅ [WEBHOOK] Adhoc price sync completed', {
+          jobId,
+          filesProcessed: result.filesProcessed,
+          duration: result.duration,
+        });
+      } else {
+        await tracker.markFailed(jobId, result.error || 'Unknown error');
+        log.error('❌ [WEBHOOK] Adhoc price sync failed', { jobId, error: result.error });
+      }
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      const errorMessage = e instanceof Error ? e.message : String(e);
+      await tracker.markFailed(jobId, errorMessage);
+      log.error('❌ [WEBHOOK] Adhoc price sync failed with exception', {
+        jobId,
+        error: errorMessage,
+        stack: e instanceof Error ? e.stack : undefined,
+      });
+      return { success: false, jobId, error: errorMessage };
+    }
+  })
+);
+```
+---
+#### `src/workflows/webhook/job-status-check.ts`
+**Purpose**: Query job status
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/price-sync-job-status`
+**Request body**: `{ "jobId": "price-sync-1234567890" }`
+```typescript
+import { webhook, fn } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+/**
+ * Webhook: Job Status Check
+ *
+ * Endpoint: POST https://{workspace}.versori.run/price-sync-job-status
+ * Request body: { "jobId": "price-sync-1234567890" }
+ *
+ * Pattern: webhook().then(fn()) - no external API needed, only KV storage
+ * Lightweight: Only queries KV store, no Fluent API calls
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const priceSyncJobStatus = webhook('price-sync-job-status', {
+  response: { mode: 'sync' },
+  connection: 'price-sync-job-status',
+}).then(
+  fn('status', async (ctx: any) => {
+    const { data, log, openKv } = ctx;
+    const jobId = data?.jobId as string;
+    log.info('🔍 [STATUS] Checking job status', { jobId });
+    if (!jobId) {
+      log.warn('❌ [STATUS] Missing jobId in request');
+      return { success: false, error: 'jobId required' };
+    }
+    const tracker = new JobTracker(openKv(':project:'), log);
+    const status = await tracker.getJob(jobId);
+    if (status) {
+      log.info('✅ [STATUS] Job found', { jobId, status: status.status });
+      return { success: true, jobId, ...status };
+    } else {
+      log.warn('❌ [STATUS] Job not found', { jobId });
+      return { success: false, error: 'Job not found', jobId };
+    }
+  })
+);
+```
+---
+### 3. Entry Point (`index.ts`)
+**Purpose**: Register all workflows with Versori platform
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/scheduled/ → Time-based triggers (cron)
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ */
+// Import scheduled workflows
+import { dailyPriceSync } from './workflows/scheduled/daily-price-sync';
+// Import webhook workflows
+import { adhocPriceSync } from './workflows/webhook/adhoc-price-sync';
+import { priceSyncJobStatus } from './workflows/webhook/job-status-check';
+// Register all workflows
+export {
+  // Scheduled (time-based triggers)
+  dailyPriceSync,
+  // Webhooks (HTTP-based triggers)
+  adhocPriceSync,
+  priceSyncJobStatus,
+};
+```
+**What Gets Exposed:**
+- ✅ `adhocPriceSync` → `https://{workspace}.versori.run/price-sync-adhoc`
+- ✅ `priceSyncJobStatus` → `https://{workspace}.versori.run/price-sync-job-status`
+- ❌ `dailyPriceSync` → NOT exposed (runs automatically on cron)
+---
+## SDK Methods Used
+**Core Services:**
+- `createClient(ctx)` - Create Fluent client (auto-detects Versori context)
+- `S3DataSource(config, log)` - S3 operations (list, download, upload, move)
+- `CSVParserService()` - CSV parsing with validation
+- `GraphQLMutationMapper(mappingConfig, log, { fluentClient: client })` - Field mapping with schema validation
+- `VersoriKVAdapter(openKv(':project:'))` - KV state management for duplicate prevention
+**Key Methods:**
+- `s3.listFiles({ prefix, maxKeys })` - List S3 files
+- `s3.downloadFile(path, options)` - Download file content
+- `s3.uploadFile(path, content)` - Upload file (accepts string or Buffer)
+- `s3.moveFile(source, dest)` - Archive or move file
+- `parser.parse(content, options)` - Parse CSV to records
+- `mapper.map(record)` - Transform single record
+- `client.graphql({ query, variables })` - Execute GraphQL mutations/queries
+- `kv.get(key)` / `kv.set(key, value)` - State management
+**Critical Imports:**
+- `Buffer` - **Required for Versori/Deno runtime** (S3 upload operations)
+ ```typescript
+ import { Buffer } from 'node:buffer';
+ ```
+ **Why:** Deno runtime (used by Versori) does not have `Buffer` as a global. However, `uploadFile()` accepts string or Buffer, so you can use strings directly without Buffer conversion.
+**Service Functions (User-Defined):**
+- `processFile()` - S3 download + CSV parsing + field mapping
+- `executeMutations()` - GraphQL price updates with validation + rate limiting
+- `writeMutationLog()` - Write execution log to S3 (uses Buffer)
+## Sample CSV Input Data
+**File**: `product-prices-20250122-001.csv`
+```csv
+sku,priceType,amount,currency,effectiveDate,expiryDate,minQuantity,maxQuantity
+PROD-001,DEFAULT,29.99,USD,2025-01-22T00:00:00Z,,1,
+PROD-002,SALE,19.99,USD,2025-01-22T00:00:00Z,2025-02-15T23:59:59Z,1,
+PROD-003,CLEARANCE,9.99,USD,2025-01-22T00:00:00Z,2025-01-31T23:59:59Z,1,
+PROD-004,DEFAULT,149.99,USD,2025-01-22T00:00:00Z,,1,
+PROD-004,BULK,129.99,USD,2025-01-22T00:00:00Z,,10,99
+PROD-004,BULK,119.99,USD,2025-01-22T00:00:00Z,,100,
+```
+**Note**: Products can have multiple price tiers. Same SKU with different `priceType` or quantity ranges = multiple rows.
+**Field Mapping**:
+- `sku` → Product reference (required) - must exist in Fluent
+- `priceType` → Price tier (DEFAULT, SALE, CLEARANCE, BULK, etc.) (required)
+- `amount` → Price value (required, must be > 0)
+- `currency` → Currency code (USD, EUR, GBP, etc.) (required)
+- `effectiveDate` → When price becomes active (ISO 8601 format)
+- `expiryDate` → When price expires (optional, ISO 8601 format)
+- `minQuantity` → Minimum quantity for this price tier (optional, default: 1)
+- `maxQuantity` → Maximum quantity for this price tier (optional)
+**Price Tier Logic**:
+- **DEFAULT**: Standard retail price (most products)
+- **SALE**: Temporary promotional price
+- **CLEARANCE**: Final markdown price
+- **BULK**: Quantity-based pricing (requires minQuantity/maxQuantity)
+## Project Setup
+```bash
+mkdir versori-s3-csv-price-sync && cd $_
+npm init -y
+npm install @fluentcommerce/fc-connect-sdk@latest @versori/run
+mkdir -p src
+```
+### Package Configuration (package.json)
+```json
+{
+ "name": "versori-s3-csv-price-sync",
+ "version": "1.0.0",
+ "description": "Versori workflow: S3 CSV price sync to Fluent GraphQL",
+ "versori": {
+  "workflows": "./src/index.ts"
+ },
+ "type": "module",
+ "scripts": {
+  "deploy": "versori deploy",
+  "logs": "versori logs"
+ },
+ "dependencies": {
+  "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+  "@versori/run": "latest"
+ },
+ "devDependencies": {
+  "typescript": "^5.0.0",
+  "@types/node": "^20.0.0"
+ }
+}
+```
+### Activation Variables (Versori)
+```bash
+# Required Variables
+s3BucketName=my-price-bucket
+awsAccessKeyId=AKIAXXXXXXXXXXXX
+awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+retailerId=your-retailer-id
+# Optional Variables (with defaults shown)
+awsRegion=us-east-1
+s3Prefix=prices/
+archivePrefix=processed/
+errorPrefix=errors/
+logPrefix=logs/       # Where to write mutation logs
+maxFilesToProcess=10
+filePattern=.csv
+enableArchival=true
+mutationRateLimit=10
+# Price Validation Rules
+minPrice=0.01       # Minimum allowed price
+maxPrice=999999.99     # Maximum allowed price
+validateProducts=true   # Validate products exist before updating prices
+```
+## Complete Workflow (src/index.ts)
+```typescript
+import { schedule, webhook, http, fn } from '@versori/run';
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
+import {
+ createClient,
+ S3DataSource,
+ CSVParserService,
+ GraphQLMutationMapper,
+ VersoriFileTracker,
+ JobTracker,
+} from '@fluentcommerce/fc-connect-sdk';
+// ============================================================================
+// Type Definitions
+// ============================================================================
+interface FileProcessingResult {
+ fileName: string;
+ successful: number;
+ failed: number;
+ validationFailed: number;
+ priceChanges: Array<{
+  sku: string;
+  type: string;
+  oldPrice?: number;
+  newPrice: number;
+ }>;
+ errors: string[];
+}
+interface MutationResult {
+ successful: number;
+ failed: number;
+ priceChanges: Array<{
+  sku: string;
+  type: string;
+  oldPrice?: number;
+  newPrice: number;
+ }>;
+}
+interface MappedPriceData {
+ productRef: string;
+ type: string;
+ value: number;
+ currency: string;
+ effectiveFrom?: string;
+ effectiveTo?: string;
+ minQuantity?: number;
+ maxQuantity?: number;
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Retry utility with exponential backoff
+ * (User-defined - not part of SDK public API)
+ */
+async function retryWithBackoff<T>(
+ operation: () => Promise<T>,
+ maxRetries = 3,
+ baseDelayMs = 1000
+): Promise<T> {
+ let lastError: any;
+ for (let attempt = 0; attempt < maxRetries; attempt++) {
+  try {
+   return await operation();
+  } catch (error) {
+   lastError = error;
+   if (attempt < maxRetries - 1) {
+    const delay = baseDelayMs * Math.pow(2, attempt) + Math.floor(Math.random() * 200);
+    await new Promise(resolve => setTimeout(resolve, delay));
+   }
+  }
+ }
+ throw lastError;
+}
+/**
+ * Validate product exists in Fluent Commerce
+ */
+async function validateProductExists(
+ client: any,
+ productRef: string,
+ retailerId: string,
+ log: any
+): Promise<boolean> {
+ const query = `
+  query GetProduct($ref: String!, $retailerId: ID!) {
+   products(first: 1, ref: [$ref], retailerId: $retailerId) {
+    edges {
+     node {
+      id
+      ref
+      status
+     }
+    }
+   }
+  }
+ `;
+ try {
+  const result = await client.graphql({
+   query,
+   variables: { ref: productRef, retailerId },
+  });
+  const product = result?.data?.products?.edges?.[0]?.node;
+  if (!product) {
+   log.warn(`Product not found: ${productRef}`);
+   return false;
+  }
+  if (product.status !== 'ACTIVE') {
+   log.warn(`Product not active: ${productRef} (status: ${product.status})`);
+   return false;
+  }
+  return true;
+ } catch (error: unknown) {
+  // ✅ Enhanced error logging: Extract all error details for visibility
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  const errorDetails = {
+   message: errorMsg,
+   stack: error instanceof Error ? error.stack : undefined,
+   errorType: error instanceof Error ? error.constructor.name : 'Error',
+  };
+  log.error(`Failed to validate product: ${productRef}`, errorDetails);
+  return false;
+ }
+}
+/**
+ * Get current product price for change tracking
+ */
+async function getCurrentPrice(
+ client: any,
+ productRef: string,
+ priceType: string,
+ currency: string,
+ retailerId: string
+): Promise<number | undefined> {
+ try {
+  const query = `
+   query GetProductPrice($ref: String!, $retailerId: ID!) {
+    products(first: 1, ref: [$ref], retailerId: $retailerId) {
+     edges {
+      node {
+       id
+       ref
+       prices {
+        type
+        value
+        currency
+       }
+      }
+     }
+    }
+   }
+  `;
+  const result = await client.graphql({
+   query,
+   variables: { ref: productRef, retailerId },
+  });
+  const product = result?.data?.products?.edges?.[0]?.node;
+  if (product?.prices) {
+   const existingPrice = product.prices.find(
+    (p: any) => p.type === priceType && p.currency === currency
+   );
+   if (existingPrice) {
+    return existingPrice.value;
+   }
+  }
+ } catch (err) {
+  // Ignore - price change tracking is optional
+ }
+ return undefined;
+}
+// ============================================================================
+// Service Function 1: Process File (S3 + CSV + Mapper)
+// ============================================================================
+/**
+ * Process single CSV file: Download from S3, parse CSV, map fields to Price schema
+ *
+ * @param s3 - S3DataSource instance
+ * @param parser - CSVParserService instance
+ * @param mapper - UniversalMapper instance (with custom price resolvers)
+ * @param filePath - S3 file path
+ * @param fileName - File name
+ * @param log - Logger instance
+ * @returns FileProcessingResult with parsed and mapped price data
+ */
+async function processFile(
+ s3: S3DataSource,
+ parser: CSVParserService,
+ mapper: GraphQLMutationMapper,
+ filePath: string,
+ fileName: string,
+ log: any
+): Promise<{ records: Array<{ query: string; variables: any; input: any }>; errors: string[] }> {
+ log.info('Processing file', { fileName });
+ // Download CSV from S3 with retry
+ const content = await retryWithBackoff(
+  () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
+ );
+ // Parse CSV
+ const rawRecords = await parser.parse(content, {
+  columns: true,
+  skip_empty_lines: true,
+  trim: true,
+ });
+ if (!rawRecords.length) {
+  log.warn('Empty CSV file', { fileName });
+  return { records: [], errors: [] };
+ }
+ log.info('CSV parsed', { fileName, recordCount: rawRecords.length });
+ // Map CSV records to Price schema
+  const mappedRecords: Array<{ query: string; variables: any; input: any }> = [];
+  const errors: string[] = [];
+  // ✅ PRODUCTION ENHANCEMENT: Log transformation start
+  log.info('Transforming records to GraphQL mutations', {
+   fileName,
+   totalRecords: rawRecords.length,
+  });
+  for (let i = 0; i < rawRecords.length; i++) {
+   const rec = rawRecords[i];
+   const recordNumber = i + 1;
+   // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 records
+   if (recordNumber % 50 === 0) {
+    log.info(`📤 Transforming record ${recordNumber}/${rawRecords.length}`, {
+     fileName,
+     recordNumber,
+     totalRecords: rawRecords.length,
+     validSoFar: mappedRecords.length,
+     errorsSoFar: errors.length,
+     progress: `${((recordNumber / rawRecords.length) * 100).toFixed(1)}%`,
+    });
+   }
+   try {
+    // GraphQLMutationMapper returns { query, variables } directly
+    const mapped = await mapper.map(rec);
+    mappedRecords.push({
+     query: mapped.query,
+     variables: mapped.variables,
+     input: mapped.variables.input || mapped.variables,
+    });
+   } catch (error: unknown) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    errors.push(`Row ${recordNumber}: ${errorMsg}`);
+   }
+  }
+ log.info('Mapping completed', {
+  fileName,
+  successful: mappedRecords.length,
+  failed: errors.length,
+  totalRecords: rawRecords.length,
+  successRate: `${((mappedRecords.length / rawRecords.length) * 100).toFixed(1)}%`,
+ });
+ return { records: mappedRecords, errors };
+}
+// ============================================================================
+// Service Function 2: Execute Mutations (GraphQL Price Updates)
+// ============================================================================
+/**
+ * Execute GraphQL mutations for price updates with validation and rate limiting
+ * ✅ Supports alias batching for improved performance
+ *
+ * @param client - FluentClient instance
+ * @param mapper - GraphQLMutationMapper instance
+ * @param priceRecords - Mapped price data with query and variables
+ * @param retailerId - Fluent retailer ID
+ * @param validateProducts - Whether to validate product existence
+ * @param batchSize - Number of concurrent requests (concurrency control)
+ * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (alias batching)
+ * @param log - Logger instance
+ * @returns MutationResult with success/failure counts and price changes
+ */
+async function executeMutations(
+ client: any,
+ mapper: GraphQLMutationMapper,
+ priceRecords: Array<{ query: string; variables: any; input: any }>,
+ retailerId: string,
+ validateProducts: boolean,
+ batchSize: number = 1, // ✅ Default: 1 (sequential)
+ mutationsPerAliasBatch?: number, // ✅ NEW: Alias batching parameter (default: undefined = disabled)
+ log: any
+): Promise<MutationResult> {
+ let successful = 0;
+ let failed = 0;
+ const priceChanges: Array<{
+  sku: string;
+  type: string;
+  oldPrice?: number;
+  newPrice: number;
+ }> = [];
+ // ✅ Use alias batching if enabled
+ const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
+ if (useAliases) {
+  // Process with alias batching
+  const results = await executeMutationsWithAliases(
+   priceRecords,
+   client,
+   mapper,
+   log,
+   retailerId,
+   batchSize,
+   mutationsPerAliasBatch,
+   'updateProduct'
+  );
+  successful = results.executed;
+  failed = results.failed;
+  // Note: Price changes tracking would need to be done separately if needed
+ } else {
+  // Process individually with validation
+  for (const priceData of priceRecords) {
+   try {
+    // Validate product exists (if enabled)
+    if (validateProducts) {
+     const productExists = await validateProductExists(
+      client,
+      priceData.input.productRef,
+      retailerId,
+      log
+     );
+     if (!productExists) {
+      log.warn(`Skipping price update for non-existent product: ${priceData.input.productRef}`);
+      failed++;
+      continue;
+     }
+    }
+    // Get current price for change tracking
+    const currentPrice = await getCurrentPrice(
+     client,
+     priceData.input.productRef,
+     priceData.input.type,
+     priceData.input.currency,
+     retailerId
+    );
+    // Execute mutation using pre-generated query and variables
+    await retryWithBackoff(() =>
+     client.graphql({
+      query: priceData.query,
+      variables: priceData.variables,
+     })
+    );
+    successful++;
+    // Track price change
+    if (currentPrice !== undefined && currentPrice !== priceData.input.value) {
+     priceChanges.push({
+      sku: priceData.input.productRef,
+      type: priceData.input.type,
+      oldPrice: currentPrice,
+      newPrice: priceData.input.value,
+     });
+    }
+    log.info('Price updated', {
+     ref: priceData.input.productRef,
+     type: priceData.input.type,
+     oldPrice: currentPrice,
+     newPrice: priceData.input.value,
+     currency: priceData.input.currency,
+    });
+   } catch (error: unknown) {
+    failed++;
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    const errorDetails = {
+     message: errorMsg,
+     stack: error instanceof Error ? error.stack : undefined,
+     errorType: error instanceof Error ? error.constructor.name : 'Error',
+    };
+    log.error('Failed to update price', errorDetails, {
+     ref: priceData.input?.productRef,
+     type: priceData.input?.type,
+    });
+   }
+  }
+ }
+ return { successful, failed, priceChanges };
+}
+/**
+ * ✅ NEW: Execute mutations with GraphQL alias batching
+ */
+async function executeMutationsWithAliases(
+ priceRecords: Array<{ query: string; variables: any; input: any }>,
+ client: any,
+ mapper: GraphQLMutationMapper,
+ log: any,
+ retailerId: string,
+ maxParallel: number,
+ mutationsPerAliasBatch: number,
+ mutationName: string
+): Promise<{ executed: number; failed: number; errors: string[] }> {
+ const results = { executed: 0, failed: 0, errors: [] as string[] };
+ const aliasBatches: Array<Array<typeof priceRecords[0]>> = [];
+ for (let i = 0; i < priceRecords.length; i += mutationsPerAliasBatch) {
+  aliasBatches.push(priceRecords.slice(i, i + mutationsPerAliasBatch));
+ }
+ log.info(`Processing ${aliasBatches.length} alias batches`, {
+  totalPrices: priceRecords.length,
+  maxParallel,
+ });
+ for (let i = 0; i < aliasBatches.length; i += maxParallel) {
+  const concurrentBatches = aliasBatches.slice(i, i + maxParallel);
+  const batchResults = await Promise.allSettled(
+   concurrentBatches.map(async (batch) => {
+    const { query, variables } = buildAliasedBatch(batch, mutationName, retailerId);
+    const response = await retryWithBackoff(() => client.graphql({ query, variables }), log);
+    return parseAliasResponse(response, batch, mutationName);
+   })
+  );
+  batchResults.forEach((result, idx) => {
+   if (result.status === 'fulfilled') {
+    const batchResult = result.value;
+    results.executed += batchResult.executed;
+    results.failed += batchResult.failed;
+    results.errors.push(...batchResult.errors);
+   } else {
+    const batch = concurrentBatches[idx];
+    const errorMsg = result.reason instanceof Error ? result.reason.message : String(result.reason);
+    batch.forEach(price => {
+     results.failed++;
+     const productRef = price.input?.productRef || 'unknown';
+     results.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
+    });
+   }
+  });
+  if (i + maxParallel < aliasBatches.length) {
+   await new Promise(resolve => setTimeout(resolve, 500));
+  }
+ }
+ return results;
+}
+/**
+ * ✅ NEW: 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> } {
+ const batchSize = batch.length;
+ const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
+ const variables = Array.from({ length: batchSize }, (_, i) =>
+  `$input${i + 1}: ${inputTypeName}!`
+ ).join(', ');
+ const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
+  const alias = `${mutationName}${i + 1}`;
+  return ` ${alias}: ${mutationName}(input: $input${i + 1}) { id ref }`;
+ }).join('\n');
+ const operationName = `Batch${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}s`;
+ const query = `mutation ${operationName}(${variables}) {\n${aliasedMutations}\n}`;
+ const variablesObj: Record<string, any> = {};
+ batch.forEach((price, index) => {
+  const input = price.variables.input || price.variables;
+  variablesObj[`input${index + 1}`] = input;
+ });
+ return { query, variables: variablesObj };
+}
+/**
+ * ✅ NEW: Parse aliased GraphQL response
+ */
+function parseAliasResponse(
+ response: any,
+ batch: Array<{ query: string; variables: any; input: any }>,
+ mutationName: string
+): { executed: number; failed: number; errors: string[] } {
+ const result = { executed: 0, failed: 0, errors: [] as string[] };
+ const data = response.data || {};
+ const errors = response.errors || [];
+ batch.forEach((price, index) => {
+  const alias = `${mutationName}${index + 1}`;
+  const aliasData = data[alias];
+  const aliasErrors = errors.filter((e: unknown) =>
+   e && typeof e === 'object' && 'path' in e && Array.isArray((e as any).path) && (e as any).path.includes(alias)
+  );
+  if (aliasData && !aliasErrors.length) {
+   result.executed++;
+  } else {
+   result.failed++;
+   const errorMsg = aliasErrors[0] && typeof aliasErrors[0] === 'object' && 'message' in aliasErrors[0]
+    ? String((aliasErrors[0] as any).message)
+    : 'Mutation failed';
+   const productRef = price.input?.productRef || 'unknown';
+   result.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
+  }
+ });
+ return result;
+}
+// ============================================================================
+// Service Function 3: Write Mutation Log (S3 Upload)
+// ============================================================================
+/**
+ * Write mutation execution log to S3
+ *
+ * @param s3 - S3DataSource instance
+ * @param fileName - Original CSV file name
+ * @param result - FileProcessingResult
+ * @param logPrefix - S3 prefix for logs
+ * @param log - Logger instance
+ */
+async function writeMutationLog(
+ s3: S3DataSource,
+ fileName: string,
+ result: FileProcessingResult,
+ logPrefix: string,
+ log: any
+): Promise<void> {
+ const logFileName = `${fileName.replace('.csv', '')}-log.json`;
+ const logPath = `${logPrefix}${logFileName}`;
+ const logData = {
+  fileName,
+  timestamp: new Date().toISOString(),
+  summary: {
+   successful: result.successful,
+   failed: result.failed,
+   validationFailed: result.validationFailed,
+   priceChanges: result.priceChanges.length,
+  },
+  priceChanges: result.priceChanges,
+  errors: result.errors,
+ };
+ const logContent = JSON.stringify(logData, null, 2);
+// Upload log to S3 (uploadFile accepts string or Buffer)
+await s3.uploadFile(logPath, logContent);
+ log.info('Mutation log written', { logPath });
+}
+// ============================================================================
+// Main Workflow Function (Per-File Processing)
+// ============================================================================
+async function executePriceSync(ctx: any, jobId: string, tracker: any) {
+ const { log, activation, openKv } = ctx;
+ const startTime = Date.now();
+ log.info('🔄 [PriceSync] Starting scheduled price sync from S3');
+ // ✅ CRITICAL: Declare S3 outside try block for safe disposal
+ let s3: S3DataSource | undefined;
+ try {
+  // ========================================
+  // STEP 1: CONFIGURATION & VALIDATION
+  // ========================================
+  // Read activation variables
+  const s3Bucket = activation?.getVariable('s3BucketName');
+  const s3Region = activation?.getVariable('awsRegion') || 'us-east-1';
+  const s3AccessKeyId = activation?.getVariable('awsAccessKeyId');
+  const s3SecretAccessKey = activation?.getVariable('awsSecretAccessKey');
+  const s3Prefix = activation?.getVariable('s3Prefix') || 'prices/';
+  const retailerId = activation?.getVariable('retailerId');
+  const maxFiles = parseInt(activation?.getVariable('maxFilesToProcess') || '10', 10);
+  const filePattern = (activation?.getVariable('filePattern') || '.csv').toLowerCase();
+  const enableArchival = activation?.getVariable('enableArchival') !== 'false';
+  const archivePrefix = activation?.getVariable('archivePrefix') || 'processed/';
+  const errorPrefix = activation?.getVariable('errorPrefix') || 'errors/';
+  const logPrefix = activation?.getVariable('logPrefix') || 'logs/';
+  // Configuration with defaults
+  const mutationBatchSize = parseInt(
+   activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
+   10
+  );
+  const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+   ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+   : undefined; // Default: undefined (disabled)
+  const minPrice = parseFloat(activation?.getVariable('minPrice') || '0.01');
+  const maxPrice = parseFloat(activation?.getVariable('maxPrice') || '999999.99');
+  const validateProducts = activation?.getVariable('validateProducts') !== 'false';
+  const validateConnection = activation?.getVariable('validateConnection') !== 'false';
+  const enableFileTracking = activation?.getVariable('enableFileTracking') !== 'false';
+  // Validate required variables
+  const missingVars: string[] = [];
+  if (!s3Bucket) missingVars.push('s3BucketName');
+  if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
+  if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
+  if (!retailerId) missingVars.push('retailerId');
+  if (missingVars.length > 0) {
+   const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
+   log.error('❌ [PriceSync] Configuration error', { error: errorMsg });
+   return {
+    success: false,
+    error: errorMsg,
+    recommendation: `Please configure these activation variables: ${missingVars.join(', ')}`,
+    processed: 0,
+    duration: Date.now() - startTime,
+   };
+  }
+  // ========================================
+  // STEP 2: CLIENT INITIALIZATION
+  // ========================================
+  const client = await createClient(ctx);
+  if (!client) {
+   throw new Error('Failed to create Fluent Commerce client');
+  }
+  // ✅ CORRECT: GraphQL mutations don't need setRetailerId()
+  // Check your GraphQL schema to determine retailerId handling:
+  // - Mandatory retailerId → Must pass it in mutation input
+  // - Optional retailerId → Can pass it if needed
+  // - No retailerId field → Don't pass it
+  // See: fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md
+  log.info('✅ [PriceSync] Fluent client initialized');
+  // ========================================
+  // STEP 3: SERVICE INITIALIZATION
+  // ========================================
+  s3 = new S3DataSource(
+   {
+    type: 'S3_CSV',
+    connectionId: 's3-price-sync',
+    name: 'Source S3',
+    s3Config: {
+     bucket: s3Bucket,
+     region: s3Region,
+     accessKeyId: s3AccessKeyId,
+     secretAccessKey: s3SecretAccessKey,
+    },
+   },
+   log
+  );
+  // Validate S3 connection if enabled
+  if (validateConnection) {
+   try {
+    await s3.listFiles({ prefix: s3Prefix, maxKeys: 1 });
+    log.info('✅ [PriceSync] S3 connection validated');
+   } catch (error: any) {
+    log.error('❌ [PriceSync] S3 connection validation failed', {
+     error: error instanceof Error ? error.message : String(error),
+    });
+    return {
+     success: false,
+     error: 'S3 connection validation failed',
+     details: error?.message,
+     recommendation: 'Please verify S3 credentials and bucket access permissions',
+     duration: Date.now() - startTime,
+    };
+   }
+  }
+  const parser = new CSVParserService();
+  const kv = openKv(':project:');
+  const fileTracker = enableFileTracking
+   ? new VersoriFileTracker(kv, 's3-csv-price-sync')
+   : null;
+ // Create custom resolvers for price validation
+ const customResolvers = {
+  'custom.validatePriceRange': (value: any) => {
+   const price = parseFloat(value);
+   if (isNaN(price)) {
+    throw new Error(`Invalid price: ${value}`);
+   }
+   if (price < minPrice) {
+    throw new Error(`Price ${price} below minimum ${minPrice}`);
+   }
+   if (price > maxPrice) {
+    throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
+   }
+   return price;
+  },
+  'custom.normalizePriceType': (value: any) => {
+   const type = String(value || 'DEFAULT').toUpperCase().trim();
+   const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
+   if (!validTypes.includes(type)) {
+    throw new Error(`Invalid price type: ${type}`);
+   }
+   return type;
+  },
+  'custom.normalizeQuantity': (value: any) => {
+   if (!value || value === '') return undefined;
+   const qty = parseInt(value, 10);
+   if (isNaN(qty) || qty < 0) {
+    throw new Error(`Invalid quantity: ${value}`);
+   }
+   return qty;
+  },
+ };
+ // ✅ CRITICAL: Load mapping config from external JSON file
+ // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
+ // File: src/config/price-mapping.json
+ const mappingConfigJson = await import('../config/price-mapping.json', { assert: { type: 'json' } });
+ const mappingConfig = mappingConfigJson.default;
+ // Initialize GraphQLMutationMapper with client for schema introspection
+ const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+  // ========================================
+  // STEP 4: FILE DISCOVERY
+  // ========================================
+  try {
+   // List files (pattern filtering handled by listFiles)
+   const files = await s3.listFiles({
+    prefix: s3Prefix,
+    pattern: filePattern,
+    maxKeys: 1000,
+   });
+   const csvFiles = files
+    .sort((a, b) => {
+     const dateA = a.lastModified ? new Date(a.lastModified).getTime() : 0;
+     const dateB = b.lastModified ? new Date(b.lastModified).getTime() : 0;
+     return dateA - dateB;
+    })
+    .slice(0, maxFiles);
+   log.info('📂 [PriceSync] Files discovered', {
+    total: files.length,
+    toProcess: csvFiles.length,
+    maxFiles,
+   });
+  const results = {
+   processed: 0,
+   skipped: 0,
+   failed: 0,
+   totalRecords: 0,
+   pricesUpdated: 0,
+   pricesSkipped: 0,
+   validationErrors: 0,
+   priceChanges: [] as Array<{
+    sku: string;
+    type: string;
+    oldPrice?: number;
+    newPrice: number;
+   }>,
+   errors: [] as string[],
+  };
+   // ========================================
+   // STEP 5: FILE PROCESSING LOOP
+   // ========================================
+   // Process each file using service functions
+   for (const file of csvFiles) {
+    const filePath = file.path;
+    const fileName = file.name;
+    const fileStartTime = Date.now();
+    log.info('📄 [PriceSync] Processing file', { fileName });
+    // Duplicate prevention via file tracker
+    if (fileTracker && (await fileTracker.wasFileProcessed(fileName))) {
+     log.info('⏭️ [PriceSync] Skipping already processed file', { fileName });
+     results.skipped++;
+     continue;
+    }
+    try {
+    // SERVICE FUNCTION 1: Process file (S3 + CSV + Mapper)
+    const { records: mappedRecords, errors: mappingErrors } = await processFile(
+     s3,
+     parser,
+     mapper,
+     filePath,
+     fileName,
+     log
+    );
+    if (!mappedRecords.length) {
+     log.warn('No valid records after mapping, archiving', { fileName });
+     if (enableArchival) {
+      await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+     }
+     results.skipped++;
+     continue;
+    }
+    // SERVICE FUNCTION 2: Execute mutations
+    // ✅ Configuration with defaults
+    const mutationBatchSize = parseInt(
+     ctx.activation?.getVariable('mutationBatchSize') || '1', // ✅ Default: 1 (sequential)
+     10
+    );
+    const mutationsPerAliasBatch = ctx.activation?.getVariable('mutationsPerAliasBatch')
+     ? parseInt(ctx.activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+     : undefined; // ✅ Default: undefined (disabled, use separate requests)
+    // ? Enhanced: Extract context for progress logging
+    const sampleProductRefs = mappedRecords.slice(0, 5).map((r: any) => r.input?.skuRef || r.input?.productRef || 'unknown');
+    const mutationType = mapper?.mutationName || 'updatePrice';
+    // ? Enhanced: Start logging with context
+    log.info(`[GraphQLMutations] Sending price mutations for file "${fileName}"`, {
+     totalMutations: mappedRecords.length,
+     mutationType,
+     batchSize: mutationBatchSize,
+     batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
+     sampleProductRefs: sampleProductRefs.join(', '),
+     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled',
+     validateProducts
+    });
+    const mutationResult = await executeMutations(
+     client,
+     mapper,
+     mappedRecords,
+     retailerId,
+     validateProducts,
+     mutationBatchSize, // Concurrency control (default: 1)
+     mutationsPerAliasBatch, // ✅ NEW: Alias batching (default: undefined)
+     log
+    );
+    // ? Enhanced: Completion logging with summary
+    log.info(`[GraphQLMutations] Price mutation submission completed for file "${fileName}"`, {
+     totalMutations: mappedRecords.length,
+     successful: mutationResult.successful,
+     failed: mutationResult.failed,
+     successRate: mappedRecords.length > 0 ? `${Math.round((mutationResult.successful / mappedRecords.length) * 100)}%` : '0%',
+     mutationType,
+     priceChanges: mutationResult.priceChanges?.length || 0
+    });
+    // Aggregate results
+    results.processed++;
+    results.totalRecords += mappedRecords.length;
+    results.pricesUpdated += mutationResult.successful;
+    results.validationErrors += mappingErrors.length;
+    results.priceChanges.push(...mutationResult.priceChanges);
+    // Build file processing result for logging
+    const fileResult: FileProcessingResult = {
+     fileName,
+     successful: mutationResult.successful,
+     failed: mutationResult.failed,
+     validationFailed: mappingErrors.length,
+     priceChanges: mutationResult.priceChanges,
+     errors: mappingErrors,
+    };
+    // SERVICE FUNCTION 3: Write mutation log to S3
+    await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
+    // Mark processed with file tracker
+    if (fileTracker) {
+     await fileTracker.markFileProcessed(fileName, {
+      successful: mutationResult.successful,
+      failed: mutationResult.failed,
+      validationFailed: mappingErrors.length,
+      recordCount: mappedRecords.length,
+      duration: Date.now() - fileStartTime,
+     });
+    }
+    if (enableArchival) {
+     await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+    }
+    const fileDuration = Date.now() - fileStartTime;
+    log.info('✅ [PriceSync] File processed successfully', {
+     fileName,
+     recordCount: mappedRecords.length,
+     successful: mutationResult.successful,
+     failed: mutationResult.failed,
+     duration: `${fileDuration}ms`,
+    });
+    if (mappingErrors.length > 0) {
+     results.errors.push(`${fileName}: ${mappingErrors.length} mapping errors`);
+    }
+   } catch (error: unknown) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    const errorDetails = {
+     message: errorMsg,
+     stack: error instanceof Error ? error.stack : undefined,
+     errorType: error instanceof Error ? error.constructor.name : 'Error',
+    };
+    log.error('❌ [PriceSync] File processing failed', {
+     fileName,
+     ...errorDetails,
+    });
+    results.failed++;
+    results.errors.push(`${fileName}: ${errorMsg}`);
+    // Attempt to move to error directory
+    try {
+     await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
+     log.info('📁 [PriceSync] Moved failed file to error directory', { fileName });
+    } catch (moveError) {
+     log.error('❌ [PriceSync] Failed to move error file', {
+      fileName,
+      error: moveError instanceof Error ? moveError.message : String(moveError),
+     });
+    }
+   }
+  }
+   // ========================================
+   // STEP 6: SUMMARY & COMPLETION
+   // ========================================
+   const totalDuration = Date.now() - startTime;
+   const summary = {
+    success: true,
+    processed: results.processed,
+    skipped: results.skipped,
+    failed: results.failed,
+    totalRecords: results.totalRecords,
+    pricesUpdated: results.pricesUpdated,
+    pricesSkipped: results.pricesSkipped,
+    validationErrors: results.validationErrors,
+    priceChanges: results.priceChanges.length,
+    errors: results.errors.length > 0 ? results.errors : undefined,
+    duration: totalDuration,
+    timestamp: new Date().toISOString(),
+   };
+   log.info('🎉 [PriceSync] Price sync completed', {
+    ...summary,
+    duration: `${totalDuration}ms`,
+   });
+   // Log significant price changes
+   if (results.priceChanges.length > 0) {
+    log.info('💰 [PriceSync] Price changes detected', {
+     count: results.priceChanges.length,
+     changes: results.priceChanges.slice(0, 10),
+    });
+   }
+   return summary;
+  } catch (error: unknown) {
+   // ✅ Enhanced error logging: Extract all error details for visibility
+   const errorMsg = error instanceof Error ? error.message : String(error);
+   const errorDetails = {
+    message: errorMsg,
+    stack: error instanceof Error ? error.stack : undefined,
+    errorType: error instanceof Error ? error.constructor.name : 'Error',
+   };
+   log.error('❌ [PriceSync] Fatal error', errorDetails);
+   return {
+    success: false,
+    error: errorMsg,
+    recommendation: 'Check error logs for details and verify configuration',
+    processed: 0,
+    duration: Date.now() - startTime,
+    timestamp: new Date().toISOString(),
+   };
+  }
+ } catch (error: unknown) {
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  log.error('❌ [PriceSync] Initialization failed', {
+   error: errorMsg,
+   stack: error instanceof Error ? error.stack : undefined,
+  });
+  return {
+   success: false,
+   error: errorMsg,
+   recommendation: 'Check configuration and service initialization',
+   duration: Date.now() - startTime,
+  };
+ } finally {
+  // ✅ CRITICAL: Always dispose S3 connection to prevent connection pool exhaustion
+  if (s3) {
+   try {
+    await s3.dispose();
+    log.info('✅ [PriceSync] S3 connection disposed successfully');
+   } catch (disposeError: any) {
+    log.error('⚠️ [PriceSync] Failed to dispose S3 connection', {
+     error: disposeError instanceof Error ? disposeError.message : String(disposeError),
+     stack: disposeError instanceof Error ? disposeError.stack : undefined,
+    });
+    // Don't throw - disposal failure shouldn't prevent workflow completion
+   }
+  }
+ }
+}
+```
+**Note:** The `runPriceSync` function above should be renamed to `executePriceSync` and moved to `src/services/price-sync.service.ts` to match the new workflow structure.
+## Key Patterns Explained
+### Pattern 1: Service Function Architecture
+**Three modular service functions for clean separation of concerns:**
+```typescript
+// SERVICE FUNCTION 1: processFile()
+// Handles: S3 download + CSV parsing + field mapping
+const { records: mappedRecords, errors: mappingErrors } = await processFile(
+ s3,
+ parser,
+ mapper,
+ filePath,
+ fileName,
+ log
+);
+// SERVICE FUNCTION 2: executeMutations()
+// Handles: GraphQL mutations + product validation + concurrency control + price change tracking
+const mutationResult = await executeMutations(
+ client,
+ mapper,
+ mappedRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize,    // Concurrency control (default: 1)
+ mutationsPerAliasBatch,  // Alias batching (default: undefined)
+ log
+);
+// SERVICE FUNCTION 3: writeMutationLog()
+// Handles: Write execution log to S3 (with Buffer for Versori/Deno)
+await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
+```
+**Why this pattern?**
+- ✅ **Testability**: Each function can be unit tested independently
+- ✅ **Reusability**: Functions can be reused in different workflows
+- ✅ **Clarity**: Clear responsibilities for each step
+- ✅ **Error handling**: Isolated error boundaries per function
+- ✅ **Maintainability**: Easy to modify single concerns without affecting others
+### Pattern 2: Buffer Import for S3 Upload (Versori/Deno)
+**CRITICAL for Versori/Deno runtime:**
+```typescript
+// MUST import Buffer explicitly (not global like Node.js)
+import { Buffer } from 'node:buffer';
+// writeMutationLog() function
+async function writeMutationLog(s3, fileName, result, logPrefix, log) {
+ const logContent = JSON.stringify(logData, null, 2);
+ // ✅ CORRECT: Use Buffer.from() for S3 upload
+ await s3.uploadFile(logPath, logContent);
+ // ✅ CORRECT: uploadFile accepts string directly (no Buffer needed)
+ // await s3.uploadFile(logPath, logContent);
+}
+```
+**Why?** Deno runtime requires explicit `Buffer` import from `node:buffer`. Without it, you'll get `Buffer is not defined` errors.
+### Pattern 3: Direct KV State Management
+```typescript
+const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
+// Check if file already processed
+const stateKey = ['processed-files', 's3-price-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) {
+ log.info('Skipping already processed file', { fileName });
+ continue;
+}
+// Mark as processed after success
+await kv.set(stateKey, {
+ successful,
+ failed,
+ validationFailed,
+ processedAt: new Date().toISOString(),
+});
+```
+### Pattern 4: Custom Price Validation Resolvers
+```typescript
+const customResolvers = {
+ 'custom.validatePriceRange': (value: any) => {
+  const price = parseFloat(value);
+  if (isNaN(price)) {
+   throw new Error(`Invalid price: ${value}`);
+  }
+  if (price < minPrice) {
+   throw new Error(`Price ${price} below minimum ${minPrice}`);
+  }
+  if (price > maxPrice) {
+   throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
+  }
+  return price;
+ },
+ 'custom.normalizePriceType': (value: any) => {
+  const type = String(value || 'DEFAULT').toUpperCase().trim();
+  const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
+  if (!validTypes.includes(type)) {
+   throw new Error(`Invalid price type: ${type}`);
+  }
+  return type;
+ },
+};
+```
+**Why this matters**: Price data requires strict validation to prevent:
+- Negative prices
+- Prices outside business rules (too low/high)
+- Invalid price tiers
+- Data entry errors
+### Pattern 5: Product Existence Validation
+```typescript
+async function validateProductExists(
+ client: any,
+ productRef: string,
+ retailerId: string,
+ log: any
+): Promise<boolean> {
+ const query = `
+  query GetProduct($ref: String!, $retailerId: ID!) {
+   products(first: 1, ref: [$ref], retailerId: $retailerId) {
+    edges {
+     node {
+      id
+      ref
+      status
+     }
+    }
+   }
+  }
+ `;
+ const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
+ const product = result?.data?.products?.edges?.[0]?.node;
+ if (!product || product.status !== 'ACTIVE') {
+  return false;
+ }
+ return true;
+}
+```
+**Why this matters**: Prevents price updates for non-existent products, which would fail at GraphQL level.
+### Pattern 6: Price Change Tracking
+```typescript
+// Get current price before update
+const currentPrice = await getCurrentPrice(
+ client,
+ priceData.productRef,
+ priceData.type,
+ priceData.currency,
+ retailerId
+);
+// Track change after update
+if (currentPrice !== undefined && currentPrice !== priceData.value) {
+ results.priceChanges.push({
+  sku: priceData.productRef,
+  type: priceData.type,
+  oldPrice: currentPrice,
+  newPrice: priceData.value,
+ });
+}
+// Log changes at end
+if (results.priceChanges.length > 0) {
+ log.info('Price changes detected', {
+  count: results.priceChanges.length,
+  changes: results.priceChanges.slice(0, 10),
+ });
+}
+```
+**Why this matters**: Provides audit trail and monitoring for price changes.
+### Pattern 7: Concurrency Control & Alias Batching
+```typescript
+// ✅ Configuration with defaults
+const mutationBatchSize = parseInt(
+ activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
+ 10
+);
+const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+ ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+ : undefined; // Default: undefined (disabled)
+// Execute with bounded concurrency + optional alias batching
+const mutationResult = await executeMutations(
+ client,
+ mapper,
+ priceRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize,    // 1=sequential, 3-10=parallel
+ mutationsPerAliasBatch,  // Optional: Group mutations (e.g., 5)
+ log
+);
+```
+**Performance Modes:**
+- `mutationBatchSize: 1` → Sequential (safe default, ~1 mutation/sec)
+- `mutationBatchSize: 3-5` → Balanced (~3-5 mutations/sec)
+- `mutationBatchSize: 10` → High-volume (~10 mutations/sec)
+- `mutationsPerAliasBatch: 5` → Alias batching (reduces network overhead by ~80%)
+## Advanced: Multi-Currency Price Management
+### External Mapping File for Multi-Currency
+**File**: `config/price-mapping.json`
+```json
+{
+ "version": "1.0.0",
+ "description": "Multi-currency price mapping",
+ "fields": {
+  "productRef": {
+   "source": "sku",
+   "required": true,
+   "resolver": "sdk.trim"
+  },
+  "type": {
+   "source": "price_type",
+   "required": true,
+   "resolver": "custom.normalizePriceType"
+  },
+  "value": {
+   "source": "amount",
+   "required": true,
+   "resolver": "custom.validatePriceRange"
+  },
+  "currency": {
+   "source": "currency_code",
+   "required": true,
+   "resolver": "custom.normalizeCurrency"
+  },
+  "effectiveFrom": {
+   "source": "start_date",
+   "resolver": "sdk.formatDate"
+  },
+  "effectiveTo": {
+   "source": "end_date",
+   "resolver": "sdk.formatDate"
+  }
+ }
+}
+```
+### Custom Resolvers for Multi-Currency
+```typescript
+const customResolvers = {
+ 'custom.normalizeCurrency': (value: string) => {
+  // Normalize currency codes to ISO 4217
+  const currencyMap: Record<string, string> = {
+   usd: 'USD',
+   us: 'USD',
+   dollar: 'USD',
+   eur: 'EUR',
+   euro: 'EUR',
+   gbp: 'GBP',
+   pound: 'GBP',
+   cad: 'CAD',
+   aud: 'AUD',
+  };
+  const normalized = currencyMap[value.toLowerCase()] || value.toUpperCase();
+  // Validate against known currencies
+  const validCurrencies = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY', 'CNY'];
+  if (!validCurrencies.includes(normalized)) {
+   throw new Error(`Invalid currency code: ${value}`);
+  }
+  return normalized;
+ },
+ 'custom.convertToBaseCurrency': (value: any, sourceRecord: any) => {
+  // Convert foreign currency to base currency
+  const amount = parseFloat(value);
+  const currency = sourceRecord.currency_code;
+  // Exchange rates (in production, fetch from API)
+  const exchangeRates: Record<string, number> = {
+   USD: 1.0,
+   EUR: 0.85,
+   GBP: 0.73,
+   CAD: 1.35,
+   AUD: 1.45,
+  };
+  const rate = exchangeRates[currency?.toUpperCase()] || 1.0;
+  return amount * rate;
+ },
+ 'custom.buildPriceAttributes': (_: any, sourceRecord: any) => {
+  // Build price attributes array
+  const attributes: Array<{ name: string; type: string; value: any }> = [];
+  if (sourceRecord.cost_basis) {
+   attributes.push({
+    name: 'costBasis',
+    type: 'Float',
+    value: parseFloat(sourceRecord.cost_basis),
+   });
+  }
+  if (sourceRecord.margin_percent) {
+   attributes.push({
+    name: 'marginPercent',
+    type: 'Float',
+    value: parseFloat(sourceRecord.margin_percent),
+   });
+  }
+  if (sourceRecord.competitor_price) {
+   attributes.push({
+    name: 'competitorPrice',
+    type: 'Float',
+    value: parseFloat(sourceRecord.competitor_price),
+   });
+  }
+  if (sourceRecord.price_source) {
+   attributes.push({
+    name: 'priceSource',
+    type: 'String',
+    value: sourceRecord.price_source,
+   });
+  }
+  return attributes;
+ },
+};
+```
+## Schema Validation (Before Deployment)
+Use SDK CLI tools to validate your GraphQL schema and mapping configuration:
+```bash
+# Install SDK globally (or use npx)
+npm install -g @fluentcommerce/fc-connect-sdk
+# 1. Introspect Fluent GraphQL schema
+fc-connect introspect-schema \
+ --url https://api.fluentcommerce.com/graphql \
+ --client-id YOUR_CLIENT_ID \
+ --client-secret YOUR_CLIENT_SECRET \
+ --output fluent-schema.json
+# 2. Create mutation file (price-mutation.graphql)
+cat > price-mutation.graphql << 'EOF'
+mutation UpdateProductPrice($input: UpdateProductInput!) {
+ updateProduct(input: $input) {
+  id
+  ref
+  prices {
+   type
+   value
+   currency
+  }
+ }
+}
+EOF
+# 3. Generate mapping from mutation (validates structure)
+fc-connect generate-mutation-mapping \
+ --file price-mutation.graphql \
+ --output price-mapping.json
+# 4. Validate mapping against schema
+fc-connect validate-schema \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+# 5. Analyze field coverage
+fc-connect analyze-coverage \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+```
+**Output Example**:
+```bash
+✓ Schema validation passed
+✓ All required fields present: ref, retailerId, prices[].type, prices[].value, prices[].currency
+✓ Mutation structure matches GraphQL schema
+⚠ Optional fields not mapped: prices[].taxType, prices[].taxRate
+```
+## Testing the Workflow
+### 1. Upload Test CSV to S3
+```bash
+# Using AWS CLI
+aws s3 cp product-prices-test.csv s3://my-price-bucket/prices/
+# Or using S3 Console
+# Navigate to bucket → prices/ → Upload
+```
+### 2. Deploy to Versori
+```bash
+npm run deploy
+```
+### 3. Manual Testing via Webhook
+```bash
+curl -X POST https://your-workspace.versori.run/sync-prices-now \
+ -H "Content-Type: application/json"
+```
+### 4. Check Status
+```bash
+curl https://your-workspace.versori.run/check-status
+```
+### 5. Monitor Logs
+```bash
+npm run logs
+# Or via Versori dashboard
+```
+---
+## Monitoring
+### Success Response
+```json
+{
+ "success": true,
+ "filesProcessed": 1,
+ "filesSkipped": 0,
+ "filesFailed": 0,
+ "totalRecords": 100,
+ "mutationsExecuted": 100,
+ "mutationsFailed": 0,
+ "results": [
+  {
+   "file": "prices_2025-01-22.csv",
+   "success": true,
+   "recordsProcessed": 100,
+   "mutationsExecuted": 100,
+   "mutationsFailed": 0
+  }
+ ],
+ "duration": 12345
+}
+```
+### Partial Success Response
+```json
+{
+ "success": true,
+ "filesProcessed": 1,
+ "filesSkipped": 0,
+ "filesFailed": 0,
+ "totalRecords": 100,
+ "mutationsExecuted": 95,
+ "mutationsFailed": 5,
+ "results": [
+  {
+   "file": "prices_2025-01-22.csv",
+   "success": true,
+   "recordsProcessed": 100,
+   "mutationsExecuted": 95,
+   "mutationsFailed": 5,
+   "errors": ["PRICE-001: Invalid price value", "PRICE-002: Missing currency"]
+  }
+ ],
+ "duration": 12345
+}
+```
+### Error Response
+```json
+{
+ "success": false,
+ "filesProcessed": 0,
+ "filesFailed": 1,
+ "totalRecords": 0,
+ "mutationsExecuted": 0,
+ "mutationsFailed": 0,
+ "results": [
+  {
+   "file": "prices_2025-01-22.csv",
+   "success": false,
+   "error": "CSV parse error: Invalid structure"
+  }
+ ],
+ "duration": 876
+}
+```
+### Monitoring Metrics
+Monitor these metrics via Versori logs filtered by `jobId` or `stage`:
+- **Files Processed** - Total files successfully processed
+- **Mutations Executed** - Total GraphQL mutations executed successfully
+- **Mutations Failed** - Mutations that failed (check error logs)
+- **Processing Duration** - Time taken for complete workflow
+- **Rate Limiting** - Watch for 429 errors indicating GraphQL throttling
+Use the status webhook for dashboards and automated monitoring.
+---
+### Issue 1: Product Not Found
+**Error**: `Skipping price update for non-existent product: PROD-XYZ`
+**Solution**:
+- Verify product exists in Fluent Commerce
+- Check SKU matches exactly (case-sensitive)
+- Ensure product status is `ACTIVE`
+- Disable validation temporarily for testing: `validateProducts=false`
+### Issue 2: Price Validation Failures
+**Error**: `Price 0.00 below minimum 0.01`
+**Solution**:
+```bash
+# Adjust validation rules in activation variables
+minPrice=0.00 # Allow zero prices
+maxPrice=9999999.99 # Increase max
+```
+Or fix source data:
+```csv
+# ❌ WRONG
+PROD-001,DEFAULT,0,USD
+# ✅ CORRECT
+PROD-001,DEFAULT,0.01,USD
+```
+### Issue 3: Invalid Price Type
+**Error**: `Invalid price type: PROMO`
+**Solution**: Update custom resolver to include new type:
+```typescript
+'custom.normalizePriceType': (value: any) => {
+ const type = String(value || 'DEFAULT').toUpperCase().trim();
+ const validTypes = [
+  'DEFAULT',
+  'SALE',
+  'CLEARANCE',
+  'BULK',
+  'PROMOTIONAL',
+  'MEMBER',
+  'PROMO', // Add new type
+ ];
+ if (!validTypes.includes(type)) {
+  throw new Error(`Invalid price type: ${type}`);
+ }
+ return type;
+};
+```
+### Issue 4: Duplicate Price Updates
+**Symptom**: Same file processed multiple times
+**Solution**: VersoriKVAdapter already prevents this:
+```typescript
+const stateKey = ['processed-files', 's3-price-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) {
+ log.info('Skipping already processed file', { fileName });
+ continue;
+}
+```
+Verify KV storage is working:
+```bash
+# Check Versori logs for:
+[INFO] Skipping already processed file: product-prices-20250122-001.csv
+```
+### Issue 5: S3 Access Denied
+Required IAM Permissions:
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+  {
+   "Effect": "Allow",
+   "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+   "Resource": [
+    "arn:aws:s3:::my-price-bucket",
+    "arn:aws:s3:::my-price-bucket/*"
+   ]
+  }
+ ]
+}
+```
+### Issue 6: GraphQL Mutation Failures
+**Common Causes**:
+- Invalid price type (check Fluent schema for valid types)
+- Missing required fields (ref, retailerId, prices)
+- Invalid currency code (must be ISO 4217: USD, EUR, GBP)
+- Product not found or inactive
+**Debugging**:
+```typescript
+// Log mutation input before execution
+log.info('GraphQL mutation input', { input });
+// Validate required fields
+if (!priceData.productRef || !priceData.type || !priceData.value) {
+ log.error('Missing required fields', { priceData });
+ continue;
+}
+```
+## Production Checklist
+- [ ] S3 credentials validated with correct IAM permissions
+- [ ] Activation secrets stored securely (not in code)
+- [ ] GraphQL schema validated using CLI tools
+- [ ] Mapping configuration uses GraphQLMutationMapper structure (NOT UniversalMapper)
+- [ ] Mapping configuration tested with sample data
+- [ ] NO setRetailerId() call in code (only for Job/Event API)
+- [ ] Price validation rules configured per business policy
+- [ ] Product existence validation enabled (`validateProducts=true`)
+- [ ] File duplicate prevention working via KV state
+- [ ] Concurrency control configured (mutationBatchSize)
+- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
+- [ ] Error handling tested with malformed CSV
+- [ ] Retry logic tested with transient failures
+- [ ] File archival working (processed and error directories)
+- [ ] Price change tracking verified in logs
+- [ ] Monitoring/alerting configured for price update failures
+- [ ] Clear runbook for error recovery
+## Related Guides
+- **GraphQL Mutation Mapping**: `docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
+- **GraphQL Alias Batching**: `docs/02-CORE-GUIDES/mapping/graphql-alias-batching-guide.md`
+- **retailerId Configuration**: `docs/00-START-HERE/retailerid-configuration.md`
+- **CLI Tools**: `fc-connect-sdk/bin/readme.md`
+- **State & KV patterns**: `docs/03-PATTERN-GUIDES/file-operations/`
+- **Error handling**: `docs/03-PATTERN-GUIDES/error-handling/`