feat: add Commerce Gateway adapter package and Apache license alignment

Introduce @loop-engine/adapter-commerce-gateway with typed client, AI actor factories, and evidence formatters, and align adapter-openclaw package licensing to Apache-2.0.

Author: betterdataco

packages/adapter-commerce-gateway/README.md

@@ -0,0 +1,61 @@
+# @loop-engine/adapter-commerce-gateway
+
+`@loop-engine/adapter-commerce-gateway` provides a typed Commerce Gateway client and actor factories that turn live commerce data into governed Loop Engine evidence.
+
+## Install
+
+```bash
+npm install @loop-engine/adapter-commerce-gateway
+```
+
+Install only the LLM SDK you use:
+
+```bash
+npm install @anthropic-ai/sdk
+# or
+npm install openai
+```
+
+## Environment
+
+- `COMMERCE_GATEWAY_URL`
+- `COMMERCE_GATEWAY_API_KEY`
+
+## Read/write boundary
+
+- AI actors call **read** endpoints only (`getInventory`, `getDemandForecast`, `getSuppliers`, pricing reads).
+- Write operations (`createPurchaseOrder`) run in automation flows after human approval has passed loop guards.
+
+## Quick start
+
+```ts
+import { CommerceGatewayClient, buildProcurementActor } from "@loop-engine/adapter-commerce-gateway";
+
+const client = new CommerceGatewayClient({
+  baseUrl: process.env.COMMERCE_GATEWAY_URL!,
+  apiKey: process.env.COMMERCE_GATEWAY_API_KEY!
+});
+
+const actor = buildProcurementActor({
+  gatewayClient: client,
+  llmProvider: "claude",
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  confidenceThreshold: 0.8
+});
+```
+
+## API surface
+
+- `CommerceGatewayClient`
+  - `getInventory(sku)`
+  - `getInventoryBatch(skus)`
+  - `getDemandForecast(sku, horizon?)`
+  - `getSuppliers(sku)`
+  - `getCurrentPrice(sku)`
+  - `getPriceHistory(sku, days)`
+  - `createPurchaseOrder(order)`
+  - `recordLoopOutcome(outcome)` (optional endpoint support by deployment)
+- `buildProcurementActor(options)`
+- `buildPricingActor(options)` (throws: coming in v0.2)
+- `buildProcurementEvidence(cgData, llmRecommendation, requestIds)`
+- `toLoopOutcomeEvent(input)`

packages/adapter-commerce-gateway/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@loop-engine/adapter-commerce-gateway",
+  "version": "0.1.0",
+  "description": "LLM Commerce Gateway adapter for Loop Engine — AI procurement and pricing actors",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@loop-engine/core": "workspace:*",
+    "@loop-engine/sdk": "workspace:*"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.39.0",
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "openai": "^4.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ]
+}

packages/adapter-commerce-gateway/src/actors/ai-pricing-actor.ts

@@ -0,0 +1,12 @@
+import type { Evidence } from "@loop-engine/core";
+
+export interface BuildPricingActorOptions {
+  llmProvider: "claude" | "openai";
+  apiKey: string;
+}
+
+export function buildPricingActor(_options: BuildPricingActorOptions) {
+  return async (): Promise<Evidence> => {
+    throw new Error("buildPricingActor is coming in v0.2");
+  };
+}

packages/adapter-commerce-gateway/src/actors/ai-procurement-actor.ts

