@unifiedcommerce/core 0.1.1 → 0.2.1

package/src/kernel/service-timing.ts

@@ -0,0 +1,89 @@
+/**
+ * Service method observability via ES Proxy.
+ *
+ * Wraps a service object so that every async method call is timed.
+ * Slow calls (above threshold) are logged with service name, method name,
+ * and duration. Failed calls always log with the error.
+ *
+ * Usage at kernel boot:
+ *   services.inventory = withTiming(inventoryService, "inventory", logger);
+ *   services.catalog = withTiming(catalogService, "catalog", logger);
+ *
+ * Produces log entries like:
+ *   { service: "inventory", method: "adjust", durationMs: 245 } "slow service call"
+ *   { service: "catalog", method: "create", durationMs: 12, err: ... } "service call failed"
+ *
+ * Only wraps own methods (not inherited). Synchronous property access
+ * (e.g., reading a field) passes through unchanged with zero overhead.
+ */
+
+interface TimingLogger {
+  info(obj: Record<string, unknown>, msg: string): void;
+  error(obj: Record<string, unknown>, msg: string): void;
+}
+
+export function withTiming<T extends object>(
+  service: T,
+  serviceName: string,
+  logger: TimingLogger,
+  slowThresholdMs = 100,
+): T {
+  return new Proxy(service, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+
+      // Only wrap functions, skip symbols and non-function props
+      if (typeof value !== "function" || typeof prop === "symbol") {
+        return value;
+      }
+
+      // Skip internal/private-looking methods
+      const methodName = String(prop);
+      if (methodName.startsWith("_")) return value;
+
+      return function proxiedMethod(this: unknown, ...args: unknown[]) {
+        const start = performance.now();
+
+        // Call the original method
+        let result: unknown;
+        try {
+          result = value.apply(target, args);
+        } catch (err) {
+          // Synchronous throw
+          const durationMs = Math.round(performance.now() - start);
+          logger.error(
+            { service: serviceName, method: methodName, durationMs, err },
+            `${serviceName}.${methodName} failed (${durationMs}ms)`,
+          );
+          throw err;
+        }
+
+        // If result is a promise, attach timing to its resolution
+        if (result && typeof (result as Promise<unknown>).then === "function") {
+          return (result as Promise<unknown>).then(
+            (resolved) => {
+              const durationMs = Math.round(performance.now() - start);
+              if (durationMs > slowThresholdMs) {
+                logger.info(
+                  { service: serviceName, method: methodName, durationMs },
+                  `${serviceName}.${methodName} slow (${durationMs}ms)`,
+                );
+              }
+              return resolved;
+            },
+            (err) => {
+              const durationMs = Math.round(performance.now() - start);
+              logger.error(
+                { service: serviceName, method: methodName, durationMs, err },
+                `${serviceName}.${methodName} failed (${durationMs}ms)`,
+              );
+              throw err;
+            },
+          );
+        }
+
+        return result;
+      };
+    },
+  });
+}

package/src/kernel/state-machine/machine.ts

