@unifiedcommerce/core 0.4.4 → 0.4.5

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 "@unifiedcommerce/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 "@unifiedcommerce/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"}