@@ -0,0 +1,110 @@
+import Anthropic from "@anthropic-ai/sdk";
+import OpenAI from "openai";
+import type { Evidence } from "@loop-engine/core";
+import { CommerceGatewayClient } from "../client/commerce-gateway-client";
+import type { DemandForecast, InventoryRecord, Supplier } from "../client/types";
+import { buildProcurementEvidence, type LlmRecommendation } from "../formatters/evidence";
+
+export interface ActorContext {
+  instance: {
+    data?: Record<string, unknown>;
+  };
+}
+
+export interface BuildProcurementActorOptions {
+  gatewayClient: CommerceGatewayClient;
+  llmProvider: "claude" | "openai";
+  apiKey: string;
+  confidenceThreshold?: number;
+}
+
+export function buildProcurementActor(options: BuildProcurementActorOptions) {
+  return async (context: ActorContext): Promise<Evidence> => {
+    const sku = String(context.instance.data?.sku ?? "");
+    if (!sku) throw new Error("ActorContext.instance.data.sku is required");
+
+    // Read-only Gateway access in AI actor: inventory, forecast, suppliers.
+    const [inventory, forecast, suppliers] = await Promise.all([
+      options.gatewayClient.getInventory(sku),
+      options.gatewayClient.getDemandForecast(sku),
+      options.gatewayClient.getSuppliers(sku)
+    ]);
+
+    const recommendation = await generateRecommendation(
+      options.llmProvider,
+      options.apiKey,
+      { inventory, forecast, suppliers },
+      options.confidenceThreshold ?? 0.8
+    );
+    const requestIds = [inventory.requestId, forecast.requestId, ...suppliers.map((supplier) => supplier.requestId)].filter(
+      (value): value is string => Boolean(value)
+    );
+    return buildProcurementEvidence({ inventory, forecast, suppliers }, recommendation, requestIds);
+  };
+}
+
+async function generateRecommendation(
+  provider: "claude" | "openai",
+  apiKey: string,
+  payload: {
+    inventory: InventoryRecord;
+    forecast: DemandForecast;
+    suppliers: Supplier[];
+  },
+  confidenceThreshold: number
+): Promise<LlmRecommendation> {
+  if (provider === "claude") {
+    const client = new Anthropic({ apiKey });
+    const response = await client.messages.create({
+      model: "claude-sonnet-4-20250514",
+      max_tokens: 500,
+      system:
+        "You are a procurement analyst. Produce strict JSON with keys recommendedQty, supplierId, confidence, rationale.",
+      messages: [{ role: "user", content: JSON.stringify(payload) }]
+    });
+    const textBlock = response.content.find((block) => block.type === "text");
+    if (!textBlock || textBlock.type !== "text") throw new Error("Claude response missing text block");
+    return parseRecommendation(textBlock.text, "claude-sonnet-4-20250514", confidenceThreshold);
+  }
+
+  const client = new OpenAI({ apiKey });
+  const response = await client.chat.completions.create({
+    model: "gpt-4o",
+    response_format: { type: "json_object" },
+    messages: [
+      {
+        role: "system",
+        content: "You are a procurement analyst. Return strict JSON with recommendedQty, supplierId, confidence, rationale."
+      },
+      { role: "user", content: JSON.stringify(payload) }
+    ]
+  });
+  const text = response.choices[0]?.message.content;
+  if (!text) throw new Error("OpenAI response missing content");
+  return parseRecommendation(text, "gpt-4o", confidenceThreshold);
+}
+
+function parseRecommendation(text: string, model: string, confidenceThreshold: number): LlmRecommendation {
+  const parsed = JSON.parse(text) as {
+    recommendedQty: number;
+    supplierId: string;
+    confidence: number;
+    rationale: string;
+  };
+  if (
+    typeof parsed.recommendedQty !== "number" ||
+    typeof parsed.supplierId !== "string" ||
+    typeof parsed.confidence !== "number" ||
+    typeof parsed.rationale !== "string"
+  ) {
+    throw new Error("Recommendation schema invalid");
+  }
+  return {
+    recommendedQty: parsed.recommendedQty,
+    supplierId: parsed.supplierId,
+    // Guard handles pass/fail; actor only reports model confidence.
+    confidence: Math.max(0, Math.min(parsed.confidence, 1)),
+    rationale: `${parsed.rationale} (threshold: ${confidenceThreshold.toFixed(2)})`,
+    model
+  };
+}

packages/adapter-commerce-gateway/src/client/commerce-gateway-client.ts

