@porulle/core 0.1.0

package/dist/kernel/factory/repository-factory.js

@@ -0,0 +1,138 @@
+import { eq, and, isNull, sql, getTableColumns, } from "drizzle-orm";
+import { CommerceNotFoundError } from "../errors.js";
+/**
+ * Creates a typed repository with standard CRUD operations from a Drizzle table schema.
+ *
+ * Usage:
+ * ```typescript
+ * const repo = createRepository(schema.promotions, db)
+ * const row = await repo.findById("abc-123")
+ * const rows = await repo.findMany({ status: "active" }, { limit: 10 })
+ * ```
+ *
+ * Tables with a `deletedAt` column automatically get `softDelete()` and `restore()`.
+ * Domain-specific queries should remain in dedicated repository classes that
+ * delegate standard CRUD to the factory-created instance.
+ */
+export function createRepository(table, db) {
+    // Use getTableColumns for type-safe column access
+    const columns = getTableColumns(table);
+    // Runtime check for soft-delete column
+    const hasSoftDelete = "deletedAt" in columns || "deleted_at" in columns;
+    const deletedAtColumn = columns["deletedAt"] ?? columns["deleted_at"] ?? null;
+    const idColumn = columns["id"];
+    // Drizzle's generic types require PgTable at the boundary.
+    // We cast once here rather than at every call site.
+    const pgTable = table;
+    function getDb(ctx) {
+        return ctx?.tx ?? db;
+    }
+    function buildWhereConditions(filters, includeDeleted = false) {
+        const conditions = [];
+        // Automatically exclude soft-deleted rows unless explicitly requested
+        if (hasSoftDelete && !includeDeleted && deletedAtColumn) {
+            conditions.push(isNull(deletedAtColumn));
+        }
+        if (filters) {
+            for (const [key, value] of Object.entries(filters)) {
+                const col = columns[key];
+                if (value !== undefined && col) {
+                    conditions.push(eq(col, value));
+                }
+            }
+        }
+        return conditions;
+    }
+    const repo = {
+        async findById(id, ctx) {
+            const conditions = buildWhereConditions(undefined, false);
+            conditions.push(eq(idColumn, id));
+            const rows = await getDb(ctx)
+                .select()
+                .from(pgTable)
+                .where(and(...conditions));
+            return rows[0];
+        },
+        async findMany(filters, options = {}, ctx) {
+            const conditions = buildWhereConditions(filters, options.withDeleted);
+            let query = getDb(ctx).select().from(pgTable).$dynamic();
+            if (conditions.length > 0) {
+                query = query.where(and(...conditions));
+            }
+            if (options.limit !== undefined) {
+                query = query.limit(options.limit);
+            }
+            if (options.offset !== undefined) {
+                query = query.offset(options.offset);
+            }
+            // Drizzle's $dynamic() erases the row type when using PgTable.
+            // Use .then() to narrow the resolved array type with a single cast.
+            return query.then((rows) => rows);
+        },
+        async findAndCount(filters, options = {}, ctx) {
+            const rows = await repo.findMany(filters, options, ctx);
+            const conditions = buildWhereConditions(filters, options.withDeleted);
+            let countQuery = getDb(ctx)
+                .select({ count: sql `count(*)::int` })
+                .from(pgTable)
+                .$dynamic();
+            if (conditions.length > 0) {
+                countQuery = countQuery.where(and(...conditions));
+            }
+            const countResult = await countQuery;
+            return { rows, total: countResult[0]?.count ?? 0 };
+        },
+        async create(data, ctx) {
+            const rows = await getDb(ctx)
+                .insert(pgTable)
+                .values(data)
+                .returning();
+            return rows[0];
+        },
+        async createMany(data, ctx) {
+            if (data.length === 0)
+                return [];
+            const rows = await getDb(ctx)
+                .insert(pgTable)
+                .values(data)
+                .returning();
+            return rows;
+        },
+        async update(id, data, ctx) {
+            const rows = await getDb(ctx)
+                .update(pgTable)
+                .set(data)
+                .where(eq(idColumn, id))
+                .returning();
+            if (!rows[0]) {
+                throw new CommerceNotFoundError(`Record ${id} not found.`);
+            }
+            return rows[0];
+        },
+        async delete(id, ctx) {
+            await getDb(ctx).delete(pgTable).where(eq(idColumn, id));
+        },
+    };
+    if (hasSoftDelete && deletedAtColumn) {
+        const softRepo = repo;
+        softRepo.softDelete = async (id, ctx) => {
+            await getDb(ctx)
+                .update(pgTable)
+                .set({ deletedAt: new Date() })
+                .where(eq(idColumn, id));
+        };
+        softRepo.restore = async (id, ctx) => {
+            const rows = await getDb(ctx)
+                .update(pgTable)
+                .set({ deletedAt: null })
+                .where(eq(idColumn, id))
+                .returning();
+            if (!rows[0]) {
+                throw new CommerceNotFoundError(`Record ${id} not found.`);
+            }
+            return rows[0];
+        };
+        return softRepo;
+    }
+    return repo;
+}

