@unifiedcommerce/core 0.4.4 → 0.5.0

package/dist/interfaces/rest/schemas/webhooks.d.ts

@@ -0,0 +1,221 @@
+import { z } from "@hono/zod-openapi";
+export declare const CreateWebhookEndpointBodySchema: z.ZodObject<{
+    url: z.ZodString;
+    events: z.ZodArray<z.ZodString>;
+    secret: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const listWebhookEndpointsRoute: {
+    method: "get";
+    path: "/";
+    tags: string[];
+    summary: string;
+    responses: {
+        200: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    }, z.core.$strip>;
+                };
+            };
+            description: string;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const deleteWebhookEndpointRoute: {
+    method: "delete";
+    path: "/{id}";
+    tags: string[];
+    summary: string;
+    request: {
+        params: z.ZodObject<{
+            id: z.ZodUUID;
+        }, z.core.$strip>;
+    };
+    responses: {
+        400: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Business logic error.";
+        };
+        401: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Authentication required.";
+        };
+        403: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Insufficient permissions.";
+        };
+        404: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Resource not found.";
+        };
+        422: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Validation error.";
+        };
+        200: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        data: z.ZodObject<{
+                            deleted: z.ZodLiteral<true>;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            description: string;
+        };
+    };
+} & {
+    getRoutingPath(): "/:id";
+};
+export declare const createWebhookEndpointRoute: {
+    method: "post";
+    path: "/";
+    tags: string[];
+    summary: string;
+    description: string;
+    request: {
+        body: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        url: z.ZodString;
+                        events: z.ZodArray<z.ZodString>;
+                        secret: z.ZodOptional<z.ZodString>;
+                        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    }, z.core.$strip>;
+                };
+            };
+            required: true;
+        };
+    };
+    responses: {
+        400: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Business logic error.";
+        };
+        401: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Authentication required.";
+        };
+        403: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Insufficient permissions.";
+        };
+        404: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Resource not found.";
+        };
+        422: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Validation error.";
+        };
+        201: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    }, z.core.$strip>;
+                };
+            };
+            description: string;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/interfaces/rest/schemas/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/schemas/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAe,MAAM,mBAAmB,CAAC;AAKnD,eAAO,MAAM,+BAA+B;;;;;iBAKF,CAAC;AAI3C,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;CAWpC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiBrC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqBrC,CAAC"}

package/dist/interfaces/rest/schemas/webhooks.js

@@ -0,0 +1,62 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+// ─── Request Schema ──────────────────────────────────────────────────────────
+export const CreateWebhookEndpointBodySchema = z.object({
+    url: z.string().url().openapi({ example: "https://example.com/webhooks" }),
+    events: z.array(z.string()).openapi({ example: ["order.created", "order.fulfilled"] }),
+    secret: z.string().optional().openapi({ example: "whsec_abc123" }),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateWebhookEndpointRequest");
+// ─── Route Definitions ──────────────────────────────────────────────────────
+export const listWebhookEndpointsRoute = createRoute({
+    method: "get",
+    path: "/",
+    tags: ["Webhooks"],
+    summary: "List webhook endpoints",
+    responses: {
+        200: {
+            content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+            description: "Webhook endpoints",
+        },
+    },
+});
+export const deleteWebhookEndpointRoute = createRoute({
+    method: "delete",
+    path: "/{id}",
+    tags: ["Webhooks"],
+    summary: "Delete a webhook endpoint",
+    request: {
+        params: z.object({
+            id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+        }),
+    },
+    responses: {
+        200: {
+            content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } },
+            description: "Webhook endpoint deleted.",
+        },
+        ...errorResponses,
+    },
+});
+export const createWebhookEndpointRoute = createRoute({
+    method: "post",
+    path: "/",
+    tags: ["Webhooks"],
+    summary: "Create a webhook endpoint",
+    description: "Registers a new webhook endpoint that will receive event notifications.",
+    request: {
+        body: {
+            content: {
+                "application/json": { schema: CreateWebhookEndpointBodySchema },
+            },
+            required: true,
+        },
+    },
+    responses: {
+        201: {
+            content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+            description: "Webhook endpoint created.",
+        },
+        ...errorResponses,
+    },
+});

package/dist/interfaces/rest/utils.d.ts

