@porulle/core 0.1.0

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.
+ */

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/module.ts

@@ -0,0 +1,25 @@
+import type { CommerceConfig } from "../../config/types.js";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { defineModule } from "../../kernel/module/index.js";
+import { DrizzleAnalyticsAdapter } from "./drizzle-adapter.js";
+import { BUILTIN_ANALYTICS_MODELS } from "./models.js";
+import { AnalyticsService } from "./service.js";
+
+export const analyticsModule = defineModule<
+  Record<string, never>,
+  AnalyticsService,
+  Record<string, never>
+>({
+  id: "analytics",
+  schema: () => ({}),
+  service: (deps) => {
+    const adapter = new DrizzleAnalyticsAdapter(deps.db.db as DrizzleDatabase);
+    for (const model of BUILTIN_ANALYTICS_MODELS) {
+      adapter.registerModel(model);
+    }
+    return new AnalyticsService({
+      adapter,
+      config: deps.config as CommerceConfig,
+    });
+  },
+});

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>;
+}