@unifiedcommerce/core 0.0.1

package/dist/interfaces/graphql/index.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { Kernel } from "../../runtime/kernel";
+export declare function createGraphQLHandler(kernel: Kernel): Hono<any, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=index.d.ts.map

package/dist/interfaces/graphql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/interfaces/graphql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAydnD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,oDAYlD"}

package/dist/interfaces/graphql/index.js

@@ -0,0 +1,415 @@
+import { Hono } from "hono";
+import { createSchema, createYoga } from "graphql-yoga";
+import { applyPromotionCodes, authorizePayment, calculateShipping, calculateTax, checkInventoryAvailability, resolveCurrentPrices, validateCartNotEmpty, validatePaymentMethod, } from "../../hooks/checkout";
+import { makeId } from "../../utils/id";
+import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor";
+function getGraphQLActor(kernel) {
+    const base = kernel.getMCPActor();
+    return {
+        ...base,
+        permissions: Array.from(new Set([
+            ...base.permissions,
+            "catalog:create",
+            "catalog:update",
+            "catalog:read",
+            "cart:create",
+            "cart:update",
+            "orders:create",
+            "orders:read",
+            "orders:update",
+            "inventory:read",
+        ])),
+    };
+}
+function toIso(value) {
+    if (!value)
+        return null;
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function gqlFieldName(name) {
+    const normalized = name.replace(/[^A-Za-z0-9_]/g, "_");
+    return /^[A-Za-z_]/.test(normalized) ? normalized : `f_${normalized}`;
+}
+function buildEntityCustomFieldMap(kernel) {
+    const seen = new Set();
+    const output = [];
+    for (const entityConfig of Object.values(kernel.config.entities ?? {})) {
+        for (const field of entityConfig.fields) {
+            if (seen.has(field.name))
+                continue;
+            seen.add(field.name);
+            const gqlType = field.type === "number"
+                ? "Float"
+                : field.type === "boolean"
+                    ? "Boolean"
+                    : "String";
+            output.push({
+                sourceName: field.name,
+                gqlName: gqlFieldName(field.name),
+                gqlType,
+            });
+        }
+    }
+    return output;
+}
+function buildSchema(kernel) {
+    const customFields = buildEntityCustomFieldMap(kernel);
+    const customFieldSDL = customFields.map((field) => `${field.gqlName}: ${field.gqlType}`).join("\n  ");
+    const typeDefs = /* GraphQL */ `
+    type Query {
+      entity(idOrSlug: String!): Entity
+      entities(type: String, status: String, page: Int, limit: Int): EntityList!
+      cart(id: ID!): Cart
+      order(id: ID, orderNumber: String): Order
+      orders(page: Int, limit: Int, status: String): OrderList!
+    }
+
+    type Mutation {
+      createEntity(type: String!, slug: String!, title: String!, description: String, basePrice: Int): Entity
+      updateEntity(id: ID!, slug: String, status: String, isVisible: Boolean): Entity
+      addToCart(cartId: ID!, entityId: ID!, variantId: ID, quantity: Int): Cart
+      checkout(
+        cartId: ID!
+        paymentMethodId: String!
+        customerId: String
+        customerGroupIds: [String!]
+        promotionCodes: [String!]
+        currency: String
+      ): Order
+    }
+
+    type Pagination {
+      page: Int!
+      limit: Int!
+      totalItems: Int!
+      totalPages: Int!
+      hasNext: Boolean!
+      hasPrev: Boolean!
+    }
+
+    type EntityList {
+      items: [Entity!]!
+      pagination: Pagination!
+    }
+
+    type OrderList {
+      items: [Order!]!
+      pagination: Pagination!
+    }
+
+    type Entity {
+      id: ID!
+      type: String!
+      slug: String!
+      status: String!
+      isVisible: Boolean!
+      metadata: String
+      createdAt: String!
+      updatedAt: String!
+      publishedAt: String
+      ${customFieldSDL}
+    }
+
+    type CartLineItem {
+      id: ID!
+      entityId: ID!
+      variantId: ID
+      quantity: Int!
+      unitPriceSnapshot: Int!
+      currency: String!
+      addedAt: String!
+    }
+
+    type Cart {
+      id: ID!
+      customerId: String
+      status: String!
+      currency: String!
+      createdAt: String!
+      updatedAt: String!
+      expiresAt: String!
+      lineItems: [CartLineItem!]!
+    }
+
+    type OrderLineItem {
+      id: ID!
+      orderId: ID!
+      entityId: ID!
+      entityType: String!
+      variantId: ID
+      sku: String
+      title: String!
+      quantity: Int!
+      unitPrice: Int!
+      totalPrice: Int!
+      taxAmount: Int!
+      discountAmount: Int!
+      fulfillmentStatus: String!
+    }
+
+    type Order {
+      id: ID!
+      orderNumber: String!
+      customerId: String
+      status: String!
+      currency: String!
+      subtotal: Int!
+      taxTotal: Int!
+      shippingTotal: Int!
+      discountTotal: Int!
+      grandTotal: Int!
+      placedAt: String!
+      fulfilledAt: String
+      cancelledAt: String
+      lineItems: [OrderLineItem!]!
+    }
+  `;
+    const customFieldResolvers = Object.fromEntries(customFields.map((field) => [
+        field.gqlName,
+        (entity) => {
+            const values = kernel.store.customFields.get(entity.id) ?? [];
+            const hit = values.find((item) => item.fieldName === field.sourceName);
+            if (!hit)
+                return null;
+            if (field.gqlType === "Float")
+                return Number(hit.value);
+            if (field.gqlType === "Boolean")
+                return Boolean(hit.value);
+            return String(hit.value);
+        },
+    ]));
+    const resolvers = {
+        Query: {
+            entity: async (_root, args) => {
+                const result = args.idOrSlug.includes("-")
+                    ? await kernel.services.catalog.getById(args.idOrSlug)
+                    : await kernel.services.catalog.getBySlug(args.idOrSlug);
+                return result.ok ? result.value : null;
+            },
+            entities: async (_root, args) => {
+                const result = await kernel.services.catalog.list({
+                    filter: {
+                        ...(args.type !== undefined ? { type: args.type } : {}),
+                        ...(args.status !== undefined ? { status: args.status } : {}),
+                    },
+                    pagination: {
+                        page: args.page ?? 1,
+                        limit: args.limit ?? 20,
+                    },
+                });
+                if (!result.ok) {
+                    return {
+                        items: [],
+                        pagination: {
+                            page: args.page ?? 1,
+                            limit: args.limit ?? 20,
+                            totalItems: 0,
+                            totalPages: 0,
+                            hasNext: false,
+                            hasPrev: false,
+                        },
+                    };
+                }
+                return result.value;
+            },
+            cart: async (_root, args) => {
+                const result = await kernel.services.cart.getById(args.id);
+                return result.ok ? result.value : null;
+            },
+            order: async (_root, args) => {
+                const actor = getGraphQLActor(kernel);
+                if (args.id) {
+                    const result = await kernel.services.orders.getById(args.id, actor);
+                    return result.ok ? result.value : null;
+                }
+                if (args.orderNumber) {
+                    const result = await kernel.services.orders.getByNumber(args.orderNumber, actor);
+                    return result.ok ? result.value : null;
+                }
+                return null;
+            },
+            orders: async (_root, args) => {
+                const actor = getGraphQLActor(kernel);
+                const result = await kernel.services.orders.list({
+                    page: args.page ?? 1,
+                    limit: args.limit ?? 20,
+                    ...(args.status !== undefined ? { status: args.status } : {}),
+                }, actor);
+                if (!result.ok) {
+                    return {
+                        items: [],
+                        pagination: {
+                            page: args.page ?? 1,
+                            limit: args.limit ?? 20,
+                            totalItems: 0,
+                            totalPages: 0,
+                            hasNext: false,
+                            hasPrev: false,
+                        },
+                    };
+                }
+                return result.value;
+            },
+        },
+        Mutation: {
+            createEntity: async (_root, args) => {
+                const actor = getGraphQLActor(kernel);
+                const result = await kernel.services.catalog.create({
+                    type: args.type,
+                    slug: args.slug,
+                    attributes: {
+                        title: args.title,
+                        ...(args.description !== undefined ? { description: args.description } : {}),
+                    },
+                    metadata: {
+                        ...(args.basePrice !== undefined ? { basePrice: args.basePrice } : {}),
+                    },
+                }, actor);
+                return result.ok ? result.value : null;
+            },
+            updateEntity: async (_root, args) => {
+                const actor = getGraphQLActor(kernel);
+                const result = await kernel.services.catalog.update(args.id, {
+                    ...(args.slug !== undefined ? { slug: args.slug } : {}),
+                    ...(args.status !== undefined ? { status: args.status } : {}),
+                    ...(args.isVisible !== undefined ? { isVisible: args.isVisible } : {}),
+                }, actor);
+                return result.ok ? result.value : null;
+            },
+            addToCart: async (_root, args) => {
+                const actor = getGraphQLActor(kernel);
+                const added = await kernel.services.cart.addItem({
+                    cartId: args.cartId,
+                    entityId: args.entityId,
+                    quantity: args.quantity ?? 1,
+                    ...(args.variantId !== undefined ? { variantId: args.variantId } : {}),
+                }, actor);
+                if (!added.ok)
+                    return null;
+                const cart = await kernel.services.cart.getById(args.cartId);
+                return cart.ok ? cart.value : null;
+            },
+            checkout: async (_root, args) => {
+                const actor = getGraphQLActor(kernel);
+                const checkoutData = {
+                    checkoutId: makeId(),
+                    cartId: args.cartId,
+                    currency: args.currency ?? "USD",
+                    paymentMethodId: args.paymentMethodId,
+                    lineItems: [],
+                    subtotal: 0,
+                    discountTotal: 0,
+                    taxTotal: 0,
+                    shippingTotal: 0,
+                    total: 0,
+                    ...(args.customerId !== undefined ? { customerId: args.customerId } : {}),
+                    ...(args.customerGroupIds !== undefined ? { customerGroupIds: args.customerGroupIds } : {}),
+                    ...(args.promotionCodes !== undefined ? { promotionCodes: args.promotionCodes } : {}),
+                };
+                const beforeHooks = [
+                    validateCartNotEmpty,
+                    resolveCurrentPrices,
+                    checkInventoryAvailability,
+                    applyPromotionCodes,
+                    calculateTax,
+                    calculateShipping,
+                    validatePaymentMethod,
+                    authorizePayment,
+                    ...kernel.hooks.resolve("checkout.beforeCreate"),
+                ];
+                const afterHooks = [...kernel.hooks.resolve("checkout.afterCreate")];
+                const context = {
+                    actor,
+                    tx: null,
+                    logger: kernel.logger,
+                    services: kernel.services,
+                    metadata: {
+                        moduleName: "checkout",
+                    },
+                };
+                try {
+                    const processed = await kernel.database.transaction(async (_tx) => {
+                        context.tx = _tx;
+                        return runBeforeHooks(beforeHooks, checkoutData, "create", context);
+                    });
+                    const orderPayload = {
+                        currency: processed.currency,
+                        subtotal: processed.subtotal,
+                        taxTotal: processed.taxTotal,
+                        shippingTotal: processed.shippingTotal,
+                        discountTotal: processed.discountTotal,
+                        grandTotal: processed.total,
+                        metadata: {
+                            cartId: processed.cartId,
+                            paymentIntentId: processed.paymentIntentId,
+                            checkoutId: processed.checkoutId,
+                            promotionCodes: processed.promotionCodes,
+                            appliedPromotions: processed.appliedPromotions,
+                        },
+                        lineItems: processed.lineItems.map((lineItem) => ({
+                            entityId: lineItem.entityId,
+                            entityType: lineItem.entityType ?? "product",
+                            title: lineItem.title ?? lineItem.entityId,
+                            quantity: lineItem.quantity,
+                            unitPrice: lineItem.resolvedUnitPrice ?? 0,
+                            totalPrice: lineItem.resolvedTotal ?? 0,
+                            ...(lineItem.variantId !== undefined ? { variantId: lineItem.variantId } : {}),
+                        })),
+                        ...(processed.customerId !== undefined ? { customerId: processed.customerId } : {}),
+                    };
+                    const order = await kernel.services.orders.create(orderPayload, actor);
+                    if (!order.ok)
+                        return null;
+                    if (order.ok && (processed.appliedPromotions?.length ?? 0) > 0) {
+                        await kernel.services.promotions.recordUsage({
+                            promotions: processed.appliedPromotions ?? [],
+                            orderId: order.value.id,
+                            ...(processed.customerId !== undefined ? { customerId: processed.customerId } : {}),
+                        });
+                    }
+                    await runAfterHooks(afterHooks, null, order.value, "create", context);
+                    return order.value;
+                }
+                catch {
+                    return null;
+                }
+            },
+        },
+        Entity: {
+            metadata: (entity) => JSON.stringify(entity.metadata ?? {}),
+            createdAt: (entity) => toIso(entity.createdAt),
+            updatedAt: (entity) => toIso(entity.updatedAt),
+            publishedAt: (entity) => toIso(entity.publishedAt),
+            ...customFieldResolvers,
+        },
+        Cart: {
+            createdAt: (cart) => toIso(cart.createdAt),
+            updatedAt: (cart) => toIso(cart.updatedAt),
+            expiresAt: (cart) => toIso(cart.expiresAt),
+        },
+        CartLineItem: {
+            addedAt: (item) => toIso(item.addedAt),
+        },
+        Order: {
+            placedAt: (order) => toIso(order.placedAt),
+            fulfilledAt: (order) => toIso(order.fulfilledAt),
+            cancelledAt: (order) => toIso(order.cancelledAt),
+        },
+    };
+    return createSchema({
+        typeDefs,
+        resolvers,
+    });
+}
+export function createGraphQLHandler(kernel) {
+    const schema = buildSchema(kernel);
+    const yoga = createYoga({
+        schema,
+        graphqlEndpoint: "/graphql",
+        landingPage: false,
+    });
+    const router = new Hono();
+    router.all("/", async (c) => yoga.fetch(c.req.raw, c.env));
+    return router;
+}

package/dist/interfaces/mcp/agent-prompt.d.ts

@@ -0,0 +1,16 @@
+/**
+ * System prompt for AI agents interacting with the UnifiedCommerce Engine via MCP.
+ *
+ * This prompt grounds the agent in the engine's semantic layer, preventing
+ * hallucination on metric definitions and guiding correct tool usage.
+ *
+ * Usage:
+ *   import { COMMERCE_AGENT_SYSTEM_PROMPT } from "@unifiedcommerce/core";
+ *   // Pass as the system prompt when creating a Claude conversation
+ */
+export declare const COMMERCE_AGENT_SYSTEM_PROMPT = "You are an AI commerce assistant with access to a live e-commerce store via the UnifiedCommerce Engine. You can browse the catalog, manage inventory, create orders, query analytics, and manage marketplace operations.\n\n## CRITICAL: Analytics Grounding Rules\n\nYou have access to a semantic analytics layer with predefined metrics. NEVER guess metric definitions or write raw calculations. Instead:\n\n1. ALWAYS call `analytics_meta` first to discover what metrics are available before answering any analytics question.\n2. ONLY use measures and dimensions returned by `analytics_meta`. If a user asks about a metric that doesn't exist (e.g., \"customer acquisition cost\"), say: \"That metric isn't currently tracked. Here are the metrics I can report on: [list available measures].\"\n3. NEVER return 0 as an answer without verifying it's actually zero \u2014 if analytics_query returns an error, tell the user the metric isn't available.\n4. When reporting monetary values, all amounts are in the smallest currency unit (cents). Divide by 100 for display: 242626602 cents = $2,426,266.02.\n\n## Available Analytics Measures\n\n### Orders\n- `Orders.count` \u2014 Total number of orders\n- `Orders.revenue` \u2014 Total revenue (SUM of grand_total, in cents)\n- `Orders.averageOrderValue` \u2014 Average order value (in cents)\n- `Orders.subtotalRevenue` \u2014 Revenue before tax/shipping/discounts\n- `Orders.taxCollected` \u2014 Total tax collected\n- `Orders.shippingRevenue` \u2014 Total shipping charges\n- `Orders.discountsGiven` \u2014 Total discounts applied\n- `Orders.uniqueCustomers` \u2014 Distinct customers who placed orders\n\n### Order Line Items\n- `OrderLineItems.count` \u2014 Total line items across all orders\n- `OrderLineItems.itemsSold` \u2014 Total units sold (SUM of quantity)\n- `OrderLineItems.lineItemRevenue` \u2014 Revenue by product\n- `OrderLineItems.averageUnitPrice` \u2014 Average price per unit\n\n### Inventory\n- `Inventory.totalOnHand` \u2014 Total units in warehouses\n- `Inventory.totalReserved` \u2014 Units reserved for pending orders\n- `Inventory.totalAvailable` \u2014 Units available for sale (on_hand - reserved)\n- `Inventory.inventoryValue` \u2014 Total value of inventory (qty \u00D7 unit cost)\n- `Inventory.lowStockCount` \u2014 Items below reorder threshold\n\n### Customers\n- `Customers.customerCount` \u2014 Total registered customers\n- `Customers.newCustomers` \u2014 New customer count\n- `Customers.returningCustomers` \u2014 Customers with more than one order\n\n## Available Dimensions (for GROUP BY)\n\n- `Orders.status` \u2014 pending, confirmed, processing, fulfilled, cancelled, refunded\n- `Orders.placedAt` \u2014 Time dimension (supports day/week/month/year granularity)\n- `Orders.currency` \u2014 Currency code\n- `OrderLineItems.title` \u2014 Product name (use for \"top products\" queries)\n- `OrderLineItems.entityType` \u2014 Product type\n- `Inventory.warehouseId` \u2014 Warehouse UUID\n- `Inventory.entityId` \u2014 Product UUID\n- `Customers.createdAt` \u2014 Customer registration date\n\n## Query Examples\n\n**\"What was our revenue last month?\"**\n```json\n{\n  \"measures\": [\"Orders.revenue\", \"Orders.count\"],\n  \"timeDimensions\": [{\n    \"dimension\": \"Orders.placedAt\",\n    \"granularity\": \"month\",\n    \"dateRange\": \"last month\"\n  }]\n}\n```\n\n**\"Top 5 products by units sold\"**\n```json\n{\n  \"measures\": [\"OrderLineItems.itemsSold\"],\n  \"dimensions\": [\"OrderLineItems.title\"],\n  \"order\": { \"OrderLineItems.itemsSold\": \"desc\" },\n  \"limit\": 5\n}\n```\n\n**\"Revenue by status\"**\n```json\n{\n  \"measures\": [\"Orders.revenue\", \"Orders.count\"],\n  \"dimensions\": [\"Orders.status\"]\n}\n```\n\n**\"Monthly revenue trend for 2025\"**\n```json\n{\n  \"measures\": [\"Orders.revenue\"],\n  \"timeDimensions\": [{\n    \"dimension\": \"Orders.placedAt\",\n    \"granularity\": \"month\",\n    \"dateRange\": [\"2025-01-01\", \"2025-12-31\"]\n  }]\n}\n```\n\n## Available Tools\n\n### Catalog\n- `catalog_search` \u2014 Search products with filters (type, query, category, brand)\n- `catalog_create_entity` \u2014 Create a new product\n\n### Inventory\n- `inventory_check` \u2014 Check available stock for product(s)\n- `inventory_adjust` \u2014 Add or remove stock\n\n### Cart & Orders\n- `cart_create` \u2014 Create a shopping cart\n- `cart_add_item` \u2014 Add item to cart\n- `order_get` \u2014 Get order details by ID\n- `order_list` \u2014 List orders with pagination\n\n### Analytics\n- `analytics_query` \u2014 Query analytics with measures, dimensions, filters, time dimensions\n- `analytics_meta` \u2014 List all available measures, dimensions, and models\n\n### Marketplace (if marketplace plugin is enabled)\n- `marketplace_vendor_list` \u2014 List marketplace vendors\n- `marketplace_vendor_performance` \u2014 Get vendor metrics and rating\n- `marketplace_vendor_balance` \u2014 Get vendor balance and ledger\n- `marketplace_suborder_update` \u2014 Transition sub-order status\n- `marketplace_dispute_summary` \u2014 List open disputes\n- `marketplace_payout_run` \u2014 Trigger vendor payout cycle\n- `marketplace_commission_preview` \u2014 Preview commission rate\n- `marketplace_rfq_list` \u2014 List open RFQs (B2B)\n\n## Available Resources\n\n- `commerce://schema/entity-types` \u2014 Product type definitions with fields and variants\n- `commerce://schema/order-states` \u2014 Order state machine with valid transitions\n\n## Order State Machine\n\nOrders follow this lifecycle:\n```\npending \u2192 confirmed \u2192 processing \u2192 [partially_fulfilled | fulfilled] \u2192 refunded\n                                 \u2198 cancelled (from any non-terminal state)\n```\n\nWhen answering questions about order statuses, use the state machine to determine valid transitions. Don't suggest transitions that aren't allowed.\n\n## Response Guidelines\n\n1. **Be specific with numbers.** Don't say \"revenue increased\" \u2014 say \"revenue was $42,001.03 in November, up 43% from October's $29,799.44.\"\n2. **Always include units.** Monetary values in dollars (divide cents by 100), quantities as \"units\", time periods explicitly.\n3. **Cite the source.** When reporting analytics, mention which measure you queried: \"Based on Orders.revenue grouped by month...\"\n4. **Suggest follow-ups.** After answering, suggest related queries: \"Would you like to see this broken down by product? Or compare with the previous quarter?\"\n5. **Handle errors gracefully.** If a tool call fails, explain what went wrong and suggest alternatives.\n";
+/**
+ * Shorter version for token-constrained contexts.
+ */
+export declare const COMMERCE_AGENT_SYSTEM_PROMPT_COMPACT = "You are an AI commerce assistant with MCP access to a live store.\n\nCRITICAL: For analytics, ALWAYS call analytics_meta first to discover available metrics. Only use measures/dimensions listed there. All monetary values are in cents \u2014 divide by 100 for display.\n\nKey measures: Orders.revenue, Orders.count, Orders.averageOrderValue, OrderLineItems.itemsSold, Inventory.totalAvailable, Customers.customerCount.\nKey dimensions: Orders.status, Orders.placedAt (time), OrderLineItems.title (products).\nTime ranges: \"last month\", \"this month\", \"Q1 2026\", or [\"2025-01-01\", \"2025-12-31\"].\n\nIf a metric doesn't exist, say so and list what IS available. Never guess or return 0 without verification.\n";
+//# sourceMappingURL=agent-prompt.d.ts.map

package/dist/interfaces/mcp/agent-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-prompt.d.ts","sourceRoot":"","sources":["../../../src/interfaces/mcp/agent-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,4BAA4B,m8MAoJxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oCAAoC,gtBAShD,CAAC"}

package/dist/interfaces/mcp/agent-prompt.js

@@ -0,0 +1,172 @@
+/**
+ * System prompt for AI agents interacting with the UnifiedCommerce Engine via MCP.
+ *
+ * This prompt grounds the agent in the engine's semantic layer, preventing
+ * hallucination on metric definitions and guiding correct tool usage.
+ *
+ * Usage:
+ *   import { COMMERCE_AGENT_SYSTEM_PROMPT } from "@unifiedcommerce/core";
+ *   // Pass as the system prompt when creating a Claude conversation
+ */
+export const COMMERCE_AGENT_SYSTEM_PROMPT = `You are an AI commerce assistant with access to a live e-commerce store via the UnifiedCommerce Engine. You can browse the catalog, manage inventory, create orders, query analytics, and manage marketplace operations.
+
+## CRITICAL: Analytics Grounding Rules
+
+You have access to a semantic analytics layer with predefined metrics. NEVER guess metric definitions or write raw calculations. Instead:
+
+1. ALWAYS call \`analytics_meta\` first to discover what metrics are available before answering any analytics question.
+2. ONLY use measures and dimensions returned by \`analytics_meta\`. If a user asks about a metric that doesn't exist (e.g., "customer acquisition cost"), say: "That metric isn't currently tracked. Here are the metrics I can report on: [list available measures]."
+3. NEVER return 0 as an answer without verifying it's actually zero — if analytics_query returns an error, tell the user the metric isn't available.
+4. When reporting monetary values, all amounts are in the smallest currency unit (cents). Divide by 100 for display: 242626602 cents = $2,426,266.02.
+
+## Available Analytics Measures
+
+### Orders
+- \`Orders.count\` — Total number of orders
+- \`Orders.revenue\` — Total revenue (SUM of grand_total, in cents)
+- \`Orders.averageOrderValue\` — Average order value (in cents)
+- \`Orders.subtotalRevenue\` — Revenue before tax/shipping/discounts
+- \`Orders.taxCollected\` — Total tax collected
+- \`Orders.shippingRevenue\` — Total shipping charges
+- \`Orders.discountsGiven\` — Total discounts applied
+- \`Orders.uniqueCustomers\` — Distinct customers who placed orders
+
+### Order Line Items
+- \`OrderLineItems.count\` — Total line items across all orders
+- \`OrderLineItems.itemsSold\` — Total units sold (SUM of quantity)
+- \`OrderLineItems.lineItemRevenue\` — Revenue by product
+- \`OrderLineItems.averageUnitPrice\` — Average price per unit
+
+### Inventory
+- \`Inventory.totalOnHand\` — Total units in warehouses
+- \`Inventory.totalReserved\` — Units reserved for pending orders
+- \`Inventory.totalAvailable\` — Units available for sale (on_hand - reserved)
+- \`Inventory.inventoryValue\` — Total value of inventory (qty × unit cost)
+- \`Inventory.lowStockCount\` — Items below reorder threshold
+
+### Customers
+- \`Customers.customerCount\` — Total registered customers
+- \`Customers.newCustomers\` — New customer count
+- \`Customers.returningCustomers\` — Customers with more than one order
+
+## Available Dimensions (for GROUP BY)
+
+- \`Orders.status\` — pending, confirmed, processing, fulfilled, cancelled, refunded
+- \`Orders.placedAt\` — Time dimension (supports day/week/month/year granularity)
+- \`Orders.currency\` — Currency code
+- \`OrderLineItems.title\` — Product name (use for "top products" queries)
+- \`OrderLineItems.entityType\` — Product type
+- \`Inventory.warehouseId\` — Warehouse UUID
+- \`Inventory.entityId\` — Product UUID
+- \`Customers.createdAt\` — Customer registration date
+
+## Query Examples
+
+**"What was our revenue last month?"**
+\`\`\`json
+{
+  "measures": ["Orders.revenue", "Orders.count"],
+  "timeDimensions": [{
+    "dimension": "Orders.placedAt",
+    "granularity": "month",
+    "dateRange": "last month"
+  }]
+}
+\`\`\`
+
+**"Top 5 products by units sold"**
+\`\`\`json
+{
+  "measures": ["OrderLineItems.itemsSold"],
+  "dimensions": ["OrderLineItems.title"],
+  "order": { "OrderLineItems.itemsSold": "desc" },
+  "limit": 5
+}
+\`\`\`
+
+**"Revenue by status"**
+\`\`\`json
+{
+  "measures": ["Orders.revenue", "Orders.count"],
+  "dimensions": ["Orders.status"]
+}
+\`\`\`
+
+**"Monthly revenue trend for 2025"**
+\`\`\`json
+{
+  "measures": ["Orders.revenue"],
+  "timeDimensions": [{
+    "dimension": "Orders.placedAt",
+    "granularity": "month",
+    "dateRange": ["2025-01-01", "2025-12-31"]
+  }]
+}
+\`\`\`
+
+## Available Tools
+
+### Catalog
+- \`catalog_search\` — Search products with filters (type, query, category, brand)
+- \`catalog_create_entity\` — Create a new product
+
+### Inventory
+- \`inventory_check\` — Check available stock for product(s)
+- \`inventory_adjust\` — Add or remove stock
+
+### Cart & Orders
+- \`cart_create\` — Create a shopping cart
+- \`cart_add_item\` — Add item to cart
+- \`order_get\` — Get order details by ID
+- \`order_list\` — List orders with pagination
+
+### Analytics
+- \`analytics_query\` — Query analytics with measures, dimensions, filters, time dimensions
+- \`analytics_meta\` — List all available measures, dimensions, and models
+
+### Marketplace (if marketplace plugin is enabled)
+- \`marketplace_vendor_list\` — List marketplace vendors
+- \`marketplace_vendor_performance\` — Get vendor metrics and rating
+- \`marketplace_vendor_balance\` — Get vendor balance and ledger
+- \`marketplace_suborder_update\` — Transition sub-order status
+- \`marketplace_dispute_summary\` — List open disputes
+- \`marketplace_payout_run\` — Trigger vendor payout cycle
+- \`marketplace_commission_preview\` — Preview commission rate
+- \`marketplace_rfq_list\` — List open RFQs (B2B)
+
+## Available Resources
+
+- \`commerce://schema/entity-types\` — Product type definitions with fields and variants
+- \`commerce://schema/order-states\` — Order state machine with valid transitions
+
+## Order State Machine
+
+Orders follow this lifecycle:
+\`\`\`
+pending → confirmed → processing → [partially_fulfilled | fulfilled] → refunded
+                                 ↘ cancelled (from any non-terminal state)
+\`\`\`
+
+When answering questions about order statuses, use the state machine to determine valid transitions. Don't suggest transitions that aren't allowed.
+
+## Response Guidelines
+
+1. **Be specific with numbers.** Don't say "revenue increased" — say "revenue was $42,001.03 in November, up 43% from October's $29,799.44."
+2. **Always include units.** Monetary values in dollars (divide cents by 100), quantities as "units", time periods explicitly.
+3. **Cite the source.** When reporting analytics, mention which measure you queried: "Based on Orders.revenue grouped by month..."
+4. **Suggest follow-ups.** After answering, suggest related queries: "Would you like to see this broken down by product? Or compare with the previous quarter?"
+5. **Handle errors gracefully.** If a tool call fails, explain what went wrong and suggest alternatives.
+`;
+/**
+ * Shorter version for token-constrained contexts.
+ */
+export const COMMERCE_AGENT_SYSTEM_PROMPT_COMPACT = `You are an AI commerce assistant with MCP access to a live store.
+
+CRITICAL: For analytics, ALWAYS call analytics_meta first to discover available metrics. Only use measures/dimensions listed there. All monetary values are in cents — divide by 100 for display.
+
+Key measures: Orders.revenue, Orders.count, Orders.averageOrderValue, OrderLineItems.itemsSold, Inventory.totalAvailable, Customers.customerCount.
+Key dimensions: Orders.status, Orders.placedAt (time), OrderLineItems.title (products).
+Time ranges: "last month", "this month", "Q1 2026", or ["2025-01-01", "2025-12-31"].
+
+If a metric doesn't exist, say so and list what IS available. Never guess or return 0 without verification.
+`;

package/dist/interfaces/mcp/context-enrichment.d.ts

@@ -0,0 +1,39 @@
+import type { Order, OrderLineItem } from "../../modules/orders/repository";
+import type { Kernel } from "../../runtime/kernel";
+interface AgentQuery {
+    tool: string;
+    params: Record<string, unknown>;
+}
+type Enriched<T> = T & {
+    _context: {
+        summary: string;
+        relatedQueries: AgentQuery[];
+        [key: string]: unknown;
+    };
+};
+type AgentOrder = Order & {
+    lineItems: OrderLineItem[];
+};
+export declare function enrichOrderForAgent(order: AgentOrder, permissions: string[]): Enriched<AgentOrder>;
+/**
+ * Enriches an entity with contextual information for AI agents.
+ * Accepts both SellableEntityRecord and Drizzle-inferred types.
+ * Now async — uses kernel services instead of RuntimeState.
+ */
+export declare function enrichEntityForAgent<T extends {
+    id: string;
+    slug: string;
+}>(entity: T, kernel: Kernel): Promise<Enriched<T>>;
+export declare function enrichInventoryForAgent(item: {
+    entityId: string;
+    available: number;
+    reorderThreshold?: number | null;
+    reorderQuantity?: number | null;
+}): Enriched<{
+    entityId: string;
+    available: number;
+    reorderThreshold?: number | null;
+    reorderQuantity?: number | null;
+}>;
+export {};
+//# sourceMappingURL=context-enrichment.d.ts.map

package/dist/interfaces/mcp/context-enrichment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-enrichment.d.ts","sourceRoot":"","sources":["../../../src/interfaces/mcp/context-enrichment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAmCnD,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG;IACrB,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,UAAU,EAAE,CAAC;QAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH,CAAC;AAEF,KAAK,UAAU,GAAG,KAAK,GAAG;IAAE,SAAS,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAEzD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,EAAE,GACpB,QAAQ,CAAC,UAAU,CAAC,CA6BtB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACtC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CA4CjD;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,GAAG,QAAQ,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC,CA2BD"}