@@ -0,0 +1,45 @@
+import { mapErrorToStatus } from "../../kernel/error-mapper.js";
+import type { Actor } from "../../auth/types.js";
+/**
+ * Shared Hono environment type for all sub-routers.
+ * Matches the Variables set by middleware in the top-level server app.
+ */
+export type AppEnv = {
+    Variables: {
+        actor: Actor | null;
+        requestId: string;
+        logger: unknown;
+        kernel: unknown;
+    };
+};
+export declare function parsePagination(query: Record<string, string | undefined>): {
+    page: number;
+    limit: number;
+};
+export declare function parseInclude(value?: string): Set<string>;
+/**
+ * Map an error to a safe client response. Internal errors are sanitized
+ * to prevent leaking SQL, schema, or stack trace details.
+ */
+export declare function mapErrorToResponse(error: unknown): {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export { mapErrorToStatus };
+/**
+ * Hono middleware that requires a specific permission on the actor.
+ * Returns 401 if no actor, 403 if permission denied.
+ * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
+ */
+export declare function requirePerm(permission: string): (c: {
+    get(key: string): unknown;
+    json(data: unknown, status: number): unknown;
+}, next: () => Promise<void>) => Promise<unknown>;
+export declare function parseSort(value?: string): {
+    field: "createdAt" | "updatedAt" | "slug";
+    direction: "asc" | "desc";
+} | undefined;
+export declare function isUUID(value: string): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/interfaces/rest/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/interfaces/rest/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,SAAS,EAAE;QACT,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH,CAAC;AAIF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAOA;AAED,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAO/F;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,IAC9B,GAAG;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,sBAkBxH;AAED,wBAAgB,SAAS,CACvB,KAAK,CAAC,EAAE,MAAM,GAEZ;IACF,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;IAC1C,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B,GACG,SAAS,CASZ;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7C"}

package/dist/interfaces/rest/utils.js

@@ -0,0 +1,71 @@
+import { mapErrorToStatus } from "../../kernel/error-mapper.js";
+import { toCommerceError } from "../../kernel/errors.js";
+const MAX_PAGE_LIMIT = 100;
+export function parsePagination(query) {
+    const page = Number.parseInt(query.page ?? "1", 10);
+    const limit = Number.parseInt(query.limit ?? "20", 10);
+    return {
+        page: Number.isFinite(page) && page > 0 ? page : 1,
+        limit: Math.min(MAX_PAGE_LIMIT, Number.isFinite(limit) && limit > 0 ? limit : 20),
+    };
+}
+export function parseInclude(value) {
+    if (!value)
+        return new Set();
+    return new Set(value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean));
+}
+/**
+ * Map an error to a safe client response. Internal errors are sanitized
+ * to prevent leaking SQL, schema, or stack trace details.
+ */
+export function mapErrorToResponse(error) {
+    const ce = toCommerceError(error);
+    if (ce.code === "INTERNAL_ERROR") {
+        // Sanitize internal errors -- do not expose raw messages to clients
+        return { error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } };
+    }
+    return { error: { code: ce.code, message: ce.message } };
+}
+export { mapErrorToStatus };
+/**
+ * Hono middleware that requires a specific permission on the actor.
+ * Returns 401 if no actor, 403 if permission denied.
+ * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
+ */
+export function requirePerm(permission) {
+    return async (c, next) => {
+        const actor = c.get("actor");
+        if (!actor) {
+            return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+        }
+        const perms = actor.permissions ?? [];
+        if (perms.includes(permission) || perms.includes("*:*")) {
+            await next();
+            return;
+        }
+        // Check resource-level wildcard (e.g., "catalog:*" matches "catalog:create")
+        const [resource] = permission.split(":");
+        if (resource && perms.includes(`${resource}:*`)) {
+            await next();
+            return;
+        }
+        return c.json({ error: { code: "FORBIDDEN", message: `Permission '${permission}' is required.` } }, 403);
+    };
+}
+export function parseSort(value) {
+    if (!value)
+        return undefined;
+    const [fieldRaw, directionRaw] = value.split(":");
+    const selectedField = fieldRaw ?? "createdAt";
+    const field = ["createdAt", "updatedAt", "slug"].includes(selectedField)
+        ? selectedField
+        : "createdAt";
+    const direction = directionRaw === "asc" ? "asc" : "desc";
+    return { field, direction };
+}
+export function isUUID(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}

package/dist/interfaces/rest/webhook-router.d.ts

