@unifiedcommerce/core 0.1.1 → 0.2.1

package/src/modules/analytics/models.ts

@@ -0,0 +1,125 @@
+import type { AnalyticsModel } from "./types.js";
+
+/**
+ * Built-in analytics model definitions for the 4 core tables.
+ *
+ * Each model maps semantic names (e.g., "Orders.revenue") to PostgreSQL
+ * columns and aggregations. The DrizzleAnalyticsAdapter compiles these
+ * into parameterized SQL queries at runtime.
+ */
+
+export const ORDERS_MODEL: AnalyticsModel = {
+  name: "Orders",
+  table: "orders",
+  scopeRules: [
+    { role: "vendor", filter: "id IN (SELECT order_id FROM marketplace_vendor_sub_orders WHERE vendor_id = :vendorId)" },
+    { role: "customer", filter: "customer_id = :customerId" },
+  ],
+  measures: {
+    count:             { type: "count" },
+    revenue:           { sql: "grand_total", type: "sum" },
+    averageOrderValue: { sql: "grand_total", type: "avg" },
+    subtotalRevenue:   { sql: "subtotal", type: "sum" },
+    taxCollected:      { sql: "tax_total", type: "sum" },
+    shippingRevenue:   { sql: "shipping_total", type: "sum" },
+    discountsGiven:    { sql: "discount_total", type: "sum" },
+    uniqueCustomers:   { sql: "customer_id", type: "countDistinct" },
+  },
+  dimensions: {
+    id:          { sql: "id", type: "string" },
+    orderNumber: { sql: "order_number", type: "string" },
+    status:      { sql: "status", type: "string" },
+    currency:    { sql: "currency", type: "string" },
+    placedAt:    { sql: "placed_at", type: "time" },
+  },
+};
+
+export const ORDER_LINE_ITEMS_MODEL: AnalyticsModel = {
+  name: "OrderLineItems",
+  table: "order_line_items",
+  scopeRules: [
+    { role: "vendor", filter: "order_id IN (SELECT order_id FROM marketplace_vendor_sub_orders WHERE vendor_id = :vendorId)" },
+    { role: "customer", filter: "order_id IN (SELECT id FROM orders WHERE customer_id = :customerId)" },
+  ],
+  joins: [
+    {
+      table: "orders",
+      type: "left",
+      on: "order_line_items.order_id = orders.id",
+    },
+  ],
+  measures: {
+    count:            { type: "count" },
+    itemsSold:        { sql: "order_line_items.quantity", type: "sum" },
+    lineItemRevenue:  { sql: "order_line_items.total_price", type: "sum" },
+    averageUnitPrice: { sql: "order_line_items.unit_price", type: "avg" },
+  },
+  dimensions: {
+    id:                { sql: "order_line_items.id", type: "string" },
+    entityType:        { sql: "order_line_items.entity_type", type: "string" },
+    sku:               { sql: "order_line_items.sku", type: "string" },
+    title:             { sql: "order_line_items.title", type: "string" },
+    fulfillmentStatus: { sql: "order_line_items.fulfillment_status", type: "string" },
+  },
+};
+
+export const INVENTORY_MODEL: AnalyticsModel = {
+  name: "Inventory",
+  table: "inventory_levels",
+  scopeRules: [
+    { role: "vendor", filter: "entity_id IN (SELECT entity_id FROM marketplace_vendor_entities WHERE vendor_id = :vendorId)" },
+  ],
+  measures: {
+    totalOnHand:    { sql: "quantity_on_hand", type: "sum" },
+    totalReserved:  { sql: "quantity_reserved", type: "sum" },
+    totalAvailable: { sql: "(quantity_on_hand - quantity_reserved)", type: "sum" },
+    inventoryValue: { sql: "(quantity_on_hand * COALESCE(unit_cost, 0))", type: "sum" },
+    lowStockCount:  {
+      type: "count",
+      filter: "reorder_threshold IS NOT NULL AND (quantity_on_hand - quantity_reserved) <= reorder_threshold",
+    },
+  },
+  dimensions: {
+    entityId:        { sql: "entity_id", type: "string" },
+    warehouseId:     { sql: "warehouse_id", type: "string" },
+    lastRestockedAt: { sql: "last_restocked_at", type: "time" },
+  },
+  segments: {
+    lowStock: {
+      sql: "reorder_threshold IS NOT NULL AND (quantity_on_hand - quantity_reserved) <= reorder_threshold",
+    },
+  },
+};
+
+export const CUSTOMERS_MODEL: AnalyticsModel = {
+  name: "Customers",
+  table: "customers",
+  scopeRules: [
+    { role: "vendor", filter: "id IN (SELECT DISTINCT customer_id FROM orders WHERE id IN (SELECT order_id FROM marketplace_vendor_sub_orders WHERE vendor_id = :vendorId) AND customer_id IS NOT NULL)" },
+    { role: "customer", filter: "id = :customerId" },
+  ],
+  measures: {
+    customerCount:      { type: "count" },
+    newCustomers:       { type: "count" },
+    returningCustomers: {
+      type: "count",
+      filter: "(SELECT COUNT(*) FROM orders WHERE orders.customer_id = customers.id) > 1",
+    },
+  },
+  dimensions: {
+    createdAt:     { sql: "created_at", type: "time" },
+    customerGroup: { sql: "COALESCE(metadata->>'customerGroup', 'default')", type: "string" },
+  },
+  segments: {
+    returning: {
+      sql: "(SELECT COUNT(*) FROM orders WHERE orders.customer_id = customers.id) > 1",
+    },
+  },
+};
+
+export const BUILTIN_ANALYTICS_MODELS: AnalyticsModel[] = [
+  ORDERS_MODEL,
+  ORDER_LINE_ITEMS_MODEL,
+  INVENTORY_MODEL,
+  CUSTOMERS_MODEL,
+];

