@unifiedcommerce/core 0.0.1

package/dist/modules/analytics/drizzle-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle-adapter.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/drizzle-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAEhB,aAAa,EACb,cAAc,EAEd,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EAEf,MAAM,SAAS,CAAC;AAiJjB,qBAAa,uBAAwB,YAAW,gBAAgB;IAGlD,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,MAAM,CAAqC;gBAE/B,EAAE,EAAE,eAAe;IAEvC,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIpC,KAAK,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAgEjG,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YAyBvD,YAAY;CAwK3B"}

package/dist/modules/analytics/drizzle-adapter.js

@@ -0,0 +1,358 @@
+import { sql } from "drizzle-orm";
+import { CommerceValidationError } from "../../kernel/errors";
+import { Err, Ok } from "../../kernel/result";
+// ─── Date Range Parsing ──────────────────────────────────────────────────────
+function parseDateRange(range) {
+    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) {
+    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 = {
+    day: "YYYY-MM-DD",
+    week: "IYYY-\"W\"IW",
+    month: "YYYY-MM",
+    year: "YYYY",
+};
+// ─── SQL Compilation Helpers ─────────────────────────────────────────────────
+function compileMeasure(cube, measureName) {
+    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, td) {
+    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, filter) {
+    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 {
+    db;
+    models = new Map();
+    constructor(db) {
+        this.db = db;
+    }
+    registerModel(model) {
+        this.models.set(model.name, model);
+    }
+    async query(params, scope) {
+        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) {
+        const models = [];
+        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 ───────────────────────────────────────────────────
+    async executeQuery(cube, params, scope) {
+        const selectParts = [];
+        const groupByParts = [];
+        const whereParts = [];
+        // ── 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 = [];
+        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 = Array.isArray(result)
+            ? result
+            : result.rows ?? [];
+        return rawRows.map((row) => {
+            const mapped = {};
+            for (const [key, value] of Object.entries(row)) {
+                mapped[key] = typeof value === "bigint" ? Number(value) : value;
+            }
+            return mapped;
+        });
+    }
+}

package/dist/modules/analytics/hooks.d.ts

@@ -0,0 +1,13 @@
+export {};
+/**
+ * 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.
+ */
+//# sourceMappingURL=hooks.d.ts.map

package/dist/modules/analytics/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/hooks.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

package/dist/modules/analytics/hooks.js

@@ -0,0 +1,12 @@
+export {};
+/**
+ * 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/dist/modules/analytics/models.d.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsModel } from "./types";
+/**
+ * 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 declare const ORDERS_MODEL: AnalyticsModel;
+export declare const ORDER_LINE_ITEMS_MODEL: AnalyticsModel;
+export declare const INVENTORY_MODEL: AnalyticsModel;
+export declare const CUSTOMERS_MODEL: AnalyticsModel;
+export declare const BUILTIN_ANALYTICS_MODELS: AnalyticsModel[];
+//# sourceMappingURL=models.d.ts.map

package/dist/modules/analytics/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;GAMG;AAEH,eAAO,MAAM,YAAY,EAAE,cAwB1B,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,cA2BpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cA0B7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,cAwB7B,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,cAAc,EAKpD,CAAC"}

package/dist/modules/analytics/models.js

@@ -0,0 +1,118 @@
+/**
+ * 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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = [
+    ORDERS_MODEL,
+    ORDER_LINE_ITEMS_MODEL,
+    INVENTORY_MODEL,
+    CUSTOMERS_MODEL,
+];

package/dist/modules/analytics/repository/index.d.ts

@@ -0,0 +1,5 @@
+import type { TxContext } from "../../../kernel/database/tx-context";
+export interface AnalyticsRepository {
+    ping(ctx: TxContext): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/analytics/repository/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/analytics/repository/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAElC,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/dist/modules/analytics/repository/index.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/analytics/service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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";
+import { type Result } from "../../kernel/result";
+import type { AnalyticsAdapter, AnalyticsMeta, AnalyticsQueryParams, AnalyticsQueryResult, AnalyticsScope } from "./types";
+export type { AnalyticsTimeDimension, AnalyticsFilter, AnalyticsQueryParams, AnalyticsModelDefinition, AnalyticsMeta, } from "./types";
+export interface AnalyticsServiceDeps {
+    adapter: AnalyticsAdapter;
+    config: CommerceConfig;
+}
+export declare class AnalyticsService {
+    private deps;
+    private pluginModels;
+    private customSchemaModels;
+    private customModelsLoaded;
+    constructor(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;
+    /**
+     * Query analytics with scope-based filtering.
+     * Scope is REQUIRED — use buildAnalyticsScope(actor) to construct it.
+     */
+    query(params: AnalyticsQueryParams, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>>;
+    getDashboard(name: string, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>>;
+    getMeta(): Promise<Result<AnalyticsMeta>>;
+    meta(): Promise<Result<{
+        measures: string[];
+        dimensions: string[];
+        segments: string[];
+    }>>;
+    private tryRegisterModel;
+    private ensureCustomSchemaModelsLoaded;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/modules/analytics/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EAGb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,wBAAwB,EACxB,aAAa,GACd,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,qBAAa,gBAAgB;IAKf,OAAO,CAAC,IAAI;IAJxB,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,kBAAkB,CAAkC;IAC5D,OAAO,CAAC,kBAAkB,CAAS;gBAEf,IAAI,EAAE,oBAAoB;IAE9C;;;;;;OAMG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAiCnC;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAIjG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IA4BxF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAsBzC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAY/F,OAAO,CAAC,gBAAgB;YA0CV,8BAA8B;CAkD7C"}