@porulle/core 0.1.0

package/dist/kernel/query/executor.js

@@ -0,0 +1,128 @@
+import { CommerceNotFoundError } from "../errors.js";
+/**
+ * Executes a query against the registry, resolving includes via
+ * batched dataloader-style fetches (one WHERE IN per relation).
+ */
+export async function executeQuery(registry, services, input) {
+    const definition = registry.get(input.entity);
+    if (!definition) {
+        throw new CommerceNotFoundError(`No entity registered with name "${input.entity}".`);
+    }
+    const service = services[definition.service];
+    // 1. Fetch primary records
+    let rows;
+    let total;
+    if (input.id) {
+        const result = (await service[definition.getByIdMethod](input.id));
+        const value = result?.value ?? result;
+        rows = value != null ? [value] : [];
+    }
+    else {
+        const result = (await service[definition.listMethod](input.filters ?? {}, input.pagination));
+        const resolved = result?.value ?? result;
+        if (resolved && typeof resolved === "object" && "items" in resolved) {
+            rows = (resolved.items ?? []);
+            total = resolved.total;
+        }
+        else if (Array.isArray(resolved)) {
+            rows = resolved;
+        }
+        else {
+            rows = [];
+        }
+    }
+    // 2. Resolve includes
+    if (input.include?.length) {
+        await resolveIncludes(rows, input.include, definition, services, registry);
+    }
+    return { data: rows, total };
+}
+async function resolveIncludes(rows, includes, definition, services, registry) {
+    // Group includes by top-level segment
+    const topLevel = new Map();
+    for (const path of includes) {
+        const dot = path.indexOf(".");
+        if (dot === -1) {
+            if (!topLevel.has(path))
+                topLevel.set(path, []);
+        }
+        else {
+            const parent = path.substring(0, dot);
+            const child = path.substring(dot + 1);
+            const existing = topLevel.get(parent) ?? [];
+            existing.push(child);
+            topLevel.set(parent, existing);
+        }
+    }
+    for (const [relationName, nestedIncludes] of topLevel) {
+        const relation = definition.relations[relationName];
+        if (!relation)
+            continue;
+        const targetService = services[relation.targetService];
+        if (!targetService)
+            continue;
+        // Collect foreign key values (deduplicated)
+        const ids = [
+            ...new Set(rows
+                .map((r) => r[relation.foreignKey])
+                .filter((v) => v != null && typeof v === "string")),
+        ];
+        if (ids.length === 0)
+            continue;
+        // One batched query
+        const batchFn = targetService[relation.batchMethod];
+        if (!batchFn)
+            continue;
+        const relatedResult = await batchFn(ids);
+        const relatedRows = extractRows(relatedResult);
+        // Build lookup
+        const map = new Map();
+        for (const related of relatedRows) {
+            const rec = related;
+            if (relation.isList) {
+                const key = rec[relation.foreignKey];
+                if (!map.has(key))
+                    map.set(key, []);
+                map.get(key).push(rec);
+            }
+            else {
+                map.set(rec["id"], rec);
+            }
+        }
+        // Attach to parent rows
+        for (const row of rows) {
+            const fkValue = row[relation.foreignKey];
+            if (!fkValue)
+                continue;
+            row[relation.attachAs] =
+                map.get(fkValue) ?? (relation.isList ? [] : null);
+        }
+        // Resolve nested includes
+        if (nestedIncludes.length > 0) {
+            const targetDef = registry.get(relation.targetService);
+            if (targetDef) {
+                const nestedRows = relation.isList
+                    ? rows.flatMap((r) => r[relation.attachAs] ?? [])
+                    : rows
+                        .map((r) => r[relation.attachAs])
+                        .filter(Boolean);
+                await resolveIncludes(nestedRows, nestedIncludes, targetDef, services, registry);
+            }
+        }
+    }
+}
+function extractRows(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && typeof result === "object") {
+        const r = result;
+        if (r.value != null) {
+            if (Array.isArray(r.value))
+                return r.value;
+            if (typeof r.value === "object" && "items" in r.value) {
+                return r.value.items;
+            }
+        }
+    }
+    return [];
+}

