@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/00-START-HERE/retailerid-configuration.md

@@ -1,404 +1,404 @@
-# retailerId Configuration Guide
-
-**Quick Answer:** `retailerId` is **OPTIONAL** at client creation. Only provide it when using Job API, Batch API, or Event API.
-
----
-
-## When is retailerId Required?
-
-| API/Method | Needs retailerId? | When to Provide It |
-|------------|-------------------|-------------------|
-| `client.graphql()` | ❌ NO | Never required |
-| `client.createJob()` | ✅ YES | In job payload or client config |
-| `client.sendEvent()` | ✅ YES | In event payload or client config |
-| `client.sendBatch()` | ❌ NO | Uses jobId (already has retailerId from job) |
-| `client.getJobStatus()` | ❌ NO | Uses jobId |
-| `client.getBatchStatus()` | ❌ NO | Uses jobId and batchId |
-
-### Why These APIs Need It
-
-- **Job API** (`createJob`): Fluent needs to know which retailer owns the job
-- **Event API** (`sendEvent`): Events are scoped to a specific retailer
-- **Batch API**: Batches inherit retailerId from the parent job (no separate retailerId needed)
-
-### What About GraphQL Mutations?
-
-**Important:** GraphQL mutations **NEVER** use `client.setRetailerId()`. They get retailerId from **mutation input variables** if the mutation schema includes it.
-
-**Three Scenarios:**
-
-1. **Mutations that REQUIRE retailerId** (mandatory in schema):
-   - Examples: Some mutations where `retailerId` or `retailer.id` is required
-   - **Must pass** retailerId in mutation input variables
-
-2. **Mutations where retailerId is OPTIONAL** (optional in schema):
-   - Examples: Some mutations where `retailerId` or `retailer.id` is optional
-   - **Can pass** retailerId if needed, or omit it
-
-3. **Mutations that DON'T HAVE retailerId** (field doesn't exist in schema):
-   - Examples: `createLocation`, `createControl`, `createPrice` (typically)
-   - **Don't pass** retailerId - field doesn't exist in the mutation input
-
-**Correct Pattern:**
-
-```typescript
-// ✅ CORRECT: Pass retailerId in mutation input if schema requires/allows it
-const { query, variables } = await mapper.map(sourceData);
-
-// Check GraphQL schema to determine:
-// 1. Is retailerId mandatory? → Must pass it
-// 2. Is retailerId optional? → Can pass it if needed
-// 3. Does retailerId field exist? → If not, don't pass it
-
-if (mutationRequiresRetailerId && variables.input) {
-  // Mandatory: Must pass
-  variables.input.retailer = { id: parseInt(retailerId) };
-  // OR depending on schema:
-  // variables.input.retailerId = parseInt(retailerId);
-} else if (mutationAllowsRetailerId && retailerId && variables.input) {
-  // Optional: Can pass if you have it
-  variables.input.retailer = { id: parseInt(retailerId) };
-}
-// If field doesn't exist in schema, don't pass it
-
-await client.graphql({ query, variables });
-
-// ❌ WRONG: Never use setRetailerId() for GraphQL mutations
-// client.setRetailerId(retailerId);  // ← This is ONLY for Job/Event API
-```
-
-**How to Check:**
-- Use GraphQL introspection to see if your mutation has `retailerId` or `retailer.id` field
-- Check if it's mandatory (`!`) or optional in the schema
-- If field doesn't exist → don't pass it
-- If mandatory → must pass it
-- If optional → can pass it if needed
-
----
-
-## Three Ways to Provide retailerId
-
-### Option 1: In Client Configuration (Standalone/Node.js)
-
-**Best for:** Node.js scripts, Deno applications
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: '1',  // ← Optional: only needed for Job/Event APIs
-  }
-});
-
-// Now you can call methods without passing retailerId each time
-await client.createJob({ name: 'inventory-sync' });
-await client.sendEvent({ name: 'ProductUpdated', entityType: 'PRODUCT' });
-```
-
-### Option 2: Set After Client Creation
-
-**Best for:** Versori `fn()` workflows, dynamic retailerId
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Create client without retailerId
-const client = await createClient({
-  data: {},  // ← No retailerId needed if only using GraphQL
-  log,
-  openKv,
-  activation
-});
-
-// Only set it if you need Job/Event APIs
-if (needsJobApi) {
-  client.setRetailerId('1');
-}
-
-// Now use it
-await client.createJob({ name: 'inventory-sync' });
-```
-
-### Option 3: Pass Directly to Methods
-
-**Best for:** Multi-tenant scenarios, different retailers per operation
-
-```typescript
-const client = await createClient({
-  data: {},  // No retailerId in client config
-  log,
-  openKv,
-  activation
-});
-
-// Pass retailerId explicitly
-await client.createJob({
-  name: 'inventory-sync',
-  retailerId: '1'  // ← Explicitly provide it
-});
-
-await client.sendEvent({
-  name: 'ProductUpdated',
-  entityType: 'PRODUCT',
-  retailerId: '2'  // ← Different retailer
-});
-```
-
----
-
-## Versori Platform Patterns
-
-### Standard Versori Pattern (Recommended)
-
-Use `schedule().then(http())` with a Fluent Commerce connection:
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Standard pattern from SDK templates
-export const dailyInventorySync = schedule('daily-sync', '0 2 * * *').then(
-  http('run-sync', { connection: 'fluent_commerce' }, async (ctx) => {
-    // createClient auto-detects Versori context
-    const client = await createClient(ctx);
-
-    // Set retailerId if needed for Job/Event APIs
-    client.setRetailerId('1');
-
-    await client.createJob({ name: 'inventory-sync' });
-  })
-);
-```
-
-### Alternative: Pass retailerId Directly
-
-```typescript
-export const dailyInventorySync = schedule('daily-sync', '0 2 * * *').then(
-  http('run-sync', { connection: 'fluent_commerce' }, async (ctx) => {
-    const client = await createClient(ctx);
-
-    // Pass retailerId explicitly per operation
-    await client.createJob({
-      name: 'inventory-sync',
-      retailerId: '1'
-    });
-  })
-);
-```
-
-### For Webhooks (Without Fluent Client)
-
-If you only need KV storage (no Fluent API calls):
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-
-export const jobStatus = webhook('job-status').then(
-  fn('status', async (ctx) => {
-    const { data, log, openKv } = ctx;
-
-    // Use SDK utilities without FluentClient
-    const tracker = new JobTracker(openKv(':project:'), log);
-    return await tracker.getJob(data.jobId);
-  })
-);
-```
-
----
-
-## Error Messages
-
-### Missing retailerId When Required
-
-```
-FluentValidationError: retailerId is required for job creation
-```
-
-**Solution:** Provide retailerId using one of the three options above.
-
-### Before v0.1.31 (Old SDK Versions)
-
-```
-Error: retailerId is required in Versori connection
-```
-
-**Solution:** Upgrade to v0.1.31+ where retailerId is optional at client creation.
-
----
-
-## Migration from Old SDK Versions
-
-**Before (v0.1.30 and earlier):**
-```typescript
-// ❌ Would fail if retailerId missing
-const client = await createClient({ data: {}, log, openKv });
-// Error: "retailerId is required in Versori connection"
-```
-
-**After (v0.1.31+):**
-```typescript
-// ✅ Works fine for GraphQL queries
-const client = await createClient({ data: {}, log, openKv });
-await client.graphql({ query: '...' });
-
-// ❌ Only fails if you try Job/Event API without retailerId
-await client.createJob({ name: 'test' });
-// Error: "retailerId is required for job creation"
-
-// ✅ Provide it when needed
-client.setRetailerId('1');
-await client.createJob({ name: 'test' });
-```
-
----
-
-## Best Practices
-
-### 1. Only Provide retailerId If You Need It
-
-```typescript
-// ✅ Good: Only using GraphQL queries
-const client = await createClient({
-  config: { baseUrl, clientId, clientSecret }
-  // No retailerId needed
-});
-
-await client.graphql({ query: '...' });
-```
-
-### 2. Set It Once for Multiple Operations
-
-```typescript
-// ✅ Good: Using Job API multiple times
-const client = await createClient({ data: {}, log, openKv });
-client.setRetailerId('1');
-
-await client.createJob({ name: 'job1' });
-await client.createJob({ name: 'job2' });
-await client.sendEvent({ name: 'Test', entityType: 'PRODUCT' });
-```
-
-### 3. Pass Explicitly for Multi-Tenant
-
-```typescript
-// ✅ Good: Different retailers per operation
-const client = await createClient({ data: {}, log, openKv });
-
-for (const tenant of tenants) {
-  await client.createJob({
-    name: `sync-${tenant.name}`,
-    retailerId: tenant.fluentRetailerId
-  });
-}
-```
-
----
-
-## How to Find Your Retailer ID
-
-### Method 1: GraphQL Query
-
-```graphql
-query {
-  retailers {
-    edges {
-      node {
-        id    # ← This is your retailerId
-        ref
-        name
-      }
-    }
-  }
-}
-```
-
-### Method 2: Fluent Console URL
-
-Check your Fluent Console URL:
-```
-https://yourinstance.fluentretail.com/console/retailer/123
-                                                        ^^^
-                                                   retailerId
-```
-
-### Method 3: Ask Your Fluent Admin
-
-They can provide the numeric retailer ID for your instance.
-
----
-
-## Summary
-
-- ✅ **retailerId is OPTIONAL** at client construction (as of v0.1.31)
-- ✅ **Only required** for Job API, Event API (NOT GraphQL or Batch)
-- ✅ **Three ways to provide it:** client config, `setRetailerId()`, or method parameter
-- ✅ **Best practice:** Only provide it if you're using Job/Event APIs
-
-**Related Docs:**
-- [Getting Started Guide](./getting-started.md)
-- [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)
-- [Versori Authentication](../02-CORE-GUIDES/api-reference/modules/api-reference-03-authentication.md)
-
----
-
-## Batch Entity Pattern: Context Injection
-
-### Problem: retailerId in Batch Entities
-
-Batch API requires `retailerId` in **each entity** (not just in `createJob`):
-
-```typescript
-await client.sendBatch(jobId, {
-  entities: [
-    {
-      locationRef: 'LOC-001',
-      skuRef: 'SKU-123',
-      qty: 100,
-      retailerId: 123  // ← Required in EACH entity
-    }
-  ]
-});
-```
-
-### Solution: Use Mapping Context (Recommended)
-
-**Mapping Config:**
-```json
-{
-  "fields": {
-    "retailerId": {
-      "source": "$context.retailerId",
-      "required": true,
-      "resolver": "sdk.parseInt"
-    },
-    "skuRef": { "source": "sku" },
-    "qty": { "source": "quantity" }
-  }
-}
-```
-
-**Workflow Code:**
-```typescript
-const fluentRetailerId = activation.getVariable('fluentRetailerId');
-
-for (const record of records) {
-  const result = await mapper.map(
-    { inventory: record },              // Source data (XML/CSV)
-    { context: { retailerId: fluentRetailerId } }  // Runtime injection
-  );
-}
-```
-
-### Why Context Injection > Custom Resolver?
-
-| Pattern | Pros | Cons |
-|---------|------|------|
-| **Context Injection** | ✅ Explicit<br>✅ Visible in mapping<br>✅ Multi-tenant ready | None |
-| **Custom Resolver** | None | ❌ Hidden<br>❌ Less flexible<br>❌ More complex |
-
-**See Template:** `docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-xml-inventory-batch.md` (lines 1365-1367)
+# retailerId Configuration Guide
+
+**Quick Answer:** `retailerId` is **OPTIONAL** at client creation. Only provide it when using Job API, Batch API, or Event API.
+
+---
+
+## When is retailerId Required?
+
+| API/Method | Needs retailerId? | When to Provide It |
+|------------|-------------------|-------------------|
+| `client.graphql()` | ❌ NO | Never required |
+| `client.createJob()` | ✅ YES | In job payload or client config |
+| `client.sendEvent()` | ✅ YES | In event payload or client config |
+| `client.sendBatch()` | ❌ NO | Uses jobId (already has retailerId from job) |
+| `client.getJobStatus()` | ❌ NO | Uses jobId |
+| `client.getBatchStatus()` | ❌ NO | Uses jobId and batchId |
+
+### Why These APIs Need It
+
+- **Job API** (`createJob`): Fluent needs to know which retailer owns the job
+- **Event API** (`sendEvent`): Events are scoped to a specific retailer
+- **Batch API**: Batches inherit retailerId from the parent job (no separate retailerId needed)
+
+### What About GraphQL Mutations?
+
+**Important:** GraphQL mutations **NEVER** use `client.setRetailerId()`. They get retailerId from **mutation input variables** if the mutation schema includes it.
+
+**Three Scenarios:**
+
+1. **Mutations that REQUIRE retailerId** (mandatory in schema):
+   - Examples: Some mutations where `retailerId` or `retailer.id` is required
+   - **Must pass** retailerId in mutation input variables
+
+2. **Mutations where retailerId is OPTIONAL** (optional in schema):
+   - Examples: Some mutations where `retailerId` or `retailer.id` is optional
+   - **Can pass** retailerId if needed, or omit it
+
+3. **Mutations that DON'T HAVE retailerId** (field doesn't exist in schema):
+   - Examples: `createLocation`, `createControl`, `createPrice` (typically)
+   - **Don't pass** retailerId - field doesn't exist in the mutation input
+
+**Correct Pattern:**
+
+```typescript
+// ✅ CORRECT: Pass retailerId in mutation input if schema requires/allows it
+const { query, variables } = await mapper.map(sourceData);
+
+// Check GraphQL schema to determine:
+// 1. Is retailerId mandatory? → Must pass it
+// 2. Is retailerId optional? → Can pass it if needed
+// 3. Does retailerId field exist? → If not, don't pass it
+
+if (mutationRequiresRetailerId && variables.input) {
+  // Mandatory: Must pass
+  variables.input.retailer = { id: parseInt(retailerId) };
+  // OR depending on schema:
+  // variables.input.retailerId = parseInt(retailerId);
+} else if (mutationAllowsRetailerId && retailerId && variables.input) {
+  // Optional: Can pass if you have it
+  variables.input.retailer = { id: parseInt(retailerId) };
+}
+// If field doesn't exist in schema, don't pass it
+
+await client.graphql({ query, variables });
+
+// ❌ WRONG: Never use setRetailerId() for GraphQL mutations
+// client.setRetailerId(retailerId);  // ← This is ONLY for Job/Event API
+```
+
+**How to Check:**
+- Use GraphQL introspection to see if your mutation has `retailerId` or `retailer.id` field
+- Check if it's mandatory (`!`) or optional in the schema
+- If field doesn't exist → don't pass it
+- If mandatory → must pass it
+- If optional → can pass it if needed
+
+---
+
+## Three Ways to Provide retailerId
+
+### Option 1: In Client Configuration (Standalone/Node.js)
+
+**Best for:** Node.js scripts, Deno applications
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: '1',  // ← Optional: only needed for Job/Event APIs
+  }
+});
+
+// Now you can call methods without passing retailerId each time
+await client.createJob({ name: 'inventory-sync' });
+await client.sendEvent({ name: 'ProductUpdated', entityType: 'PRODUCT' });
+```
+
+### Option 2: Set After Client Creation
+
+**Best for:** Versori `fn()` workflows, dynamic retailerId
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Create client without retailerId
+const client = await createClient({
+  data: {},  // ← No retailerId needed if only using GraphQL
+  log,
+  openKv,
+  activation
+});
+
+// Only set it if you need Job/Event APIs
+if (needsJobApi) {
+  client.setRetailerId('1');
+}
+
+// Now use it
+await client.createJob({ name: 'inventory-sync' });
+```
+
+### Option 3: Pass Directly to Methods
+
+**Best for:** Multi-tenant scenarios, different retailers per operation
+
+```typescript
+const client = await createClient({
+  data: {},  // No retailerId in client config
+  log,
+  openKv,
+  activation
+});
+
+// Pass retailerId explicitly
+await client.createJob({
+  name: 'inventory-sync',
+  retailerId: '1'  // ← Explicitly provide it
+});
+
+await client.sendEvent({
+  name: 'ProductUpdated',
+  entityType: 'PRODUCT',
+  retailerId: '2'  // ← Different retailer
+});
+```
+
+---
+
+## Versori Platform Patterns
+
+### Standard Versori Pattern (Recommended)
+
+Use `schedule().then(http())` with a Fluent Commerce connection:
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Standard pattern from SDK templates
+export const dailyInventorySync = schedule('daily-sync', '0 2 * * *').then(
+  http('run-sync', { connection: 'fluent_commerce' }, async (ctx) => {
+    // createClient auto-detects Versori context
+    const client = await createClient(ctx);
+
+    // Set retailerId if needed for Job/Event APIs
+    client.setRetailerId('1');
+
+    await client.createJob({ name: 'inventory-sync' });
+  })
+);
+```
+
+### Alternative: Pass retailerId Directly
+
+```typescript
+export const dailyInventorySync = schedule('daily-sync', '0 2 * * *').then(
+  http('run-sync', { connection: 'fluent_commerce' }, async (ctx) => {
+    const client = await createClient(ctx);
+
+    // Pass retailerId explicitly per operation
+    await client.createJob({
+      name: 'inventory-sync',
+      retailerId: '1'
+    });
+  })
+);
+```
+
+### For Webhooks (Without Fluent Client)
+
+If you only need KV storage (no Fluent API calls):
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+
+export const jobStatus = webhook('job-status').then(
+  fn('status', async (ctx) => {
+    const { data, log, openKv } = ctx;
+
+    // Use SDK utilities without FluentClient
+    const tracker = new JobTracker(openKv(':project:'), log);
+    return await tracker.getJob(data.jobId);
+  })
+);
+```
+
+---
+
+## Error Messages
+
+### Missing retailerId When Required
+
+```
+FluentValidationError: retailerId is required for job creation
+```
+
+**Solution:** Provide retailerId using one of the three options above.
+
+### Before v0.1.31 (Old SDK Versions)
+
+```
+Error: retailerId is required in Versori connection
+```
+
+**Solution:** Upgrade to v0.1.31+ where retailerId is optional at client creation.
+
+---
+
+## Migration from Old SDK Versions
+
+**Before (v0.1.30 and earlier):**
+```typescript
+// ❌ Would fail if retailerId missing
+const client = await createClient({ data: {}, log, openKv });
+// Error: "retailerId is required in Versori connection"
+```
+
+**After (v0.1.31+):**
+```typescript
+// ✅ Works fine for GraphQL queries
+const client = await createClient({ data: {}, log, openKv });
+await client.graphql({ query: '...' });
+
+// ❌ Only fails if you try Job/Event API without retailerId
+await client.createJob({ name: 'test' });
+// Error: "retailerId is required for job creation"
+
+// ✅ Provide it when needed
+client.setRetailerId('1');
+await client.createJob({ name: 'test' });
+```
+
+---
+
+## Best Practices
+
+### 1. Only Provide retailerId If You Need It
+
+```typescript
+// ✅ Good: Only using GraphQL queries
+const client = await createClient({
+  config: { baseUrl, clientId, clientSecret }
+  // No retailerId needed
+});
+
+await client.graphql({ query: '...' });
+```
+
+### 2. Set It Once for Multiple Operations
+
+```typescript
+// ✅ Good: Using Job API multiple times
+const client = await createClient({ data: {}, log, openKv });
+client.setRetailerId('1');
+
+await client.createJob({ name: 'job1' });
+await client.createJob({ name: 'job2' });
+await client.sendEvent({ name: 'Test', entityType: 'PRODUCT' });
+```
+
+### 3. Pass Explicitly for Multi-Tenant
+
+```typescript
+// ✅ Good: Different retailers per operation
+const client = await createClient({ data: {}, log, openKv });
+
+for (const tenant of tenants) {
+  await client.createJob({
+    name: `sync-${tenant.name}`,
+    retailerId: tenant.fluentRetailerId
+  });
+}
+```
+
+---
+
+## How to Find Your Retailer ID
+
+### Method 1: GraphQL Query
+
+```graphql
+query {
+  retailers {
+    edges {
+      node {
+        id    # ← This is your retailerId
+        ref
+        name
+      }
+    }
+  }
+}
+```
+
+### Method 2: Fluent Console URL
+
+Check your Fluent Console URL:
+```
+https://yourinstance.fluentretail.com/console/retailer/123
+                                                        ^^^
+                                                   retailerId
+```
+
+### Method 3: Ask Your Fluent Admin
+
+They can provide the numeric retailer ID for your instance.
+
+---
+
+## Summary
+
+- ✅ **retailerId is OPTIONAL** at client construction (as of v0.1.31)
+- ✅ **Only required** for Job API, Event API (NOT GraphQL or Batch)
+- ✅ **Three ways to provide it:** client config, `setRetailerId()`, or method parameter
+- ✅ **Best practice:** Only provide it if you're using Job/Event APIs
+
+**Related Docs:**
+- [Getting Started Guide](./getting-started.md)
+- [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)
+- [Versori Authentication](../02-CORE-GUIDES/api-reference/modules/api-reference-03-authentication.md)
+
+---
+
+## Batch Entity Pattern: Context Injection
+
+### Problem: retailerId in Batch Entities
+
+Batch API requires `retailerId` in **each entity** (not just in `createJob`):
+
+```typescript
+await client.sendBatch(jobId, {
+  entities: [
+    {
+      locationRef: 'LOC-001',
+      skuRef: 'SKU-123',
+      qty: 100,
+      retailerId: 123  // ← Required in EACH entity
+    }
+  ]
+});
+```
+
+### Solution: Use Mapping Context (Recommended)
+
+**Mapping Config:**
+```json
+{
+  "fields": {
+    "retailerId": {
+      "source": "$context.retailerId",
+      "required": true,
+      "resolver": "sdk.parseInt"
+    },
+    "skuRef": { "source": "sku" },
+    "qty": { "source": "quantity" }
+  }
+}
+```
+
+**Workflow Code:**
+```typescript
+const fluentRetailerId = activation.getVariable('fluentRetailerId');
+
+for (const record of records) {
+  const result = await mapper.map(
+    { inventory: record },              // Source data (XML/CSV)
+    { context: { retailerId: fluentRetailerId } }  // Runtime injection
+  );
+}
+```
+
+### Why Context Injection > Custom Resolver?
+
+| Pattern | Pros | Cons |
+|---------|------|------|
+| **Context Injection** | ✅ Explicit<br>✅ Visible in mapping<br>✅ Multi-tenant ready | None |
+| **Custom Resolver** | None | ❌ Hidden<br>❌ Less flexible<br>❌ More complex |
+
+**See Template:** `docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-xml-inventory-batch.md` (lines 1365-1367)