@@ -0,0 +1,41 @@
+/**
+ * webhookRouter() — route builder for external webhook receivers.
+ *
+ * Unlike router() which uses UC authentication (.auth(), .permission()),
+ * webhookRouter() uses HMAC signature verification. This is for routes
+ * that receive callbacks from external services (Shopify, WooCommerce,
+ * Stripe, BNPL providers) that authenticate via provider-specific signatures.
+ *
+ * Provides typed access to kernel.services, kernel.database.db, and
+ * kernel.logger without casting through `unknown`.
+ *
+ * Usage:
+ *
+ *   import { webhookRouter } from "@unifiedcommerce/core";
+ *
+ *   export function createMyWebhookRoutes(kernel: Kernel) {
+ *     const { app, services, db, logger } = webhookRouter(kernel);
+ *
+ *     app.post("/product-updated", async (c) => {
+ *       const body = await c.req.json();
+ *       await services.catalog.update(body.id, { ... }, systemActor);
+ *       return c.json({ status: "ok" });
+ *     });
+ *
+ *     return app;
+ *   }
+ */
+import { Hono } from "hono";
+import type { Kernel } from "../../runtime/kernel.js";
+export interface WebhookRouterResult {
+    /** Raw Hono app — mount routes on this. No UC auth middleware attached. */
+    app: Hono;
+    /** Kernel services (catalog, inventory, orders, etc.). Typed properly. */
+    services: Kernel["services"];
+    /** Drizzle database instance for direct queries. */
+    db: Kernel["database"]["db"];
+    /** Structured Pino logger. */
+    logger: Kernel["logger"];
+}
+export declare function webhookRouter(kernel: Kernel): WebhookRouterResult;
+//# sourceMappingURL=webhook-router.d.ts.map

package/dist/interfaces/rest/webhook-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-router.d.ts","sourceRoot":"","sources":["../../../src/interfaces/rest/webhook-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,GAAG,EAAE,IAAI,CAAC;IACV,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7B,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAOjE"}

package/dist/interfaces/rest/webhook-router.js