package/dist/kernel/query/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Defines a relation from a parent entity to a related entity.
+ * Used by the query executor to batch-load related records.
+ */
+export interface RelationDefinition {
+    foreignKey: string;
+    targetService: string;
+    batchMethod: string;
+    attachAs: string;
+    isList?: boolean;
+}
+/**
+ * Defines an entity that can be queried via kernel.query().
+ */
+export interface EntityDefinition {
+    service: string;
+    getByIdMethod: string;
+    listMethod: string;
+    relations: Record<string, RelationDefinition>;
+}
+/**
+ * Registry of queryable entities and their relations.
+ * Modules register their entities at kernel boot.
+ * Plugins can register additional entities.
+ */
+export declare class QueryRegistry {
+    private entities;
+    register(name: string, definition: EntityDefinition): void;
+    get(name: string): EntityDefinition | undefined;
+    has(name: string): boolean;
+    listEntities(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/kernel/query/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/query/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAuC;IAEvD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAI1D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI/C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,YAAY,IAAI,MAAM,EAAE;CAGzB"}

package/dist/kernel/query/registry.js

@@ -0,0 +1,20 @@
+/**
+ * Registry of queryable entities and their relations.
+ * Modules register their entities at kernel boot.
+ * Plugins can register additional entities.
+ */
+export class QueryRegistry {
+    entities = new Map();
+    register(name, definition) {
+        this.entities.set(name, definition);
+    }
+    get(name) {
+        return this.entities.get(name);
+    }
+    has(name) {
+        return this.entities.has(name);
+    }
+    listEntities() {
+        return [...this.entities.keys()];
+    }
+}

package/dist/kernel/result.d.ts

@@ -0,0 +1,36 @@
+import type { CommerceError } from "./errors.js";
+export type Result<T, E = CommerceError> = {
+    ok: true;
+    value: T;
+    meta?: Record<string, unknown>;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Simplified Result types for plugin services.
+ * Plugin services return `PluginResult<T>` instead of `Result<T, CommerceError>`.
+ * This matches the `{ ok: true; value: T } | { ok: false; error: string }` pattern
+ * that every plugin has been copy-pasting.
+ */
+export type PluginResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+export type PluginResultErr = {
+    ok: false;
+    error: string;
+    code?: string;
+};
+export declare function Ok<T>(value: T, meta?: Record<string, unknown>): Result<T, never>;
+export declare function Err<E>(error: E): Result<never, E>;
+/**
+ * String-based Err for plugin services.
+ * Usage: `return PluginErr("Not found", "NOT_FOUND")`
+ */
+export declare function PluginErr(error: string, code?: string): PluginResultErr;
+//# sourceMappingURL=result.d.ts.map

package/dist/kernel/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/kernel/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,aAAa,IACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACnG,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAKhF;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAEvE"}

package/dist/kernel/result.js

@@ -0,0 +1,16 @@
+export function Ok(value, meta) {
+    if (meta !== undefined) {
+        return { ok: true, value, meta };
+    }
+    return { ok: true, value };
+}
+export function Err(error) {
+    return { ok: false, error };
+}
+/**
+ * String-based Err for plugin services.
+ * Usage: `return PluginErr("Not found", "NOT_FOUND")`
+ */
+export function PluginErr(error, code) {
+    return code ? { ok: false, error, code } : { ok: false, error };
+}

package/dist/kernel/service-registry.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ServiceRegistry -- typed surface of the kernel service container
+ * for plugin-to-plugin communication.
+ *
+ * Plugin services accept this as an optional constructor parameter
+ * to call core services without resorting to raw SQL.
+ *
+ * Core services are loosely typed here (method signatures use `unknown`)
+ * to avoid plugin packages depending on core's internal service types.
+ * Plugin authors cast the return values at the call site.
+ *
+ * Usage in a plugin service:
+ *
+ *   import type { ServiceRegistry } from "@porulle/core";
+ *
+ *   class MyService {
+ *     constructor(private db: PluginDb, private services?: ServiceRegistry) {}
+ *
+ *     async doWork() {
+ *       const result = await this.services?.inventory.adjust({
+ *         entityId: "...", adjustment: -5, reason: "recipe deduction"
+ *       }, actor);
+ *     }
+ *   }
+ */
+export interface ServiceRegistry {
+    inventory: {
+        adjust(input: {
+            entityId: string;
+            variantId?: string;
+            warehouseId?: string;
+            adjustment: number;
+            reason?: string;
+        }, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        createWarehouse(input: {
+            name: string;
+            code: string;
+        }, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        reserve(input: unknown, actor?: unknown): Promise<unknown>;
+        release(input: unknown, actor?: unknown): Promise<unknown>;
+        getAvailable(input: unknown, actor?: unknown): Promise<unknown>;
+        [method: string]: unknown;
+    };
+    catalog: {
+        create(input: unknown, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        getById(id: string, options?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        publish(id: string, actor?: unknown): Promise<unknown>;
+        list(input?: unknown): Promise<unknown>;
+        [method: string]: unknown;
+    };
+    customers: {
+        getByUserId(userId: string, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        getById(id: string, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        [method: string]: unknown;
+    };
+    orders: {
+        create(input: unknown, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        changeStatus(input: unknown, actor?: unknown): Promise<unknown>;
+        [method: string]: unknown;
+    };
+    cart: {
+        create(input: unknown, actor?: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        [method: string]: unknown;
+    };
+    organization: {
+        create(input: unknown): Promise<{
+            ok: boolean;
+            value?: unknown;
+            error?: unknown;
+        }>;
+        getById(id: string): Promise<unknown>;
+        [method: string]: unknown;
+    };
+    /** Access plugin-registered services by plugin ID or service name */
+    [key: string]: unknown;
+}
+//# sourceMappingURL=service-registry.d.ts.map

package/dist/kernel/service-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.d.ts","sourceRoot":"","sources":["../../src/kernel/service-registry.ts"],"names":[],"mappings":"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"}

package/dist/kernel/service-registry.js

@@ -0,0 +1,26 @@
+/**
+ * ServiceRegistry -- typed surface of the kernel service container
+ * for plugin-to-plugin communication.
+ *
+ * Plugin services accept this as an optional constructor parameter
+ * to call core services without resorting to raw SQL.
+ *
+ * Core services are loosely typed here (method signatures use `unknown`)
+ * to avoid plugin packages depending on core's internal service types.
+ * Plugin authors cast the return values at the call site.
+ *
+ * Usage in a plugin service:
+ *
+ *   import type { ServiceRegistry } from "@porulle/core";
+ *
+ *   class MyService {
+ *     constructor(private db: PluginDb, private services?: ServiceRegistry) {}
+ *
+ *     async doWork() {
+ *       const result = await this.services?.inventory.adjust({
+ *         entityId: "...", adjustment: -5, reason: "recipe deduction"
+ *       }, actor);
+ *     }
+ *   }
+ */
+export {};

package/dist/kernel/service-timing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare function withTiming<T extends object>(service: T, serviceName: string, logger: TimingLogger, slowThresholdMs?: number): T;
+export {};
+//# sourceMappingURL=service-timing.d.ts.map

package/dist/kernel/service-timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-timing.d.ts","sourceRoot":"","sources":["../../src/kernel/service-timing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,UAAU,YAAY;IACpB,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACxD;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,OAAO,EAAE,CAAC,EACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,YAAY,EACpB,eAAe,SAAM,GACpB,CAAC,CA2DH"}

package/dist/kernel/service-timing.js

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+export function withTiming(service, serviceName, logger, slowThresholdMs = 100) {
+    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(...args) {
+                const start = performance.now();
+                // Call the original method
+                let result;
+                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.then === "function") {
+                    return result.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/dist/kernel/state-machine/machine.d.ts

@@ -0,0 +1,24 @@
+export interface StateDefinition<TState extends string> {
+    states: readonly TState[];
+    initial: TState;
+    transitions: Record<TState, readonly TState[]>;
+    terminal: readonly TState[];
+}
+export type OrderState = string;
+export declare const orderStateMachine: StateDefinition<string>;
+/**
+ * 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 declare function extendOrderStateMachine(customTransitions: Record<string, string[]>): StateDefinition<string>;
+export declare function canTransition<TState extends string>(machine: StateDefinition<TState>, from: TState, to: TState): boolean;
+export declare function assertTransition<TState extends string>(machine: StateDefinition<TState>, from: TState, to: TState): void;
+//# sourceMappingURL=machine.d.ts.map

package/dist/kernel/state-machine/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../src/kernel/state-machine/machine.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe,CAAC,MAAM,SAAS,MAAM;IACpD,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC/C,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAmBhC,eAAO,MAAM,iBAAiB,EAAE,eAAe,CAAC,MAAM,CAKrD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAC1C,eAAe,CAAC,MAAM,CAAC,CA6BzB;AAED,wBAAgB,aAAa,CAAC,MAAM,SAAS,MAAM,EACjD,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAET;AAED,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,EACpD,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,IAAI,CAQN"}

package/dist/kernel/state-machine/machine.js

@@ -0,0 +1,70 @@
+import { CommerceInvalidTransitionError } from "../errors.js";
+const DEFAULT_TRANSITIONS = {
+    pending: ["confirmed", "cancelled"],
+    confirmed: ["processing", "cancelled"],
+    processing: ["partially_fulfilled", "fulfilled", "cancelled"],
+    partially_fulfilled: ["fulfilled", "cancelled"],
+    fulfilled: ["refunded"],
+    cancelled: [],
+    refunded: [],
+};
+const DEFAULT_STATES = [
+    "pending", "confirmed", "processing", "partially_fulfilled",
+    "fulfilled", "cancelled", "refunded",
+];
+const DEFAULT_TERMINAL = ["cancelled", "refunded"];
+export const orderStateMachine = {
+    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) {
+    const merged = {};
+    // 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(machine, from, to) {
+    return machine.transitions[from].includes(to);
+}
+export function assertTransition(machine, from, to) {
+    if (!canTransition(machine, from, to)) {
+        throw new CommerceInvalidTransitionError(`Cannot transition from "${from}" to "${to}". Allowed transitions from "${from}": [${machine.transitions[from].join(", ")}]`);
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { type Result } from "../../kernel/result.js";
+import type { AnalyticsAdapter, AnalyticsMeta, AnalyticsModel, AnalyticsQueryParams, AnalyticsQueryResult, AnalyticsScope } from "./types.js";
+export declare class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
+    private db;
+    private models;
+    constructor(db: DrizzleDatabase);
+    registerModel(model: AnalyticsModel): void;
+    query(params: AnalyticsQueryParams, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>>;
+    getMeta(_scope: AnalyticsScope): Promise<Result<AnalyticsMeta>>;
+    private executeQuery;
+}
+//# sourceMappingURL=drizzle-adapter.d.ts.map

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,qCAAqC,CAAC;AAE3E,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EACV,gBAAgB,EAEhB,aAAa,EACb,cAAc,EAEd,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EAEf,MAAM,YAAY,CAAC;AAiJpB,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"}