@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-02-quick-start.md

@@ -1,560 +1,560 @@
-# Module 2: Quick Start - Your First Versori Connector
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 2 of 8** | **Level**: Beginner | **Time**: 20 minutes
-
----
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Create a Versori connector project from scratch
-- ✅ Configure Fluent Commerce connection in Versori UI
-- ✅ Deploy your first HTTP workflow
-- ✅ Test the deployed endpoint
-- ✅ View logs and monitor execution
-
----
-
-## Project Setup
-
-### Step 1: Create Project Directory
-
-```bash
-mkdir my-fluent-connector
-cd my-fluent-connector
-npm init -y
-```
-
-### Step 2: Install Dependencies
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk @versori/run
-npm install --save-dev typescript @types/node
-```
-
-### Step 3: TypeScript Configuration
-
-Create `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
-
-### Step 4: Package Configuration
-
-Update `package.json`:
-
-```json
-{
-  "name": "my-fluent-connector",
-  "version": "1.0.0",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "deploy": "versori deploy",
-    "logs": "versori logs",
-    "validate": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "latest",
-    "@versori/run": "^0.4.4"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^20.0.0"
-  },
-  "versori": {
-    "workflows": "dist/index.js"
-  }
-}
-```
-
-**Critical**: The `versori.workflows` field tells Versori where to find your exported workflows.
-
----
-
-## Your First Workflow: Query Fluent Inventory
-
-### Create Workflow File
-
-Create `src/index.ts`:
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * HTTP workflow: Query Fluent Commerce inventory
- *
- * Endpoint: https://{workspace}.versori.run/query-inventory
- * Method: GET
- */
-export const queryInventory = http('query-inventory', {
-  connection: 'fluent_commerce',  // CRITICAL: Matches connection name in Versori UI
-  timeout: 30000,                 // 30 second timeout
-  retry: {
-    attempts: 3,                  // Retry up to 3 times on failure
-    delay: 1000                   // 1 second between retries
-  }
-}, async (ctx) => {
-  // Log workflow start
-  ctx.log('info', 'Starting inventory query');
-
-  try {
-    // Create SDK client (auto-configured from connection)
-    const client = await createClient(ctx);
-
-    // Query inventory positions
-    const result = await client.graphql({
-      query: `
-        query GetInventoryPositions($first: Int!) {
-          inventoryPositions(first: $first) {
-            edges {
-              node {
-                id
-                ref
-                productRef
-                locationRef
-                onHand
-                status
-              }
-              cursor
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      `,
-      variables: { first: 10 }
-    });
-
-    // Check for GraphQL errors
-    if (result.errors?.length) {
-      throw new Error(`GraphQL error: ${result.errors[0].message}`);
-    }
-
-    const positions = result.data.inventoryPositions.edges;
-
-    ctx.log('info', `Retrieved ${positions.length} inventory positions`);
-
-    // Return results
-    return {
-      success: true,
-      count: positions.length,
-      data: positions.map(edge => edge.node),
-      pageInfo: result.data.inventoryPositions.pageInfo
-    };
-
-  } catch (error) {
-    ctx.log('error', 'Inventory query failed', {
-      error: error instanceof Error ? error.message : String(error)
-    });
-
-    // Return error response
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error'
-    };
-  }
-});
-```
-
-### Understanding the Code
-
-**Workflow Type**: `http()` - External API calls
-- Requires `connection` parameter for OAuth2
-- Provides `ctx.fetch` (pre-authenticated)
-- Supports retry and timeout configuration
-
-**createClient(ctx)**: Universal factory
-- Detects Versori context automatically
-- Creates `FluentVersoriClient` with connection credentials
-- Handles OAuth2 token management
-
-**ctx.log()**: Platform logging
-- Levels: `'debug'`, `'info'`, `'warn'`, `'error'`
-- Logs visible in Versori dashboard
-- Structured logging with metadata
-
-**GraphQL Query**:
-- Uses Fluent Commerce schema
-- `inventoryPositions` query with pagination
-- Returns edges/nodes structure
-
----
-
-## Configure Versori Connection
-
-### Step 1: Access Versori Dashboard
-
-1. Log in to [Versori Platform](https://app.versori.com)
-2. Navigate to your workspace
-3. Go to **Connections** section
-
-### Step 2: Create Fluent Commerce Connection
-
-Click **"Add Connection"** and configure:
-
-**Connection Details**:
-```
-Name: fluent_commerce
-Type: Custom OAuth2
-Auth URL: https://api.fluentcommerce.com/oauth/token
-Token URL: https://api.fluentcommerce.com/oauth/token
-Grant Type: client_credentials
-```
-
-**Credentials**:
-```
-Client ID: [Your Fluent OAuth2 Client ID]
-Client Secret: [Your Fluent OAuth2 Client Secret]
-```
-
-**Custom Headers**:
-```json
-{
-  "Content-Type": "application/json"
-}
-```
-
-**Custom Parameters** (optional):
-```json
-{
-  "retailerId": "1"
-}
-```
-
-### Step 3: Test Connection
-
-Click **"Test Connection"** to verify credentials. You should see:
-```
-✓ Connection successful
-✓ Token retrieved
-```
-
----
-
-## Deploy Your Connector
-
-### Build TypeScript
-
-```bash
-npm run build
-```
-
-This compiles `src/index.ts` → `dist/index.js`.
-
-### Deploy to Versori
-
-```bash
-npm run deploy
-```
-
-**Expected output**:
-```
-✓ Building project...
-✓ Uploading to Versori...
-✓ Deployment successful
-
-Workflows deployed:
-  - query-inventory (HTTP)
-    URL: https://{workspace}.versori.run/query-inventory
-```
-
-### Deployment Notes
-
-- **Workspace**: Your unique Versori workspace ID
-- **Endpoint**: Auto-generated based on workflow name
-- **Environment**: Dev/staging/production (configured in Versori UI)
-
----
-
-## Test Your Workflow
-
-### Option 1: Browser
-
-Open your browser and navigate to:
-```
-https://{workspace}.versori.run/query-inventory
-```
-
-**Expected Response**:
-```json
-{
-  "success": true,
-  "count": 10,
-  "data": [
-    {
-      "id": "123",
-      "ref": "INV-PROD123-LOC001",
-      "productRef": "PROD-123",
-      "locationRef": "LOC-001",
-      "onHand": 100,
-      "status": "AVAILABLE"
-    }
-  ],
-  "pageInfo": {
-    "hasNextPage": true,
-    "endCursor": "cursor-value"
-  }
-}
-```
-
-### Option 2: cURL
-
-```bash
-curl https://{workspace}.versori.run/query-inventory
-```
-
-### Option 3: Postman
-
-```
-Method: GET
-URL: https://{workspace}.versori.run/query-inventory
-Headers:
-  Accept: application/json
-```
-
----
-
-## View Logs
-
-### Versori Dashboard
-
-1. Go to **Workflows** section
-2. Click **query-inventory**
-3. View **Executions** tab
-
-**You'll see**:
-- Execution timestamp
-- Duration (ms)
-- Status (success/error)
-- Logs (`ctx.log()` calls)
-
-### CLI Logs
-
-```bash
-npm run logs
-```
-
-**Output**:
-```
-[2025-10-19 12:00:00] INFO: Starting inventory query
-[2025-10-19 12:00:01] INFO: Retrieved 10 inventory positions
-```
-
-### Log Filtering
-
-```bash
-# Filter by workflow
-versori logs --workflow query-inventory
-
-# Filter by level
-versori logs --level error
-
-# Tail logs (live)
-versori logs --follow
-```
-
----
-
-## Add Query Parameters
-
-Let's enhance the workflow to accept query parameters:
-
-Update `src/index.ts`:
-
-```typescript
-export const queryInventory = http('query-inventory', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  // Extract query parameters
-  const limit = parseInt(ctx.query?.limit || '10');
-  const locationRef = ctx.query?.locationRef;
-
-  ctx.log('info', 'Query parameters', { limit, locationRef });
-
-  const client = await createClient(ctx);
-
-  // Build GraphQL query with filters
-  let query = `
-    query GetInventoryPositions($first: Int!) {
-      inventoryPositions(first: $first) {
-        edges {
-          node {
-            id
-            ref
-            productRef
-            locationRef
-            onHand
-          }
-        }
-      }
-    }
-  `;
-
-  // Add location filter if provided
-  if (locationRef) {
-    query = `
-      query GetInventoryPositions($first: Int!, $locationRef: String!) {
-        inventoryPositions(first: $first, locationRef: $locationRef) {
-          edges {
-            node {
-              id
-              ref
-              productRef
-              locationRef
-              onHand
-            }
-          }
-        }
-      }
-    `;
-  }
-
-  const result = await client.graphql({
-    query,
-    variables: locationRef
-      ? { first: limit, locationRef }
-      : { first: limit }
-  });
-
-  return {
-    success: true,
-    count: result.data.inventoryPositions.edges.length,
-    data: result.data.inventoryPositions.edges.map(e => e.node)
-  };
-});
-```
-
-**Rebuild and deploy**:
-```bash
-npm run build && npm run deploy
-```
-
-**Test with parameters**:
-```bash
-# Limit results
-curl "https://{workspace}.versori.run/query-inventory?limit=5"
-
-# Filter by location
-curl "https://{workspace}.versori.run/query-inventory?locationRef=LOC-001"
-
-# Combined
-curl "https://{workspace}.versori.run/query-inventory?limit=20&locationRef=WH-NYC"
-```
-
----
-
-## Common Issues & Fixes
-
-### Issue 1: "No authentication credentials found"
-
-**Cause**: Using `fn()` instead of `http()` for external API calls
-
-**Fix**: Use `http()` with connection parameter
-```typescript
-// ❌ Wrong
-export const bad = fn('bad', async (ctx) => {
-  const client = await createClient(ctx);  // FAILS
-});
-
-// ✅ Correct
-export const good = http('good', { connection: 'fluent_commerce' }, async (ctx) => {
-  const client = await createClient(ctx);  // WORKS
-});
-```
-
-### Issue 2: "Connection 'fluent_commerce' not found"
-
-**Cause**: Connection name mismatch between code and Versori UI
-
-**Fix**: Ensure exact name match (case-sensitive)
-- Code: `connection: 'fluent_commerce'`
-- Versori UI: Name = `fluent_commerce`
-
-### Issue 3: "GraphQL validation failed"
-
-**Cause**: Invalid GraphQL schema or missing fields
-
-**Fix**: Verify query against Fluent schema
-```bash
-# Use SDK introspection tool
-npx @fluentcommerce/fc-connect-sdk introspect-schema \
-  --url https://api.fluentcommerce.com/graphql
-```
-
-### Issue 4: Deployment fails
-
-**Cause**: Missing `versori.workflows` in package.json
-
-**Fix**: Add configuration
-```json
-{
-  "versori": {
-    "workflows": "dist/index.js"
-  }
-}
-```
-
----
-
-## Key Takeaways
-
-- 🎯 **http() workflows** require `connection` parameter for OAuth2
-- 🎯 **createClient(ctx)** automatically configures SDK from connection
-- 🎯 **Connection name** must match between code and Versori UI
-- 🎯 **ctx.log()** provides platform logging visible in dashboard
-- 🎯 **versori.workflows** in package.json tells platform where to find workflows
-- 🎯 **Deploy workflow**: Build → Deploy → Test → Monitor logs
-
----
-
-## Practice Exercise
-
-Create a second workflow that creates an inventory position:
-
-**Requirements**:
-1. Use `http()` with `fluent_commerce` connection
-2. Accept POST request with body: `{ productRef, locationRef, qty }`
-3. Use GraphQL mutation to create inventory position
-4. Return created position ID
-5. Log operation start and completion
-
-**Hints**:
-- Use `ctx.data` to access POST body
-- Use `createInventoryPosition` mutation
-- Handle validation errors
-
-**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
-
----
-
-## Next Steps
-
-Now that you have a working connector, let's dive deeper into authentication and connections.
-
-Continue to [Module 3: Authentication →](./platforms-versori-03-authentication.md) to learn about OAuth2, connection management, and FluentVersoriClient.
-
----
-
-## Related Documentation
-
-- [Module 1: Introduction](./platforms-versori-01-introduction.md) - Platform overview
-- [Module 3: Authentication](./platforms-versori-03-authentication.md) - OAuth2 and connections
-- [Module 4: Workflows](./platforms-versori-04-workflows.md) - All workflow types
-- [Module 7: Deployment](./platforms-versori-07-deployment.md) - Production deployment patterns
-
----
-
-[← Previous: Module 1](./platforms-versori-01-introduction.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 3: Authentication →](./platforms-versori-03-authentication.md)
+# Module 2: Quick Start - Your First Versori Connector
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 2 of 8** | **Level**: Beginner | **Time**: 20 minutes
+
+---
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Create a Versori connector project from scratch
+- ✅ Configure Fluent Commerce connection in Versori UI
+- ✅ Deploy your first HTTP workflow
+- ✅ Test the deployed endpoint
+- ✅ View logs and monitor execution
+
+---
+
+## Project Setup
+
+### Step 1: Create Project Directory
+
+```bash
+mkdir my-fluent-connector
+cd my-fluent-connector
+npm init -y
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk @versori/run
+npm install --save-dev typescript @types/node
+```
+
+### Step 3: TypeScript Configuration
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+
+### Step 4: Package Configuration
+
+Update `package.json`:
+
+```json
+{
+  "name": "my-fluent-connector",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "deploy": "versori deploy",
+    "logs": "versori logs",
+    "validate": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "latest",
+    "@versori/run": "^0.4.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "versori": {
+    "workflows": "dist/index.js"
+  }
+}
+```
+
+**Critical**: The `versori.workflows` field tells Versori where to find your exported workflows.
+
+---
+
+## Your First Workflow: Query Fluent Inventory
+
+### Create Workflow File
+
+Create `src/index.ts`:
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * HTTP workflow: Query Fluent Commerce inventory
+ *
+ * Endpoint: https://{workspace}.versori.run/query-inventory
+ * Method: GET
+ */
+export const queryInventory = http('query-inventory', {
+  connection: 'fluent_commerce',  // CRITICAL: Matches connection name in Versori UI
+  timeout: 30000,                 // 30 second timeout
+  retry: {
+    attempts: 3,                  // Retry up to 3 times on failure
+    delay: 1000                   // 1 second between retries
+  }
+}, async (ctx) => {
+  // Log workflow start
+  ctx.log('info', 'Starting inventory query');
+
+  try {
+    // Create SDK client (auto-configured from connection)
+    const client = await createClient(ctx);
+
+    // Query inventory positions
+    const result = await client.graphql({
+      query: `
+        query GetInventoryPositions($first: Int!) {
+          inventoryPositions(first: $first) {
+            edges {
+              node {
+                id
+                ref
+                productRef
+                locationRef
+                onHand
+                status
+              }
+              cursor
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      `,
+      variables: { first: 10 }
+    });
+
+    // Check for GraphQL errors
+    if (result.errors?.length) {
+      throw new Error(`GraphQL error: ${result.errors[0].message}`);
+    }
+
+    const positions = result.data.inventoryPositions.edges;
+
+    ctx.log('info', `Retrieved ${positions.length} inventory positions`);
+
+    // Return results
+    return {
+      success: true,
+      count: positions.length,
+      data: positions.map(edge => edge.node),
+      pageInfo: result.data.inventoryPositions.pageInfo
+    };
+
+  } catch (error) {
+    ctx.log('error', 'Inventory query failed', {
+      error: error instanceof Error ? error.message : String(error)
+    });
+
+    // Return error response
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    };
+  }
+});
+```
+
+### Understanding the Code
+
+**Workflow Type**: `http()` - External API calls
+- Requires `connection` parameter for OAuth2
+- Provides `ctx.fetch` (pre-authenticated)
+- Supports retry and timeout configuration
+
+**createClient(ctx)**: Universal factory
+- Detects Versori context automatically
+- Creates `FluentVersoriClient` with connection credentials
+- Handles OAuth2 token management
+
+**ctx.log()**: Platform logging
+- Levels: `'debug'`, `'info'`, `'warn'`, `'error'`
+- Logs visible in Versori dashboard
+- Structured logging with metadata
+
+**GraphQL Query**:
+- Uses Fluent Commerce schema
+- `inventoryPositions` query with pagination
+- Returns edges/nodes structure
+
+---
+
+## Configure Versori Connection
+
+### Step 1: Access Versori Dashboard
+
+1. Log in to [Versori Platform](https://app.versori.com)
+2. Navigate to your workspace
+3. Go to **Connections** section
+
+### Step 2: Create Fluent Commerce Connection
+
+Click **"Add Connection"** and configure:
+
+**Connection Details**:
+```
+Name: fluent_commerce
+Type: Custom OAuth2
+Auth URL: https://api.fluentcommerce.com/oauth/token
+Token URL: https://api.fluentcommerce.com/oauth/token
+Grant Type: client_credentials
+```
+
+**Credentials**:
+```
+Client ID: [Your Fluent OAuth2 Client ID]
+Client Secret: [Your Fluent OAuth2 Client Secret]
+```
+
+**Custom Headers**:
+```json
+{
+  "Content-Type": "application/json"
+}
+```
+
+**Custom Parameters** (optional):
+```json
+{
+  "retailerId": "1"
+}
+```
+
+### Step 3: Test Connection
+
+Click **"Test Connection"** to verify credentials. You should see:
+```
+✓ Connection successful
+✓ Token retrieved
+```
+
+---
+
+## Deploy Your Connector
+
+### Build TypeScript
+
+```bash
+npm run build
+```
+
+This compiles `src/index.ts` → `dist/index.js`.
+
+### Deploy to Versori
+
+```bash
+npm run deploy
+```
+
+**Expected output**:
+```
+✓ Building project...
+✓ Uploading to Versori...
+✓ Deployment successful
+
+Workflows deployed:
+  - query-inventory (HTTP)
+    URL: https://{workspace}.versori.run/query-inventory
+```
+
+### Deployment Notes
+
+- **Workspace**: Your unique Versori workspace ID
+- **Endpoint**: Auto-generated based on workflow name
+- **Environment**: Dev/staging/production (configured in Versori UI)
+
+---
+
+## Test Your Workflow
+
+### Option 1: Browser
+
+Open your browser and navigate to:
+```
+https://{workspace}.versori.run/query-inventory
+```
+
+**Expected Response**:
+```json
+{
+  "success": true,
+  "count": 10,
+  "data": [
+    {
+      "id": "123",
+      "ref": "INV-PROD123-LOC001",
+      "productRef": "PROD-123",
+      "locationRef": "LOC-001",
+      "onHand": 100,
+      "status": "AVAILABLE"
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": true,
+    "endCursor": "cursor-value"
+  }
+}
+```
+
+### Option 2: cURL
+
+```bash
+curl https://{workspace}.versori.run/query-inventory
+```
+
+### Option 3: Postman
+
+```
+Method: GET
+URL: https://{workspace}.versori.run/query-inventory
+Headers:
+  Accept: application/json
+```
+
+---
+
+## View Logs
+
+### Versori Dashboard
+
+1. Go to **Workflows** section
+2. Click **query-inventory**
+3. View **Executions** tab
+
+**You'll see**:
+- Execution timestamp
+- Duration (ms)
+- Status (success/error)
+- Logs (`ctx.log()` calls)
+
+### CLI Logs
+
+```bash
+npm run logs
+```
+
+**Output**:
+```
+[2025-10-19 12:00:00] INFO: Starting inventory query
+[2025-10-19 12:00:01] INFO: Retrieved 10 inventory positions
+```
+
+### Log Filtering
+
+```bash
+# Filter by workflow
+versori logs --workflow query-inventory
+
+# Filter by level
+versori logs --level error
+
+# Tail logs (live)
+versori logs --follow
+```
+
+---
+
+## Add Query Parameters
+
+Let's enhance the workflow to accept query parameters:
+
+Update `src/index.ts`:
+
+```typescript
+export const queryInventory = http('query-inventory', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  // Extract query parameters
+  const limit = parseInt(ctx.query?.limit || '10');
+  const locationRef = ctx.query?.locationRef;
+
+  ctx.log('info', 'Query parameters', { limit, locationRef });
+
+  const client = await createClient(ctx);
+
+  // Build GraphQL query with filters
+  let query = `
+    query GetInventoryPositions($first: Int!) {
+      inventoryPositions(first: $first) {
+        edges {
+          node {
+            id
+            ref
+            productRef
+            locationRef
+            onHand
+          }
+        }
+      }
+    }
+  `;
+
+  // Add location filter if provided
+  if (locationRef) {
+    query = `
+      query GetInventoryPositions($first: Int!, $locationRef: String!) {
+        inventoryPositions(first: $first, locationRef: $locationRef) {
+          edges {
+            node {
+              id
+              ref
+              productRef
+              locationRef
+              onHand
+            }
+          }
+        }
+      }
+    `;
+  }
+
+  const result = await client.graphql({
+    query,
+    variables: locationRef
+      ? { first: limit, locationRef }
+      : { first: limit }
+  });
+
+  return {
+    success: true,
+    count: result.data.inventoryPositions.edges.length,
+    data: result.data.inventoryPositions.edges.map(e => e.node)
+  };
+});
+```
+
+**Rebuild and deploy**:
+```bash
+npm run build && npm run deploy
+```
+
+**Test with parameters**:
+```bash
+# Limit results
+curl "https://{workspace}.versori.run/query-inventory?limit=5"
+
+# Filter by location
+curl "https://{workspace}.versori.run/query-inventory?locationRef=LOC-001"
+
+# Combined
+curl "https://{workspace}.versori.run/query-inventory?limit=20&locationRef=WH-NYC"
+```
+
+---
+
+## Common Issues & Fixes
+
+### Issue 1: "No authentication credentials found"
+
+**Cause**: Using `fn()` instead of `http()` for external API calls
+
+**Fix**: Use `http()` with connection parameter
+```typescript
+// ❌ Wrong
+export const bad = fn('bad', async (ctx) => {
+  const client = await createClient(ctx);  // FAILS
+});
+
+// ✅ Correct
+export const good = http('good', { connection: 'fluent_commerce' }, async (ctx) => {
+  const client = await createClient(ctx);  // WORKS
+});
+```
+
+### Issue 2: "Connection 'fluent_commerce' not found"
+
+**Cause**: Connection name mismatch between code and Versori UI
+
+**Fix**: Ensure exact name match (case-sensitive)
+- Code: `connection: 'fluent_commerce'`
+- Versori UI: Name = `fluent_commerce`
+
+### Issue 3: "GraphQL validation failed"
+
+**Cause**: Invalid GraphQL schema or missing fields
+
+**Fix**: Verify query against Fluent schema
+```bash
+# Use SDK introspection tool
+npx @fluentcommerce/fc-connect-sdk introspect-schema \
+  --url https://api.fluentcommerce.com/graphql
+```
+
+### Issue 4: Deployment fails
+
+**Cause**: Missing `versori.workflows` in package.json
+
+**Fix**: Add configuration
+```json
+{
+  "versori": {
+    "workflows": "dist/index.js"
+  }
+}
+```
+
+---
+
+## Key Takeaways
+
+- 🎯 **http() workflows** require `connection` parameter for OAuth2
+- 🎯 **createClient(ctx)** automatically configures SDK from connection
+- 🎯 **Connection name** must match between code and Versori UI
+- 🎯 **ctx.log()** provides platform logging visible in dashboard
+- 🎯 **versori.workflows** in package.json tells platform where to find workflows
+- 🎯 **Deploy workflow**: Build → Deploy → Test → Monitor logs
+
+---
+
+## Practice Exercise
+
+Create a second workflow that creates an inventory position:
+
+**Requirements**:
+1. Use `http()` with `fluent_commerce` connection
+2. Accept POST request with body: `{ productRef, locationRef, qty }`
+3. Use GraphQL mutation to create inventory position
+4. Return created position ID
+5. Log operation start and completion
+
+**Hints**:
+- Use `ctx.data` to access POST body
+- Use `createInventoryPosition` mutation
+- Handle validation errors
+
+**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
+
+---
+
+## Next Steps
+
+Now that you have a working connector, let's dive deeper into authentication and connections.
+
+Continue to [Module 3: Authentication →](./platforms-versori-03-authentication.md) to learn about OAuth2, connection management, and FluentVersoriClient.
+
+---
+
+## Related Documentation
+
+- [Module 1: Introduction](./platforms-versori-01-introduction.md) - Platform overview
+- [Module 3: Authentication](./platforms-versori-03-authentication.md) - OAuth2 and connections
+- [Module 4: Workflows](./platforms-versori-04-workflows.md) - All workflow types
+- [Module 7: Deployment](./platforms-versori-07-deployment.md) - Production deployment patterns
+
+---
+
+[← Previous: Module 1](./platforms-versori-01-introduction.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 3: Authentication →](./platforms-versori-03-authentication.md)