package/dist/kernel/hooks/create-context.d.ts

@@ -0,0 +1,32 @@
+import type { Actor } from "../../auth/types.js";
+import type { JobsAdapter } from "../jobs/adapter.js";
+import type { PluginDb } from "../database/plugin-types.js";
+import type { HookContext, HookOrigin, Logger, ServiceContainer } from "./types.js";
+export interface CreateHookContextArgs {
+    actor: Actor | null;
+    tx?: unknown;
+    logger: Logger;
+    services: ServiceContainer;
+    context?: Record<string, unknown>;
+    requestId?: string;
+    origin?: HookOrigin;
+    jobs?: JobsAdapter;
+    db?: PluginDb;
+    /** Prefer this over {@link CreateHookContextArgs.kernel}. */
+    database?: {
+        db: PluginDb;
+    };
+    /**
+     * @deprecated Pass {@link CreateHookContextArgs.database} or {@link CreateHookContextArgs.db} instead.
+     */
+    kernel?: {
+        database: {
+            db: PluginDb;
+        };
+    };
+}
+/**
+ * Creates a HookContext with sensible defaults.
+ */
+export declare function createHookContext(args: CreateHookContextArgs): HookContext;
+//# sourceMappingURL=create-context.d.ts.map

package/dist/kernel/hooks/create-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-context.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/create-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpF,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,6DAA6D;IAC7D,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC5B;;OAEG;IACH,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE;YAAE,EAAE,EAAE,QAAQ,CAAA;SAAE,CAAA;KAAE,CAAC;CACzC;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,WAAW,CAqB1E"}

package/dist/kernel/hooks/create-context.js

@@ -0,0 +1,23 @@
+import { randomUUID } from "node:crypto";
+import { NullJobsAdapter } from "../jobs/adapter.js";
+const nullJobs = new NullJobsAdapter();
+/**
+ * Creates a HookContext with sensible defaults.
+ */
+export function createHookContext(args) {
+    const db = args.db ?? args.database?.db ?? args.kernel?.database?.db ?? null;
+    if (db == null) {
+        throw new Error("createHookContext requires a database: pass `db`, `database: { db }`, or `kernel: { database: { db } }`.");
+    }
+    return {
+        actor: args.actor,
+        tx: args.tx ?? null,
+        logger: args.logger,
+        services: args.services,
+        context: args.context ?? {},
+        requestId: args.requestId ?? randomUUID(),
+        origin: args.origin ?? "rest",
+        jobs: args.jobs ?? nullJobs,
+        db,
+    };
+}

package/dist/kernel/hooks/executor.d.ts

@@ -0,0 +1,13 @@
+import type { AfterHook, BeforeHook, HookContext, HookOperation } from "./types.js";
+export interface HookError {
+    hookName: string;
+    message: string;
+}
+export interface HookReport {
+    errors: HookError[];
+    hasErrors: boolean;
+}
+export declare function mergeHookReports(a: HookReport, b: HookReport): HookReport;
+export declare function runBeforeHooks<T>(hooks: BeforeHook<T>[], data: T, operation: HookOperation, context: HookContext): Promise<T>;
+export declare function runAfterHooks<T>(hooks: AfterHook<T>[], originalData: T | null, committedResult: T, operation: HookOperation, context: HookContext): Promise<HookReport>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/kernel/hooks/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpF,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAKzE;AAmBD,wBAAsB,cAAc,CAAC,CAAC,EACpC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EACrB,YAAY,EAAE,CAAC,GAAG,IAAI,EACtB,eAAe,EAAE,CAAC,EAClB,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CA0BrB"}

