@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/business-examples/business-examples-graphql-parquet-extraction.md

@@ -1,518 +1,518 @@
----
-template_id: tpl-extract-graphql-to-s3-parquet
-canonical_filename: graphql-parquet-extraction.md
-sdk_version: latest
-runtime: versori
-direction: extraction
-source: fluent-graphql
-destination: s3-parquet
-entity: inventory|orders
-format: parquet
-logging: versori
-status: stable
----
-
-# Template: Extraction - GraphQL to S3 Parquet
-
-**SDK**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-**Deployment Target:** Versori Platform
-
----
-
----
-
-## 📋 Implementation Prompt
-
-```
-I need a Versori extractor that:
-
-1) Queries Fluent Commerce GraphQL with auto-pagination (Relay cursors)
-2) Supports incremental runs via KV state (date overlap buffer optional)
-3) Transforms results using UniversalMapper per mapping config
-4) Writes partitioned Parquet files to S3 with metadata
-5) Uses native Versori log (LoggingService removed - use native log)
-
-Use the loaded docs to fill in SDK specifics and best practices.
-Keep the structure identical to the template; only adapt where needed.
-```
-
----
-
-## 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:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-graphql-parquet-extraction/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── webhook/
-    │   │   └── adhoc-extraction.ts       # Webhook: Manual extraction
-    │   │
-    │   └── scheduled/
-    │       └── daily-extraction.ts       # Scheduled: Daily extraction
-    │
-    ├── services/
-    │   └── extraction.service.ts         # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── extraction-config.json        # Configuration
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Scalable (add new workflows without cluttering)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Easy to modify individual workflows without affecting others
-
----
-
-## 💻 STEP 3: Implementation
-
-- Source: GraphQL (`createClient().graphql` with auto-pagination)
-- Transform: `UniversalMapper` (mapping per entity)
-- Destination: S3 Parquet (`S3DataSource.writeParquetContent` + `uploadFile`)
-- State: `VersoriKVAdapter` + `StateService` for incremental cursor
-- Execution modes: scheduled workflow, ad hoc webhook
-
-### 📦 SDK Imports (Verified - Versori Optimized)
-
-```typescript
-import {
-  createClient,
-  UniversalMapper,
-  S3DataSource,
-  VersoriKVAdapter,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform
-import { schedule, webhook, http, fn } from '@versori/run';
-```
-
-> Note: Use native Versori `log` from context; do not import `LoggingService` on Versori.
-
----
-
-# Versori: GraphQL Extraction → Partitioned Parquet on S3
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Versori workflow that extracts records from Fluent via GraphQL with auto-pagination, transforms with UniversalMapper, and writes partitioned Parquet files to S3.
-
-**Type**: Extraction
-
-**Complexity**: Medium
-
-**Runtime**: Versori Platform (Scheduled or Manual Webhook)
-
-**Estimated Lines**: ~600
-
-## What You'll Build
-
-- Versori scheduled workflow (daily) and manual webhook trigger
-- Fluent client via Versori connection
-- GraphQL query with auto-pagination (progress callbacks)
-- UniversalMapper transform for export schema
-- Partitioning by date/entity/size with multiple Parquet files
-- Upload to S3 target with metadata
-- Incremental extraction using Versori KV state
-
-## 📦 SDK Imports (Verified - Versori Optimized)
-
-**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
-
-**✅ VERSORI PLATFORM - Use Native Logs:**
-
-- Use `log` from context: `const { log } = ctx;`
-- Don't import or use LoggingService for Versori connectors
-- Native Versori logs are simpler and automatically integrated with platform monitoring
-
-```typescript
-import {
-  createClient,
-  UniversalMapper,
-  S3DataSource,
-  VersoriKVAdapter,
-} from '@fluentcommerce/fc-connect-sdk';
-
-await createClient(ctx); // Versori context-aware client
-await client.graphql({ query, variables, pagination });
-new UniversalMapper(mapping, { customResolvers });
-await s3.writeParquetContent(data, { compression: 'SNAPPY' });
-await s3.uploadFile(key, buffer, { contentType: 'application/octet-stream' });
-const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
-```
-
-## Project Setup
-
-```bash
-# Create project
-mkdir versori-graphql-parquet && cd $_
-
-# Initialize
-npm init -y
-
-# Install dependencies
-npm install @fluentcommerce/fc-connect-sdk @versori/run
-
-# Structure
-mkdir -p src
-```
-
-### Package Configuration (package.json)
-
-```json
-{
-  "name": "versori-graphql-parquet",
-  "version": "1.0.0",
-  "description": "Versori workflow: GraphQL extraction → partitioned Parquet on S3",
-  "versori": {
-    "workflows": "./src/index.ts"
-  },
-  "type": "module",
-  "scripts": {
-    "deploy": "versori deploy",
-    "logs": "versori logs"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^20.0.0"
-  }
-}
-```
-
-### TypeScript Configuration (tsconfig.json)
-
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
-
-### Activation Variables (Versori)
-
-```bash
-# Fluent
-retailerId=your-retailer-id
-
-# Target S3
-targetBucket=fluent-exports
-targetRegion=us-east-1
-targetAccessKeyId=AKIAXXXXXXXXXXXX
-targetSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-targetPrefix=exports/
-
-# Extraction controls
-entityType=inventory        # inventory | orders
-pageSize=200
-maxRecords=20000
-incremental=true
-partitionBy=date            # date | entity | none
-partitionSize=10000         # records per Parquet file (cap)
-stateKey=export:last-run    # KV key for last export timestamp
-```
-
----
-
-## Complete Workflow (src/index.ts)
-
-```typescript
-import { schedule, webhook, http, fn } from '@versori/run';
-import {
-  createClient,
-  UniversalMapper,
-  S3DataSource,
-  VersoriKVAdapter,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Inline query templates (vendor-agnostic)
-const queries = {
-  inventory: {
-    connectionPath: 'inventoryPositions',
-    query: `query GetInventory($retailerId: ID!, $first: Int!, $after: String, $updatedFrom: DateTime) {
-      inventoryPositions(retailerId: $retailerId, first: $first, after: $after, updatedOn: { from: $updatedFrom }) {
-        edges { node { id ref productRef locationRef qty availableQty reservedQty status updatedOn } cursor }
-        pageInfo { hasNextPage }
-      }
-    }`,
-  },
-  orders: {
-    connectionPath: 'orders',
-    query: `query GetOrders($retailerId: ID!, $first: Int!, $after: String, $createdFrom: DateTime) {
-      orders(retailerId: $retailerId, first: $first, after: $after, createdOn: { from: $createdFrom }) {
-        edges { node { id ref status totalPrice totalTaxPrice createdOn customer { ref email firstName lastName } } cursor }
-        pageInfo { hasNextPage }
-      }
-    }`,
-  },
-} as const;
-
-// Inline mapping templates (minimal generic fields)
-const mappings = {
-  inventory: {
-    fields: {
-      sku: { source: 'productRef', resolver: 'sdk.uppercase' },
-      location: { source: 'locationRef' },
-      quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-      available: { source: 'availableQty', resolver: 'sdk.parseInt' },
-      status: { source: 'status', resolver: 'sdk.lowercase' },
-      updated_at: { source: 'updatedOn', resolver: 'sdk.formatDate' },
-    },
-  },
-  orders: {
-    fields: {
-      order_id: { source: 'ref' },
-      status: { source: 'status', resolver: 'sdk.lowercase' },
-      total: { source: 'totalPrice', resolver: 'sdk.parseFloat' },
-      created_at: { source: 'createdOn', resolver: 'sdk.formatDate' },
-      customer_email: { source: 'customer.email' },
-      customer_name: {
-        source: null,
-        resolver: 'custom.fullName',  // Custom resolver defined below
-      },
-    },
-  },
-} as const;
-
-async function runExport(ctx: any) {
-  // ✅ VERSORI PLATFORM: Extract native log from context
-  const { log, openKv, activation } = ctx;
-
-  const entityType = (activation?.getVariable('entityType') || 'inventory').toLowerCase();
-  const retailerId = activation?.getVariable('retailerId');
-  const pageSize = parseInt(activation?.getVariable('pageSize') || '200', 10);
-  const maxRecords = parseInt(activation?.getVariable('maxRecords') || '20000', 10);
-  const incremental = (activation?.getVariable('incremental') || 'true') === 'true';
-  const partitionBy = (activation?.getVariable('partitionBy') || 'date').toLowerCase();
-  const partitionSize = parseInt(activation?.getVariable('partitionSize') || '10000', 10);
-
-  // Target S3
-  const s3 = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      name: 'Target S3',
-      s3Config: {
-        bucket: activation?.getVariable('targetBucket'),
-        region: activation?.getVariable('targetRegion') || 'us-east-1',
-        accessKeyId: activation?.getVariable('targetAccessKeyId'),
-        secretAccessKey: activation?.getVariable('targetSecretAccessKey'),
-      },
-    },
-    log
-  );
-
-  // Fluent client from Versori connection
-  const client = await createClient(ctx);
-  const queryCfg = (queries as any)[entityType];
-  if (!queryCfg) {
-    log.error('[GraphQLParquetExtraction] Configuration error: Unknown entityType', {
-      entityType,
-      recommendation: `Set entityType to one of: ${Object.keys(queries).join(', ')}`
-    });
-    throw new Error(`Unknown entityType: ${entityType}`);
-  }
-
-  const variables: any = { retailerId, first: pageSize };
-
-  // Incremental state via Versori KV
-  const kv = new VersoriKVAdapter(openKv(':project:'));
-  const stateKey = activation?.getVariable('stateKey') || 'export:last-run';
-
-  if (incremental) {
-    const state = await kv.get([stateKey]);
-    const lastIso = (state?.value as any)?.lastExportIso;
-    if (lastIso) {
-      if (entityType === 'inventory') variables.updatedFrom = lastIso;
-      if (entityType === 'orders') variables.createdFrom = lastIso;
-    }
-  }
-
-  // Execute GraphQL with auto-pagination
-  const start = Date.now();
-  const result = await client.graphql({
-    query: queryCfg.query,
-    variables,
-    pagination: {
-      maxRecords,
-      onProgress: (page: number, count: number) => {
-        if (page % 10 === 0) log.info('Pagination progress', { page, count });
-      },
-    },
-  });
-
-  const connection = (result.data as any)[queryCfg.connectionPath];
-  const nodes = Array.isArray(connection?.edges) ? connection.edges.map((e: any) => e.node) : [];
-
-  log.info('Extracted records', { count: nodes.length, ms: Date.now() - start });
-
-  if (nodes.length === 0) return { uploaded: [], total: 0 };
-
-  // Transform
-  const mapper = new UniversalMapper((mappings as any)[entityType] || { fields: {} }, {
-    customResolvers: {
-      'custom.fullName': (v: any, s: any) =>
-        `${s?.customer?.firstName || ''} ${s?.customer?.lastName || ''}`.trim(),
-    },
-  });
-
-  const transformed: any[] = [];
-  for (const n of nodes) {
-    const res = await mapper.map(n);
-    if (res.success) transformed.push(res.data);
-  }
-
-  // Partitioning
-  const groups: any[][] = [];
-  if (partitionBy === 'none') {
-    for (let i = 0; i < transformed.length; i += partitionSize)
-      groups.push(transformed.slice(i, i + partitionSize));
-  } else if (partitionBy === 'entity') {
-    const byKey = new Map<string, any[]>();
-    for (const rec of transformed) {
-      const key = String(rec.status || 'default');
-      const arr = byKey.get(key) || [];
-      arr.push(rec);
-      byKey.set(key, arr);
-    }
-    for (const arr of byKey.values())
-      for (let i = 0; i < arr.length; i += partitionSize)
-        groups.push(arr.slice(i, i + partitionSize));
-  } else {
-    // date partition (YYYY/MM/DD)
-    const byDate = new Map<string, any[]>();
-    for (const rec of transformed) {
-      const iso = String(rec.updated_at || rec.created_at || new Date().toISOString());
-      const d = new Date(iso);
-      const key = `${d.getUTCFullYear()}/${String(d.getUTCMonth() + 1).padStart(2, '0')}/${String(d.getUTCDate()).padStart(2, '0')}`;
-      const arr = byDate.get(key) || [];
-      arr.push(rec);
-      byDate.set(key, arr);
-    }
-    for (const [dateKey, arr] of byDate.entries()) {
-      for (let i = 0; i < arr.length; i += partitionSize)
-        groups.push(Object.assign(arr.slice(i, i + partitionSize), { __dateKey: dateKey }));
-    }
-  }
-
-  // Upload Parquet parts
-  const uploaded: string[] = [];
-  const prefix = activation?.getVariable('targetPrefix') || 'exports/';
-  let idx = 0;
-
-  for (const group of groups) {
-    const dateKey = (group as any).__dateKey as string | undefined;
-    const ts = new Date().toISOString().replace(/[:.]/g, '-');
-    const folder =
-      partitionBy === 'date' && dateKey
-        ? `${prefix}${entityType}/${dateKey}/`
-        : `${prefix}${entityType}/`;
-    const key = `${folder}${entityType}_${ts}_part-${idx++}.parquet`;
-
-    const buffer = await (s3 as any).writeParquetContent(group as any[], {
-      compression: 'SNAPPY',
-      rowGroupSize: 10000,
-    });
-
-    await s3.uploadFile(key, buffer, {
-      contentType: 'application/octet-stream',
-      metadata: {
-        'entity-type': entityType,
-        'record-count': String(group.length),
-        'exported-at': new Date().toISOString(),
-      },
-    });
-
-    uploaded.push(key);
-  }
-
-  // Save incremental state
-  if (incremental) {
-    await kv.set([stateKey], { lastExportIso: new Date().toISOString() });
-  }
-
-  return { uploaded, total: transformed.length };
-}
-
-// Scheduled export (e.g., daily 2 AM UTC)
-export const scheduledGraphqlExport = schedule('graphql-export-daily', '0 2 * * *').then(
-  http('export-to-parquet', { connection: 'fluent_commerce' }, async ctx => {
-    const result = await runExport(ctx);
-    return { success: true, ...result };
-  })
-);
-
-// Manual trigger for testing
-export const exportNow = webhook('export-now').then(
-  http('export-now-run', { connection: 'fluent_commerce' }, async ctx => {
-    const result = await runExport(ctx);
-    return { success: true, ...result };
-  })
-);
-```
-
----
-
-## Deployment (Versori)
-
-```bash
-npm run deploy
-npm run logs
-
-# Test manual endpoint:
-# curl -X POST https://{workspace}.versori.run/export-now -H "Content-Type: application/json" -d '{}'
-```
-
-## Testing
-
-- Small run: set `pageSize=50`, `maxRecords=200`, `incremental=false` and trigger `export-now`.
-- Verify S3 keys under `targetPrefix/entityType/YYYY/MM/DD/`.
-- Check metadata on uploaded objects for `record-count` and `exported-at`.
-
-## Common Issues & Solutions
-
-- **Auto-pagination not running**
-  - Ensure GraphQL query uses `$first` and `$after` variables and you pass `first` in variables.
-- **KV state not updating**
-  - Verify `stateKey` and that `:project:` scope is used with `openKv(':project:')`.
-- **Large uploads slow**
-  - Use SNAPPY compression (default shown), reduce partition size, and consider parallel uploads.
-- **Time gaps in incremental**
-  - Add an overlap (export last 5-10 minutes again) and dedupe in downstream consumers.
-
-## Production Checklist
-
-- Activation variables set and secured (no secrets in code)
-- Connection configured for Fluent Commerce
-- S3 permissions validated (PutObject, ListBucket)
-- Partition strategy agreed with consumers (date/entity/size)
-- Incremental strategy defined with overlap
-- Observability (logs/metrics) and alerting on failures
-- Cost/performance tuned (page size, row groups, partition size)
-
-## Related Guides
-
-- Auto-pagination: `fc-connect-sdk/docs/guides/pagination.md`
-- Universal Mapping: `fc-connect-sdk/docs/guides/mapping/readme.md`
-- Versori KV patterns: `docs/use-cases/versori/03-kv-state-management.md`
-- Error handling: `docs/use-cases/patterns/error-handling-retry.md`
+---
+template_id: tpl-extract-graphql-to-s3-parquet
+canonical_filename: graphql-parquet-extraction.md
+sdk_version: latest
+runtime: versori
+direction: extraction
+source: fluent-graphql
+destination: s3-parquet
+entity: inventory|orders
+format: parquet
+logging: versori
+status: stable
+---
+
+# Template: Extraction - GraphQL to S3 Parquet
+
+**SDK**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+**Deployment Target:** Versori Platform
+
+---
+
+---
+
+## 📋 Implementation Prompt
+
+```
+I need a Versori extractor that:
+
+1) Queries Fluent Commerce GraphQL with auto-pagination (Relay cursors)
+2) Supports incremental runs via KV state (date overlap buffer optional)
+3) Transforms results using UniversalMapper per mapping config
+4) Writes partitioned Parquet files to S3 with metadata
+5) Uses native Versori log (LoggingService removed - use native log)
+
+Use the loaded docs to fill in SDK specifics and best practices.
+Keep the structure identical to the template; only adapt where needed.
+```
+
+---
+
+## 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:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+graphql-parquet-extraction/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── webhook/
+    │   │   └── adhoc-extraction.ts       # Webhook: Manual extraction
+    │   │
+    │   └── scheduled/
+    │       └── daily-extraction.ts       # Scheduled: Daily extraction
+    │
+    ├── services/
+    │   └── extraction.service.ts         # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── extraction-config.json        # Configuration
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Scalable (add new workflows without cluttering)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Easy to modify individual workflows without affecting others
+
+---
+
+## 💻 STEP 3: Implementation
+
+- Source: GraphQL (`createClient().graphql` with auto-pagination)
+- Transform: `UniversalMapper` (mapping per entity)
+- Destination: S3 Parquet (`S3DataSource.writeParquetContent` + `uploadFile`)
+- State: `VersoriKVAdapter` + `StateService` for incremental cursor
+- Execution modes: scheduled workflow, ad hoc webhook
+
+### 📦 SDK Imports (Verified - Versori Optimized)
+
+```typescript
+import {
+  createClient,
+  UniversalMapper,
+  S3DataSource,
+  VersoriKVAdapter,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform
+import { schedule, webhook, http, fn } from '@versori/run';
+```
+
+> Note: Use native Versori `log` from context; do not import `LoggingService` on Versori.
+
+---
+
+# Versori: GraphQL Extraction → Partitioned Parquet on S3
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Versori workflow that extracts records from Fluent via GraphQL with auto-pagination, transforms with UniversalMapper, and writes partitioned Parquet files to S3.
+
+**Type**: Extraction
+
+**Complexity**: Medium
+
+**Runtime**: Versori Platform (Scheduled or Manual Webhook)
+
+**Estimated Lines**: ~600
+
+## What You'll Build
+
+- Versori scheduled workflow (daily) and manual webhook trigger
+- Fluent client via Versori connection
+- GraphQL query with auto-pagination (progress callbacks)
+- UniversalMapper transform for export schema
+- Partitioning by date/entity/size with multiple Parquet files
+- Upload to S3 target with metadata
+- Incremental extraction using Versori KV state
+
+## 📦 SDK Imports (Verified - Versori Optimized)
+
+**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
+
+**✅ VERSORI PLATFORM - Use Native Logs:**
+
+- Use `log` from context: `const { log } = ctx;`
+- Don't import or use LoggingService for Versori connectors
+- Native Versori logs are simpler and automatically integrated with platform monitoring
+
+```typescript
+import {
+  createClient,
+  UniversalMapper,
+  S3DataSource,
+  VersoriKVAdapter,
+} from '@fluentcommerce/fc-connect-sdk';
+
+await createClient(ctx); // Versori context-aware client
+await client.graphql({ query, variables, pagination });
+new UniversalMapper(mapping, { customResolvers });
+await s3.writeParquetContent(data, { compression: 'SNAPPY' });
+await s3.uploadFile(key, buffer, { contentType: 'application/octet-stream' });
+const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
+```
+
+## Project Setup
+
+```bash
+# Create project
+mkdir versori-graphql-parquet && cd $_
+
+# Initialize
+npm init -y
+
+# Install dependencies
+npm install @fluentcommerce/fc-connect-sdk @versori/run
+
+# Structure
+mkdir -p src
+```
+
+### Package Configuration (package.json)
+
+```json
+{
+  "name": "versori-graphql-parquet",
+  "version": "1.0.0",
+  "description": "Versori workflow: GraphQL extraction → partitioned Parquet on S3",
+  "versori": {
+    "workflows": "./src/index.ts"
+  },
+  "type": "module",
+  "scripts": {
+    "deploy": "versori deploy",
+    "logs": "versori logs"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}
+```
+
+### TypeScript Configuration (tsconfig.json)
+
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+
+### Activation Variables (Versori)
+
+```bash
+# Fluent
+retailerId=your-retailer-id
+
+# Target S3
+targetBucket=fluent-exports
+targetRegion=us-east-1
+targetAccessKeyId=AKIAXXXXXXXXXXXX
+targetSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+targetPrefix=exports/
+
+# Extraction controls
+entityType=inventory        # inventory | orders
+pageSize=200
+maxRecords=20000
+incremental=true
+partitionBy=date            # date | entity | none
+partitionSize=10000         # records per Parquet file (cap)
+stateKey=export:last-run    # KV key for last export timestamp
+```
+
+---
+
+## Complete Workflow (src/index.ts)
+
+```typescript
+import { schedule, webhook, http, fn } from '@versori/run';
+import {
+  createClient,
+  UniversalMapper,
+  S3DataSource,
+  VersoriKVAdapter,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Inline query templates (vendor-agnostic)
+const queries = {
+  inventory: {
+    connectionPath: 'inventoryPositions',
+    query: `query GetInventory($retailerId: ID!, $first: Int!, $after: String, $updatedFrom: DateTime) {
+      inventoryPositions(retailerId: $retailerId, first: $first, after: $after, updatedOn: { from: $updatedFrom }) {
+        edges { node { id ref productRef locationRef qty availableQty reservedQty status updatedOn } cursor }
+        pageInfo { hasNextPage }
+      }
+    }`,
+  },
+  orders: {
+    connectionPath: 'orders',
+    query: `query GetOrders($retailerId: ID!, $first: Int!, $after: String, $createdFrom: DateTime) {
+      orders(retailerId: $retailerId, first: $first, after: $after, createdOn: { from: $createdFrom }) {
+        edges { node { id ref status totalPrice totalTaxPrice createdOn customer { ref email firstName lastName } } cursor }
+        pageInfo { hasNextPage }
+      }
+    }`,
+  },
+} as const;
+
+// Inline mapping templates (minimal generic fields)
+const mappings = {
+  inventory: {
+    fields: {
+      sku: { source: 'productRef', resolver: 'sdk.uppercase' },
+      location: { source: 'locationRef' },
+      quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+      available: { source: 'availableQty', resolver: 'sdk.parseInt' },
+      status: { source: 'status', resolver: 'sdk.lowercase' },
+      updated_at: { source: 'updatedOn', resolver: 'sdk.formatDate' },
+    },
+  },
+  orders: {
+    fields: {
+      order_id: { source: 'ref' },
+      status: { source: 'status', resolver: 'sdk.lowercase' },
+      total: { source: 'totalPrice', resolver: 'sdk.parseFloat' },
+      created_at: { source: 'createdOn', resolver: 'sdk.formatDate' },
+      customer_email: { source: 'customer.email' },
+      customer_name: {
+        source: null,
+        resolver: 'custom.fullName',  // Custom resolver defined below
+      },
+    },
+  },
+} as const;
+
+async function runExport(ctx: any) {
+  // ✅ VERSORI PLATFORM: Extract native log from context
+  const { log, openKv, activation } = ctx;
+
+  const entityType = (activation?.getVariable('entityType') || 'inventory').toLowerCase();
+  const retailerId = activation?.getVariable('retailerId');
+  const pageSize = parseInt(activation?.getVariable('pageSize') || '200', 10);
+  const maxRecords = parseInt(activation?.getVariable('maxRecords') || '20000', 10);
+  const incremental = (activation?.getVariable('incremental') || 'true') === 'true';
+  const partitionBy = (activation?.getVariable('partitionBy') || 'date').toLowerCase();
+  const partitionSize = parseInt(activation?.getVariable('partitionSize') || '10000', 10);
+
+  // Target S3
+  const s3 = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      name: 'Target S3',
+      s3Config: {
+        bucket: activation?.getVariable('targetBucket'),
+        region: activation?.getVariable('targetRegion') || 'us-east-1',
+        accessKeyId: activation?.getVariable('targetAccessKeyId'),
+        secretAccessKey: activation?.getVariable('targetSecretAccessKey'),
+      },
+    },
+    log
+  );
+
+  // Fluent client from Versori connection
+  const client = await createClient(ctx);
+  const queryCfg = (queries as any)[entityType];
+  if (!queryCfg) {
+    log.error('[GraphQLParquetExtraction] Configuration error: Unknown entityType', {
+      entityType,
+      recommendation: `Set entityType to one of: ${Object.keys(queries).join(', ')}`
+    });
+    throw new Error(`Unknown entityType: ${entityType}`);
+  }
+
+  const variables: any = { retailerId, first: pageSize };
+
+  // Incremental state via Versori KV
+  const kv = new VersoriKVAdapter(openKv(':project:'));
+  const stateKey = activation?.getVariable('stateKey') || 'export:last-run';
+
+  if (incremental) {
+    const state = await kv.get([stateKey]);
+    const lastIso = (state?.value as any)?.lastExportIso;
+    if (lastIso) {
+      if (entityType === 'inventory') variables.updatedFrom = lastIso;
+      if (entityType === 'orders') variables.createdFrom = lastIso;
+    }
+  }
+
+  // Execute GraphQL with auto-pagination
+  const start = Date.now();
+  const result = await client.graphql({
+    query: queryCfg.query,
+    variables,
+    pagination: {
+      maxRecords,
+      onProgress: (page: number, count: number) => {
+        if (page % 10 === 0) log.info('Pagination progress', { page, count });
+      },
+    },
+  });
+
+  const connection = (result.data as any)[queryCfg.connectionPath];
+  const nodes = Array.isArray(connection?.edges) ? connection.edges.map((e: any) => e.node) : [];
+
+  log.info('Extracted records', { count: nodes.length, ms: Date.now() - start });
+
+  if (nodes.length === 0) return { uploaded: [], total: 0 };
+
+  // Transform
+  const mapper = new UniversalMapper((mappings as any)[entityType] || { fields: {} }, {
+    customResolvers: {
+      'custom.fullName': (v: any, s: any) =>
+        `${s?.customer?.firstName || ''} ${s?.customer?.lastName || ''}`.trim(),
+    },
+  });
+
+  const transformed: any[] = [];
+  for (const n of nodes) {
+    const res = await mapper.map(n);
+    if (res.success) transformed.push(res.data);
+  }
+
+  // Partitioning
+  const groups: any[][] = [];
+  if (partitionBy === 'none') {
+    for (let i = 0; i < transformed.length; i += partitionSize)
+      groups.push(transformed.slice(i, i + partitionSize));
+  } else if (partitionBy === 'entity') {
+    const byKey = new Map<string, any[]>();
+    for (const rec of transformed) {
+      const key = String(rec.status || 'default');
+      const arr = byKey.get(key) || [];
+      arr.push(rec);
+      byKey.set(key, arr);
+    }
+    for (const arr of byKey.values())
+      for (let i = 0; i < arr.length; i += partitionSize)
+        groups.push(arr.slice(i, i + partitionSize));
+  } else {
+    // date partition (YYYY/MM/DD)
+    const byDate = new Map<string, any[]>();
+    for (const rec of transformed) {
+      const iso = String(rec.updated_at || rec.created_at || new Date().toISOString());
+      const d = new Date(iso);
+      const key = `${d.getUTCFullYear()}/${String(d.getUTCMonth() + 1).padStart(2, '0')}/${String(d.getUTCDate()).padStart(2, '0')}`;
+      const arr = byDate.get(key) || [];
+      arr.push(rec);
+      byDate.set(key, arr);
+    }
+    for (const [dateKey, arr] of byDate.entries()) {
+      for (let i = 0; i < arr.length; i += partitionSize)
+        groups.push(Object.assign(arr.slice(i, i + partitionSize), { __dateKey: dateKey }));
+    }
+  }
+
+  // Upload Parquet parts
+  const uploaded: string[] = [];
+  const prefix = activation?.getVariable('targetPrefix') || 'exports/';
+  let idx = 0;
+
+  for (const group of groups) {
+    const dateKey = (group as any).__dateKey as string | undefined;
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const folder =
+      partitionBy === 'date' && dateKey
+        ? `${prefix}${entityType}/${dateKey}/`
+        : `${prefix}${entityType}/`;
+    const key = `${folder}${entityType}_${ts}_part-${idx++}.parquet`;
+
+    const buffer = await (s3 as any).writeParquetContent(group as any[], {
+      compression: 'SNAPPY',
+      rowGroupSize: 10000,
+    });
+
+    await s3.uploadFile(key, buffer, {
+      contentType: 'application/octet-stream',
+      metadata: {
+        'entity-type': entityType,
+        'record-count': String(group.length),
+        'exported-at': new Date().toISOString(),
+      },
+    });
+
+    uploaded.push(key);
+  }
+
+  // Save incremental state
+  if (incremental) {
+    await kv.set([stateKey], { lastExportIso: new Date().toISOString() });
+  }
+
+  return { uploaded, total: transformed.length };
+}
+
+// Scheduled export (e.g., daily 2 AM UTC)
+export const scheduledGraphqlExport = schedule('graphql-export-daily', '0 2 * * *').then(
+  http('export-to-parquet', { connection: 'fluent_commerce' }, async ctx => {
+    const result = await runExport(ctx);
+    return { success: true, ...result };
+  })
+);
+
+// Manual trigger for testing
+export const exportNow = webhook('export-now').then(
+  http('export-now-run', { connection: 'fluent_commerce' }, async ctx => {
+    const result = await runExport(ctx);
+    return { success: true, ...result };
+  })
+);
+```
+
+---
+
+## Deployment (Versori)
+
+```bash
+npm run deploy
+npm run logs
+
+# Test manual endpoint:
+# curl -X POST https://{workspace}.versori.run/export-now -H "Content-Type: application/json" -d '{}'
+```
+
+## Testing
+
+- Small run: set `pageSize=50`, `maxRecords=200`, `incremental=false` and trigger `export-now`.
+- Verify S3 keys under `targetPrefix/entityType/YYYY/MM/DD/`.
+- Check metadata on uploaded objects for `record-count` and `exported-at`.
+
+## Common Issues & Solutions
+
+- **Auto-pagination not running**
+  - Ensure GraphQL query uses `$first` and `$after` variables and you pass `first` in variables.
+- **KV state not updating**
+  - Verify `stateKey` and that `:project:` scope is used with `openKv(':project:')`.
+- **Large uploads slow**
+  - Use SNAPPY compression (default shown), reduce partition size, and consider parallel uploads.
+- **Time gaps in incremental**
+  - Add an overlap (export last 5-10 minutes again) and dedupe in downstream consumers.
+
+## Production Checklist
+
+- Activation variables set and secured (no secrets in code)
+- Connection configured for Fluent Commerce
+- S3 permissions validated (PutObject, ListBucket)
+- Partition strategy agreed with consumers (date/entity/size)
+- Incremental strategy defined with overlap
+- Observability (logs/metrics) and alerting on failures
+- Cost/performance tuned (page size, row groups, partition size)
+
+## Related Guides
+
+- Auto-pagination: `fc-connect-sdk/docs/guides/pagination.md`
+- Universal Mapping: `fc-connect-sdk/docs/guides/mapping/readme.md`
+- Versori KV patterns: `docs/use-cases/versori/03-kv-state-management.md`
+- Error handling: `docs/use-cases/patterns/error-handling-retry.md`