@unifiedcommerce/core 0.0.1

package/src/hooks/order-emails.ts

@@ -0,0 +1,62 @@
+/**
+ * Order lifecycle email notifications.
+ *
+ * Sends emails on status changes: confirmed, fulfilled, cancelled, refunded.
+ * Registered as an orders.afterStatusChange hook.
+ */
+
+import type { AfterHook } from "../kernel/hooks/types";
+
+interface StatusChangeResult {
+  orderId: string;
+  customerId?: string | null;
+  newStatus: string;
+  previousStatus: string;
+}
+
+export const sendOrderStatusEmail: AfterHook<StatusChangeResult> = async ({
+  result,
+  context,
+}) => {
+  const email = context.services.email as
+    | { send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void> }
+    | undefined;
+
+  if (!email?.send) return;
+
+  // Only send for customer-facing status changes
+  const notifiableStatuses = ["confirmed", "processing", "fulfilled", "cancelled", "refunded"];
+  if (!notifiableStatuses.includes(result.newStatus)) return;
+
+  // Look up customer email
+  const customerId = result.customerId;
+  if (!customerId) return;
+
+  const customers = context.services.customers as
+    | { getByUserId(id: string, actor?: unknown): Promise<{ ok: boolean; value?: { email?: string | null } }> }
+    | undefined;
+
+  if (!customers) return;
+
+  try {
+    const customer = await customers.getByUserId(customerId, context.actor);
+    if (!customer.ok || !customer.value?.email) return;
+
+    await email.send({
+      template: "order-status-change",
+      to: customer.value.email,
+      data: {
+        orderId: result.orderId,
+        newStatus: result.newStatus,
+        previousStatus: result.previousStatus,
+      },
+    });
+  } catch (err) {
+    // Email failure must not break the order flow
+    context.logger.warn("Order status email failed", {
+      orderId: result.orderId,
+      newStatus: result.newStatus,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+};

package/src/index.ts

@@ -0,0 +1,214 @@
+export { defineConfig } from "./config/define-config";
+export type {
+  CommerceConfig,
+  CommercePlugin,
+  MCPResource,
+  MCPTool,
+} from "./config/types";
+export { defineCommercePlugin } from "./kernel/plugin/manifest";
+export type {
+  CommercePluginManifest,
+  PluginContext,
+  PluginHookRegistration,
+  PluginLogger,
+  PluginPermission,
+  PluginRouteRegistration,
+} from "./kernel/plugin/manifest";
+
+export { router } from "./interfaces/rest/router";
+export { webhookRouter, type WebhookRouterResult } from "./interfaces/rest/webhook-router";
+export { isPrivateUrl, isPrivateIp } from "./modules/webhooks/ssrf-guard";
+export { createServer } from "./runtime/server";
+export { createLogger } from "./runtime/logger";
+export type { Logger as PinoLogger } from "./runtime/logger";
+export { setupGracefulShutdown } from "./runtime/shutdown";
+export { createKernel } from "./runtime/kernel";
+export type { Kernel } from "./runtime/kernel";
+export { createTestKernel } from "./test-utils/create-test-kernel";
+export { createTestPluginContext } from "./test-utils/create-test-plugin-context";
+export { createRepositoryTestHarness } from "./test-utils/create-repository-test-harness";
+export { createPluginTestApp, type PluginTestApp, type TestAppEnv } from "./test-utils/create-plugin-test-app";
+export {
+  testAdminActor, testStaffActor, testCustomerActor, testNoPermActor,
+  jsonHeaders,
+} from "./test-utils/test-actors";
+export { beforeHook, afterHook } from "./test-utils/typed-hooks";
+
+export type { Actor } from "./auth/types";
+export { resolveOrgId, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org";
+export { OrganizationService } from "./modules/organization/service";
+export { createScopedDb } from "./kernel/database/scoped-db";
+export { assertOwnership, assertPermission } from "./auth/permissions";
+export type { AccessResult, AccessContext, AccessFn, WhereClause } from "./auth/access";
+export {
+  accessOR,
+  accessAND,
+  conditional,
+  isAdmin,
+  isAuthenticated,
+  isDocumentOwner,
+  publicAccess,
+  denyAll,
+} from "./auth/access";
+
+export { HookRegistry } from "./kernel/hooks/registry";
+export type {
+  BeforeHook,
+  AfterHook,
+  HookContext,
+  HookOperation,
+  HookOrigin,
+  Logger,
+  ServiceContainer,
+} from "./kernel/hooks/types";
+export { runBeforeHooks, runAfterHooks } from "./kernel/hooks/executor";
+export { createHookContext } from "./kernel/hooks/create-context";
+export type { CreateHookContextArgs } from "./kernel/hooks/create-context";
+export type { JobsAdapter, EnqueueOptions } from "./kernel/jobs/adapter";
+export { NullJobsAdapter } from "./kernel/jobs/adapter";
+export { DrizzleJobsAdapter } from "./kernel/jobs/drizzle-adapter";
+export { runPendingJobs } from "./kernel/jobs/runner";
+export type { RunPendingJobsArgs } from "./kernel/jobs/runner";
+export type {
+  TaskDefinition,
+  TaskContext,
+  TaskRetryConfig,
+} from "./kernel/jobs/types";
+
+export { createLocalAPI, LocalAPI } from "./kernel/local-api";
+export type { CommerceLocalAPI, LocalAPIOptions } from "./kernel/local-api";
+export { createCommerce } from "./runtime/commerce";
+export type { CommerceInstance } from "./runtime/commerce";
+
+export { createAuditService, createNullAuditService } from "./modules/audit/service";
+export type {
+  AuditService,
+  AuditEntry,
+  RecordArgs,
+  ListForEntityArgs,
+} from "./modules/audit/service";
+
+export type { Result, PluginResult, PluginResultErr } from "./kernel/result";
+export { Ok, Err, PluginErr } from "./kernel/result";
+export type { PluginDb, PluginTxFn } from "./kernel/database/plugin-types";
+export type { ServiceRegistry } from "./kernel/service-registry";
+export { toHttpError, type HttpErrorResponse } from "./kernel/http-error";
+export { withTiming } from "./kernel/service-timing";
+
+export {
+  CommerceNotFoundError,
+  CommerceValidationError,
+  CommerceForbiddenError,
+  CommerceConflictError,
+  CommerceInvalidTransitionError,
+} from "./kernel/errors";
+
+export { mapErrorToStatus } from "./kernel/error-mapper";
+
+export {
+  canTransition,
+  assertTransition,
+  orderStateMachine,
+  extendOrderStateMachine,
+} from "./kernel/state-machine/machine";
+
+export type {
+  PaymentAdapter,
+  PaymentCapture,
+  PaymentIntent,
+  PaymentRefund,
+  PaymentWebhookEvent,
+} from "./modules/payments/adapter";
+export type { StorageAdapter } from "./modules/media/adapter";
+export type {
+  SearchAdapter,
+  SearchDocument,
+  SearchFilters,
+  SearchHit,
+  SearchQueryParams,
+  SearchQueryResult,
+  SearchSuggestParams,
+} from "./modules/search/adapter";
+export type { DatabaseAdapter } from "./kernel/database/adapter";
+export {
+  createTxContext,
+  reuseOrCreateTxContext,
+  withTransaction,
+} from "./kernel/database/tx-context";
+export type {
+  TxContext,
+  WithTransactionOptions,
+} from "./kernel/database/tx-context";
+export type {
+  TaxAdapter,
+  TaxAddress,
+  TaxCalculationParams,
+  TaxCalculationResult,
+  TaxLineItem,
+  TaxReportParams,
+  TaxVoidParams,
+} from "./modules/tax/adapter";
+
+export { getSchema, buildSchema, getTableNames } from "./kernel/database/migrate";
+export { consoleEmailAdapter } from "./adapters/console-email";
+
+export { runCompensationChain } from "./kernel/compensation/executor";
+export type {
+  CompensationContext,
+  Step,
+} from "./kernel/compensation/types";
+
+export { createRepository } from "./kernel/factory/repository-factory";
+export type {
+  BaseRepository,
+  SoftDeletableRepository,
+  RepositoryFor,
+  Filters,
+  FindOptions,
+} from "./kernel/factory/repository-factory";
+
+export { mergeExtraColumns } from "./kernel/schema/extra-columns";
+export type { ExtraColumnsOption } from "./kernel/schema/extra-columns";
+
+export type { CartItemMatcher } from "./modules/cart/matcher";
+export { defaultCartItemMatcher } from "./modules/cart/matcher";
+export { canAccessCart } from "./modules/cart/access";
+
+export { QueryRegistry } from "./kernel/query/registry";
+export { executeQuery } from "./kernel/query/executor";
+export type {
+  RelationDefinition,
+  EntityDefinition,
+} from "./kernel/query/registry";
+export type { QueryInput, QueryResult } from "./kernel/query/executor";
+
+export type { CommerceModuleTypes } from "./types/commerce-types";
+
+export { staleOrderCleanupTask } from "./modules/orders/stale-order-cleanup";
+export {
+  COMMERCE_AGENT_SYSTEM_PROMPT,
+  COMMERCE_AGENT_SYSTEM_PROMPT_COMPACT,
+} from "./interfaces/mcp/agent-prompt";
+
+export { DrizzleAnalyticsAdapter } from "./modules/analytics/drizzle-adapter";
+export { BUILTIN_ANALYTICS_MODELS } from "./modules/analytics/models";
+export { buildAnalyticsScope } from "./modules/analytics/types";
+export type {
+  AnalyticsAdapter,
+  AnalyticsQueryParams,
+  AnalyticsQueryResult,
+  AnalyticsMeta,
+  AnalyticsModelDefinition,
+  AnalyticsScope,
+  AnalyticsModel,
+  AnalyticsScopeRule,
+  AnalyticsMeasure,
+  AnalyticsDimension,
+  AnalyticsJoin,
+  // Deprecated aliases (remove in next major)
+  CubeScopeRule,
+  CubeDefinition,
+  MeasureDefinition,
+  DimensionDefinition,
+  JoinDefinition,
+} from "./modules/analytics/types";

package/src/interfaces/mcp/agent-prompt.ts

@@ -0,0 +1,174 @@
+/**
+ * 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/src/interfaces/mcp/context-enrichment.ts

@@ -0,0 +1,177 @@
+import { orderStateMachine } from "../../kernel/state-machine/machine";
+import type { Order, OrderLineItem } from "../../modules/orders/repository";
+import type { Kernel } from "../../runtime/kernel";
+
+function getAvailableTransitions(status: string): string[] {
+  const transitions = (
+    orderStateMachine.transitions as Record<string, readonly string[]>
+  )[status];
+  return transitions ? [...transitions] : [];
+}
+
+async function inventorySummary(
+  kernel: Kernel,
+  entityId: string,
+): Promise<{
+  onHand: number;
+  reserved: number;
+  available: number;
+  lowStock: boolean;
+  reorderSuggestionUnits: number;
+}> {
+  const result = await kernel.services.inventory.checkMultiple([entityId]);
+  const available = result.ok ? (result.value[entityId] ?? 0) : 0;
+
+  // For low stock detection, we need a simple heuristic since we don't have
+  // direct access to all level details from service API. Use available <= 0.
+  const lowStock = available <= 0;
+
+  return {
+    onHand: available, // approximation when detailed levels not available
+    reserved: 0,
+    available,
+    lowStock,
+    reorderSuggestionUnits: 0,
+  };
+}
+
+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 function enrichOrderForAgent(
+  order: AgentOrder,
+  permissions: string[],
+): Enriched<AgentOrder> {
+  return {
+    ...order,
+    _context: {
+      availableTransitions: getAvailableTransitions(order.status),
+      permittedActions: permissions.filter((permission) =>
+        ["orders:update", "orders:read", "orders:cancel"].includes(permission),
+      ),
+      summary: `Order ${order.orderNumber}: ${order.lineItems.reduce((sum, lineItem) => sum + lineItem.quantity, 0)} item(s) totaling ${order.grandTotal} ${order.currency}. Status: ${order.status}.`,
+      relatedQueries: [
+        {
+          tool: "inventory_check",
+          params: {
+            entityIds: order.lineItems.map((lineItem) => lineItem.entityId),
+          },
+        },
+        {
+          tool: "analytics_query",
+          params: {
+            measures: ["Orders.revenue"],
+            dimensions: ["Orders.status"],
+            filters: [
+              { member: "Orders.id", operator: "equals", values: [order.id] },
+            ],
+          },
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * 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 async function enrichEntityForAgent<
+  T extends { id: string; slug: string },
+>(entity: T, kernel: Kernel): Promise<Enriched<T>> {
+  const inventory = await inventorySummary(kernel, entity.id);
+
+  // Get entity details with variants to count them
+  const entityResult = await kernel.services.catalog.getById(entity.id, {
+    includeVariants: true,
+  });
+  const variantCount =
+    entityResult.ok && entityResult.value.variants
+      ? entityResult.value.variants.length
+      : 0;
+
+  return {
+    ...entity,
+    _context: {
+      summary: `${entity.slug} has ${variantCount} variant(s), ${inventory.available} available units.`,
+      stockStatus: inventory.lowStock
+        ? "low"
+        : inventory.available > 0
+          ? "in_stock"
+          : "out_of_stock",
+      variantCount,
+      relatedQueries: [
+        {
+          tool: "inventory_check",
+          params: { entityIds: [entity.id] },
+        },
+        {
+          tool: "analytics_query",
+          params: {
+            measures: ["OrderLineItems.itemsSold"],
+            dimensions: ["OrderLineItems.title"],
+            filters: [
+              {
+                member: "OrderLineItems.title",
+                operator: "equals",
+                values: [entity.slug],
+              },
+            ],
+          },
+        },
+      ],
+    },
+  };
+}
+
+export function enrichInventoryForAgent(item: {
+  entityId: string;
+  available: number;
+  reorderThreshold?: number | null;
+  reorderQuantity?: number | null;
+}): Enriched<{
+  entityId: string;
+  available: number;
+  reorderThreshold?: number | null;
+  reorderQuantity?: number | null;
+}> {
+  const lowStock =
+    item.reorderThreshold != null
+      ? item.available <= item.reorderThreshold
+      : item.available <= 0;
+
+  return {
+    ...item,
+    _context: {
+      lowStockWarning: lowStock,
+      reorderSuggestion:
+        lowStock && item.reorderQuantity != null
+          ? {
+              suggestedUnits: item.reorderQuantity,
+            }
+          : null,
+      summary: lowStock
+        ? `Entity ${item.entityId} is low on stock (${item.available} available).`
+        : `Entity ${item.entityId} has healthy stock (${item.available} available).`,
+      relatedQueries: [
+        {
+          tool: "catalog_search",
+          params: { query: item.entityId },
+        },
+      ],
+    },
+  };
+}