@@ -0,0 +1,101 @@
+import { CommerceInvalidTransitionError } from "../errors.js";
+
+export interface StateDefinition<TState extends string> {
+  states: readonly TState[];
+  initial: TState;
+  transitions: Record<TState, readonly TState[]>;
+  terminal: readonly TState[];
+}
+
+export type OrderState = string;
+
+const DEFAULT_TRANSITIONS: Record<string, readonly string[]> = {
+  pending: ["confirmed", "cancelled"],
+  confirmed: ["processing", "cancelled"],
+  processing: ["partially_fulfilled", "fulfilled", "cancelled"],
+  partially_fulfilled: ["fulfilled", "cancelled"],
+  fulfilled: ["refunded"],
+  cancelled: [],
+  refunded: [],
+};
+
+const DEFAULT_STATES: readonly string[] = [
+  "pending", "confirmed", "processing", "partially_fulfilled",
+  "fulfilled", "cancelled", "refunded",
+];
+
+const DEFAULT_TERMINAL: readonly string[] = ["cancelled", "refunded"];
+
+export const orderStateMachine: StateDefinition<string> = {
+  states: DEFAULT_STATES,
+  initial: "pending",
+  transitions: DEFAULT_TRANSITIONS,
+  terminal: DEFAULT_TERMINAL,
+};
+
+/**
+ * Extend the order state machine with custom transitions.
+ * New states are added automatically. Existing state transition arrays
+ * are merged (union, not replaced) with the custom ones.
+ *
+ * Usage:
+ *   const extended = extendOrderStateMachine({
+ *     pending: ["payment_initiated"],
+ *     payment_initiated: ["payment_authorized", "payment_failed"],
+ *     payment_authorized: ["processing"],
+ *   });
+ */
+export function extendOrderStateMachine(
+  customTransitions: Record<string, string[]>,
+): StateDefinition<string> {
+  const merged: Record<string, string[]> = {};
+
+  // Copy defaults
+  for (const [state, targets] of Object.entries(DEFAULT_TRANSITIONS)) {
+    merged[state] = [...targets];
+  }
+
+  // Merge custom
+  for (const [state, targets] of Object.entries(customTransitions)) {
+    if (!merged[state]) merged[state] = [];
+    for (const t of targets) {
+      if (!merged[state].includes(t)) merged[state].push(t);
+    }
+    // Ensure target states also exist in the map
+    for (const t of targets) {
+      if (!merged[t]) merged[t] = [];
+    }
+  }
+
+  const allStates = Object.keys(merged);
+  const terminal = allStates.filter((s) => merged[s]!.length === 0);
+
+  return {
+    states: allStates,
+    initial: "pending",
+    transitions: merged,
+    terminal,
+  };
+}
+
+export function canTransition<TState extends string>(
+  machine: StateDefinition<TState>,
+  from: TState,
+  to: TState,
+): boolean {
+  return machine.transitions[from].includes(to);
+}
+
+export function assertTransition<TState extends string>(
+  machine: StateDefinition<TState>,
+  from: TState,
+  to: TState,
+): void {
+  if (!canTransition(machine, from, to)) {
+    throw new CommerceInvalidTransitionError(
+      `Cannot transition from "${from}" to "${to}". Allowed transitions from "${from}": [${machine.transitions[
+        from
+      ].join(", ")}]`,
+    );
+  }
+}

package/src/modules/analytics/drizzle-adapter.ts

