@unifiedcommerce/core 0.1.0 → 0.1.1

package/src/modules/analytics/models.ts

@@ -1,125 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,245 +0,0 @@
-/**
- * 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

@@ -1,180 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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),
-  }),
-);