@@ -0,0 +1,87 @@
+import type {
+  CommerceGatewayClientOptions,
+  CreatePORequest,
+  DemandForecast,
+  InventoryRecord,
+  LoopOutcomeEvent,
+  PORecord,
+  PriceRecord,
+  Supplier
+} from "./types";
+
+export class CommerceGatewayClient {
+  constructor(private readonly options: CommerceGatewayClientOptions) {}
+
+  async getInventory(sku: string): Promise<InventoryRecord> {
+    return this.request<InventoryRecord>(`/inventory/${encodeURIComponent(sku)}`);
+  }
+
+  async getInventoryBatch(skus: string[]): Promise<InventoryRecord[]> {
+    return this.request<InventoryRecord[]>("/inventory/batch", {
+      method: "POST",
+      body: JSON.stringify({ skus })
+    });
+  }
+
+  async getDemandForecast(sku: string, horizon?: number): Promise<DemandForecast> {
+    const params = new URLSearchParams();
+    if (horizon !== undefined) params.set("horizon", String(horizon));
+    const query = params.size > 0 ? `?${params}` : "";
+    return this.request<DemandForecast>(`/demand-forecast/${encodeURIComponent(sku)}${query}`);
+  }
+
+  async getSuppliers(sku: string): Promise<Supplier[]> {
+    return this.request<Supplier[]>(`/suppliers/${encodeURIComponent(sku)}`);
+  }
+
+  async getCurrentPrice(sku: string): Promise<PriceRecord> {
+    return this.request<PriceRecord>(`/pricing/${encodeURIComponent(sku)}`);
+  }
+
+  async getPriceHistory(sku: string, days: number): Promise<PriceRecord[]> {
+    return this.request<PriceRecord[]>(`/pricing/${encodeURIComponent(sku)}/history?days=${days}`);
+  }
+
+  async createPurchaseOrder(order: CreatePORequest): Promise<PORecord> {
+    return this.request<PORecord>("/purchase-orders", {
+      method: "POST",
+      body: JSON.stringify(order)
+    });
+  }
+
+  async recordLoopOutcome(outcome: LoopOutcomeEvent): Promise<void> {
+    // Endpoint availability differs across Commerce Gateway deployments.
+    // If unavailable, caller can ignore this optional integration.
+    try {
+      await this.request<unknown>("/loop-outcomes", {
+        method: "POST",
+        body: JSON.stringify(outcome)
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`recordLoopOutcome is unavailable on this Commerce Gateway instance: ${message}`);
+    }
+  }
+
+  private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const baseUrl = this.options.baseUrl.replace(/\/$/, "");
+    const response = await fetch(`${baseUrl}${path}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.options.apiKey}`,
+        ...(init.headers as Record<string, string> | undefined)
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Commerce Gateway request failed: ${response.status} ${response.statusText}`);
+    }
+    if (response.status === 204) return undefined as T;
+    const payload = (await response.json()) as T;
+    const requestId = response.headers.get("x-request-id");
+    if (requestId && payload && typeof payload === "object") {
+      (payload as Record<string, unknown>).requestId = requestId;
+    }
+    return payload;
+  }
+}

packages/adapter-commerce-gateway/src/client/types.ts

@@ -0,0 +1,61 @@
+export interface InventoryRecord {
+  sku: string;
+  currentStock: number;
+  reorderPoint: number;
+  leadTimeDays?: number;
+  requestId?: string;
+}
+
+export interface DemandForecast {
+  sku: string;
+  forecastedDemand: number;
+  confidence: number;
+  horizonDays?: number;
+  requestId?: string;
+}
+
+export interface Supplier {
+  id: string;
+  sku: string;
+  unitCost: number;
+  leadTimeDays: number;
+  requestId?: string;
+}
+
+export interface PriceRecord {
+  sku: string;
+  currency: string;
+  value: number;
+  effectiveAt: string;
+  requestId?: string;
+}
+
+export interface CreatePORequest {
+  sku: string;
+  qty: number;
+  supplierId: string;
+  expectedUnitCost?: number;
+}
+
+export interface PORecord {
+  id: string;
+  sku: string;
+  qty: number;
+  supplierId: string;
+  status: string;
+  createdAt?: string;
+  requestId?: string;
+}
+
+export interface LoopOutcomeEvent {
+  loopId: string;
+  aggregateId: string;
+  outcomeId: string;
+  occurredAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CommerceGatewayClientOptions {
+  baseUrl: string;
+  apiKey: string;
+}