@@ -0,0 +1,36 @@
+/**
+ * webhookRouter() — route builder for external webhook receivers.
+ *
+ * Unlike router() which uses UC authentication (.auth(), .permission()),
+ * webhookRouter() uses HMAC signature verification. This is for routes
+ * that receive callbacks from external services (Shopify, WooCommerce,
+ * Stripe, BNPL providers) that authenticate via provider-specific signatures.
+ *
+ * Provides typed access to kernel.services, kernel.database.db, and
+ * kernel.logger without casting through `unknown`.
+ *
+ * Usage:
+ *
+ *   import { webhookRouter } from "@unifiedcommerce/core";
+ *
+ *   export function createMyWebhookRoutes(kernel: Kernel) {
+ *     const { app, services, db, logger } = webhookRouter(kernel);
+ *
+ *     app.post("/product-updated", async (c) => {
+ *       const body = await c.req.json();
+ *       await services.catalog.update(body.id, { ... }, systemActor);
+ *       return c.json({ status: "ok" });
+ *     });
+ *
+ *     return app;
+ *   }
+ */
+import { Hono } from "hono";
+export function webhookRouter(kernel) {
+    return {
+        app: new Hono(),
+        services: kernel.services,
+        db: kernel.database.db,
+        logger: kernel.logger,
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { CompensationContext, Step } from "./types.js";
+import type { Result } from "../result.js";
+/**
+ * AnyStep erases the output type parameter so that heterogeneous step
+ * arrays can be passed to runCompensationChain without variance issues
+ * under exactOptionalPropertyTypes.
+ */
+type AnyStep<TInput> = Step<TInput, any>;
+/**
+ * Runs a list of steps in order. If any step fails, compensates all
+ * previously completed steps in reverse. Steps share the same input
+ * object (they may mutate it to enrich downstream steps, following
+ * the same pattern established by BeforeHooks).
+ *
+ * Compensation failures are logged but do not override the original error.
+ * A failed compensation is a separate operational concern that requires
+ * manual review — it should never mask the root cause returned to the caller.
+ */
+export declare function runCompensationChain<TInput>(steps: ReadonlyArray<AnyStep<TInput>>, input: TInput, ctx: CompensationContext): Promise<Result<TInput>>;
+export {};
+//# sourceMappingURL=executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/compensation/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;GAIG;AAEH,KAAK,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEzC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAC/C,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EACrC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,mBAAmB,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAmCzB"}

package/dist/kernel/compensation/executor.js

@@ -0,0 +1,36 @@
+/**
+ * Runs a list of steps in order. If any step fails, compensates all
+ * previously completed steps in reverse. Steps share the same input
+ * object (they may mutate it to enrich downstream steps, following
+ * the same pattern established by BeforeHooks).
+ *
+ * Compensation failures are logged but do not override the original error.
+ * A failed compensation is a separate operational concern that requires
+ * manual review — it should never mask the root cause returned to the caller.
+ */
+export async function runCompensationChain(steps, input, ctx) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches AnyStep output erasure
+    const completed = [];
+    for (const step of steps) {
+        const result = await step.run(input, ctx);
+        if (!result.ok) {
+            ctx.hook.logger.error(`Compensation chain failed at step "${step.id}". ` +
+                `Running ${completed.length} compensation(s).`, { error: result.error });
+            // Compensate in reverse order — most recently completed step first
+            for (const done of [...completed].reverse()) {
+                if (!done.step.compensate)
+                    continue;
+                try {
+                    await done.step.compensate(done.output, ctx);
+                    ctx.hook.logger.info(`Compensated step "${done.step.id}"`);
+                }
+                catch (compensateError) {
+                    ctx.hook.logger.error(`Compensation for step "${done.step.id}" failed. Manual review required.`, { compensateError });
+                }
+            }
+            return result;
+        }
+        completed.push({ step, output: result.value });
+    }
+    return { ok: true, value: input };
+}

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

@@ -0,0 +1,25 @@
+import type { TxContext } from "../database/tx-context.js";
+import type { HookContext } from "../hooks/types.js";
+import type { Result } from "../result.js";
+/**
+ * CompensationContext carries the transaction and hook context into
+ * both the run and compensate functions. Steps have access to services,
+ * the actor, and the logger through ctx.hook.
+ */
+export interface CompensationContext {
+    tx: TxContext | null;
+    hook: HookContext;
+}
+/**
+ * A Step is one unit of work in a compensation chain.
+ *
+ * TInput is the data the step receives (typically the shared checkout data object).
+ * TOutput is what the step produces. This same value is passed to compensate()
+ * so the compensate function has everything it needs to reverse the work.
+ */
+export interface Step<TInput, TOutput> {
+    id: string;
+    run: (input: TInput, ctx: CompensationContext) => Promise<Result<TOutput>>;
+    compensate?: (output: TOutput, ctx: CompensationContext) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kernel/compensation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,IAAI,CAAC,MAAM,EAAE,OAAO;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E"}

package/dist/kernel/compensation/types.js

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

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

@@ -0,0 +1,18 @@
+/**
+ * Database adapter interface for the commerce engine.
+ *
+ * Generic defaults to `unknown` so that any driver-specific adapter
+ * (postgres-js, PGlite, etc.) can implement it without type conflicts.
+ * Internal code narrows to `PluginDb` at the consumption site — see
+ * PluginContext in manifest.ts and createHookContext.
+ */
+export interface DatabaseAdapter<TDatabase = unknown, TTransaction = unknown> {
+    provider: string;
+    db: TDatabase;
+    transaction<T>(fn: (tx: TTransaction) => Promise<T>): Promise<T>;
+}
+export interface DatabaseConnectionFactoryInput {
+    adapter: DatabaseAdapter;
+}
+export declare function createDatabaseConnection(input: DatabaseConnectionFactoryInput): DatabaseAdapter;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,GAAG,OAAO,EAAE,YAAY,GAAG,OAAO;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,SAAS,CAAC;IACd,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,8BAA8B,GAAG,eAAe,CAE/F"}

package/dist/kernel/database/adapter.js

@@ -0,0 +1,3 @@
+export function createDatabaseConnection(input) {
+    return input.adapter;
+}

package/dist/kernel/database/drizzle-db.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Drizzle Database Type Definitions
+ *
+ * This module provides type-safe, driver-agnostic database access for
+ * PostgreSQL repositories.
+ *
+ * We use `PgDatabase` from `drizzle-orm/pg-core` — the base class that all
+ * PostgreSQL drivers extend (postgres-js, pglite, node-postgres, bun-sql).
+ * This means:
+ *
+ * - Repositories accept any PG driver without casts
+ * - PGlite in tests and postgres-js in production use the same type
+ * - Row types are fully inferred from pgTable schema definitions
+ * - No coupling to any specific driver package
+ */
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import * as schema from "./schema.js";
+/**
+ * Combined schema type for type inference
+ */
+export type Schema = typeof schema;
+/**
+ * Driver-agnostic PostgreSQL database instance with full schema type
+ * information.
+ *
+ * Both `PostgresJsDatabase<Schema>` and `PgliteDatabase<Schema>` are
+ * assignable to this type, so repositories work identically in production
+ * and tests without any casts.
+ */
+export type DrizzleDatabase = PgDatabase<PgQueryResultHKT, Schema>;
+/**
+ * Transaction type extracted from the database type.
+ * Used when operating within a transaction context.
+ *
+ * This type is derived from the transaction callback parameter:
+ * db.transaction(async (tx) => { ... })
+ *                       ^^-- This is DrizzleTx
+ */
+export type DrizzleTx = Parameters<Parameters<DrizzleDatabase["transaction"]>[0]>[0];
+/**
+ * Union type for database or transaction - repositories can accept either.
+ * Both have the same query builder interface.
+ */
+export type DbOrTx = DrizzleDatabase | DrizzleTx;
+/**
+ * Re-export schema for convenience
+ */
+export { schema };
+//# sourceMappingURL=drizzle-db.d.ts.map

package/dist/kernel/database/drizzle-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle-db.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/drizzle-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAChC,UAAU,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9C,CAAC,CAAC,CAAC,CAAC;AAEL;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;AAEjD;;GAEG;AACH,OAAO,EAAE,MAAM,EAAE,CAAC"}