@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-json-location-graphql.md

@@ -1,1710 +1,1710 @@
----
-template_id: tpl-ingest-sftp-json-to-location-graphql
-canonical_filename: template-ingestion-sftp-json-location-graphql.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: sftp-json
-destination: fluent-graphql
-entity: location
-format: json
-logging: versori
-status: stable
-compliance: gold-standard
-features:
-  - graphql-mutation-mapper
-  - memory-management
-  - enhanced-logging
-  - attribute-transformation
-  - dispose-finally
----
-
-# Template: Ingestion - SFTP JSON to Location GraphQL
-
-**Deployment Target:** Versori Platform
-**Compliance Status:** ✅ GOLD STANDARD APPROVED
-
----
-
-## 📋 Implementation Prompt
-
-```
-I need a Versori scheduled ingestion that:
-
-1) Discovers JSON files on SFTP with file tracking to skip duplicates
-2) Downloads and parses JSON (locations array) with JSONParserService
-3) Transforms records with GraphQLMutationMapper (NOT UniversalMapper)
-4) Executes GraphQL createLocation mutations with rate limiting
-5) Archives files to processed/ or errors/ and writes error reports
-6) Tracks progress with JobTracker and exposes job status webhook
-7) Uses native Versori log and follows modular service architecture
-
-CRITICAL: This template uses GraphQLMutationMapper for GraphQL mutations,
-NOT UniversalMapper (which is for Batch API). Do NOT use setRetailerId()
-for GraphQL mutations - it's only needed for Job/Event API.
-
-Use the loaded docs to fill in SDK specifics and best practices.
-```
-
----
-
-## 📋 Template Overview
-
-This connector runs on the Versori platform with **gold standard compliance**. It reads location data from SFTP JSON files, transforms it with GraphQLMutationMapper, and creates/updates locations via GraphQL mutations.
-
-### What This Template Does
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│         INGESTION WORKFLOW (GraphQL Mutations Pattern)          │
-└─────────────────────────────────────────────────────────────────┘
-
-1. TRIGGER
-   ├─ Scheduled (Cron): Daily at 2 AM
-   ├─ Ad hoc (Webhook): Manual trigger
-   └─ Status Query (Webhook): Check progress
-
-2. DISCOVER FILES (SftpDataSource)
-   ├─ List files matching pattern
-   ├─ Check VersoriFileTracker (skip processed)
-   └─ Sort by oldest first
-
-3. DOWNLOAD & PARSE (LocationFileProcessorService)
-   ├─ Download from SFTP
-   ├─ Parse JSON with JSONParserService
-   ├─ Validate structure with type guards
-   └─ Return LocationRecord[]
-
-4. TRANSFORM (GraphQLMutationMapper)
-   ├─ Map to GraphQL CreateLocationInput
-   ├─ Handle nested objects (primaryAddress, openingSchedule)
-   ├─ Validate against GraphQL schema
-   └─ Generate mutation query
-
-5. EXECUTE MUTATIONS (MutationSenderService)
-   ├─ Execute createLocation mutations
-   ├─ Rate limiting (configurable concurrency)
-   ├─ Per-record error handling
-   └─ Track success/failure per mutation
-
-6. ARCHIVE & LOG
-   ├─ Move to processed/ or errors/
-   ├─ Write error reports
-   └─ Track state in VersoriFileTracker
-
-7. JOB TRACKING
-   ├─ Update job status at each step
-   └─ Enable status queries via webhook
-```
-
-### Key Features
-
-- ✅ **Gold Standard Compliant** - Modular architecture, proper patterns
-- ✅ **GraphQLMutationMapper** - Correct mapper for GraphQL mutations
-- ✅ **retailerId Configuration** - CRITICAL for GraphQL API calls
-- ✅ **Type-Safe** - Comprehensive TypeScript interfaces
-- ✅ **Modular Services** - 4 services + utils (testable, reusable)
-- ✅ **External Config** - Mapping in JSON file
-- ✅ **Error Handling** - Per-record failures don't block others
-- ✅ **File Tracking** - Prevents duplicate processing
-- ✅ **Job Tracking** - Status queries via webhook
-
----
-
-## 📦 SDK Imports
-
-```typescript
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno
-
-import {
-  createClient,
-  SftpDataSource,
-  JSONParserService,
-  GraphQLMutationMapper, // ✅ CRITICAL: Use this for GraphQL (NOT UniversalMapper)
-  VersoriFileTracker,
-  JobTracker,
-} from '@fluentcommerce/fc-connect-sdk';
-
-import type {
-  FluentClient,
-  FileMetadata,
-  Logger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-import { schedule, webhook, http, fn } from '@versori/run';
-```
-
-**✅ Type-Only Imports:** Separating value and type imports improves tree-shaking and bundle size.
-
----
-
----
-
-## SFTP Connection Setup (Recommended)
-
-**🔒 BEST PRACTICE:** Store SFTP credentials in a Versori connection object with Basic Auth:
-
-### Connection Configuration
-
-1. In Versori platform, create a connection named `SFTP`
-2. Set **Authentication Type**: `Basic Auth`
-3. Enter **Username**: Your SFTP username
-4. Enter **Password**: Your SFTP password
-5. The SDK will automatically retrieve and decode credentials
-
-### Code Implementation
-
-The workflow retrieves credentials programmatically from the Versori connection:
-
-```typescript
-import { Buffer } from 'node:buffer';
-
-// Retrieve SFTP credentials from connection configuration
-log.info('Retrieving SFTP credentials from connection configuration');
-
-let sftpUsername: string;
-let sftpPassword: string;
-
-try {
-  // Retrieve credentials from the 'SFTP' connection
-  const sftpCred = await ctx.credentials().getAccessToken('SFTP');
-
-  if (!sftpCred?.accessToken) {
-    throw new Error('No SFTP credentials found in connection configuration');
-  }
-
-  // Decode base64 accessToken to get "username:password"
-  const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
-
-  // Split on ':' to extract username and password
-  const parts = rawBasicAuth.split(':');
-
-  if (parts.length !== 2) {
-    throw new Error('Invalid SFTP credential format - expected username:password');
-  }
-
-  sftpUsername = parts[0];
-  sftpPassword = parts[1];
-
-  log.info('SFTP credentials retrieved successfully', {
-    hasUsername: !!sftpUsername,
-    hasPassword: !!sftpPassword,
-    usernameLength: sftpUsername.length,
-    passwordLength: sftpPassword.length,
-  });
-} catch (error: any) {
-  log.error('Failed to retrieve SFTP credentials', {
-    message: error instanceof Error ? error.message : String(error),
-    stack: error instanceof Error ? error.stack : undefined,
-    errorType: error instanceof Error ? error.constructor.name : 'Error'
-  });
-
-  return {
-    success: false,
-    error: 'Failed to retrieve SFTP credentials from connection configuration',
-    details: error?.message,
-    recommendation: 'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)',
-  };
-}
-
-// Use credentials in SftpDataSource
-const sftp = new SftpDataSource({
-  type: 'SFTP_JSON',
-  connectionId: 'sftp-location-sync',
-  name: 'Location Sync SFTP',
-  settings: {
-    host: activation.getVariable('sftpHost'),
-    port: parseInt(activation.getVariable('sftpPort') || '22', 10),
-    username: sftpUsername, // From connection
-    password: sftpPassword, // From connection
-    remotePath: activation.getVariable('sftpRemotePath'),
-    filePattern: activation.getVariable('filePattern'),
-    encoding: 'utf8',
-  },
-}, log);
-```
-
-### Why Use Connections Instead of Activation Variables?
-
-| Aspect | Activation Variables ❌ | Versori Connections ✅ |
-|--------|------------------------|------------------------|
-| **Security** | Plain text in config UI | Encrypted in Versori vault |
-| **Visibility** | Visible to all users | Controlled access |
-| **Rotation** | Manual update per workflow | Update once, affects all |
-| **Best Practice** | Legacy approach | **Recommended approach** |
-| **Audit Trail** | Limited | Full connection audit logs |
-
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Connection can be reused across workflows
-- ✅ No sensitive data in activation variables
-- ✅ Easier credential rotation (one place to update)
-- ✅ Better security posture (credentials never exposed in UI)
-
----
-
-## ⚙️ Activation Variables
-
-**Configuration is driven by activation variables - modify these instead of code:**
-
-> **Note:** `sftpUsername` and `sftpPassword` are fetched from the `SFTP` Basic Auth connection (see SFTP Connection Setup above).
-
-```bash
-# SFTP Configuration
-SFTP_HOST=sftp.partner.com
-SFTP_PORT=22
-
-# SFTP Paths
-SFTP_REMOTE_PATH=/locations/incoming
-SFTP_ARCHIVE_PATH=/locations/processed
-SFTP_ERROR_PATH=/locations/errors
-
-# File Processing
-FILE_PATTERN=locations_*.json
-MAX_FILES_PER_RUN=10
-
-# GraphQL Configuration
-FLUENT_RETAILER_ID=1                          # Optional: Only if mutation schema requires retailerId in input
-MAX_PARALLEL_MUTATIONS=10                     # Concurrent mutation limit (1=sequential, 3-10=parallel)
-
-# Feature Toggles
-REQUIRE_ABSOLUTE_PATHS=true                   # "true" for AWS Transfer Family, "false" for standard OpenSSH
-VALIDATE_CONNECTION=true                      # Validate SFTP connection on startup (default: true)
-ENABLE_FILE_TRACKING=true                     # Enable/disable file tracking (default: true)
-```
-
-**Security:**
-- **SFTP Authentication:** Credentials stored in Versori connection vault (not in activation variables). See [SFTP Connection Setup](#sftp-connection-setup-recommended) section above.
-- **Webhook Authentication:** Enforced by Versori connection configuration. Configure your webhook connection with API key authentication in the Versori Dashboard, then reference it in `webhook({ connection: 'webhook-auth' })`.
-
----
-
-## 📄 Mapping Configuration
-
-**File:** `src/config/location-mapping.json`
-
-**✅ PRODUCTION STANDARD:** External JSON file with GraphQLMutationMapper structure
-
-```json
-{
-  "mutation": "createLocation",
-  "sourceFormat": "json",
-  "version": "1.0.0",
-  "returnFields": ["id", "ref", "name", "type", "status"],
-  "arguments": {
-    "input": {
-      "ref": {
-        "source": "locationRef",
-        "required": true,
-        "resolver": "trim"
-      },
-      "name": {
-        "source": "locationName",
-        "required": true,
-        "resolver": "trim"
-      },
-      "type": {
-        "source": "locationType",
-        "required": true,
-        "resolver": "toUpperCase"
-      },
-      "status": {
-        "value": "ACTIVE",
-        "required": true
-      },
-      "primaryAddress": {
-        "ref": {
-          "source": "locationRef",
-          "required": true,
-          "resolver": "trim"
-        },
-        "street": {
-          "source": "address.street1",
-          "resolver": "trim"
-        },
-        "city": {
-          "source": "address.city",
-          "resolver": "trim"
-        },
-        "state": {
-          "source": "address.state",
-          "resolver": "toUpperCase"
-        },
-        "postcode": {
-          "source": "address.postalCode",
-          "resolver": "trim"
-        },
-        "country": {
-          "source": "address.country",
-          "resolver": "toUpperCase"
-        },
-        "latitude": {
-          "source": "geo.latitude",
-          "required": true,
-          "resolver": "parseFloat"
-        },
-        "longitude": {
-          "source": "geo.longitude",
-          "required": true,
-          "resolver": "parseFloat"
-        },
-        "timeZone": {
-          "source": "timeZone",
-          "resolver": "trim"
-        }
-      },
-      "openingSchedule": {
-        "allHours": {
-          "source": "openingSchedule.allHours",
-          "required": true,
-          "resolver": "toBoolean"
-        },
-        "monStart": {
-          "source": "openingSchedule.monStart",
-          "required": true,
-          "resolver": "parseInt"
-        },
-        "monEnd": {
-          "source": "openingSchedule.monEnd",
-          "required": true,
-          "resolver": "parseInt"
-        }
-      }
-    }
-  }
-}
-```
-
-**Key Differences from UniversalMapper:**
-- ✅ `mutation` property (not `mutationName`)
-- ✅ `arguments.input` structure (matches GraphQL schema)
-- ✅ Nested objects (not dotted paths like `primaryAddress.street`)
-- ✅ Resolver names without `sdk.` prefix (`trim`, `toUpperCase`, `parseInt`, `parseFloat`, `toBoolean`)
-- ✅ Used with `GraphQLMutationMapper.map()` method (not `UniversalMapper.map()`)
-
----
-
-## Expected JSON Format
-
-```json
-{
-  "locations": [
-    {
-      "locationRef": "LOC-001",
-      "locationName": "Main Warehouse",
-      "locationType": "WAREHOUSE",
-      "address": {
-        "street1": "123 Main St",
-        "city": "New York",
-        "state": "NY",
-        "postalCode": "10001",
-        "country": "US"
-      },
-      "geo": {
-        "latitude": 40.7128,
-        "longitude": -74.0060
-      },
-      "timeZone": "America/New_York",
-      "openingSchedule": {
-        "allHours": false,
-        "monStart": 480,
-        "monEnd": 1020
-      }
-    }
-  ]
-}
-```
-
-**Alternative:** Root array `[{...}]` is also supported.
-
----
-
-## 🔧 Production Code Structure
-
-### Modular Architecture (Gold Standard)
-
-```
-sftp-json-location-graphql/
-├── package.json
-├── tsconfig.json
-├── index.ts                                  # Entry point
-└── src/
-    ├── workflows/
-    │   └── location-ingestion.ts              # 3 workflows
-    ├── services/
-    │   ├── location-file-processor.service.ts # Download, parse, transform
-    │   ├── mutation-sender.service.ts         # Execute GraphQL mutations
-    │   ├── mutation-logger.service.ts         # Write error logs
-    │   └── location-ingestion.service.ts      # Main orchestration
-    ├── types/
-    │   └── location-ingestion.types.ts        # TypeScript interfaces
-    ├── utils/
-    │   ├── sftp-path.utils.ts                 # Path helpers
-    │   ├── retry.utils.ts                     # Retry logic
-    │   └── job-id-generator.ts                # Job IDs
-    └── config/
-        └── location-mapping.json              # GraphQL mapping config
-```
-
----
-
-## Critical Implementation Patterns
-
-### ✅ MUST HAVE: retailerId Configuration ⚠️ VERIFICATION REQUIRED
-
-```typescript
-// In main orchestration service (location-ingestion.service.ts)
-
-export async function executeLocationIngestion(ctx: VersoriContext, params: LocationIngestionParams) {
-  const { log, activation } = ctx;
-
-  // Step 1: Create client
-  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
-
-  // Step 2: Initialize GraphQLMutationMapper with client
-  import mappingConfig from '../config/location-mapping.json' with { type: 'json' };
-  const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-
-  // Step 3: Process files and execute mutations
-  // ... rest of workflow
-  
-  // ✅ 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, use separate requests)
-  
-  // ? Enhanced: Extract context for progress logging
-  const sampleLocationRefs = locations.slice(0, 5).map((loc: any) => loc.ref || loc.input?.ref || 'unknown');
-  const mutationType = mapper?.mutationName || 'createLocation';
-
-  // ? Enhanced: Start logging with context
-  log.info(`[GraphQLMutations] Sending mutations for locations`, {
-   totalMutations: locations.length,
-   mutationType,
-   batchSize: mutationBatchSize,
-   batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
-   sampleLocationRefs: sampleLocationRefs.join(', '),
-   aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled'
-  });
-
-  // Use in executeMutations:
-  const mutationResults = await mutationSender.executeMutations(
-    locations,
-    mutationBatchSize,  // Concurrency control (default: 1)
-    mutationsPerAliasBatch  // ✅ NEW: Alias batching (default: undefined)
-  );
-
-  // ? Enhanced: Completion logging with summary
-  log.info(`[GraphQLMutations] Mutation submission completed`, {
-   totalMutations: locations.length,
-   mutationsExecuted: mutationResults.mutationsExecuted,
-   mutationsFailed: mutationResults.mutationsFailed,
-   successRate: locations.length > 0 ? `${Math.round((mutationResults.mutationsExecuted / locations.length) * 100)}%` : '0%',
-   mutationType
-  });
-}
-```
-
-**✅ VERIFIED Pattern:**
-- GraphQL mutations do NOT need `client.setRetailerId()`
-- `setRetailerId()` is only for Job API and Event API
-- Pass retailerId in mutation input variables if schema requires it
-
-**Example (For mutations that require retailerId in schema):**
-```typescript
-// Only needed if mutation schema explicitly requires retailerId
-const fluentRetailerId = activation.getVariable('fluentRetailerId');
-const { query, variables } = await mapper.map(location);
-
-// Add to input if mutation schema requires it
-if (fluentRetailerId && variables.input) {
-  variables.input.retailer = { id: parseInt(fluentRetailerId) };
-}
-
-await client.graphql({ query, variables });
-```
-
-**Note:** Check your GraphQL schema (via introspection) to determine retailerId handling:
-1. Does the mutation have `retailerId` or `retailer.id` field?
-2. Is it mandatory (`!`) or optional?
-3. If field doesn't exist → don't pass it
-
-### ✅ MUST HAVE: Double-Finally SFTP Disposal
-
-**What:** Defensive resource cleanup with nested finally blocks (matches Event API gold standard)
-
-**Gold Standard Pattern:**
-
-```typescript
-// ✅ CRITICAL: Declare SFTP outside try block for safe disposal
-let sftp: SftpDataSource | undefined;
-
-try {
-  // 📊 Execution boundary: Start workflow
-  const startTime = Date.now();
-  log.info('🚀 Starting location ingestion workflow', {
-    stage: 'initialization',
-    jobId,
-    triggeredBy: params.triggeredBy
-  });
-
-  // Initialize SFTP
-  sftp = new SftpDataSource(...);
-
-  // ✅ Validate connection (if enabled)
-  const validateConnection = activation?.getVariable('validateConnection') === 'true';
-  if (validateConnection) {
-    log.info('🔌 Validating SFTP connection', { stage: 'connection_validation' });
-    await sftp.validateConnection();
-    log.info('✅ SFTP connection validated successfully');
-  }
-
-  try {
-    // Use SFTP
-    await sftp.listFiles(...);
-    await sftp.downloadFile(...);
-    // ... rest of workflow
-
-    // 📊 Execution boundary: End workflow
-    const duration = Date.now() - startTime;
-    log.info('✅ Location ingestion workflow completed', {
-      stage: 'completion',
-      jobId,
-      duration,
-      filesProcessed,
-      mutationsExecuted
-    });
-  } finally {
-    // Inner finally - normal cleanup
-    if (sftp) {
-      await sftp.dispose();
-      log.info('🔌 SFTP connection disposed');
-    }
-  }
-} catch (error: unknown) {
-  // ✅ Enhanced error logging: Extract all error details + recommendations
-  const errorMessage = error instanceof Error ? error.message : String(error);
-  const errorDetails = {
-    message: errorMessage,
-    stack: error instanceof Error ? error.stack : undefined,
-    errorType: error instanceof Error ? error.constructor.name : 'Error',
-    stage: 'workflow_execution',
-    jobId
-  };
-
-  // ✅ Add error recommendations
-  const recommendations: string[] = [];
-  if (errorMessage.includes('ECONNREFUSED')) {
-    recommendations.push('Check SFTP host and port configuration');
-    recommendations.push('Verify network connectivity to SFTP server');
-  } else if (errorMessage.includes('Authentication failed')) {
-    recommendations.push('Verify SFTP username and password');
-    recommendations.push('Check if account is locked or expired');
-  } else if (errorMessage.includes('No such file')) {
-    recommendations.push('Verify incoming path exists on SFTP server');
-    recommendations.push('Check file pattern matches existing files');
-  }
-
-  log.error('❌ Workflow failed', { ...errorDetails, recommendations });
-
-  // Handle error (mark job failed, etc.)
-} finally {
-  // Outer finally - defensive cleanup
-  // ⚠️ CRITICAL: Ensures disposal even if error occurs after SFTP creation
-  // but before inner try block (e.g., during connection validation)
-  if (sftp) {
-    try {
-      await sftp.dispose();
-      log.info('🔌 SFTP connection disposed (outer finally)');
-    } catch (disposeError: unknown) {
-      const disposeErrorMessage = disposeError instanceof Error
-        ? disposeError.message
-        : String(disposeError);
-      log.warn('⚠️ Error disposing SFTP in outer finally', { error: disposeErrorMessage });
-    }
-  }
-}
-```
-
-**Why This is Critical:**
-- Ensures disposal even if error occurs after SFTP creation but before inner try block
-- Defensive cleanup catches edge cases
-- Prevents resource leaks in error scenarios
-- Matches Event API gold standard pattern
-
----
-
-## Processing Modes
-
-**⚠️ IMPORTANT:** Choose ONE processing mode per connector. These are alternative patterns, not features to use together.
-
-The SDK supports two processing modes for handling multiple files. **Select the mode that best fits your use case** and configure your connector accordingly:
-
-### Mode 1: Per-File Processing (Recommended Default) ✅ IMPLEMENTED
-
-**When to use:**
-- Multiple large files that shouldn't be in memory together
-- Need file-level consistency (file 3 fails → files 1-2 already archived)
-- Clear error isolation per file
-
-**How it works:**
-1. Process file 1 completely (download → parse → transform → execute mutations → archive)
-2. Move to file 2
-3. Continue sequentially
-
-**Benefits:**
-- ✅ Low memory usage (one file at a time)
-- ✅ Clear error isolation (failed file doesn't block others)
-- ✅ Incremental progress (files archived as completed)
-
-**Example implementation (see code section below)**
-
-### Mode 2: Chunked Per-File Processing ⚠️ OPTIONAL - Choose if needed
-
-**When to use:**
-- Many small files that can be processed in parallel
-- Need better throughput for many files
-- Files are independent (no cross-file dependencies)
-
-**How it works:**
-1. Group files into chunks (e.g., 5 files per chunk)
-2. Process chunk 1 files in parallel
-3. Wait for chunk completion, then move to chunk 2
-
-**Benefits:**
-- ✅ Better throughput (parallel processing)
-- ✅ Still maintains file-level isolation
-- ✅ Configurable chunk size
-
-**Note:** GraphQL mutations are typically one-off operations, so per-file processing is usually sufficient. Chunked mode is optional for high-volume scenarios.
-
----
-
-## Key Service Patterns
-
-### Service 1: Location File Processor (Complete Implementation)
-
-**File:** `src/services/location-file-processor.service.ts`
-
-```typescript
-/**
- * Location File Processor Service
- *
- * Downloads JSON files from SFTP, parses content, and transforms with GraphQLMutationMapper.
- * Reusable service for location file processing workflows.
- */
-
-import {
-  SftpDataSource,
-  JSONParserService,
-  GraphQLMutationMapper,
-} from '@fluentcommerce/fc-connect-sdk';
-import type {
-  ProcessFileResult,
-  LocationRecord,
-} from '../types/location-ingestion.types';
-import { extractFileName } from '../utils/sftp-path.utils';
-
-/**
- * Location file processing service
- * Coordinates SFTP download, JSON parsing (via SDK), and GraphQL mutation generation
- */
-export class LocationFileProcessorService {
-  constructor(
-    private sftp: SftpDataSource,
-    private jsonParser: JSONParserService,
-    private mapper: GraphQLMutationMapper
-  ) {} // ✅ No logger param - workflow handles logging
-
-  /**
-   * Download JSON file from SFTP, parse, and generate GraphQL mutations
-   */
-  async downloadParseAndTransform(remoteFilePath: string): Promise<ProcessFileResult> {
-    // ✅ Extract filename for logging
-    const fileName = extractFileName(remoteFilePath);
-
-    try {
-      // Download JSON content
-      const content = (await this.sftp.downloadFile(remoteFilePath, {
-        encoding: 'utf8',
-      })) as string;
-
-      // Parse JSON with type safety
-      let parsed: unknown;
-      try {
-        parsed = await this.jsonParser.parse(content);
-      } catch (parseError: unknown) {
-        const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
-        return {
-          success: false,
-          locations: [],
-          error: `JSON parse error: ${errorMessage}`,
-          fileName,
-        };
-      }
-
-      // Normalize locations array (handle both { locations: [...] } and root array formats)
-      const jsonData = parsed as Record<string, unknown>;
-      const locations = jsonData.locations
-        ? (Array.isArray(jsonData.locations) ? jsonData.locations : [jsonData.locations])
-        : (Array.isArray(jsonData) ? jsonData : []);
-
-      if (locations.length === 0) {
-        return {
-          success: false,
-          locations: [],
-          error: 'No locations found in JSON',
-          fileName,
-        };
-      }
-
-      // Validate with type guard
-      const validLocations = locations.filter(isLocationRecord);
-
-      if (validLocations.length === 0) {
-        return {
-          success: false,
-          locations: [],
-          error: 'No valid locations found after validation',
-          fileName,
-        };
-      }
-
-      // Transform with GraphQLMutationMapper
-      const mapped = await Promise.all(
-        validLocations.map(loc => this.mapper.map(loc))
-      );
-
-      return {
-        success: true,
-        locations: mapped.map(m => m.variables.input),
-        fileName,
-      };
-    } catch (error: unknown) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      return {
-        success: false,
-        locations: [],
-        error: errorMessage,
-        fileName,
-      };
-    }
-  }
-}
-
-/**
- * Type guard: Check if parsed value is a valid LocationRecord
- */
-function isLocationRecord(obj: unknown): obj is LocationRecord {
-  if (typeof obj !== 'object' || obj === null) return false;
-  const loc = obj as Record<string, unknown>;
-
-  return (
-    typeof loc.locationRef === 'string' &&
-    typeof loc.locationName === 'string' &&
-    typeof loc.locationType === 'string' &&
-    typeof loc.address === 'object' &&
-    loc.address !== null &&
-    typeof loc.geo === 'object' &&
-    loc.geo !== null
-  );
-}
-```
-
-### Service 2: Mutation Sender (Complete Implementation)
-
-**File:** `src/services/mutation-sender.service.ts`
-
-```typescript
-/**
- * Mutation Sender Service
- *
- * Executes GraphQL mutations with per-record error handling.
- * Continues processing on individual failures (GraphQL mutation pattern).
- */
-
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-import type { MutationResult, MappedLocation } from '../types/location-ingestion.types';
-
-/**
- * Service for executing GraphQL mutations
- */
-export class MutationSenderService {
-  constructor(
-    private client: FluentClient,
-    private mapper: GraphQLMutationMapper
-  ) {}
-
-  /**
-   * Execute GraphQL mutations with configurable concurrency and alias batching
-   *
-   * **Performance Characteristics:**
-   * - `maxParallel: 1` → Sequential processing (safe default, ~1 mutation/sec)
-   * - `maxParallel: 3-5` → Balanced throughput (~3-5 mutations/sec)
-   * - `maxParallel: 10` → High-volume processing (~10 mutations/sec, 100+ locations)
-   *
-   * **Implementation Strategy:**
-   * - Sequential (1): Optimized loop (no Promise.allSettled overhead)
-   * - Parallel (>1): Chunked processing with bounded concurrency
-   * - Alias batching: Groups mutations into aliased GraphQL requests (reduces network overhead)
-   * - Both modes: Per-record error tracking (failures don't block others)
-   *
-   * **Alias Batching:**
-   * - When `mutationsPerAliasBatch > 1`, groups mutations into aliased requests
-   * - Example: 5 mutations → 1 HTTP request with aliases (createLocation1, createLocation2, ...)
-   * - Reduces network overhead by ~80% for high-volume scenarios
-   *
-   * @param locations - Array of mapped locations to create/update
-   * @param maxParallel - Number of concurrent mutations or alias batches (default: 1, min: 1)
-   * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (default: undefined = disabled)
-   * @returns MutationResult with counts (mutationsExecuted/mutationsFailed) and error details
-   */
-  async executeMutations(
-    locations: MappedLocation[],
-    maxParallel: number = 1,  // ✅ Default: 1 (sequential)
-    mutationsPerAliasBatch?: number  // ✅ NEW: Alias batching parameter (default: undefined = disabled)
-  ): Promise<MutationResult> {
-    // Determine mode: use aliases if mutationsPerAliasBatch is set and > 1
-    const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
-    
-    if (useAliases) {
-      return await this.executeMutationsWithAliases(
-        locations,
-        maxParallel,
-        mutationsPerAliasBatch!
-      );
-    } else {
-      return await this.executeMutationsSeparate(locations, maxParallel);
-    }
-  }
-
-  /**
-   * Execute mutations using separate concurrent requests (current mode)
-   */
-  private async executeMutationsSeparate(
-    locations: MappedLocation[],
-    maxParallel: number
-  ): Promise<MutationResult> {
-    // Validate concurrency (guard against invalid values)
-    const safeConc = Math.max(1, Math.floor(maxParallel));
-
-    // Result accumulators
-    let mutationsExecuted = 0;
-    let mutationsFailed = 0;
-    const errors: Array<{ locationRef: string; error: string }> = [];
-
-    // ============================================================================
-    // SEQUENTIAL MODE (maxParallel === 1)
-    // ============================================================================
-    if (safeConc === 1) {
-      for (const location of locations) {
-        try {
-          const { query, variables } = await this.mapper.map(location);
-          await this.client.graphql({ query, variables });
-          mutationsExecuted++;
-        } catch (err: unknown) {
-          mutationsFailed++;
-          const errorMsg = err instanceof Error ? err.message : String(err);
-          errors.push({
-            locationRef: location.ref || 'unknown',
-            error: errorMsg,
-          });
-          // Continue processing (failure doesn't block other locations)
-        }
-      }
-      return { mutationsExecuted, mutationsFailed, errors };
-    }
-
-    // ============================================================================
-    // PARALLEL MODE (maxParallel > 1)
-    // ============================================================================
-    // Chunked processing with bounded concurrency
-    for (let i = 0; i < locations.length; i += safeConc) {
-      const chunk = locations.slice(i, i + safeConc);
-
-      // Fire all mutations in chunk concurrently
-      const results = await Promise.allSettled(
-        chunk.map(async (location) => {
-          const { query, variables } = await this.mapper.map(location);
-          return await this.client.graphql({ query, variables });
-        })
-      );
-
-      // Aggregate chunk results
-      results.forEach((result, idx) => {
-        if (result.status === 'fulfilled') {
-          mutationsExecuted++;
-        } else {
-          mutationsFailed++;
-          const error = result.reason;
-          errors.push({
-            locationRef: chunk[idx]?.ref || 'unknown',
-            error: error?.message || String(error) || 'Unknown error',
-          });
-        }
-      });
-
-      // Small delay between batches to avoid rate limiting
-      if (i + safeConc < locations.length) {
-        await new Promise(resolve => setTimeout(resolve, 100));
-      }
-    }
-
-    return { mutationsExecuted, mutationsFailed, errors };
-  }
-
-  /**
-   * ✅ NEW: Execute mutations using GraphQL aliases (batched requests)
-   *
-   * Groups mutations into alias batches and executes them with concurrency control.
-   * Each aliased request contains multiple mutations identified by alias names.
-   *
-   * @param locations - Array of mapped locations
-   * @param maxParallel - Number of concurrent alias batch requests
-   * @param mutationsPerAliasBatch - Number of mutations per aliased request
-   * @returns Mutation execution results
-   */
-  private async executeMutationsWithAliases(
-    locations: MappedLocation[],
-    maxParallel: number,
-    mutationsPerAliasBatch: number
-  ): Promise<MutationResult> {
-    const results: MutationResult = { mutationsExecuted: 0, mutationsFailed: 0, errors: [] };
-    
-    // Extract mutation name from mapper config
-    const mutationName = (this.mapper as any).config.mutation || 'createLocation';
-    
-    // Group locations into alias batches
-    const aliasBatches: Array<MappedLocation[]> = [];
-    for (let i = 0; i < locations.length; i += mutationsPerAliasBatch) {
-      aliasBatches.push(locations.slice(i, i + mutationsPerAliasBatch));
-    }
-    
-    // Process batches with concurrency control
-    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) => {
-          // Build aliased query and variables
-          const { query, variables } = await this.buildAliasedBatch(batch, mutationName);
-          
-          // Execute aliased mutation
-          const response = await this.client.graphql({ query, variables });
-          
-          // Parse results and errors
-          return this.parseAliasResponse(response, batch, mutationName);
-        })
-      );
-      
-      // Aggregate results
-      batchResults.forEach((result, idx) => {
-        if (result.status === 'fulfilled') {
-          const batchResult = result.value;
-          results.mutationsExecuted += batchResult.executed;
-          results.mutationsFailed += batchResult.failed;
-          results.errors.push(...batchResult.errors);
-        } else {
-          // Entire batch failed
-          const batch = concurrentBatches[idx];
-          const errorMsg = result.reason instanceof Error ? result.reason.message : String(result.reason);
-          batch.forEach(loc => {
-            results.mutationsFailed++;
-            results.errors.push({
-              locationRef: loc.ref || 'unknown',
-              error: `Batch execution failed: ${errorMsg}`
-            });
-          });
-        }
-      });
-      
-      // Add small delay between concurrent batches to respect rate limits
-      if (i + maxParallel < aliasBatches.length) {
-        await new Promise(resolve => setTimeout(resolve, 500));
-      }
-    }
-    
-    return results;
-  }
-
-  /**
-   * ✅ NEW: Build aliased batch query and variables
-   *
-   * @param batch - Array of location objects
-   * @param mutationName - GraphQL mutation name (e.g., 'createLocation')
-   * @returns GraphQL query and variables for aliased batch
-   */
-  private async buildAliasedBatch(
-    batch: MappedLocation[],
-    mutationName: string
-  ): Promise<{ query: string; variables: Record<string, any> }> {
-    const batchSize = batch.length;
-    const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
-    
-    // Build aliased query (simple naming: mutationName + index)
-    const variables = Array.from({ length: batchSize }, (_, i) => 
-      `$input${i + 1}: ${inputTypeName}!`
-    ).join(', ');
-    
-    const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
-      const alias = `${mutationName}${i + 1}`;  // Simple: createLocation1, createLocation2, etc.
-      return `  ${alias}: ${mutationName}(input: $input${i + 1}) { id ref name }`;
-    }).join('\n');
-    
-    const operationName = `Batch${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}s`;
-    const query = `mutation ${operationName}(${variables}) {\n${aliasedMutations}\n}`;
-    
-    // Build variables from mapped locations (await all mappings)
-    const mappedItems = await Promise.all(
-      batch.map(loc => this.mapper.map(loc))
-    );
-    
-    const variablesObj: Record<string, unknown> = {};
-    mappedItems.forEach((mapped, index) => {
-      const input = mapped.variables.input || mapped.variables;
-      variablesObj[`input${index + 1}`] = input;
-    });
-    
-    return { query, variables: variablesObj };
-  }
-
-  /**
-   * ✅ NEW: Parse aliased GraphQL response and extract individual mutation results
-   *
-   * @param response - GraphQL response from aliased mutation
-   * @param batch - Original batch of location objects
-   * @param mutationName - GraphQL mutation name (e.g., 'createLocation')
-   * @returns Parsed results with executed/failed counts and errors
-   */
-  private parseAliasResponse(
-    response: { data?: Record<string, unknown>; errors?: Array<{ path?: string[]; message: string }> },
-    batch: MappedLocation[],
-    mutationName: string
-  ): { executed: number; failed: number; errors: Array<{ locationRef: string; error: string }> } {
-    const result = { executed: 0, failed: 0, errors: [] as Array<{ locationRef: string; error: string }> };
-
-    const data = response.data || {};
-    const errors = response.errors || [];
-
-    // Process each alias result
-    batch.forEach((loc, index) => {
-      const alias = `${mutationName}${index + 1}`;  // Simple: createLocation1, createLocation2, etc.
-      const aliasData = data[alias];
-      const aliasErrors = errors.filter((e) =>
-        e.path && Array.isArray(e.path) && e.path.includes(alias)
-      );
-      
-      if (aliasData && !aliasErrors.length) {
-        result.executed++;
-      } else {
-        result.failed++;
-        const errorMsg = aliasErrors[0]?.message || 'Mutation failed';
-        const locationRef = loc.ref || 'unknown';
-        result.errors.push({
-          locationRef,
-          error: errorMsg,
-        });
-      }
-    });
-    
-    return result;
-  }
-}
-```
-
-### Service 3: Mutation Logger (Complete Implementation)
-
-**File:** `src/services/mutation-logger.service.ts`
-
-```typescript
-/**
- * Mutation Logger Service
- *
- * Writes mutation processing logs to SFTP for audit purposes.
- * Log writing failures don't stop the workflow (non-critical).
- */
-
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-import type { MutationResult } from '../types/location-ingestion.types';
-
-/**
- * Service for writing mutation logs to SFTP
- */
-export class MutationLoggerService {
-  constructor(private sftp: SftpDataSource) {}
-
-  /**
-   * Write mutation processing log to SFTP
-   *
-   * Creates JSON log file with mutation results.
-   * Only write logs when there are failures (optional).
-   *
-   * Returns log file path on success, or throws on critical errors.
-   */
-  async writeMutationLog(
-    fileName: string,
-    result: MutationResult,
-    remotePath: string,
-    requireAbsolutePaths: boolean
-  ): Promise<string> {
-    const timestamp = new Date().toISOString();
-    const logContent = JSON.stringify(
-      {
-        fileName,
-        timestamp,
-        mutationsExecuted: result.mutationsExecuted,
-        mutationsFailed: result.mutationsFailed,
-        errors: result.errors,
-      },
-      null,
-      2
-    );
-
-    const logFileName = `${fileName.replace(/\.json$/i, '')}-mutations-${timestamp.replace(/[:.]/g, '-')}.json`;
-
-    const logPath =
-      requireAbsolutePaths && !remotePath.startsWith('/')
-        ? `/${remotePath}/${logFileName}`.replace(/\/+/g, '/')
-        : `${remotePath}/${logFileName}`.replace(/\/+/g, '/');
-
-    await this.sftp.uploadFile(logPath, logContent);
-
-    return logPath; // Return path for workflow logging
-  }
-}
-```
-
----
-
-## Type Definitions
-
-**File:** `src/types/location-ingestion.types.ts`
-
-```typescript
-export interface LocationRecord {
-  locationRef: string;
-  locationName: string;
-  locationType: string;
-  address: {
-    street1: string;
-    city: string;
-    state: string;
-    postalCode: string;
-    country: string;
-  };
-  geo: {
-    latitude: number;
-    longitude: number;
-  };
-  timeZone: string;
-  openingSchedule: {
-    allHours: boolean;
-    monStart: number;
-    monEnd: number;
-    // ... other schedule fields
-  };
-}
-
-export interface MappedLocation {
-  ref: string;
-  name: string;
-  type: string;
-  status: string;
-  primaryAddress: {
-    ref: string;
-    street?: string;
-    city?: string;
-    latitude: number;
-    longitude: number;
-  };
-  openingSchedule: {
-    allHours: boolean;
-    monStart: number;
-    monEnd: number;
-  };
-}
-
-export interface MutationResult {
-  mutationsExecuted: number;
-  mutationsFailed: number;
-  errors: Array<{ locationRef: string; error: string }>;
-}
-
-export interface ProcessFileResult {
-  success: boolean;
-  locations: Array<{ query: string; variables: Record<string, unknown> }>;
-  error?: string;
-  fileName: string;
-}
-
-// Type guard for validation
-export function isLocationRecord(obj: unknown): obj is LocationRecord {
-  if (typeof obj !== 'object' || obj === null) return false;
-  const loc = obj as Record<string, unknown>;
-
-  return (
-    typeof loc.locationRef === 'string' &&
-    typeof loc.locationName === 'string' &&
-    typeof loc.locationType === 'string' &&
-    typeof loc.address === 'object' &&
-    typeof loc.geo === 'object'
-  );
-}
-```
-
----
-
----
-
-## 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
-
-```
-sftp-json-location-graphql/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-location-sync.ts   # Scheduled: Daily location sync
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-location-sync.ts   # Webhook: Manual trigger
-    │       └── job-status-check.ts     # Webhook: Status query
-    │
-    ├── services/
-    │   └── location-sync.service.ts     # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── location-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-location-sync.ts`
-
-**Purpose**: Automatic daily location sync
-**Trigger**: Cron schedule (`0 2 * * *`)
-**Exposed as Endpoint**: ❌ NO - Runs automatically
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { executeLocationIngestion } from '../../services/location-sync.service';
-import { generateJobId } from '../../utils/job-id-generator';
-
-/**
- * Scheduled Workflow: Daily Location Sync
- *
- * Runs automatically daily at 2 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Uses shared service: location-sync.service.ts
- */
-export const dailyLocationSync = schedule(
-  'location-sync-scheduled',
-  '0 2 * * *' // Daily at 2 AM UTC
-).then(
-  http('run-location-sync', { connection: 'fluent_commerce' }, async ctx => {
-    const jobId = generateJobId('SCHEDULED', 'LOC');
-    return await executeLocationIngestion(ctx, { jobId, triggeredBy: 'schedule' });
-  })
-);
-```
-
----
-
-### 2. Webhook Workflows (`src/workflows/webhook/`)
-
-All HTTP-based triggers that create webhook endpoints.
-
-#### `src/workflows/webhook/adhoc-location-sync.ts`
-
-**Purpose**: Manual location sync trigger (on-demand)
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/location-sync-adhoc`
-**Use Cases**: Testing, priority processing, ad-hoc runs
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { executeLocationIngestion } from '../../services/location-sync.service';
-import { generateJobId } from '../../utils/job-id-generator';
-
-/**
- * Webhook: Manual Location Sync Trigger
- *
- * Endpoint: POST https://{workspace}.versori.run/location-sync-adhoc
- * Request body (optional): { filePattern: "urgent_*.json", maxFiles: 5, forceReprocess: true }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: location-sync.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const adhocLocationSync = webhook('location-sync-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'location-sync-adhoc', // Versori validates API key
-}).then(
-  http('run-location-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
-    const jobId = generateJobId('ADHOC', 'LOC');
-    const { filePattern, maxFiles, forceReprocess } = ctx.data;
-    return await executeLocationIngestion(ctx, {
-      jobId,
-      triggeredBy: 'manual',
-      filePattern,
-      maxFiles,
-      forceReprocess,
-    });
-  })
-);
-```
-
----
-
-#### `src/workflows/webhook/job-status-check.ts`
-
-**Purpose**: Query job status and progress
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/location-sync-job-status`
-**Request Body**: `{ "jobId": "SCHEDULED_LOC_20250124_183045_abc123" }`
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { getJobStatus } from '../../services/location-sync.service';
-
-/**
- * Webhook: Job Status Check
- *
- * Endpoint: POST https://{workspace}.versori.run/location-sync-job-status
- * Request body: { "jobId": "SCHEDULED_LOC_20250124_183045_abc123" }
- *
- * 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 locationSyncJobStatus = webhook('location-sync-job-status', {
-  response: { mode: 'sync' },
-  connection: 'location-sync-job-status',
-}).then(
-  fn('query-job-status', async ctx => {
-    const { jobId } = ctx.data;
-    const status = await getJobStatus(ctx.openKv(':project:'), jobId, ctx.log);
-    return { success: !!status, jobId, ...status };
-  })
-);
-```
-
----
-
-### 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 { MemoryInterpreter } from '@versori/run';
-
-// Import scheduled workflows
-import { dailyLocationSync } from './src/workflows/scheduled/daily-location-sync';
-
-// Import webhook workflows
-import { adhocLocationSync } from './src/workflows/webhook/adhoc-location-sync';
-import { locationSyncJobStatus } from './src/workflows/webhook/job-status-check';
-
-// Register all workflows
-export {
-  // Scheduled (time-based triggers)
-  dailyLocationSync,
-
-  // Webhooks (HTTP-based triggers)
-  adhocLocationSync,
-  locationSyncJobStatus,
-};
-
-// ✅ Memory interpreter for local development
-export const interpreter = new MemoryInterpreter({
-  workflows: [dailyLocationSync, adhocLocationSync, locationSyncJobStatus],
-});
-```
-
-**What Gets Exposed:**
-- ✅ `adhocLocationSync` → `https://{workspace}.versori.run/location-sync-adhoc`
-- ✅ `locationSyncJobStatus` → `https://{workspace}.versori.run/location-sync-job-status`
-- ❌ `dailyLocationSync` → NOT exposed (runs automatically on cron)
-
----
-
-## Package Configuration
-
-**File:** `package.json`
-
-```json
-{
-  "name": "sftp-json-location-graphql",
-  "type": "module",
-  "main": "index.ts",
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  }
-}
-```
-
-**File:** `tsconfig.json`
-
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
-
----
-
-## Deployment
-
-```bash
-# 1. Install dependencies
-npm install
-
-# 2. Deploy to Versori
-npm run deploy
-
-# 3. Configure activation variables in Versori Dashboard
-# CRITICAL: Set fluentRetailerId
-
-# 4. Test with sample file
-curl -X POST https://your-workspace.versori.run/location-ingestion-adhoc \
-  -H "Content-Type: application/json" \
-  -d '{"forceReprocess": false}'
-```
-
----
-
-## Testing
-
-### Test Scheduled Run
-Upload test JSON to SFTP and wait for scheduled execution (2 AM daily).
-
-### Test Ad hoc Trigger
-```bash
-curl -X POST https://workspace.versori.run/location-ingestion-adhoc \
-  -d '{"filePattern": "test_*.json"}'
-```
-
-### Test Job Status
-```bash
-curl -X POST https://workspace.versori.run/location-ingestion-job-status \
-  -d '{"jobId": "ADHOC_LOC_20251101_183045_abc123"}'
-```
-
----
-
-## Monitoring
-
-### Success Response
-
-```json
-{
-  "success": true,
-  "filesProcessed": 1,
-  "filesSkipped": 0,
-  "filesFailed": 0,
-  "totalRecords": 50,
-  "mutationsExecuted": 50,
-  "mutationsFailed": 0,
-  "results": [
-    {
-      "file": "locations_2025-01-22.json",
-      "success": true,
-      "recordsProcessed": 50,
-      "mutationsExecuted": 50,
-      "mutationsFailed": 0
-    }
-  ],
-  "duration": 12345
-}
-```
-
-### Partial Success Response
-
-```json
-{
-  "success": true,
-  "filesProcessed": 1,
-  "filesSkipped": 0,
-  "filesFailed": 0,
-  "totalRecords": 50,
-  "mutationsExecuted": 45,
-  "mutationsFailed": 5,
-  "results": [
-    {
-      "file": "locations_2025-01-22.json",
-      "success": true,
-      "recordsProcessed": 50,
-      "mutationsExecuted": 45,
-      "mutationsFailed": 5,
-      "errors": ["LOC-001: Invalid location ref", "LOC-002: Missing required field"]
-    }
-  ],
-  "duration": 12345
-}
-```
-
-### Error Response
-
-```json
-{
-  "success": false,
-  "filesProcessed": 0,
-  "filesFailed": 1,
-  "totalRecords": 0,
-  "mutationsExecuted": 0,
-  "mutationsFailed": 0,
-  "results": [
-    {
-      "file": "locations_2025-01-22.json",
-      "success": false,
-      "error": "JSON 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.
-
----
-
-Before deployment, verify:
-
-- [ ] ✅ `GraphQLMutationMapper` imported (NOT `UniversalMapper`)
-- [ ] ✅ NO `client.setRetailerId()` call (not needed for GraphQL mutations)
-- [ ] ✅ `fluentRetailerId` activation variable configured (only if mutation schema requires it)
-- [ ] ✅ Mapping config in external JSON file
-- [ ] ✅ Mapping config uses correct structure (`mutation` property, `arguments.input`, resolver names without `sdk.` prefix)
-- [ ] ✅ Uses `mapper.map()` method (returns `{ query, variables }`)
-- [ ] ✅ Type definitions include `LocationRecord`, `MappedLocation`
-- [ ] ✅ Services follow modular pattern (no logger params in business logic)
-- [ ] ✅ Three workflows implemented (scheduled, ad hoc, status)
-- [ ] ✅ Buffer imported from `node:buffer`
-- [ ] ✅ **Double-finally SFTP disposal** pattern implemented (inner + outer finally)
-- [ ] ✅ Complete service implementations (processor, sender, logger)
-- [ ] ✅ Error handling with per-record tracking
-- [ ] ✅ Processing mode documented (per-file vs chunked)
-
----
-
-## Troubleshooting
-
-### GraphQL Mutations Failing
-**Problem:** Mutations return auth errors
-**Solution:**
-1. Verify OAuth2 credentials are correct in Versori connection
-2. Check if mutation schema requires retailerId in input variables
-3. Do NOT use `client.setRetailerId()` - it's only for Job/Event API
-
-### Wrong Mapper Error
-**Problem:** "UniversalMapper not suitable for GraphQL"
-**Solution:** Replace `UniversalMapper` with `GraphQLMutationMapper`
-
-### Mapping Config Errors
-**Problem:** "Invalid mapping structure"
-**Solution:** Ensure config has `mutation` property (not `mutationName`) and `arguments.input` structure. Resolver names should be without `sdk.` prefix (`trim`, `toUpperCase`, `parseInt`, `parseFloat`, `toBoolean`)
-
-### Wrong Method Name
-**Problem:** "generateMutation is not a function"
-**Solution:** Use `mapper.map()` method, not `generateMutation()`. Returns `{ query, variables }`
-
----
-
-## Key Takeaways
-
-- ✅ **Use GraphQLMutationMapper** for GraphQL mutations (NOT UniversalMapper)
-- ⚠️ **Set retailerId** on client before mutations (VERIFICATION REQUIRED - may need mutation input instead)
-- ✅ **Double-finally SFTP disposal** for resource safety (matches Event API gold standard)
-- ✅ **External JSON config** for production (not inline)
-- ✅ **Modular services** for testability and reusability
-- ✅ **Complete error handling** with per-record tracking
-- ✅ **Processing modes** documented (per-file recommended, chunked optional)
-- ✅ **Type-safe** with comprehensive interfaces
-- ✅ **Native Versori logging** (LoggingService removed - use native log)
-- ✅ **GraphQL alias batching** support for high-volume scenarios (mutationsPerAliasBatch parameter)
-
----
-
-## References
-
-- **Gold Standard Guide:** `internal/GOLD-STANDARD-APPLICATION-GUIDE.md`
-- **GraphQL Mutation Mapping:** `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
-- **GraphQL Alias Batching:** `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/graphql-alias-batching-guide.md`
-- **retailerId Configuration:** `fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md`
-- **Event API Template:** `template-ingestion-sftp-xml-product-event.md` (architectural reference)
-
----
-
-**Status:** ✅ Gold Standard Compliant
-**Compliance:** All patterns verified against SDK and Fluent GraphQL schema
+---
+template_id: tpl-ingest-sftp-json-to-location-graphql
+canonical_filename: template-ingestion-sftp-json-location-graphql.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: sftp-json
+destination: fluent-graphql
+entity: location
+format: json
+logging: versori
+status: stable
+compliance: gold-standard
+features:
+  - graphql-mutation-mapper
+  - memory-management
+  - enhanced-logging
+  - attribute-transformation
+  - dispose-finally
+---
+
+# Template: Ingestion - SFTP JSON to Location GraphQL
+
+**Deployment Target:** Versori Platform
+**Compliance Status:** ✅ GOLD STANDARD APPROVED
+
+---
+
+## 📋 Implementation Prompt
+
+```
+I need a Versori scheduled ingestion that:
+
+1) Discovers JSON files on SFTP with file tracking to skip duplicates
+2) Downloads and parses JSON (locations array) with JSONParserService
+3) Transforms records with GraphQLMutationMapper (NOT UniversalMapper)
+4) Executes GraphQL createLocation mutations with rate limiting
+5) Archives files to processed/ or errors/ and writes error reports
+6) Tracks progress with JobTracker and exposes job status webhook
+7) Uses native Versori log and follows modular service architecture
+
+CRITICAL: This template uses GraphQLMutationMapper for GraphQL mutations,
+NOT UniversalMapper (which is for Batch API). Do NOT use setRetailerId()
+for GraphQL mutations - it's only needed for Job/Event API.
+
+Use the loaded docs to fill in SDK specifics and best practices.
+```
+
+---
+
+## 📋 Template Overview
+
+This connector runs on the Versori platform with **gold standard compliance**. It reads location data from SFTP JSON files, transforms it with GraphQLMutationMapper, and creates/updates locations via GraphQL mutations.
+
+### What This Template Does
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│         INGESTION WORKFLOW (GraphQL Mutations Pattern)          │
+└─────────────────────────────────────────────────────────────────┘
+
+1. TRIGGER
+   ├─ Scheduled (Cron): Daily at 2 AM
+   ├─ Ad hoc (Webhook): Manual trigger
+   └─ Status Query (Webhook): Check progress
+
+2. DISCOVER FILES (SftpDataSource)
+   ├─ List files matching pattern
+   ├─ Check VersoriFileTracker (skip processed)
+   └─ Sort by oldest first
+
+3. DOWNLOAD & PARSE (LocationFileProcessorService)
+   ├─ Download from SFTP
+   ├─ Parse JSON with JSONParserService
+   ├─ Validate structure with type guards
+   └─ Return LocationRecord[]
+
+4. TRANSFORM (GraphQLMutationMapper)
+   ├─ Map to GraphQL CreateLocationInput
+   ├─ Handle nested objects (primaryAddress, openingSchedule)
+   ├─ Validate against GraphQL schema
+   └─ Generate mutation query
+
+5. EXECUTE MUTATIONS (MutationSenderService)
+   ├─ Execute createLocation mutations
+   ├─ Rate limiting (configurable concurrency)
+   ├─ Per-record error handling
+   └─ Track success/failure per mutation
+
+6. ARCHIVE & LOG
+   ├─ Move to processed/ or errors/
+   ├─ Write error reports
+   └─ Track state in VersoriFileTracker
+
+7. JOB TRACKING
+   ├─ Update job status at each step
+   └─ Enable status queries via webhook
+```
+
+### Key Features
+
+- ✅ **Gold Standard Compliant** - Modular architecture, proper patterns
+- ✅ **GraphQLMutationMapper** - Correct mapper for GraphQL mutations
+- ✅ **retailerId Configuration** - CRITICAL for GraphQL API calls
+- ✅ **Type-Safe** - Comprehensive TypeScript interfaces
+- ✅ **Modular Services** - 4 services + utils (testable, reusable)
+- ✅ **External Config** - Mapping in JSON file
+- ✅ **Error Handling** - Per-record failures don't block others
+- ✅ **File Tracking** - Prevents duplicate processing
+- ✅ **Job Tracking** - Status queries via webhook
+
+---
+
+## 📦 SDK Imports
+
+```typescript
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno
+
+import {
+  createClient,
+  SftpDataSource,
+  JSONParserService,
+  GraphQLMutationMapper, // ✅ CRITICAL: Use this for GraphQL (NOT UniversalMapper)
+  VersoriFileTracker,
+  JobTracker,
+} from '@fluentcommerce/fc-connect-sdk';
+
+import type {
+  FluentClient,
+  FileMetadata,
+  Logger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+import { schedule, webhook, http, fn } from '@versori/run';
+```
+
+**✅ Type-Only Imports:** Separating value and type imports improves tree-shaking and bundle size.
+
+---
+
+---
+
+## SFTP Connection Setup (Recommended)
+
+**🔒 BEST PRACTICE:** Store SFTP credentials in a Versori connection object with Basic Auth:
+
+### Connection Configuration
+
+1. In Versori platform, create a connection named `SFTP`
+2. Set **Authentication Type**: `Basic Auth`
+3. Enter **Username**: Your SFTP username
+4. Enter **Password**: Your SFTP password
+5. The SDK will automatically retrieve and decode credentials
+
+### Code Implementation
+
+The workflow retrieves credentials programmatically from the Versori connection:
+
+```typescript
+import { Buffer } from 'node:buffer';
+
+// Retrieve SFTP credentials from connection configuration
+log.info('Retrieving SFTP credentials from connection configuration');
+
+let sftpUsername: string;
+let sftpPassword: string;
+
+try {
+  // Retrieve credentials from the 'SFTP' connection
+  const sftpCred = await ctx.credentials().getAccessToken('SFTP');
+
+  if (!sftpCred?.accessToken) {
+    throw new Error('No SFTP credentials found in connection configuration');
+  }
+
+  // Decode base64 accessToken to get "username:password"
+  const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
+
+  // Split on ':' to extract username and password
+  const parts = rawBasicAuth.split(':');
+
+  if (parts.length !== 2) {
+    throw new Error('Invalid SFTP credential format - expected username:password');
+  }
+
+  sftpUsername = parts[0];
+  sftpPassword = parts[1];
+
+  log.info('SFTP credentials retrieved successfully', {
+    hasUsername: !!sftpUsername,
+    hasPassword: !!sftpPassword,
+    usernameLength: sftpUsername.length,
+    passwordLength: sftpPassword.length,
+  });
+} catch (error: any) {
+  log.error('Failed to retrieve SFTP credentials', {
+    message: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+    errorType: error instanceof Error ? error.constructor.name : 'Error'
+  });
+
+  return {
+    success: false,
+    error: 'Failed to retrieve SFTP credentials from connection configuration',
+    details: error?.message,
+    recommendation: 'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)',
+  };
+}
+
+// Use credentials in SftpDataSource
+const sftp = new SftpDataSource({
+  type: 'SFTP_JSON',
+  connectionId: 'sftp-location-sync',
+  name: 'Location Sync SFTP',
+  settings: {
+    host: activation.getVariable('sftpHost'),
+    port: parseInt(activation.getVariable('sftpPort') || '22', 10),
+    username: sftpUsername, // From connection
+    password: sftpPassword, // From connection
+    remotePath: activation.getVariable('sftpRemotePath'),
+    filePattern: activation.getVariable('filePattern'),
+    encoding: 'utf8',
+  },
+}, log);
+```
+
+### Why Use Connections Instead of Activation Variables?
+
+| Aspect | Activation Variables ❌ | Versori Connections ✅ |
+|--------|------------------------|------------------------|
+| **Security** | Plain text in config UI | Encrypted in Versori vault |
+| **Visibility** | Visible to all users | Controlled access |
+| **Rotation** | Manual update per workflow | Update once, affects all |
+| **Best Practice** | Legacy approach | **Recommended approach** |
+| **Audit Trail** | Limited | Full connection audit logs |
+
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Connection can be reused across workflows
+- ✅ No sensitive data in activation variables
+- ✅ Easier credential rotation (one place to update)
+- ✅ Better security posture (credentials never exposed in UI)
+
+---
+
+## ⚙️ Activation Variables
+
+**Configuration is driven by activation variables - modify these instead of code:**
+
+> **Note:** `sftpUsername` and `sftpPassword` are fetched from the `SFTP` Basic Auth connection (see SFTP Connection Setup above).
+
+```bash
+# SFTP Configuration
+SFTP_HOST=sftp.partner.com
+SFTP_PORT=22
+
+# SFTP Paths
+SFTP_REMOTE_PATH=/locations/incoming
+SFTP_ARCHIVE_PATH=/locations/processed
+SFTP_ERROR_PATH=/locations/errors
+
+# File Processing
+FILE_PATTERN=locations_*.json
+MAX_FILES_PER_RUN=10
+
+# GraphQL Configuration
+FLUENT_RETAILER_ID=1                          # Optional: Only if mutation schema requires retailerId in input
+MAX_PARALLEL_MUTATIONS=10                     # Concurrent mutation limit (1=sequential, 3-10=parallel)
+
+# Feature Toggles
+REQUIRE_ABSOLUTE_PATHS=true                   # "true" for AWS Transfer Family, "false" for standard OpenSSH
+VALIDATE_CONNECTION=true                      # Validate SFTP connection on startup (default: true)
+ENABLE_FILE_TRACKING=true                     # Enable/disable file tracking (default: true)
+```
+
+**Security:**
+- **SFTP Authentication:** Credentials stored in Versori connection vault (not in activation variables). See [SFTP Connection Setup](#sftp-connection-setup-recommended) section above.
+- **Webhook Authentication:** Enforced by Versori connection configuration. Configure your webhook connection with API key authentication in the Versori Dashboard, then reference it in `webhook({ connection: 'webhook-auth' })`.
+
+---
+
+## 📄 Mapping Configuration
+
+**File:** `src/config/location-mapping.json`
+
+**✅ PRODUCTION STANDARD:** External JSON file with GraphQLMutationMapper structure
+
+```json
+{
+  "mutation": "createLocation",
+  "sourceFormat": "json",
+  "version": "1.0.0",
+  "returnFields": ["id", "ref", "name", "type", "status"],
+  "arguments": {
+    "input": {
+      "ref": {
+        "source": "locationRef",
+        "required": true,
+        "resolver": "trim"
+      },
+      "name": {
+        "source": "locationName",
+        "required": true,
+        "resolver": "trim"
+      },
+      "type": {
+        "source": "locationType",
+        "required": true,
+        "resolver": "toUpperCase"
+      },
+      "status": {
+        "value": "ACTIVE",
+        "required": true
+      },
+      "primaryAddress": {
+        "ref": {
+          "source": "locationRef",
+          "required": true,
+          "resolver": "trim"
+        },
+        "street": {
+          "source": "address.street1",
+          "resolver": "trim"
+        },
+        "city": {
+          "source": "address.city",
+          "resolver": "trim"
+        },
+        "state": {
+          "source": "address.state",
+          "resolver": "toUpperCase"
+        },
+        "postcode": {
+          "source": "address.postalCode",
+          "resolver": "trim"
+        },
+        "country": {
+          "source": "address.country",
+          "resolver": "toUpperCase"
+        },
+        "latitude": {
+          "source": "geo.latitude",
+          "required": true,
+          "resolver": "parseFloat"
+        },
+        "longitude": {
+          "source": "geo.longitude",
+          "required": true,
+          "resolver": "parseFloat"
+        },
+        "timeZone": {
+          "source": "timeZone",
+          "resolver": "trim"
+        }
+      },
+      "openingSchedule": {
+        "allHours": {
+          "source": "openingSchedule.allHours",
+          "required": true,
+          "resolver": "toBoolean"
+        },
+        "monStart": {
+          "source": "openingSchedule.monStart",
+          "required": true,
+          "resolver": "parseInt"
+        },
+        "monEnd": {
+          "source": "openingSchedule.monEnd",
+          "required": true,
+          "resolver": "parseInt"
+        }
+      }
+    }
+  }
+}
+```
+
+**Key Differences from UniversalMapper:**
+- ✅ `mutation` property (not `mutationName`)
+- ✅ `arguments.input` structure (matches GraphQL schema)
+- ✅ Nested objects (not dotted paths like `primaryAddress.street`)
+- ✅ Resolver names without `sdk.` prefix (`trim`, `toUpperCase`, `parseInt`, `parseFloat`, `toBoolean`)
+- ✅ Used with `GraphQLMutationMapper.map()` method (not `UniversalMapper.map()`)
+
+---
+
+## Expected JSON Format
+
+```json
+{
+  "locations": [
+    {
+      "locationRef": "LOC-001",
+      "locationName": "Main Warehouse",
+      "locationType": "WAREHOUSE",
+      "address": {
+        "street1": "123 Main St",
+        "city": "New York",
+        "state": "NY",
+        "postalCode": "10001",
+        "country": "US"
+      },
+      "geo": {
+        "latitude": 40.7128,
+        "longitude": -74.0060
+      },
+      "timeZone": "America/New_York",
+      "openingSchedule": {
+        "allHours": false,
+        "monStart": 480,
+        "monEnd": 1020
+      }
+    }
+  ]
+}
+```
+
+**Alternative:** Root array `[{...}]` is also supported.
+
+---
+
+## 🔧 Production Code Structure
+
+### Modular Architecture (Gold Standard)
+
+```
+sftp-json-location-graphql/
+├── package.json
+├── tsconfig.json
+├── index.ts                                  # Entry point
+└── src/
+    ├── workflows/
+    │   └── location-ingestion.ts              # 3 workflows
+    ├── services/
+    │   ├── location-file-processor.service.ts # Download, parse, transform
+    │   ├── mutation-sender.service.ts         # Execute GraphQL mutations
+    │   ├── mutation-logger.service.ts         # Write error logs
+    │   └── location-ingestion.service.ts      # Main orchestration
+    ├── types/
+    │   └── location-ingestion.types.ts        # TypeScript interfaces
+    ├── utils/
+    │   ├── sftp-path.utils.ts                 # Path helpers
+    │   ├── retry.utils.ts                     # Retry logic
+    │   └── job-id-generator.ts                # Job IDs
+    └── config/
+        └── location-mapping.json              # GraphQL mapping config
+```
+
+---
+
+## Critical Implementation Patterns
+
+### ✅ MUST HAVE: retailerId Configuration ⚠️ VERIFICATION REQUIRED
+
+```typescript
+// In main orchestration service (location-ingestion.service.ts)
+
+export async function executeLocationIngestion(ctx: VersoriContext, params: LocationIngestionParams) {
+  const { log, activation } = ctx;
+
+  // Step 1: Create client
+  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
+
+  // Step 2: Initialize GraphQLMutationMapper with client
+  import mappingConfig from '../config/location-mapping.json' with { type: 'json' };
+  const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+
+  // Step 3: Process files and execute mutations
+  // ... rest of workflow
+  
+  // ✅ 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, use separate requests)
+  
+  // ? Enhanced: Extract context for progress logging
+  const sampleLocationRefs = locations.slice(0, 5).map((loc: any) => loc.ref || loc.input?.ref || 'unknown');
+  const mutationType = mapper?.mutationName || 'createLocation';
+
+  // ? Enhanced: Start logging with context
+  log.info(`[GraphQLMutations] Sending mutations for locations`, {
+   totalMutations: locations.length,
+   mutationType,
+   batchSize: mutationBatchSize,
+   batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
+   sampleLocationRefs: sampleLocationRefs.join(', '),
+   aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled'
+  });
+
+  // Use in executeMutations:
+  const mutationResults = await mutationSender.executeMutations(
+    locations,
+    mutationBatchSize,  // Concurrency control (default: 1)
+    mutationsPerAliasBatch  // ✅ NEW: Alias batching (default: undefined)
+  );
+
+  // ? Enhanced: Completion logging with summary
+  log.info(`[GraphQLMutations] Mutation submission completed`, {
+   totalMutations: locations.length,
+   mutationsExecuted: mutationResults.mutationsExecuted,
+   mutationsFailed: mutationResults.mutationsFailed,
+   successRate: locations.length > 0 ? `${Math.round((mutationResults.mutationsExecuted / locations.length) * 100)}%` : '0%',
+   mutationType
+  });
+}
+```
+
+**✅ VERIFIED Pattern:**
+- GraphQL mutations do NOT need `client.setRetailerId()`
+- `setRetailerId()` is only for Job API and Event API
+- Pass retailerId in mutation input variables if schema requires it
+
+**Example (For mutations that require retailerId in schema):**
+```typescript
+// Only needed if mutation schema explicitly requires retailerId
+const fluentRetailerId = activation.getVariable('fluentRetailerId');
+const { query, variables } = await mapper.map(location);
+
+// Add to input if mutation schema requires it
+if (fluentRetailerId && variables.input) {
+  variables.input.retailer = { id: parseInt(fluentRetailerId) };
+}
+
+await client.graphql({ query, variables });
+```
+
+**Note:** Check your GraphQL schema (via introspection) to determine retailerId handling:
+1. Does the mutation have `retailerId` or `retailer.id` field?
+2. Is it mandatory (`!`) or optional?
+3. If field doesn't exist → don't pass it
+
+### ✅ MUST HAVE: Double-Finally SFTP Disposal
+
+**What:** Defensive resource cleanup with nested finally blocks (matches Event API gold standard)
+
+**Gold Standard Pattern:**
+
+```typescript
+// ✅ CRITICAL: Declare SFTP outside try block for safe disposal
+let sftp: SftpDataSource | undefined;
+
+try {
+  // 📊 Execution boundary: Start workflow
+  const startTime = Date.now();
+  log.info('🚀 Starting location ingestion workflow', {
+    stage: 'initialization',
+    jobId,
+    triggeredBy: params.triggeredBy
+  });
+
+  // Initialize SFTP
+  sftp = new SftpDataSource(...);
+
+  // ✅ Validate connection (if enabled)
+  const validateConnection = activation?.getVariable('validateConnection') === 'true';
+  if (validateConnection) {
+    log.info('🔌 Validating SFTP connection', { stage: 'connection_validation' });
+    await sftp.validateConnection();
+    log.info('✅ SFTP connection validated successfully');
+  }
+
+  try {
+    // Use SFTP
+    await sftp.listFiles(...);
+    await sftp.downloadFile(...);
+    // ... rest of workflow
+
+    // 📊 Execution boundary: End workflow
+    const duration = Date.now() - startTime;
+    log.info('✅ Location ingestion workflow completed', {
+      stage: 'completion',
+      jobId,
+      duration,
+      filesProcessed,
+      mutationsExecuted
+    });
+  } finally {
+    // Inner finally - normal cleanup
+    if (sftp) {
+      await sftp.dispose();
+      log.info('🔌 SFTP connection disposed');
+    }
+  }
+} catch (error: unknown) {
+  // ✅ Enhanced error logging: Extract all error details + recommendations
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorDetails = {
+    message: errorMessage,
+    stack: error instanceof Error ? error.stack : undefined,
+    errorType: error instanceof Error ? error.constructor.name : 'Error',
+    stage: 'workflow_execution',
+    jobId
+  };
+
+  // ✅ Add error recommendations
+  const recommendations: string[] = [];
+  if (errorMessage.includes('ECONNREFUSED')) {
+    recommendations.push('Check SFTP host and port configuration');
+    recommendations.push('Verify network connectivity to SFTP server');
+  } else if (errorMessage.includes('Authentication failed')) {
+    recommendations.push('Verify SFTP username and password');
+    recommendations.push('Check if account is locked or expired');
+  } else if (errorMessage.includes('No such file')) {
+    recommendations.push('Verify incoming path exists on SFTP server');
+    recommendations.push('Check file pattern matches existing files');
+  }
+
+  log.error('❌ Workflow failed', { ...errorDetails, recommendations });
+
+  // Handle error (mark job failed, etc.)
+} finally {
+  // Outer finally - defensive cleanup
+  // ⚠️ CRITICAL: Ensures disposal even if error occurs after SFTP creation
+  // but before inner try block (e.g., during connection validation)
+  if (sftp) {
+    try {
+      await sftp.dispose();
+      log.info('🔌 SFTP connection disposed (outer finally)');
+    } catch (disposeError: unknown) {
+      const disposeErrorMessage = disposeError instanceof Error
+        ? disposeError.message
+        : String(disposeError);
+      log.warn('⚠️ Error disposing SFTP in outer finally', { error: disposeErrorMessage });
+    }
+  }
+}
+```
+
+**Why This is Critical:**
+- Ensures disposal even if error occurs after SFTP creation but before inner try block
+- Defensive cleanup catches edge cases
+- Prevents resource leaks in error scenarios
+- Matches Event API gold standard pattern
+
+---
+
+## Processing Modes
+
+**⚠️ IMPORTANT:** Choose ONE processing mode per connector. These are alternative patterns, not features to use together.
+
+The SDK supports two processing modes for handling multiple files. **Select the mode that best fits your use case** and configure your connector accordingly:
+
+### Mode 1: Per-File Processing (Recommended Default) ✅ IMPLEMENTED
+
+**When to use:**
+- Multiple large files that shouldn't be in memory together
+- Need file-level consistency (file 3 fails → files 1-2 already archived)
+- Clear error isolation per file
+
+**How it works:**
+1. Process file 1 completely (download → parse → transform → execute mutations → archive)
+2. Move to file 2
+3. Continue sequentially
+
+**Benefits:**
+- ✅ Low memory usage (one file at a time)
+- ✅ Clear error isolation (failed file doesn't block others)
+- ✅ Incremental progress (files archived as completed)
+
+**Example implementation (see code section below)**
+
+### Mode 2: Chunked Per-File Processing ⚠️ OPTIONAL - Choose if needed
+
+**When to use:**
+- Many small files that can be processed in parallel
+- Need better throughput for many files
+- Files are independent (no cross-file dependencies)
+
+**How it works:**
+1. Group files into chunks (e.g., 5 files per chunk)
+2. Process chunk 1 files in parallel
+3. Wait for chunk completion, then move to chunk 2
+
+**Benefits:**
+- ✅ Better throughput (parallel processing)
+- ✅ Still maintains file-level isolation
+- ✅ Configurable chunk size
+
+**Note:** GraphQL mutations are typically one-off operations, so per-file processing is usually sufficient. Chunked mode is optional for high-volume scenarios.
+
+---
+
+## Key Service Patterns
+
+### Service 1: Location File Processor (Complete Implementation)
+
+**File:** `src/services/location-file-processor.service.ts`
+
+```typescript
+/**
+ * Location File Processor Service
+ *
+ * Downloads JSON files from SFTP, parses content, and transforms with GraphQLMutationMapper.
+ * Reusable service for location file processing workflows.
+ */
+
+import {
+  SftpDataSource,
+  JSONParserService,
+  GraphQLMutationMapper,
+} from '@fluentcommerce/fc-connect-sdk';
+import type {
+  ProcessFileResult,
+  LocationRecord,
+} from '../types/location-ingestion.types';
+import { extractFileName } from '../utils/sftp-path.utils';
+
+/**
+ * Location file processing service
+ * Coordinates SFTP download, JSON parsing (via SDK), and GraphQL mutation generation
+ */
+export class LocationFileProcessorService {
+  constructor(
+    private sftp: SftpDataSource,
+    private jsonParser: JSONParserService,
+    private mapper: GraphQLMutationMapper
+  ) {} // ✅ No logger param - workflow handles logging
+
+  /**
+   * Download JSON file from SFTP, parse, and generate GraphQL mutations
+   */
+  async downloadParseAndTransform(remoteFilePath: string): Promise<ProcessFileResult> {
+    // ✅ Extract filename for logging
+    const fileName = extractFileName(remoteFilePath);
+
+    try {
+      // Download JSON content
+      const content = (await this.sftp.downloadFile(remoteFilePath, {
+        encoding: 'utf8',
+      })) as string;
+
+      // Parse JSON with type safety
+      let parsed: unknown;
+      try {
+        parsed = await this.jsonParser.parse(content);
+      } catch (parseError: unknown) {
+        const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
+        return {
+          success: false,
+          locations: [],
+          error: `JSON parse error: ${errorMessage}`,
+          fileName,
+        };
+      }
+
+      // Normalize locations array (handle both { locations: [...] } and root array formats)
+      const jsonData = parsed as Record<string, unknown>;
+      const locations = jsonData.locations
+        ? (Array.isArray(jsonData.locations) ? jsonData.locations : [jsonData.locations])
+        : (Array.isArray(jsonData) ? jsonData : []);
+
+      if (locations.length === 0) {
+        return {
+          success: false,
+          locations: [],
+          error: 'No locations found in JSON',
+          fileName,
+        };
+      }
+
+      // Validate with type guard
+      const validLocations = locations.filter(isLocationRecord);
+
+      if (validLocations.length === 0) {
+        return {
+          success: false,
+          locations: [],
+          error: 'No valid locations found after validation',
+          fileName,
+        };
+      }
+
+      // Transform with GraphQLMutationMapper
+      const mapped = await Promise.all(
+        validLocations.map(loc => this.mapper.map(loc))
+      );
+
+      return {
+        success: true,
+        locations: mapped.map(m => m.variables.input),
+        fileName,
+      };
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        locations: [],
+        error: errorMessage,
+        fileName,
+      };
+    }
+  }
+}
+
+/**
+ * Type guard: Check if parsed value is a valid LocationRecord
+ */
+function isLocationRecord(obj: unknown): obj is LocationRecord {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const loc = obj as Record<string, unknown>;
+
+  return (
+    typeof loc.locationRef === 'string' &&
+    typeof loc.locationName === 'string' &&
+    typeof loc.locationType === 'string' &&
+    typeof loc.address === 'object' &&
+    loc.address !== null &&
+    typeof loc.geo === 'object' &&
+    loc.geo !== null
+  );
+}
+```
+
+### Service 2: Mutation Sender (Complete Implementation)
+
+**File:** `src/services/mutation-sender.service.ts`
+
+```typescript
+/**
+ * Mutation Sender Service
+ *
+ * Executes GraphQL mutations with per-record error handling.
+ * Continues processing on individual failures (GraphQL mutation pattern).
+ */
+
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+import type { MutationResult, MappedLocation } from '../types/location-ingestion.types';
+
+/**
+ * Service for executing GraphQL mutations
+ */
+export class MutationSenderService {
+  constructor(
+    private client: FluentClient,
+    private mapper: GraphQLMutationMapper
+  ) {}
+
+  /**
+   * Execute GraphQL mutations with configurable concurrency and alias batching
+   *
+   * **Performance Characteristics:**
+   * - `maxParallel: 1` → Sequential processing (safe default, ~1 mutation/sec)
+   * - `maxParallel: 3-5` → Balanced throughput (~3-5 mutations/sec)
+   * - `maxParallel: 10` → High-volume processing (~10 mutations/sec, 100+ locations)
+   *
+   * **Implementation Strategy:**
+   * - Sequential (1): Optimized loop (no Promise.allSettled overhead)
+   * - Parallel (>1): Chunked processing with bounded concurrency
+   * - Alias batching: Groups mutations into aliased GraphQL requests (reduces network overhead)
+   * - Both modes: Per-record error tracking (failures don't block others)
+   *
+   * **Alias Batching:**
+   * - When `mutationsPerAliasBatch > 1`, groups mutations into aliased requests
+   * - Example: 5 mutations → 1 HTTP request with aliases (createLocation1, createLocation2, ...)
+   * - Reduces network overhead by ~80% for high-volume scenarios
+   *
+   * @param locations - Array of mapped locations to create/update
+   * @param maxParallel - Number of concurrent mutations or alias batches (default: 1, min: 1)
+   * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (default: undefined = disabled)
+   * @returns MutationResult with counts (mutationsExecuted/mutationsFailed) and error details
+   */
+  async executeMutations(
+    locations: MappedLocation[],
+    maxParallel: number = 1,  // ✅ Default: 1 (sequential)
+    mutationsPerAliasBatch?: number  // ✅ NEW: Alias batching parameter (default: undefined = disabled)
+  ): Promise<MutationResult> {
+    // Determine mode: use aliases if mutationsPerAliasBatch is set and > 1
+    const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
+    
+    if (useAliases) {
+      return await this.executeMutationsWithAliases(
+        locations,
+        maxParallel,
+        mutationsPerAliasBatch!
+      );
+    } else {
+      return await this.executeMutationsSeparate(locations, maxParallel);
+    }
+  }
+
+  /**
+   * Execute mutations using separate concurrent requests (current mode)
+   */
+  private async executeMutationsSeparate(
+    locations: MappedLocation[],
+    maxParallel: number
+  ): Promise<MutationResult> {
+    // Validate concurrency (guard against invalid values)
+    const safeConc = Math.max(1, Math.floor(maxParallel));
+
+    // Result accumulators
+    let mutationsExecuted = 0;
+    let mutationsFailed = 0;
+    const errors: Array<{ locationRef: string; error: string }> = [];
+
+    // ============================================================================
+    // SEQUENTIAL MODE (maxParallel === 1)
+    // ============================================================================
+    if (safeConc === 1) {
+      for (const location of locations) {
+        try {
+          const { query, variables } = await this.mapper.map(location);
+          await this.client.graphql({ query, variables });
+          mutationsExecuted++;
+        } catch (err: unknown) {
+          mutationsFailed++;
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          errors.push({
+            locationRef: location.ref || 'unknown',
+            error: errorMsg,
+          });
+          // Continue processing (failure doesn't block other locations)
+        }
+      }
+      return { mutationsExecuted, mutationsFailed, errors };
+    }
+
+    // ============================================================================
+    // PARALLEL MODE (maxParallel > 1)
+    // ============================================================================
+    // Chunked processing with bounded concurrency
+    for (let i = 0; i < locations.length; i += safeConc) {
+      const chunk = locations.slice(i, i + safeConc);
+
+      // Fire all mutations in chunk concurrently
+      const results = await Promise.allSettled(
+        chunk.map(async (location) => {
+          const { query, variables } = await this.mapper.map(location);
+          return await this.client.graphql({ query, variables });
+        })
+      );
+
+      // Aggregate chunk results
+      results.forEach((result, idx) => {
+        if (result.status === 'fulfilled') {
+          mutationsExecuted++;
+        } else {
+          mutationsFailed++;
+          const error = result.reason;
+          errors.push({
+            locationRef: chunk[idx]?.ref || 'unknown',
+            error: error?.message || String(error) || 'Unknown error',
+          });
+        }
+      });
+
+      // Small delay between batches to avoid rate limiting
+      if (i + safeConc < locations.length) {
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+    }
+
+    return { mutationsExecuted, mutationsFailed, errors };
+  }
+
+  /**
+   * ✅ NEW: Execute mutations using GraphQL aliases (batched requests)
+   *
+   * Groups mutations into alias batches and executes them with concurrency control.
+   * Each aliased request contains multiple mutations identified by alias names.
+   *
+   * @param locations - Array of mapped locations
+   * @param maxParallel - Number of concurrent alias batch requests
+   * @param mutationsPerAliasBatch - Number of mutations per aliased request
+   * @returns Mutation execution results
+   */
+  private async executeMutationsWithAliases(
+    locations: MappedLocation[],
+    maxParallel: number,
+    mutationsPerAliasBatch: number
+  ): Promise<MutationResult> {
+    const results: MutationResult = { mutationsExecuted: 0, mutationsFailed: 0, errors: [] };
+    
+    // Extract mutation name from mapper config
+    const mutationName = (this.mapper as any).config.mutation || 'createLocation';
+    
+    // Group locations into alias batches
+    const aliasBatches: Array<MappedLocation[]> = [];
+    for (let i = 0; i < locations.length; i += mutationsPerAliasBatch) {
+      aliasBatches.push(locations.slice(i, i + mutationsPerAliasBatch));
+    }
+    
+    // Process batches with concurrency control
+    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) => {
+          // Build aliased query and variables
+          const { query, variables } = await this.buildAliasedBatch(batch, mutationName);
+          
+          // Execute aliased mutation
+          const response = await this.client.graphql({ query, variables });
+          
+          // Parse results and errors
+          return this.parseAliasResponse(response, batch, mutationName);
+        })
+      );
+      
+      // Aggregate results
+      batchResults.forEach((result, idx) => {
+        if (result.status === 'fulfilled') {
+          const batchResult = result.value;
+          results.mutationsExecuted += batchResult.executed;
+          results.mutationsFailed += batchResult.failed;
+          results.errors.push(...batchResult.errors);
+        } else {
+          // Entire batch failed
+          const batch = concurrentBatches[idx];
+          const errorMsg = result.reason instanceof Error ? result.reason.message : String(result.reason);
+          batch.forEach(loc => {
+            results.mutationsFailed++;
+            results.errors.push({
+              locationRef: loc.ref || 'unknown',
+              error: `Batch execution failed: ${errorMsg}`
+            });
+          });
+        }
+      });
+      
+      // Add small delay between concurrent batches to respect rate limits
+      if (i + maxParallel < aliasBatches.length) {
+        await new Promise(resolve => setTimeout(resolve, 500));
+      }
+    }
+    
+    return results;
+  }
+
+  /**
+   * ✅ NEW: Build aliased batch query and variables
+   *
+   * @param batch - Array of location objects
+   * @param mutationName - GraphQL mutation name (e.g., 'createLocation')
+   * @returns GraphQL query and variables for aliased batch
+   */
+  private async buildAliasedBatch(
+    batch: MappedLocation[],
+    mutationName: string
+  ): Promise<{ query: string; variables: Record<string, any> }> {
+    const batchSize = batch.length;
+    const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
+    
+    // Build aliased query (simple naming: mutationName + index)
+    const variables = Array.from({ length: batchSize }, (_, i) => 
+      `$input${i + 1}: ${inputTypeName}!`
+    ).join(', ');
+    
+    const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
+      const alias = `${mutationName}${i + 1}`;  // Simple: createLocation1, createLocation2, etc.
+      return `  ${alias}: ${mutationName}(input: $input${i + 1}) { id ref name }`;
+    }).join('\n');
+    
+    const operationName = `Batch${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}s`;
+    const query = `mutation ${operationName}(${variables}) {\n${aliasedMutations}\n}`;
+    
+    // Build variables from mapped locations (await all mappings)
+    const mappedItems = await Promise.all(
+      batch.map(loc => this.mapper.map(loc))
+    );
+    
+    const variablesObj: Record<string, unknown> = {};
+    mappedItems.forEach((mapped, index) => {
+      const input = mapped.variables.input || mapped.variables;
+      variablesObj[`input${index + 1}`] = input;
+    });
+    
+    return { query, variables: variablesObj };
+  }
+
+  /**
+   * ✅ NEW: Parse aliased GraphQL response and extract individual mutation results
+   *
+   * @param response - GraphQL response from aliased mutation
+   * @param batch - Original batch of location objects
+   * @param mutationName - GraphQL mutation name (e.g., 'createLocation')
+   * @returns Parsed results with executed/failed counts and errors
+   */
+  private parseAliasResponse(
+    response: { data?: Record<string, unknown>; errors?: Array<{ path?: string[]; message: string }> },
+    batch: MappedLocation[],
+    mutationName: string
+  ): { executed: number; failed: number; errors: Array<{ locationRef: string; error: string }> } {
+    const result = { executed: 0, failed: 0, errors: [] as Array<{ locationRef: string; error: string }> };
+
+    const data = response.data || {};
+    const errors = response.errors || [];
+
+    // Process each alias result
+    batch.forEach((loc, index) => {
+      const alias = `${mutationName}${index + 1}`;  // Simple: createLocation1, createLocation2, etc.
+      const aliasData = data[alias];
+      const aliasErrors = errors.filter((e) =>
+        e.path && Array.isArray(e.path) && e.path.includes(alias)
+      );
+      
+      if (aliasData && !aliasErrors.length) {
+        result.executed++;
+      } else {
+        result.failed++;
+        const errorMsg = aliasErrors[0]?.message || 'Mutation failed';
+        const locationRef = loc.ref || 'unknown';
+        result.errors.push({
+          locationRef,
+          error: errorMsg,
+        });
+      }
+    });
+    
+    return result;
+  }
+}
+```
+
+### Service 3: Mutation Logger (Complete Implementation)
+
+**File:** `src/services/mutation-logger.service.ts`
+
+```typescript
+/**
+ * Mutation Logger Service
+ *
+ * Writes mutation processing logs to SFTP for audit purposes.
+ * Log writing failures don't stop the workflow (non-critical).
+ */
+
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+import type { MutationResult } from '../types/location-ingestion.types';
+
+/**
+ * Service for writing mutation logs to SFTP
+ */
+export class MutationLoggerService {
+  constructor(private sftp: SftpDataSource) {}
+
+  /**
+   * Write mutation processing log to SFTP
+   *
+   * Creates JSON log file with mutation results.
+   * Only write logs when there are failures (optional).
+   *
+   * Returns log file path on success, or throws on critical errors.
+   */
+  async writeMutationLog(
+    fileName: string,
+    result: MutationResult,
+    remotePath: string,
+    requireAbsolutePaths: boolean
+  ): Promise<string> {
+    const timestamp = new Date().toISOString();
+    const logContent = JSON.stringify(
+      {
+        fileName,
+        timestamp,
+        mutationsExecuted: result.mutationsExecuted,
+        mutationsFailed: result.mutationsFailed,
+        errors: result.errors,
+      },
+      null,
+      2
+    );
+
+    const logFileName = `${fileName.replace(/\.json$/i, '')}-mutations-${timestamp.replace(/[:.]/g, '-')}.json`;
+
+    const logPath =
+      requireAbsolutePaths && !remotePath.startsWith('/')
+        ? `/${remotePath}/${logFileName}`.replace(/\/+/g, '/')
+        : `${remotePath}/${logFileName}`.replace(/\/+/g, '/');
+
+    await this.sftp.uploadFile(logPath, logContent);
+
+    return logPath; // Return path for workflow logging
+  }
+}
+```
+
+---
+
+## Type Definitions
+
+**File:** `src/types/location-ingestion.types.ts`
+
+```typescript
+export interface LocationRecord {
+  locationRef: string;
+  locationName: string;
+  locationType: string;
+  address: {
+    street1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+  };
+  geo: {
+    latitude: number;
+    longitude: number;
+  };
+  timeZone: string;
+  openingSchedule: {
+    allHours: boolean;
+    monStart: number;
+    monEnd: number;
+    // ... other schedule fields
+  };
+}
+
+export interface MappedLocation {
+  ref: string;
+  name: string;
+  type: string;
+  status: string;
+  primaryAddress: {
+    ref: string;
+    street?: string;
+    city?: string;
+    latitude: number;
+    longitude: number;
+  };
+  openingSchedule: {
+    allHours: boolean;
+    monStart: number;
+    monEnd: number;
+  };
+}
+
+export interface MutationResult {
+  mutationsExecuted: number;
+  mutationsFailed: number;
+  errors: Array<{ locationRef: string; error: string }>;
+}
+
+export interface ProcessFileResult {
+  success: boolean;
+  locations: Array<{ query: string; variables: Record<string, unknown> }>;
+  error?: string;
+  fileName: string;
+}
+
+// Type guard for validation
+export function isLocationRecord(obj: unknown): obj is LocationRecord {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const loc = obj as Record<string, unknown>;
+
+  return (
+    typeof loc.locationRef === 'string' &&
+    typeof loc.locationName === 'string' &&
+    typeof loc.locationType === 'string' &&
+    typeof loc.address === 'object' &&
+    typeof loc.geo === 'object'
+  );
+}
+```
+
+---
+
+---
+
+## 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
+
+```
+sftp-json-location-graphql/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-location-sync.ts   # Scheduled: Daily location sync
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-location-sync.ts   # Webhook: Manual trigger
+    │       └── job-status-check.ts     # Webhook: Status query
+    │
+    ├── services/
+    │   └── location-sync.service.ts     # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── location-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-location-sync.ts`
+
+**Purpose**: Automatic daily location sync
+**Trigger**: Cron schedule (`0 2 * * *`)
+**Exposed as Endpoint**: ❌ NO - Runs automatically
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { executeLocationIngestion } from '../../services/location-sync.service';
+import { generateJobId } from '../../utils/job-id-generator';
+
+/**
+ * Scheduled Workflow: Daily Location Sync
+ *
+ * Runs automatically daily at 2 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Uses shared service: location-sync.service.ts
+ */
+export const dailyLocationSync = schedule(
+  'location-sync-scheduled',
+  '0 2 * * *' // Daily at 2 AM UTC
+).then(
+  http('run-location-sync', { connection: 'fluent_commerce' }, async ctx => {
+    const jobId = generateJobId('SCHEDULED', 'LOC');
+    return await executeLocationIngestion(ctx, { jobId, triggeredBy: 'schedule' });
+  })
+);
+```
+
+---
+
+### 2. Webhook Workflows (`src/workflows/webhook/`)
+
+All HTTP-based triggers that create webhook endpoints.
+
+#### `src/workflows/webhook/adhoc-location-sync.ts`
+
+**Purpose**: Manual location sync trigger (on-demand)
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/location-sync-adhoc`
+**Use Cases**: Testing, priority processing, ad-hoc runs
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { executeLocationIngestion } from '../../services/location-sync.service';
+import { generateJobId } from '../../utils/job-id-generator';
+
+/**
+ * Webhook: Manual Location Sync Trigger
+ *
+ * Endpoint: POST https://{workspace}.versori.run/location-sync-adhoc
+ * Request body (optional): { filePattern: "urgent_*.json", maxFiles: 5, forceReprocess: true }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: location-sync.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const adhocLocationSync = webhook('location-sync-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'location-sync-adhoc', // Versori validates API key
+}).then(
+  http('run-location-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
+    const jobId = generateJobId('ADHOC', 'LOC');
+    const { filePattern, maxFiles, forceReprocess } = ctx.data;
+    return await executeLocationIngestion(ctx, {
+      jobId,
+      triggeredBy: 'manual',
+      filePattern,
+      maxFiles,
+      forceReprocess,
+    });
+  })
+);
+```
+
+---
+
+#### `src/workflows/webhook/job-status-check.ts`
+
+**Purpose**: Query job status and progress
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/location-sync-job-status`
+**Request Body**: `{ "jobId": "SCHEDULED_LOC_20250124_183045_abc123" }`
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { getJobStatus } from '../../services/location-sync.service';
+
+/**
+ * Webhook: Job Status Check
+ *
+ * Endpoint: POST https://{workspace}.versori.run/location-sync-job-status
+ * Request body: { "jobId": "SCHEDULED_LOC_20250124_183045_abc123" }
+ *
+ * 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 locationSyncJobStatus = webhook('location-sync-job-status', {
+  response: { mode: 'sync' },
+  connection: 'location-sync-job-status',
+}).then(
+  fn('query-job-status', async ctx => {
+    const { jobId } = ctx.data;
+    const status = await getJobStatus(ctx.openKv(':project:'), jobId, ctx.log);
+    return { success: !!status, jobId, ...status };
+  })
+);
+```
+
+---
+
+### 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 { MemoryInterpreter } from '@versori/run';
+
+// Import scheduled workflows
+import { dailyLocationSync } from './src/workflows/scheduled/daily-location-sync';
+
+// Import webhook workflows
+import { adhocLocationSync } from './src/workflows/webhook/adhoc-location-sync';
+import { locationSyncJobStatus } from './src/workflows/webhook/job-status-check';
+
+// Register all workflows
+export {
+  // Scheduled (time-based triggers)
+  dailyLocationSync,
+
+  // Webhooks (HTTP-based triggers)
+  adhocLocationSync,
+  locationSyncJobStatus,
+};
+
+// ✅ Memory interpreter for local development
+export const interpreter = new MemoryInterpreter({
+  workflows: [dailyLocationSync, adhocLocationSync, locationSyncJobStatus],
+});
+```
+
+**What Gets Exposed:**
+- ✅ `adhocLocationSync` → `https://{workspace}.versori.run/location-sync-adhoc`
+- ✅ `locationSyncJobStatus` → `https://{workspace}.versori.run/location-sync-job-status`
+- ❌ `dailyLocationSync` → NOT exposed (runs automatically on cron)
+
+---
+
+## Package Configuration
+
+**File:** `package.json`
+
+```json
+{
+  "name": "sftp-json-location-graphql",
+  "type": "module",
+  "main": "index.ts",
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+**File:** `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+
+---
+
+## Deployment
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Deploy to Versori
+npm run deploy
+
+# 3. Configure activation variables in Versori Dashboard
+# CRITICAL: Set fluentRetailerId
+
+# 4. Test with sample file
+curl -X POST https://your-workspace.versori.run/location-ingestion-adhoc \
+  -H "Content-Type: application/json" \
+  -d '{"forceReprocess": false}'
+```
+
+---
+
+## Testing
+
+### Test Scheduled Run
+Upload test JSON to SFTP and wait for scheduled execution (2 AM daily).
+
+### Test Ad hoc Trigger
+```bash
+curl -X POST https://workspace.versori.run/location-ingestion-adhoc \
+  -d '{"filePattern": "test_*.json"}'
+```
+
+### Test Job Status
+```bash
+curl -X POST https://workspace.versori.run/location-ingestion-job-status \
+  -d '{"jobId": "ADHOC_LOC_20251101_183045_abc123"}'
+```
+
+---
+
+## Monitoring
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "filesProcessed": 1,
+  "filesSkipped": 0,
+  "filesFailed": 0,
+  "totalRecords": 50,
+  "mutationsExecuted": 50,
+  "mutationsFailed": 0,
+  "results": [
+    {
+      "file": "locations_2025-01-22.json",
+      "success": true,
+      "recordsProcessed": 50,
+      "mutationsExecuted": 50,
+      "mutationsFailed": 0
+    }
+  ],
+  "duration": 12345
+}
+```
+
+### Partial Success Response
+
+```json
+{
+  "success": true,
+  "filesProcessed": 1,
+  "filesSkipped": 0,
+  "filesFailed": 0,
+  "totalRecords": 50,
+  "mutationsExecuted": 45,
+  "mutationsFailed": 5,
+  "results": [
+    {
+      "file": "locations_2025-01-22.json",
+      "success": true,
+      "recordsProcessed": 50,
+      "mutationsExecuted": 45,
+      "mutationsFailed": 5,
+      "errors": ["LOC-001: Invalid location ref", "LOC-002: Missing required field"]
+    }
+  ],
+  "duration": 12345
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "filesProcessed": 0,
+  "filesFailed": 1,
+  "totalRecords": 0,
+  "mutationsExecuted": 0,
+  "mutationsFailed": 0,
+  "results": [
+    {
+      "file": "locations_2025-01-22.json",
+      "success": false,
+      "error": "JSON 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.
+
+---
+
+Before deployment, verify:
+
+- [ ] ✅ `GraphQLMutationMapper` imported (NOT `UniversalMapper`)
+- [ ] ✅ NO `client.setRetailerId()` call (not needed for GraphQL mutations)
+- [ ] ✅ `fluentRetailerId` activation variable configured (only if mutation schema requires it)
+- [ ] ✅ Mapping config in external JSON file
+- [ ] ✅ Mapping config uses correct structure (`mutation` property, `arguments.input`, resolver names without `sdk.` prefix)
+- [ ] ✅ Uses `mapper.map()` method (returns `{ query, variables }`)
+- [ ] ✅ Type definitions include `LocationRecord`, `MappedLocation`
+- [ ] ✅ Services follow modular pattern (no logger params in business logic)
+- [ ] ✅ Three workflows implemented (scheduled, ad hoc, status)
+- [ ] ✅ Buffer imported from `node:buffer`
+- [ ] ✅ **Double-finally SFTP disposal** pattern implemented (inner + outer finally)
+- [ ] ✅ Complete service implementations (processor, sender, logger)
+- [ ] ✅ Error handling with per-record tracking
+- [ ] ✅ Processing mode documented (per-file vs chunked)
+
+---
+
+## Troubleshooting
+
+### GraphQL Mutations Failing
+**Problem:** Mutations return auth errors
+**Solution:**
+1. Verify OAuth2 credentials are correct in Versori connection
+2. Check if mutation schema requires retailerId in input variables
+3. Do NOT use `client.setRetailerId()` - it's only for Job/Event API
+
+### Wrong Mapper Error
+**Problem:** "UniversalMapper not suitable for GraphQL"
+**Solution:** Replace `UniversalMapper` with `GraphQLMutationMapper`
+
+### Mapping Config Errors
+**Problem:** "Invalid mapping structure"
+**Solution:** Ensure config has `mutation` property (not `mutationName`) and `arguments.input` structure. Resolver names should be without `sdk.` prefix (`trim`, `toUpperCase`, `parseInt`, `parseFloat`, `toBoolean`)
+
+### Wrong Method Name
+**Problem:** "generateMutation is not a function"
+**Solution:** Use `mapper.map()` method, not `generateMutation()`. Returns `{ query, variables }`
+
+---
+
+## Key Takeaways
+
+- ✅ **Use GraphQLMutationMapper** for GraphQL mutations (NOT UniversalMapper)
+- ⚠️ **Set retailerId** on client before mutations (VERIFICATION REQUIRED - may need mutation input instead)
+- ✅ **Double-finally SFTP disposal** for resource safety (matches Event API gold standard)
+- ✅ **External JSON config** for production (not inline)
+- ✅ **Modular services** for testability and reusability
+- ✅ **Complete error handling** with per-record tracking
+- ✅ **Processing modes** documented (per-file recommended, chunked optional)
+- ✅ **Type-safe** with comprehensive interfaces
+- ✅ **Native Versori logging** (LoggingService removed - use native log)
+- ✅ **GraphQL alias batching** support for high-volume scenarios (mutationsPerAliasBatch parameter)
+
+---
+
+## References
+
+- **Gold Standard Guide:** `internal/GOLD-STANDARD-APPLICATION-GUIDE.md`
+- **GraphQL Mutation Mapping:** `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
+- **GraphQL Alias Batching:** `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/graphql-alias-batching-guide.md`
+- **retailerId Configuration:** `fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md`
+- **Event API Template:** `template-ingestion-sftp-xml-product-event.md` (architectural reference)
+
+---
+
+**Status:** ✅ Gold Standard Compliant
+**Compliance:** All patterns verified against SDK and Fluent GraphQL schema