@@ -0,0 +1,426 @@
+import { sql, type SQL } from "drizzle-orm";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import type {
+  AnalyticsAdapter,
+  AnalyticsFilter,
+  AnalyticsMeta,
+  AnalyticsModel,
+  AnalyticsModelDefinition,
+  AnalyticsQueryParams,
+  AnalyticsQueryResult,
+  AnalyticsScope,
+  AnalyticsTimeDimension,
+} from "./types.js";
+
+// ─── Date Range Parsing ──────────────────────────────────────────────────────
+
+function parseDateRange(range: AnalyticsTimeDimension["dateRange"]): [Date, Date] | null {
+  if (Array.isArray(range)) {
+    const start = new Date(range[0]!);
+    const end = new Date(range[1]!);
+    if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) return null;
+    return [start, end];
+  }
+  if (typeof range !== "string") return null;
+
+  const now = new Date();
+  const lower = range.toLowerCase();
+
+  if (lower === "last month") {
+    return [
+      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1)),
+      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 0, 23, 59, 59, 999)),
+    ];
+  }
+  if (lower === "this month") {
+    return [
+      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)),
+      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 0, 23, 59, 59, 999)),
+    ];
+  }
+
+  const qMatch = range.match(/^Q([1-4])\s+(\d{4})$/i);
+  if (qMatch) {
+    const quarter = Number(qMatch[1]);
+    const year = Number(qMatch[2]);
+    const monthStart = (quarter - 1) * 3;
+    return [
+      new Date(Date.UTC(year, monthStart, 1)),
+      new Date(Date.UTC(year, monthStart + 3, 0, 23, 59, 59, 999)),
+    ];
+  }
+
+  return null;
+}
+
+function pickCube(params: AnalyticsQueryParams): string {
+  const first = [
+    ...(params.measures ?? []),
+    ...(params.dimensions ?? []),
+    ...(params.timeDimensions ?? []).map((td) => td.dimension),
+    ...(params.filters ?? []).map((f) => f.member),
+  ][0];
+  if (!first) return "Orders";
+  return first.split(".")[0] ?? "Orders";
+}
+
+// ─── Granularity to TO_CHAR format ───────────────────────────────────────────
+
+const GRANULARITY_FORMAT: Record<string, string> = {
+  day: "YYYY-MM-DD",
+  week: "IYYY-\"W\"IW",
+  month: "YYYY-MM",
+  year: "YYYY",
+};
+
+// ─── SQL Compilation Helpers ─────────────────────────────────────────────────
+
+function compileMeasure(cube: AnalyticsModel, measureName: string): SQL {
+  const shortName = measureName.split(".")[1]!;
+  const def = cube.measures[shortName];
+  if (!def) return sql`0`;
+
+  switch (def.type) {
+    case "count":
+      if (def.filter) {
+        return sql.raw(`COUNT(CASE WHEN ${def.filter} THEN 1 END)`);
+      }
+      return sql`COUNT(*)`;
+    case "sum":
+      return sql.raw(`COALESCE(SUM(${def.sql!}), 0)`);
+    case "avg":
+      return sql.raw(`COALESCE(ROUND(AVG(${def.sql!})), 0)`);
+    case "min":
+      return sql.raw(`MIN(${def.sql!})`);
+    case "max":
+      return sql.raw(`MAX(${def.sql!})`);
+    case "countDistinct":
+      return sql.raw(`COUNT(DISTINCT ${def.sql!})`);
+  }
+}
+
+function compileTimeDimensionSelect(cube: AnalyticsModel, td: AnalyticsTimeDimension): SQL {
+  const shortName = td.dimension.split(".")[1]!;
+  const dimDef = cube.dimensions[shortName];
+  if (!dimDef) return sql`NULL`;
+
+  const gran = td.granularity ?? "day";
+  // Validate granularity against whitelist to prevent SQL injection
+  if (!(gran in GRANULARITY_FORMAT)) {
+    return sql`NULL`;
+  }
+  const format = GRANULARITY_FORMAT[gran]!;
+  return sql.raw(`TO_CHAR(DATE_TRUNC('${gran}', ${dimDef.sql}), '${format}')`);
+}
+
+function compileFilter(cube: AnalyticsModel, filter: AnalyticsFilter): SQL | null {
+  const shortName = filter.member.split(".")[1]!;
+  const dimDef = cube.dimensions[shortName];
+  if (!dimDef) return null;
+
+  const col = dimDef.sql;
+  const values = filter.values ?? [];
+  if (values.length === 0) return null;
+
+  switch (filter.operator) {
+    case "equals":
+      return sql`${sql.raw(col)} = ${values[0]!}`;
+    case "notEquals":
+      return sql`${sql.raw(col)} != ${values[0]!}`;
+    case "contains":
+      return sql`${sql.raw(col)} ILIKE ${"%" + values[0]! + "%"}`;
+    case "in":
+      return sql`${sql.raw(col)} IN (${sql.join(values.map((v) => sql`${v}`), sql`, `)})`;
+    case "notIn":
+      return sql`${sql.raw(col)} NOT IN (${sql.join(values.map((v) => sql`${v}`), sql`, `)})`;
+    case "gt":
+      return sql`${sql.raw(col)} > ${Number(values[0]!)}`;
+    case "gte":
+      return sql`${sql.raw(col)} >= ${Number(values[0]!)}`;
+    case "lt":
+      return sql`${sql.raw(col)} < ${Number(values[0]!)}`;
+    case "lte":
+      return sql`${sql.raw(col)} <= ${Number(values[0]!)}`;
+    case "beforeDate":
+      return sql`${sql.raw(col)} <= ${values[0]!}::timestamptz`;
+    case "afterDate":
+      return sql`${sql.raw(col)} >= ${values[0]!}::timestamptz`;
+    case "inDateRange":
+      if (values.length >= 2) {
+        return sql`${sql.raw(col)} BETWEEN ${values[0]!}::timestamptz AND ${values[1]!}::timestamptz`;
+      }
+      return null;
+  }
+}
+
+// ─── DrizzleAnalyticsAdapter ─────────────────────────────────────────────────
+
+export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
+  private models = new Map<string, AnalyticsModel>();
+
+  constructor(private db: DrizzleDatabase) {}
+
+  registerModel(model: AnalyticsModel): void {
+    this.models.set(model.name, model);
+  }
+
+  async query(params: AnalyticsQueryParams, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>> {
+    if (!params.measures || params.measures.length === 0) {
+      return Err(new CommerceValidationError("analytics.query requires at least one measure."));
+    }
+
+    const cubeName = pickCube(params);
+
+    // Validate all members are from the same cube
+    const allMembers = [
+      ...params.measures,
+      ...(params.dimensions ?? []),
+      ...(params.timeDimensions ?? []).map((td) => td.dimension),
+    ];
+    const wrongCube = allMembers.find((m) => m.split(".")[0] !== cubeName);
+    if (wrongCube) {
+      return Err(new CommerceValidationError(
+        `analytics.query currently requires measures from a single cube. Found "${wrongCube}" in "${cubeName}" query.`,
+      ));
+    }
+
+    const cube = this.models.get(cubeName);
+    if (!cube) {
+      const available = [...this.models.keys()].join(", ");
+      return Err(new CommerceValidationError(
+        `Unknown analytics cube: "${cubeName}". Available cubes: ${available}`,
+      ));
+    }
+
+    // Validate that requested measures exist in the cube
+    for (const measure of params.measures) {
+      const shortName = measure.split(".")[1];
+      if (shortName && !cube.measures[shortName]) {
+        const available = Object.keys(cube.measures).map((m) => `${cubeName}.${m}`).join(", ");
+        return Err(new CommerceValidationError(
+          `Unknown measure: "${measure}". Available measures for ${cubeName}: ${available}`,
+        ));
+      }
+    }
+
+    // Validate that requested dimensions exist in the cube
+    for (const dim of params.dimensions ?? []) {
+      const shortName = dim.split(".")[1];
+      if (shortName && !cube.dimensions[shortName]) {
+        const available = Object.keys(cube.dimensions).map((d) => `${cubeName}.${d}`).join(", ");
+        return Err(new CommerceValidationError(
+          `Unknown dimension: "${dim}". Available dimensions for ${cubeName}: ${available}`,
+        ));
+      }
+    }
+
+    try {
+      const rows = await this.executeQuery(cube, params, scope);
+      return Ok({
+        query: params,
+        rows,
+        source: cubeName,
+      });
+    } catch (error) {
+      return Err(new CommerceValidationError(
+        `Analytics query failed: ${error instanceof Error ? error.message : String(error)}`,
+      ));
+    }
+  }
+
+  async getMeta(_scope: AnalyticsScope): Promise<Result<AnalyticsMeta>> {
+    const models: AnalyticsModelDefinition[] = [];
+
+    for (const cube of this.models.values()) {
+      models.push({
+        name: cube.name,
+        source: "builtin",
+        measures: Object.keys(cube.measures).map((m) => `${cube.name}.${m}`),
+        dimensions: Object.keys(cube.dimensions).map((d) => `${cube.name}.${d}`),
+        segments: cube.segments
+          ? Object.keys(cube.segments).map((s) => `${cube.name}.${s}`)
+          : [],
+      });
+    }
+
+    return Ok({
+      models,
+      measures: models.flatMap((m) => m.measures),
+      dimensions: models.flatMap((m) => m.dimensions),
+      segments: models.flatMap((m) => m.segments ?? []),
+    });
+  }
+
+  // ─── SQL Query Builder ───────────────────────────────────────────────────
+
+  private async executeQuery(
+    cube: AnalyticsModel,
+    params: AnalyticsQueryParams,
+    scope: AnalyticsScope,
+  ): Promise<Record<string, unknown>[]> {
+    const selectParts: SQL[] = [];
+    const groupByParts: SQL[] = [];
+    const whereParts: SQL[] = [];
+
+    // ── Scope-based filtering (always applied) ───────────────────────
+    //
+    // Security model (hardened by default):
+    //   admin/staff → no filter (full access)
+    //   vendor/customer → MUST have a matching scopeRule, or blocked
+    //   public → always blocked
+    //
+    // Scope is REQUIRED — there is no unscoped code path.
+    {
+      if (scope.role === "public") {
+        whereParts.push(sql.raw("1 = 0"));
+      } else if (scope.role !== "admin" && scope.role !== "staff") {
+        // Vendor or customer: look for a matching scope rule
+        let scopeApplied = false;
+
+        if (cube.scopeRules) {
+          for (const rule of cube.scopeRules) {
+            if (rule.role === scope.role) {
+              // Use parameterized SQL for scope values to prevent injection.
+              // The filter template uses :vendorId / :customerId placeholders.
+              // We split the filter on placeholders and build a parameterized
+              // sql`` template instead of using sql.raw() with string interpolation.
+              let filterSql = rule.filter;
+              if (scope.vendorId && filterSql.includes(":vendorId")) {
+                // Replace placeholder with parameterized value
+                const parts = filterSql.split(":vendorId");
+                const fragments = parts.map((part, i) =>
+                  i < parts.length - 1
+                    ? sql`${sql.raw(part)}${scope.vendorId!}`
+                    : sql.raw(part),
+                );
+                whereParts.push(sql.join(fragments, sql``));
+                scopeApplied = true;
+                continue;
+              }
+              if (scope.customerId && filterSql.includes(":customerId")) {
+                const parts = filterSql.split(":customerId");
+                const fragments = parts.map((part, i) =>
+                  i < parts.length - 1
+                    ? sql`${sql.raw(part)}${scope.customerId!}`
+                    : sql.raw(part),
+                );
+                whereParts.push(sql.join(fragments, sql``));
+                scopeApplied = true;
+                continue;
+              }
+              // No placeholder found — use raw (trusted scope rule SQL)
+              whereParts.push(sql.raw(filterSql));
+              scopeApplied = true;
+            }
+          }
+        }
+
+        // Deny-by-default: if no scope rule matched, block access
+        if (!scopeApplied) {
+          whereParts.push(sql.raw("1 = 0"));
+        }
+      }
+      // admin/staff: no filter applied — full access
+    }
+
+    // Dimensions → SELECT + GROUP BY
+    for (const dim of params.dimensions ?? []) {
+      const shortName = dim.split(".")[1]!;
+      const dimDef = cube.dimensions[shortName];
+      if (!dimDef) continue;
+      selectParts.push(sql.raw(`${dimDef.sql} AS "${dim}"`));
+      groupByParts.push(sql.raw(dimDef.sql));
+    }
+
+    // Time dimensions → SELECT + GROUP BY + WHERE (dateRange)
+    for (const td of params.timeDimensions ?? []) {
+      const selectExpr = compileTimeDimensionSelect(cube, td);
+      selectParts.push(sql`${selectExpr} AS ${sql.raw(`"${td.dimension}"`)}`);
+      groupByParts.push(selectExpr);
+
+      // Date range filter
+      if (td.dateRange) {
+        const range = parseDateRange(td.dateRange);
+        if (range) {
+          const shortName = td.dimension.split(".")[1]!;
+          const dimDef = cube.dimensions[shortName];
+          if (dimDef) {
+            whereParts.push(
+              sql`${sql.raw(dimDef.sql)} >= ${range[0].toISOString()}::timestamptz AND ${sql.raw(dimDef.sql)} < ${range[1].toISOString()}::timestamptz`,
+            );
+          }
+        }
+      }
+    }
+
+    // Measures → SELECT
+    for (const measure of params.measures) {
+      selectParts.push(sql`${compileMeasure(cube, measure)} AS ${sql.raw(`"${measure}"`)}`);
+    }
+
+    // If no select parts (shouldn't happen with validation), bail
+    if (selectParts.length === 0) {
+      return [];
+    }
+
+    // FROM + JOINs
+    let fromFragment = sql.raw(cube.table);
+    for (const join of cube.joins ?? []) {
+      const joinType = join.type === "inner" ? "INNER JOIN" : "LEFT JOIN";
+      fromFragment = sql`${fromFragment} ${sql.raw(joinType)} ${sql.raw(join.table)} ON ${sql.raw(join.on)}`;
+    }
+
+    // Filters → WHERE
+    for (const filter of params.filters ?? []) {
+      const compiled = compileFilter(cube, filter);
+      if (compiled) whereParts.push(compiled);
+    }
+
+    // ORDER BY — validate member names against the cube's registered measures/dimensions
+    const validMeasures = new Set(Object.keys(cube.measures).map((m) => `${cube.name}.${m}`));
+    const validDimensions = new Set(Object.keys(cube.dimensions).map((d) => `${cube.name}.${d}`));
+    const orderParts: SQL[] = [];
+    for (const [member, dir] of Object.entries(params.order ?? {})) {
+      if (!validMeasures.has(member) && !validDimensions.has(member)) {
+        continue; // skip unknown members to prevent SQL injection via sql.raw()
+      }
+      const normalizedDir = dir.toUpperCase() === "DESC" ? "DESC" : "ASC";
+      orderParts.push(sql.raw(`"${member}" ${normalizedDir}`));
+    }
+
+    // LIMIT
+    const limit = Math.max(1, Math.min(params.limit ?? 100, 1000));
+
+    // Assemble the full query
+    const selectClause = sql.join(selectParts, sql`, `);
+    const whereClause = whereParts.length > 0
+      ? sql`WHERE ${sql.join(whereParts, sql` AND `)}`
+      : sql``;
+    const groupByClause = groupByParts.length > 0
+      ? sql`GROUP BY ${sql.join(groupByParts, sql`, `)}`
+      : sql``;
+    const orderClause = orderParts.length > 0
+      ? sql`ORDER BY ${sql.join(orderParts, sql`, `)}`
+      : sql``;
+
+    const fullQuery = sql`SELECT ${selectClause} FROM ${fromFragment} ${whereClause} ${groupByClause} ${orderClause} LIMIT ${limit}`;
+
+    const result = await this.db.execute(fullQuery);
+
+    // Map results: convert bigint to number, preserve column aliases
+    // db.execute() returns different shapes per driver — normalize to array of rows
+    const rawRows: Record<string, unknown>[] = Array.isArray(result)
+      ? result
+      : (result as { rows?: Record<string, unknown>[] }).rows ?? [];
+
+    return rawRows.map((row: Record<string, unknown>) => {
+      const mapped: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(row)) {
+        mapped[key] = typeof value === "bigint" ? Number(value) : value;
+      }
+      return mapped;
+    });
+  }
+}

package/src/modules/analytics/hooks.ts

@@ -0,0 +1,11 @@
+/**
+ * Analytics hooks — RFC-006
+ *
+ * The in-memory event recording hooks (recordOrderAnalyticsEvent,
+ * recordInventoryAnalyticsEvent) have been removed. The source tables
+ * (orders, inventory_levels, customers) ARE the source of truth.
+ * The DrizzleAnalyticsAdapter queries them directly via SQL.
+ *
+ * These empty exports preserve backwards compatibility for any code
+ * that imports from this module.
+ */