package/dist/kernel/hooks/executor.js

@@ -0,0 +1,56 @@
+export function mergeHookReports(a, b) {
+    return {
+        errors: [...a.errors, ...b.errors],
+        hasErrors: a.hasErrors || b.hasErrors,
+    };
+}
+/** Default hook timeout: 20 seconds */
+const HOOK_TIMEOUT_MS = 20_000;
+function withTimeout(promiseOrValue, timeoutMs, hookName) {
+    const promise = Promise.resolve(promiseOrValue);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Hook "${hookName}" timed out after ${timeoutMs}ms`)), timeoutMs);
+        promise.then((val) => { clearTimeout(timer); resolve(val); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
+export async function runBeforeHooks(hooks, data, operation, context) {
+    let current = data;
+    for (const hook of hooks) {
+        const hookName = hook.name || "(anonymous beforeHook)";
+        try {
+            current = await withTimeout(hook({ data: current, operation, context }), HOOK_TIMEOUT_MS, hookName);
+        }
+        catch (error) {
+            context.logger.error(`Before-hook "${hookName}" failed during ${operation}`, {
+                error: error instanceof Error ? error.message : String(error),
+                requestId: context.requestId,
+            });
+            throw error; // Re-throw — beforeHooks MUST succeed
+        }
+    }
+    return current;
+}
+export async function runAfterHooks(hooks, originalData, committedResult, operation, context) {
+    const errors = [];
+    for (const hook of hooks) {
+        const hookName = hook.name || "(anonymous afterHook)";
+        try {
+            await withTimeout(hook({
+                data: originalData,
+                result: committedResult,
+                operation,
+                context,
+            }), HOOK_TIMEOUT_MS, hookName);
+        }
+        catch (error) {
+            errors.push({
+                hookName,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            context.logger.error(`After-hook "${hookName}" failed`, {
+                error,
+            });
+        }
+    }
+    return { errors, hasErrors: errors.length > 0 };
+}

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

@@ -0,0 +1,28 @@
+export type HookHandler = (...args: never[]) => unknown;
+export declare class HookRegistry {
+    private registry;
+    private logger?;
+    registerConfigHooks(hookName: string, handlers: HookHandler[]): void;
+    append(hookName: string, handler: HookHandler): void;
+    prepend(hookName: string, handler: HookHandler): void;
+    resolve(hookName: string): HookHandler[];
+    /**
+     * Emit a plugin event to all registered listeners.
+     *
+     * Unlike the before/after hook pattern (which transforms data through
+     * a pipeline), emit is fire-and-forget notification. Errors in handlers
+     * are caught and logged but do not propagate to the emitter.
+     *
+     * Usage:
+     *   kernel.hooks.emit("production.afterComplete", { orderId, quantity });
+     *
+     * Any plugin can listen:
+     *   hooks: () => [{ key: "production.afterComplete", handler: async (payload) => { ... } }]
+     */
+    setLogger(logger: {
+        error: (obj: Record<string, unknown>, msg: string) => void;
+    }): void;
+    emit(key: string, payload: unknown): Promise<void>;
+    private ensureEntry;
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/registry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAQxD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,MAAM,CAAC,CAAiE;IAEhF,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAKpE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKpD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKrD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAMxC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI;IAIjF,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD,OAAO,CAAC,WAAW;CASpB"}

package/dist/kernel/hooks/registry.js

@@ -0,0 +1,58 @@
+export class HookRegistry {
+    registry = new Map();
+    logger;
+    registerConfigHooks(hookName, handlers) {
+        this.ensureEntry(hookName);
+        this.registry.get(hookName).configured = [...handlers];
+    }
+    append(hookName, handler) {
+        this.ensureEntry(hookName);
+        this.registry.get(hookName).appended.push(handler);
+    }
+    prepend(hookName, handler) {
+        this.ensureEntry(hookName);
+        this.registry.get(hookName).prepended.push(handler);
+    }
+    resolve(hookName) {
+        const entry = this.registry.get(hookName);
+        if (!entry)
+            return [];
+        return [...entry.prepended, ...entry.configured, ...entry.appended];
+    }
+    /**
+     * Emit a plugin event to all registered listeners.
+     *
+     * Unlike the before/after hook pattern (which transforms data through
+     * a pipeline), emit is fire-and-forget notification. Errors in handlers
+     * are caught and logged but do not propagate to the emitter.
+     *
+     * Usage:
+     *   kernel.hooks.emit("production.afterComplete", { orderId, quantity });
+     *
+     * Any plugin can listen:
+     *   hooks: () => [{ key: "production.afterComplete", handler: async (payload) => { ... } }]
+     */
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    async emit(key, payload) {
+        const handlers = this.resolve(key);
+        for (const handler of handlers) {
+            try {
+                await handler(payload);
+            }
+            catch (err) {
+                this.logger?.error({ err, hookKey: key }, `Event handler failed for "${key}"`);
+            }
+        }
+    }
+    ensureEntry(hookName) {
+        if (!this.registry.has(hookName)) {
+            this.registry.set(hookName, {
+                prepended: [],
+                configured: [],
+                appended: [],
+            });
+        }
+    }
+}

package/dist/kernel/hooks/types.d.ts

@@ -0,0 +1,40 @@
+import type { Actor } from "../../auth/types.js";
+import type { JobsAdapter } from "../jobs/adapter.js";
+import type { PluginDb } from "../database/plugin-types.js";
+export type HookOperation = "create" | "update" | "delete" | "read" | "list" | "statusChange" | "addItem" | "removeItem" | "custom";
+export interface Logger {
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+export interface ServiceContainer {
+    [key: string]: unknown;
+}
+export type HookOrigin = "rest" | "local";
+export interface HookContext {
+    actor: Actor | null;
+    tx: unknown;
+    logger: Logger;
+    services: ServiceContainer;
+    context: Record<string, unknown>;
+    requestId: string;
+    origin: HookOrigin;
+    jobs: JobsAdapter;
+    /**
+     * Drizzle database instance for hook handlers.
+     * Populated by `createHookContext` when callers pass `db`, `database`, or `kernel`.
+     */
+    db: PluginDb;
+}
+export type BeforeHook<TData> = (args: {
+    data: TData;
+    operation: HookOperation;
+    context: HookContext;
+}) => Promise<TData> | TData;
+export type AfterHook<TData> = (args: {
+    data: TData | null;
+    result: TData;
+    operation: HookOperation;
+    context: HookContext;
+}) => Promise<void> | void;
+//# sourceMappingURL=types.d.ts.map

package/dist/kernel/hooks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,cAAc,GACd,SAAS,GACT,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,UAAU,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;AAE7B,MAAM,MAAM,SAAS,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC"}

package/dist/kernel/hooks/types.js

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

package/dist/kernel/http-error.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Converts a PluginResultErr into a structured HTTP error response.
+ *
+ * Replaces the `throw new Error(result.error)` pattern in plugin routes
+ * which always produces HTTP 500 with no structured error code.
+ *
+ * Usage in routes:
+ *   const result = await service.doSomething(orgId, input);
+ *   if (!result.ok) return toHttpError(result);
+ *   return result.value;
+ *
+ * The function infers HTTP status from the error code or message content:
+ *   - "NOT_FOUND" or "not found"        --> 404
+ *   - "FORBIDDEN" or "permission"        --> 403
+ *   - "CONFLICT" or "already exists"     --> 409
+ *   - "VALIDATION" or "cannot/must"      --> 422
+ *   - Everything else                    --> 400
+ */
+import type { PluginResultErr } from "./result.js";
+export interface HttpErrorResponse {
+    status: 400 | 403 | 404 | 409 | 422;
+    body: {
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+}
+export declare function toHttpError(result: PluginResultErr): HttpErrorResponse;
+//# sourceMappingURL=http-error.d.ts.map

package/dist/kernel/http-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-error.d.ts","sourceRoot":"","sources":["../../src/kernel/http-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACpC,IAAI,EAAE;QAAE,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACpD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAiBtE"}

package/dist/kernel/http-error.js

@@ -0,0 +1,35 @@
+/**
+ * Converts a PluginResultErr into a structured HTTP error response.
+ *
+ * Replaces the `throw new Error(result.error)` pattern in plugin routes
+ * which always produces HTTP 500 with no structured error code.
+ *
+ * Usage in routes:
+ *   const result = await service.doSomething(orgId, input);
+ *   if (!result.ok) return toHttpError(result);
+ *   return result.value;
+ *
+ * The function infers HTTP status from the error code or message content:
+ *   - "NOT_FOUND" or "not found"        --> 404
+ *   - "FORBIDDEN" or "permission"        --> 403
+ *   - "CONFLICT" or "already exists"     --> 409
+ *   - "VALIDATION" or "cannot/must"      --> 422
+ *   - Everything else                    --> 400
+ */
+export function toHttpError(result) {
+    const message = result.error;
+    const code = result.code;
+    if (code === "NOT_FOUND" || /not found/i.test(message)) {
+        return { status: 404, body: { error: { code: "NOT_FOUND", message } } };
+    }
+    if (code === "FORBIDDEN" || /permission|forbidden|unauthorized/i.test(message)) {
+        return { status: 403, body: { error: { code: "FORBIDDEN", message } } };
+    }
+    if (code === "CONFLICT" || /already|duplicate|exists|unique/i.test(message)) {
+        return { status: 409, body: { error: { code: "CONFLICT", message } } };
+    }
+    if (code === "VALIDATION" || /invalid|cannot|must|required|exceeded|negative/i.test(message)) {
+        return { status: 422, body: { error: { code: "VALIDATION_FAILED", message } } };
+    }
+    return { status: 400, body: { error: { code: code ?? "BAD_REQUEST", message } } };
+}

package/dist/kernel/jobs/adapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal interface for enqueueing background jobs.
+ * The full DrizzleJobsAdapter implements this; hooks receive
+ * it on HookContext.jobs so they can defer work without caring
+ * about the underlying storage.
+ */
+export interface JobsAdapter {
+    enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
+}
+export interface EnqueueOptions {
+    organizationId: string;
+    queue?: string;
+    maxAttempts?: number;
+    delayMs?: number;
+    concurrencyKey?: string;
+    supersedes?: boolean;
+}
+/**
+ * No-op adapter used when no jobs backend is configured.
+ * All enqueue calls silently succeed and return a placeholder ID.
+ */
+export declare class NullJobsAdapter implements JobsAdapter {
+    enqueue(_taskSlug: string, _input: Record<string, unknown>, _options: EnqueueOptions): Promise<string>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/kernel/jobs/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/kernel/jobs/adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAC3C,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC;CAGnB"}

package/dist/kernel/jobs/adapter.js

@@ -0,0 +1,9 @@
+/**
+ * No-op adapter used when no jobs backend is configured.
+ * All enqueue calls silently succeed and return a placeholder ID.
+ */
+export class NullJobsAdapter {
+    async enqueue(_taskSlug, _input, _options) {
+        return "null-job-id";
+    }
+}

package/dist/kernel/jobs/builtin-job-tasks.d.ts

@@ -0,0 +1,3 @@
+import type { TaskDefinition } from "./types.js";
+export declare const defaultKernelJobTasks: TaskDefinition<Record<string, unknown>, Record<string, unknown>>[];
+//# sourceMappingURL=builtin-job-tasks.d.ts.map

package/dist/kernel/jobs/builtin-job-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-job-tasks.d.ts","sourceRoot":"","sources":["../../../src/kernel/jobs/builtin-job-tasks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAChD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,EASA,CAAC"}

package/dist/kernel/jobs/builtin-job-tasks.js

@@ -0,0 +1,6 @@
+import { webhookDeliveryTask } from "../../modules/webhooks/tasks.js";
+import { staleJobReaperTask } from "./reaper.js";
+export const defaultKernelJobTasks = [
+    webhookDeliveryTask,
+    staleJobReaperTask,
+];

package/dist/kernel/jobs/drizzle-adapter.d.ts

@@ -0,0 +1,15 @@
+import type { DrizzleDatabase } from "../database/drizzle-db.js";
+import type { TaskDefinition } from "./types.js";
+import type { JobsAdapter, EnqueueOptions } from "./adapter.js";
+/**
+ * PostgreSQL-backed job queue adapter using the application's own database.
+ * Stores jobs in the `commerce_jobs` table. Supports concurrency keys
+ * and supersede semantics for deduplication.
+ */
+export declare class DrizzleJobsAdapter implements JobsAdapter {
+    private db;
+    private tasks;
+    constructor(db: DrizzleDatabase, tasks: Map<string, TaskDefinition>);
+    enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
+}
+//# sourceMappingURL=drizzle-adapter.d.ts.map

package/dist/kernel/jobs/drizzle-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle-adapter.d.ts","sourceRoot":"","sources":["../../../src/kernel/jobs/drizzle-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAIhE;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IAElD,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,KAAK;gBADL,EAAE,EAAE,eAAe,EACnB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAGtC,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC;CA0CnB"}

package/dist/kernel/jobs/drizzle-adapter.js

@@ -0,0 +1,46 @@
+import { eq, and } from "drizzle-orm";
+import { OrgResolutionError } from "../errors.js";
+import { commerceJobs } from "./schema.js";
+/**
+ * PostgreSQL-backed job queue adapter using the application's own database.
+ * Stores jobs in the `commerce_jobs` table. Supports concurrency keys
+ * and supersede semantics for deduplication.
+ */
+export class DrizzleJobsAdapter {
+    db;
+    tasks;
+    constructor(db, tasks) {
+        this.db = db;
+        this.tasks = tasks;
+    }
+    async enqueue(taskSlug, input, options) {
+        const organizationId = options.organizationId.trim();
+        if (!organizationId) {
+            throw new OrgResolutionError("Jobs enqueue requires a non-empty organizationId.");
+        }
+        // If supersedes is set, delete existing pending jobs with the same concurrency key
+        if (options.concurrencyKey && options.supersedes) {
+            await this.db
+                .delete(commerceJobs)
+                .where(and(eq(commerceJobs.concurrencyKey, options.concurrencyKey), eq(commerceJobs.status, "pending")));
+        }
+        // Look up task definition for default retry config
+        const task = this.tasks.get(taskSlug);
+        const maxAttempts = options.maxAttempts ?? task?.retries?.attempts ?? 1;
+        const rows = await this.db
+            .insert(commerceJobs)
+            .values({
+            organizationId,
+            taskSlug,
+            input,
+            queue: options.queue ?? "default",
+            maxAttempts,
+            waitUntil: options.delayMs
+                ? new Date(Date.now() + options.delayMs)
+                : null,
+            concurrencyKey: options.concurrencyKey ?? null,
+        })
+            .returning({ id: commerceJobs.id });
+        return rows[0].id;
+    }
+}

package/dist/kernel/jobs/reaper.d.ts

@@ -0,0 +1,12 @@
+import type { DbOrTx } from "../database/drizzle-db.js";
+import type { Logger } from "../hooks/types.js";
+import type { TaskDefinition } from "./types.js";
+export declare function getJobReapThresholdMs(): number;
+export declare function getJobsReaperIntervalMs(): number;
+export declare function runStaleJobReaper(db: DbOrTx, thresholdMs: number, logger: Logger): Promise<{
+    reapedCount: number;
+}>;
+export declare const staleJobReaperTask: TaskDefinition<Record<string, unknown>, {
+    reapedCount: number;
+}>;
+//# sourceMappingURL=reaper.d.ts.map

package/dist/kernel/jobs/reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaper.d.ts","sourceRoot":"","sources":["../../../src/kernel/jobs/reaper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,qBAAqB,IAAI,MAAM,CAK9C;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAKhD;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDlC;AAED,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAC7C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAYxB,CAAC"}