package/src/modules/analytics/repository/index.ts

@@ -0,0 +1,6 @@
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+
+export interface AnalyticsRepository {
+  // RFC-002 scaffold: module repositories become the only persistence boundary.
+  ping(ctx: TxContext): Promise<void>;
+}

package/src/modules/analytics/service.ts

@@ -0,0 +1,245 @@
+/**
+ * AnalyticsService — thin delegation layer over AnalyticsAdapter.
+ *
+ * The service manages plugin model registration, custom schema loading,
+ * and delegates all query execution to the configured adapter
+ * (DrizzleAnalyticsAdapter — always on, built into core).
+ */
+
+import type { CommerceConfig } from "../../config/types.js";
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import type {
+  AnalyticsAdapter,
+  AnalyticsMeta,
+  AnalyticsModel,
+  AnalyticsModelDefinition,
+  AnalyticsQueryParams,
+  AnalyticsQueryResult,
+  AnalyticsScope,
+} from "./types.js";
+
+// Re-export types for backwards compatibility
+export type {
+  AnalyticsTimeDimension,
+  AnalyticsFilter,
+  AnalyticsQueryParams,
+  AnalyticsModelDefinition,
+  AnalyticsMeta,
+} from "./types.js";
+
+export interface AnalyticsServiceDeps {
+  adapter: AnalyticsAdapter;
+  config: CommerceConfig;
+}
+
+export class AnalyticsService {
+  private pluginModels: AnalyticsModelDefinition[] = [];
+  private customSchemaModels: AnalyticsModelDefinition[] = [];
+  private customModelsLoaded = false;
+
+  constructor(private deps: AnalyticsServiceDeps) {}
+
+  /**
+   * Register a plugin-contributed analytics model.
+   *
+   * If the model includes a `table` field and structured measures/dimensions,
+   * it is also registered as an AnalyticsModel on the adapter for SQL queries.
+   * Otherwise, it appears in getMeta() but queries return zero-value rows.
+   */
+  registerModel(model: unknown): void {
+    if (!model || typeof model !== "object") return;
+
+    const raw = model as Record<string, unknown>;
+    const name =
+      typeof raw.name === "string"
+        ? raw.name
+        : `PluginModel_${this.pluginModels.length + 1}`;
+    const measures = Array.isArray(raw.measures)
+      ? raw.measures.filter((v): v is string => typeof v === "string")
+      : [];
+    const dimensions = Array.isArray(raw.dimensions)
+      ? raw.dimensions.filter((v): v is string => typeof v === "string")
+      : [];
+    const segments = Array.isArray(raw.segments)
+      ? raw.segments.filter((v): v is string => typeof v === "string")
+      : [];
+
+    this.pluginModels.push({
+      name,
+      source: "plugin",
+      measures,
+      dimensions,
+      segments,
+      raw: model,
+    });
+
+    // If the model provides a table + structured definitions, register on the adapter
+    if (typeof raw.table === "string" && Array.isArray(raw.measures)) {
+      this.tryRegisterModel(name, raw);
+    }
+  }
+
+  /**
+   * Query analytics with scope-based filtering.
+   * Scope is REQUIRED — use buildAnalyticsScope(actor) to construct it.
+   */
+  async query(params: AnalyticsQueryParams, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>> {
+    return this.deps.adapter.query(params, scope);
+  }
+
+  async getDashboard(name: string, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>> {
+    const normalized = name.trim().toLowerCase();
+
+    if (normalized === "revenue" || normalized === "revenue-overview") {
+      return this.query({
+        measures: ["Orders.revenue", "Orders.count"],
+        timeDimensions: [{
+          dimension: "Orders.placedAt",
+          granularity: "month",
+          dateRange: "this month",
+        }],
+        order: { "Orders.placedAt": "asc" },
+      }, scope);
+    }
+
+    if (normalized === "inventory" || normalized === "inventory-health") {
+      return this.query({
+        measures: ["Inventory.totalAvailable", "Inventory.lowStockCount"],
+        dimensions: ["Inventory.warehouseId"],
+        order: { "Inventory.totalAvailable": "desc" },
+      }, scope);
+    }
+
+    return Err(
+      new CommerceValidationError(`Unknown analytics dashboard: ${name}`),
+    );
+  }
+
+  async getMeta(): Promise<Result<AnalyticsMeta>> {
+    await this.ensureCustomSchemaModelsLoaded();
+
+    // Meta returns model definitions, not data — always use admin scope
+    const adapterMeta = await this.deps.adapter.getMeta({ role: "admin" });
+    if (!adapterMeta.ok) return adapterMeta;
+
+    // Merge with plugin and custom schema models
+    const allModels = [
+      ...adapterMeta.value.models,
+      ...this.pluginModels,
+      ...this.customSchemaModels,
+    ];
+
+    return Ok({
+      models: allModels,
+      measures: allModels.flatMap((m) => m.measures),
+      dimensions: allModels.flatMap((m) => m.dimensions),
+      segments: allModels.flatMap((m) => m.segments ?? []),
+    });
+  }
+
+  async meta(): Promise<Result<{ measures: string[]; dimensions: string[]; segments: string[] }>> {
+    const meta = await this.getMeta();
+    if (!meta.ok) return meta;
+    return Ok({
+      measures: meta.value.measures,
+      dimensions: meta.value.dimensions,
+      segments: meta.value.segments,
+    });
+  }
+
+  // ─── Private ─────────────────────────────────────────────────────────────
+
+  private tryRegisterModel(name: string, raw: Record<string, unknown>): void {
+    try {
+      const table = raw.table as string;
+      const measuresArray = raw.measures as Array<Record<string, unknown>>;
+      const dimensionsArray = (raw.dimensions ?? []) as Array<Record<string, unknown>>;
+
+      const modelDef: AnalyticsModel = {
+        name,
+        table,
+        measures: {},
+        dimensions: {},
+      };
+
+      for (const m of measuresArray) {
+        if (typeof m === "string") continue;
+        if (typeof m.name === "string" && typeof m.type === "string") {
+          modelDef.measures[m.name] = {
+            type: m.type as AnalyticsModel["measures"][string]["type"],
+            sql: typeof m.sql === "string" ? m.sql : undefined,
+            filter: typeof m.filter === "string" ? m.filter : undefined,
+          };
+        }
+      }
+
+      for (const d of dimensionsArray) {
+        if (typeof d === "string") continue;
+        if (typeof d.name === "string" && typeof d.sql === "string") {
+          modelDef.dimensions[d.name] = {
+            sql: d.sql,
+            type: (typeof d.type === "string" ? d.type : "string") as AnalyticsModel["dimensions"][string]["type"],
+          };
+        }
+      }
+
+      if (Object.keys(modelDef.measures).length > 0) {
+        this.deps.adapter.registerModel(modelDef);
+      }
+    } catch {
+      // Silently skip malformed plugin models
+    }
+  }
+
+  private async ensureCustomSchemaModelsLoaded(): Promise<void> {
+    if (this.customModelsLoaded) return;
+    this.customModelsLoaded = true;
+
+    const customSchemaPath = this.deps.config.analytics?.customSchemaPath;
+    if (!customSchemaPath) return;
+
+    try {
+      const fs = await import("node:fs/promises");
+      const path = await import("node:path");
+      const entries = await fs.readdir(customSchemaPath);
+
+      for (const entry of entries) {
+        if (!entry.endsWith(".js")) continue;
+        const filePath = path.join(customSchemaPath, entry);
+        const content = await fs.readFile(filePath, "utf8");
+
+        const nameMatch = content.match(/cube\s*\(\s*["'`]([\w-]+)["'`]/);
+        const name = nameMatch?.[1] ?? entry.replace(/\.js$/, "");
+
+        const measures = [
+          ...content.matchAll(/measures\s*:\s*{([\s\S]*?)}\s*,/g),
+        ].flatMap((match) => {
+          const block = match[1] ?? "";
+          return [...block.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*:\s*{/g)].map(
+            (x) => `${name}.${x[1]}`,
+          );
+        });
+
+        const dimensions = [
+          ...content.matchAll(/dimensions\s*:\s*{([\s\S]*?)}\s*,/g),
+        ].flatMap((match) => {
+          const block = match[1] ?? "";
+          return [...block.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*:\s*{/g)].map(
+            (x) => `${name}.${x[1]}`,
+          );
+        });
+
+        this.customSchemaModels.push({
+          name,
+          source: "custom-schema",
+          measures,
+          dimensions,
+          raw: { path: filePath },
+        });
+      }
+    } catch {
+      // Optional extension path: ignore file-system issues
+    }
+  }
+}

package/src/modules/analytics/types.ts

@@ -0,0 +1,180 @@
+import type { Result } from "../../kernel/result.js";
+
+// ─── Query Params (unchanged from existing API) ─────────────────────────────
+
+export interface AnalyticsTimeDimension {
+  dimension: string;
+  granularity?: "day" | "week" | "month" | "year";
+  dateRange?: [string, string] | string;
+}
+
+export interface AnalyticsFilter {
+  member: string;
+  operator:
+    | "equals"
+    | "notEquals"
+    | "contains"
+    | "in"
+    | "notIn"
+    | "gt"
+    | "gte"
+    | "lt"
+    | "lte"
+    | "beforeDate"
+    | "afterDate"
+    | "inDateRange";
+  values?: string[];
+}
+
+export interface AnalyticsQueryParams {
+  measures: string[];
+  dimensions?: string[];
+  timeDimensions?: AnalyticsTimeDimension[];
+  filters?: AnalyticsFilter[];
+  order?: Record<string, "asc" | "desc">;
+  limit?: number;
+}
+
+// ─── Query Result ────────────────────────────────────────────────────────────
+
+export interface AnalyticsQueryResult {
+  query: AnalyticsQueryParams;
+  rows: Record<string, unknown>[];
+  source: string;
+}
+
+// ─── Model / Meta ────────────────────────────────────────────────────────────
+
+export interface AnalyticsModelDefinition {
+  name: string;
+  measures: string[];
+  dimensions: string[];
+  segments?: string[];
+  source: "builtin" | "plugin" | "custom-schema";
+  raw?: unknown;
+}
+
+export interface AnalyticsMeta {
+  models: AnalyticsModelDefinition[];
+  measures: string[];
+  dimensions: string[];
+  segments: string[];
+}
+
+// ─── Analytics Model (declarative SQL mapping) ──────────────────────────────
+
+export type MeasureType = "count" | "sum" | "avg" | "min" | "max" | "countDistinct";
+
+export interface AnalyticsMeasure {
+  type: MeasureType;
+  /** SQL column or expression (e.g., "grand_total" or "quantity_on_hand * COALESCE(unit_cost, 0)") */
+  sql?: string | undefined;
+  /** SQL filter expression that must be true for this measure to count a row */
+  filter?: string | undefined;
+}
+
+export type DimensionType = "string" | "number" | "time" | "boolean";
+
+export interface AnalyticsDimension {
+  /** SQL column or expression */
+  sql: string;
+  type: DimensionType;
+}
+
+export interface AnalyticsJoin {
+  table: string;
+  type: "left" | "inner";
+  on: string;
+}
+
+export interface AnalyticsModel {
+  name: string;
+  table: string;
+  joins?: AnalyticsJoin[];
+  measures: Record<string, AnalyticsMeasure>;
+  dimensions: Record<string, AnalyticsDimension>;
+  segments?: Record<string, { sql: string }>;
+  /**
+   * Scope rules define how this model is filtered by role.
+   * The filter SQL uses :vendorId or :customerId as placeholders.
+   *
+   * Example: { role: "vendor", filter: "vendor_id = :vendorId" }
+   */
+  scopeRules?: AnalyticsScopeRule[];
+}
+
+// ─── Scope (Role-Based Query Filtering) ──────────────────────────────────────
+
+export interface AnalyticsScope {
+  role: "admin" | "staff" | "vendor" | "customer" | "public";
+  vendorId?: string | undefined;
+  customerId?: string | undefined;
+}
+
+/**
+ * Scope rule: defines how an analytics model is filtered for a given role.
+ * Registered alongside model definitions.
+ */
+export interface AnalyticsScopeRule {
+  /** Which role this rule applies to */
+  role: "vendor" | "customer";
+  /** SQL WHERE clause fragment. Use :vendorId or :customerId as placeholders. */
+  filter: string;
+}
+
+// ─── Scope Builder ───────────────────────────────────────────────────────────
+
+/**
+ * Build an AnalyticsScope from an actor (or null for public).
+ *
+ * This is the ONLY way scopes should be created. Every call site that
+ * invokes analytics.query() MUST use this function — never construct
+ * a scope manually. This ensures the scope always reflects the
+ * authenticated actor's actual role and identity.
+ */
+export function buildAnalyticsScope(actor: {
+  role?: string;
+  vendorId?: string | null;
+  userId?: string;
+} | null): AnalyticsScope {
+  if (!actor) return { role: "public" };
+
+  const role = actor.role ?? "public";
+
+  if (role === "admin" || role === "owner" || role === "staff" || role === "ai_agent") {
+    return { role: "admin" };
+  }
+
+  if (actor.vendorId) {
+    return { role: "vendor", vendorId: actor.vendorId };
+  }
+
+  if (role === "customer" && actor.userId) {
+    return { role: "customer", customerId: actor.userId };
+  }
+
+  // Unknown role — deny access
+  return { role: "public" };
+}
+
+// ─── Adapter Interface ───────────────────────────────────────────────────────
+
+export interface AnalyticsAdapter {
+  /** Scope is REQUIRED. Use buildAnalyticsScope(actor) to construct it. */
+  query(params: AnalyticsQueryParams, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>>;
+  getMeta(scope: AnalyticsScope): Promise<Result<AnalyticsMeta>>;
+  registerModel(model: AnalyticsModel): void;
+}
+
+// ─── Deprecated aliases (remove in next major version) ──────────────────────
+
+/** @deprecated Use AnalyticsModel instead */
+export type CubeDefinition = AnalyticsModel;
+/** @deprecated Use AnalyticsScopeRule instead */
+export type CubeScopeRule = AnalyticsScopeRule;
+/** @deprecated Use AnalyticsMeasure instead */
+export type MeasureDefinition = AnalyticsMeasure;
+/** @deprecated Use AnalyticsDimension instead */
+export type DimensionDefinition = AnalyticsDimension;
+/** @deprecated Use AnalyticsJoin instead */
+export type JoinDefinition = AnalyticsJoin;

package/src/modules/audit/hooks.ts

@@ -0,0 +1,78 @@
+import type { AfterHook } from "../../kernel/hooks/types.js";
+import type { HookHandler } from "../../kernel/hooks/registry.js";
+import type { AuditService } from "./service.js";
+
+/**
+ * Creates an after-hook that records an audit entry for the operation.
+ *
+ * The audit entry is written using the same transaction context as the
+ * business operation (via ctx.tx). If the operation rolls back, the
+ * audit entry rolls back too.
+ */
+function createAuditAfterHook(entityType: string, event: string): AfterHook<Record<string, unknown>> {
+  return async ({ result, context }) => {
+    const audit = context.services.audit as AuditService | undefined;
+    if (!audit?.record) return;
+
+    const entityId = (result as { id?: string })?.id ?? "unknown";
+
+    await audit.record({
+      entityType,
+      entityId,
+      event,
+      payload: safePayload(result),
+      ctx: context,
+    });
+  };
+}
+
+/**
+ * Strips the result to a safe subset for audit logging.
+ * Avoids storing sensitive fields or excessively large payloads.
+ */
+function safePayload(result: unknown): Record<string, unknown> {
+  if (result == null || typeof result !== "object") return {};
+  const obj = result as Record<string, unknown>;
+
+  // Shallow copy, exclude fields that could be huge
+  const safe: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    // Skip binary data, nested arrays > 10 items, and known sensitive fields
+    if (key === "password" || key === "secret" || key === "bankAccount") continue;
+    if (Array.isArray(value) && value.length > 10) {
+      safe[key] = `[${value.length} items]`;
+      continue;
+    }
+    safe[key] = value;
+  }
+  return safe;
+}
+
+/**
+ * All audit hooks, keyed by hook registration key.
+ * Registered in kernel boot via hooks.append().
+ */
+export const auditHooks: Record<string, HookHandler> = {
+  // Catalog
+  "catalog.afterCreate": createAuditAfterHook("catalog_entity", "created") as HookHandler,
+  "catalog.afterUpdate": createAuditAfterHook("catalog_entity", "updated") as HookHandler,
+
+  // Orders
+  "orders.afterCreate": createAuditAfterHook("order", "created") as HookHandler,
+  "orders.afterStatusChange": createAuditAfterHook("order", "status_changed") as HookHandler,
+
+  // Inventory
+  "inventory.afterAdjust": createAuditAfterHook("inventory", "adjusted") as HookHandler,
+
+  // Customers
+  "customers.afterCreate": createAuditAfterHook("customer", "created") as HookHandler,
+  "customers.afterUpdate": createAuditAfterHook("customer", "updated") as HookHandler,
+
+  // Pricing
+  "pricing.afterCreate": createAuditAfterHook("price", "created") as HookHandler,
+  "pricing.afterUpdate": createAuditAfterHook("price", "updated") as HookHandler,
+
+  // Promotions
+  "promotions.afterCreate": createAuditAfterHook("promotion", "created") as HookHandler,
+  "promotions.afterUpdate": createAuditAfterHook("promotion", "updated") as HookHandler,
+};

package/src/modules/audit/schema.ts

@@ -0,0 +1,33 @@
+import {
+  pgTable,
+  uuid,
+  text,
+  jsonb,
+  timestamp,
+  index,
+} from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+
+export const auditLog = pgTable(
+  "commerce_audit_log",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    entityType: text("entity_type").notNull(),
+    entityId: text("entity_id").notNull(),
+    event: text("event").notNull(),
+    payload: jsonb("payload").notNull().default("{}"),
+    actorId: text("actor_id"),
+    actorType: text("actor_type"),
+    requestId: text("request_id"),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => ({
+    entityIdx: index("idx_audit_entity").on(table.entityType, table.entityId),
+    orgIdx: index("idx_audit_org").on(table.organizationId),
+  }),
+);