@porulle/core 0.1.0

package/dist/interfaces/rest/router.js

@@ -0,0 +1,259 @@
+/**
+ * Type-safe route builder for UnifiedCommerce plugins.
+ *
+ * Wraps @hono/zod-openapi's createRoute() with sensible defaults:
+ * - /api prefix prepended automatically
+ * - Error responses (400, 401, 403, 404, 422) injected
+ * - Path params auto-detected from {id} patterns
+ * - POST defaults to 201, others to 200
+ * - .auth() enforces login, .permission() enforces specific scope
+ * - Handler receives { input, params, query, actor, services, db, logger }
+ * - Return value auto-wrapped in { data: result }
+ * - Errors auto-caught and mapped to { error: { code, message } }
+ *
+ * @example
+ * ```typescript
+ * import { router, z } from "@porulle/core";
+ *
+ * const vendors = router("Vendors", "/marketplace/vendors");
+ *
+ * vendors.get("/").summary("List").auth().handler(async ({ actor, services }) => {
+ *   return services.vendor.list();
+ * });
+ *
+ * vendors.post("/").summary("Create").permission("marketplace:admin").input(Schema)
+ *   .handler(async ({ input, services }) => services.vendor.create(input));
+ * ```
+ */
+import { createRoute, z } from "@hono/zod-openapi";
+import { ErrorSchema } from "./schemas/shared.js";
+import { mapErrorToResponse, mapErrorToStatus } from "./utils.js";
+import { createScopedDb } from "../../kernel/database/scoped-db.js";
+import { resolveOrgId } from "../../auth/org.js";
+// ─── Shared OpenAPI Error Responses ──────────────────────────────────────────
+const errorResponses = {
+    400: { content: { "application/json": { schema: ErrorSchema } }, description: "Bad request." },
+    401: { content: { "application/json": { schema: ErrorSchema } }, description: "Unauthorized." },
+    403: { content: { "application/json": { schema: ErrorSchema } }, description: "Forbidden." },
+    404: { content: { "application/json": { schema: ErrorSchema } }, description: "Not found." },
+    422: { content: { "application/json": { schema: ErrorSchema } }, description: "Validation error." },
+};
+function wrapJson(schema) {
+    return { content: { "application/json": { schema } }, description: "Success" };
+}
+function extractPathParams(path) {
+    return [...path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+}
+// ─── Route Chain ─────────────────────────────────────────────────────────────
+class RouteChain {
+    method;
+    fullPath;
+    tag;
+    routesList;
+    pluginCtx;
+    _summary = "";
+    _description = "";
+    _input;
+    _query;
+    _params;
+    _requireAuth = false;
+    _requiredPermission;
+    constructor(method, fullPath, tag, routesList, pluginCtx) {
+        this.method = method;
+        this.fullPath = fullPath;
+        this.tag = tag;
+        this.routesList = routesList;
+        this.pluginCtx = pluginCtx;
+        const paramNames = extractPathParams(fullPath);
+        if (paramNames.length > 0) {
+            this._params = z.object(Object.fromEntries(paramNames.map((n) => [n, z.uuid()])));
+        }
+    }
+    /** Set the OpenAPI summary for this route. */
+    summary(text) { this._summary = text; return this; }
+    /** Set the OpenAPI description for this route. */
+    description(text) { this._description = text; return this; }
+    /** Set the request body schema. Only for POST/PATCH/PUT. */
+    input(schema) { this._input = schema; return this; }
+    /** Set the query parameter schema. */
+    query(schema) { this._query = schema; return this; }
+    /** Override the auto-detected path parameter schema. */
+    params(schema) { this._params = schema; return this; }
+    /**
+     * Require authentication. The handler's `actor` is guaranteed non-null.
+     * Returns 401 if the request has no authenticated actor.
+     */
+    auth() { this._requireAuth = true; return this; }
+    /**
+     * Require a specific permission scope. Implies .auth().
+     * Returns 401 if not authenticated, 403 if the actor lacks the permission.
+     *
+     * Permission scopes should be declared in the plugin's `permissions` manifest.
+     * The wildcard `*:*` always passes.
+     *
+     * @example
+     * ```typescript
+     * vendors.post("/").permission("marketplace:admin").handler(...)
+     * wishlist.post("/").permission("wishlist:write").handler(...)
+     * ```
+     */
+    permission(scope) {
+        this._requireAuth = true;
+        this._requiredPermission = scope;
+        return this;
+    }
+    /**
+     * Register the handler for this route.
+     *
+     * The handler receives a context object with typed input, params, query,
+     * actor, services, and db. Return data is auto-wrapped in { data: result }.
+     * Thrown errors are auto-caught and mapped to { error: { code, message } }.
+     */
+    handler(fn) {
+        const request = {};
+        if (this._input)
+            request.body = { ...wrapJson(this._input), required: true };
+        if (this._query)
+            request.query = this._query;
+        if (this._params)
+            request.params = this._params;
+        const status = this.method === "post" ? 201 : 200;
+        const routeConfig = createRoute({
+            method: this.method,
+            path: this.fullPath,
+            tags: [this.tag],
+            summary: this._summary,
+            ...(this._description ? { description: this._description } : {}),
+            ...(Object.keys(request).length > 0 ? { request } : {}),
+            responses: {
+                [status]: wrapJson(z.object({ data: z.any() })),
+                ...errorResponses,
+            },
+        });
+        const inputSchema = this._input;
+        const querySchema = this._query;
+        const pathParams = extractPathParams(this.fullPath);
+        const successStatus = status;
+        const requireAuth = this._requireAuth;
+        const requiredPermission = this._requiredPermission;
+        const pluginCtx = this.pluginCtx;
+        const honoHandler = async (c) => {
+            const ctx = c;
+            try {
+                // ─── Auth + Permission Check ─────────────────────────────────
+                // .permission() implies .auth() — both are enforced here.
+                // Order: auth first (401), then permission (403).
+                const actor = ctx.get("actor");
+                if ((requireAuth || requiredPermission) && !actor) {
+                    return ctx.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+                }
+                if (requiredPermission) {
+                    const perms = actor?.permissions ?? [];
+                    if (!perms.includes(requiredPermission) && !perms.includes("*:*")) {
+                        return ctx.json({
+                            error: { code: "FORBIDDEN", message: `Permission '${requiredPermission}' is required.` },
+                        }, 403);
+                    }
+                }
+                // ─── Extract context ─────────────────────────────────────────
+                const params = {};
+                for (const name of pathParams) {
+                    params[name] = ctx.req.param(name);
+                }
+                // Use plugin context if provided (plugin routes), fallback to kernel on Hono context (core routes)
+                const kernel = pluginCtx ?? ctx.get("kernel");
+                // Scope the database to the actor's organization.
+                // Plugin route handlers receive a db that auto-filters queries
+                // and auto-stamps inserts with the actor's organizationId.
+                const rawDb = kernel?.db;
+                const orgId = resolveOrgId(actor);
+                const scopedDb = rawDb ? createScopedDb(rawDb, orgId) : rawDb;
+                const handlerCtx = {
+                    input: inputSchema ? ctx.req.valid("json") : undefined,
+                    query: querySchema ? ctx.req.valid("query") : {},
+                    params,
+                    actor,
+                    orgId,
+                    services: kernel?.services ?? {},
+                    db: scopedDb,
+                    logger: ctx.get("logger"),
+                    requestId: ctx.get("requestId") ?? "",
+                    raw: c,
+                };
+                const result = await fn(handlerCtx);
+                if (result === undefined || result === null) {
+                    return ctx.json({ data: null }, successStatus);
+                }
+                return ctx.json({ data: result }, successStatus);
+            }
+            catch (error) {
+                try {
+                    return ctx.json(mapErrorToResponse(error), mapErrorToStatus(error));
+                }
+                catch {
+                    // Fallback if mapErrorToResponse/mapErrorToStatus themselves throw
+                    return ctx.json({ error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } }, 500);
+                }
+            }
+        };
+        this.routesList.push({ openapi: routeConfig, handler: honoHandler });
+    }
+}
+// ─── Router ──────────────────────────────────────────────────────────────────
+class RouterImpl {
+    tag;
+    _routes = [];
+    _prefix;
+    _pluginCtx;
+    constructor(tag, prefix, pluginCtx) {
+        this.tag = tag;
+        // Normalize: ensure /api prefix, strip trailing slash
+        let p = prefix.startsWith("/api") ? prefix : `/api${prefix}`;
+        p = p.replace(/\/+$/, ""); // remove trailing slashes
+        this._prefix = p;
+        // If plugin context is provided, wire services + db for handler access
+        if (pluginCtx) {
+            this._pluginCtx = {
+                services: pluginCtx.services ?? {},
+                db: pluginCtx.database?.db,
+            };
+        }
+    }
+    /** @internal — used by RouteChain to wire plugin context into handlers */
+    get pluginContext() { return this._pluginCtx; }
+    resolvePath(path) {
+        // "/" means "the resource root" → just the prefix, no trailing slash
+        if (path === "/")
+            return this._prefix;
+        return (this._prefix + path).replace(/\/\/+/g, "/");
+    }
+    get(path) { return new RouteChain("get", this.resolvePath(path), this.tag, this._routes, this._pluginCtx); }
+    post(path) { return new RouteChain("post", this.resolvePath(path), this.tag, this._routes, this._pluginCtx); }
+    patch(path) { return new RouteChain("patch", this.resolvePath(path), this.tag, this._routes, this._pluginCtx); }
+    delete(path) { return new RouteChain("delete", this.resolvePath(path), this.tag, this._routes, this._pluginCtx); }
+    put(path) { return new RouteChain("put", this.resolvePath(path), this.tag, this._routes, this._pluginCtx); }
+    /** Returns all registered routes as PluginRouteRegistration[] */
+    routes() { return this._routes; }
+}
+/**
+ * Create a typed route group for plugin routes.
+ *
+ * @param tag — OpenAPI tag for Swagger UI grouping
+ * @param prefix — Path prefix without /api (e.g., "/marketplace/vendors"). /api is prepended automatically.
+ * @param ctx — Optional PluginContext. When provided, handler receives { services, db } from the plugin.
+ *
+ * @example
+ * ```typescript
+ * // In plugin routes callback:
+ * routes: (ctx) => {
+ *   const r = router("Vendors", "/marketplace/vendors", ctx);
+ *   r.get("/").summary("List").handler(async ({ services }) => {
+ *     return (services as VendorServices).vendor.list();
+ *   });
+ *   return r.routes();
+ * }
+ * ```
+ */
+export function router(tag, prefix, ctx) {
+    return new RouterImpl(tag, prefix, ctx);
+}

package/dist/interfaces/rest/routes/admin/compensation-failures.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import { type AppEnv } from "../../utils.js";
+export declare function compensationFailureAdminRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=compensation-failures.d.ts.map

package/dist/interfaces/rest/routes/admin/compensation-failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compensation-failures.d.ts","sourceRoot":"","sources":["../../../../../src/interfaces/rest/routes/admin/compensation-failures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAU5D,OAAO,EAAE,KAAK,MAAM,EAAwC,MAAM,gBAAgB,CAAC;AAuDnF,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,gCA6F5D"}

package/dist/interfaces/rest/routes/admin/compensation-failures.js

@@ -0,0 +1,114 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { assertPermission } from "../../../../auth/permissions.js";
+import { resolveOrgId } from "../../../../auth/org.js";
+import { CommerceValidationError } from "../../../../kernel/errors.js";
+import { listCompensationFailuresRoute, resolveCompensationFailureRoute, } from "../../schemas/compensation-failures.js";
+import { mapErrorToResponse, mapErrorToStatus } from "../../utils.js";
+function toIso(d) {
+    if (d == null)
+        return null;
+    return d.toISOString();
+}
+function digestFailure(row) {
+    return {
+        id: row.id,
+        organizationId: row.organizationId,
+        correlationId: row.correlationId,
+        chainName: row.chainName,
+        stepName: row.stepName,
+        originalError: {
+            message: row.originalError.message,
+            ...(row.originalError.code != null
+                ? { code: row.originalError.code }
+                : {}),
+        },
+        compensationError: {
+            message: row.compensationError.message,
+        },
+        occurredAt: row.occurredAt instanceof Date
+            ? row.occurredAt.toISOString()
+            : String(row.occurredAt ?? ""),
+        resolvedAt: toIso(row.resolvedAt ?? null),
+        resolvedBy: row.resolvedBy ?? null,
+        resolutionNotes: row.resolutionNotes ?? null,
+    };
+}
+function parseResolvedFilter(raw) {
+    const v = raw ?? "false";
+    if (v === "all")
+        return { ok: true, value: undefined };
+    if (v === "true")
+        return { ok: true, value: true };
+    if (v === "false")
+        return { ok: true, value: false };
+    return { ok: false };
+}
+export function compensationFailureAdminRoutes(kernel) {
+    const router = new OpenAPIHono();
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(listCompensationFailuresRoute, async (c) => {
+        const actor = c.get("actor");
+        assertPermission(actor, "compensation:admin");
+        const orgId = resolveOrgId(actor);
+        const resolvedParsed = parseResolvedFilter(c.req.query("resolved"));
+        if (!resolvedParsed.ok) {
+            return c.json(mapErrorToResponse(new CommerceValidationError('Query "resolved" must be true, false, or all.')), 422);
+        }
+        const limitRaw = c.req.query("limit");
+        const offsetRaw = c.req.query("offset");
+        const limitParsed = limitRaw != null ? Number(limitRaw) : 50;
+        const offsetParsed = offsetRaw != null ? Number(offsetRaw) : 0;
+        const limit = Math.min(200, Math.max(1, Number.isFinite(limitParsed) ? limitParsed : 50));
+        const offset = Math.max(0, Number.isFinite(offsetParsed) ? offsetParsed : 0);
+        const listed = await kernel.services.compensationFailures.list({
+            organizationId: orgId,
+            limit,
+            offset,
+            ...(resolvedParsed.value !== undefined
+                ? { resolved: resolvedParsed.value }
+                : {}),
+        });
+        if (!listed.ok) {
+            return c.json(mapErrorToResponse(listed.error), mapErrorToStatus(listed.error));
+        }
+        return c.json({
+            items: listed.value.items.map(digestFailure),
+            total: listed.value.total,
+            limit,
+            offset,
+        });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(resolveCompensationFailureRoute, async (c) => {
+        const actor = c.get("actor");
+        assertPermission(actor, "compensation:admin");
+        const orgId = resolveOrgId(actor);
+        const id = c.req.param("id");
+        const body = c.req.valid("json");
+        const found = await kernel.services.compensationFailures.findById(id);
+        if (!found.ok) {
+            return c.json(mapErrorToResponse(found.error), mapErrorToStatus(found.error));
+        }
+        const row = found.value;
+        if (!row) {
+            return c.json({ error: { code: "NOT_FOUND", message: "Compensation failure not found." } }, 404);
+        }
+        if (row.organizationId !== orgId) {
+            return c.json({ error: { code: "FORBIDDEN", message: "Compensation failure belongs to another organization." } }, 403);
+        }
+        if (row.resolvedAt != null) {
+            return c.json({ error: { code: "CONFLICT", message: "Compensation failure is already resolved." } }, 409);
+        }
+        const resolved = await kernel.services.compensationFailures.markResolved({
+            id,
+            organizationId: orgId,
+            resolvedBy: actor.userId,
+            ...(body.notes !== undefined ? { notes: body.notes } : {}),
+        });
+        if (!resolved.ok) {
+            return c.json(mapErrorToResponse(resolved.error), mapErrorToStatus(resolved.error));
+        }
+        return c.json({ failure: digestFailure(resolved.value) });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/admin/permissions.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import type { AppEnv } from "../../utils.js";
+export declare function adminPermissionsRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/interfaces/rest/routes/admin/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../../../../src/interfaces/rest/routes/admin/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAI5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAa7C,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,gCAkBpD"}

package/dist/interfaces/rest/routes/admin/permissions.js

@@ -0,0 +1,28 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { assertPermission } from "../../../../auth/permissions.js";
+import { listAdminPermissionsRoute } from "../../schemas/admin-permissions.js";
+function flattenCoreRolePermissions(config) {
+    const roles = config.auth?.roles ?? {};
+    const set = new Set();
+    for (const def of Object.values(roles)) {
+        for (const p of def.permissions) {
+            set.add(p);
+        }
+    }
+    return [...set].sort((a, b) => a.localeCompare(b));
+}
+export function adminPermissionsRoutes(kernel) {
+    const router = new OpenAPIHono();
+    router.openapi(listAdminPermissionsRoute, (c) => {
+        const actor = c.get("actor");
+        assertPermission(actor, "admin");
+        const core = flattenCoreRolePermissions(kernel.config);
+        const plugin = kernel.pluginPermissions.map((p) => ({
+            scope: p.scope,
+            description: p.description,
+            plugin: p.pluginId ?? "(unknown)",
+        }));
+        return c.json({ core, plugin });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/admin-jobs.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv } from "../utils.js";
+export declare function adminJobRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=admin-jobs.d.ts.map

package/dist/interfaces/rest/routes/admin-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-jobs.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/admin-jobs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,EAAE,KAAK,MAAM,EAAe,MAAM,aAAa,CAAC;AAKvD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCA8C5C"}

package/dist/interfaces/rest/routes/admin-jobs.js

@@ -0,0 +1,48 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { eq, and, desc } from "drizzle-orm";
+import { commerceJobs } from "../../../kernel/jobs/schema.js";
+import { listFailedJobsRoute, retryJobRoute } from "../schemas/admin-jobs.js";
+import { requirePerm } from "../utils.js";
+import { resolveOrgId } from "../../../auth/org.js";
+export function adminJobRoutes(kernel) {
+    const router = new OpenAPIHono();
+    const db = kernel.database.db;
+    router.use("/jobs/failed", requirePerm("jobs:admin"));
+    router.openapi(listFailedJobsRoute, async (c) => {
+        const actor = c.get("actor");
+        const orgId = resolveOrgId(actor);
+        const limit = Math.min(Number(c.req.query("limit") ?? "50"), 100);
+        const conditions = [eq(commerceJobs.status, "failed")];
+        // Scope to org unless wildcard admin
+        if (!actor?.permissions?.includes("*:*")) {
+            conditions.push(eq(commerceJobs.organizationId, orgId));
+        }
+        const failed = await db.select()
+            .from(commerceJobs)
+            .where(and(...conditions))
+            .orderBy(desc(commerceJobs.completedAt))
+            .limit(limit);
+        return c.json({ data: failed });
+    });
+    router.use("/jobs/:id/retry", requirePerm("jobs:admin"));
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(retryJobRoute, async (c) => {
+        const actor = c.get("actor");
+        const orgId = resolveOrgId(actor);
+        const id = c.req.param("id");
+        const conditions = [eq(commerceJobs.id, id)];
+        // Scope to org unless wildcard admin
+        if (!actor?.permissions?.includes("*:*")) {
+            conditions.push(eq(commerceJobs.organizationId, orgId));
+        }
+        const result = await db.update(commerceJobs)
+            .set({ status: "pending", attempts: 0, error: null, waitUntil: null, updatedAt: new Date() })
+            .where(and(...conditions))
+            .returning();
+        if (result.length === 0) {
+            return c.json({ error: { code: "NOT_FOUND", message: "Job not found." } }, 404);
+        }
+        return c.json({ data: { retried: true } });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/audit.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv } from "../utils.js";
+export declare function auditRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=audit.d.ts.map

package/dist/interfaces/rest/routes/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,KAAK,MAAM,EAAe,MAAM,aAAa,CAAC;AAGvD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,gCA2CzC"}

package/dist/interfaces/rest/routes/audit.js

@@ -0,0 +1,43 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { listAuditRoute, listEntityAuditRoute } from "../schemas/audit.js";
+import { requirePerm } from "../utils.js";
+import { resolveOrgId } from "../../../auth/org.js";
+export function auditRoutes(kernel) {
+    const router = new OpenAPIHono();
+    /**
+     * GET /api/audit
+     * List audit entries with optional filters.
+     */
+    router.use("/", requirePerm("audit:read"));
+    router.openapi(listAuditRoute, async (c) => {
+        const actor = c.get("actor");
+        const orgId = resolveOrgId(actor);
+        const entries = await kernel.services.audit.list({
+            organizationId: orgId,
+            entityType: c.req.query("entityType"),
+            entityId: c.req.query("entityId"),
+            event: c.req.query("event"),
+            actorId: c.req.query("actorId"),
+            from: c.req.query("from") ? new Date(c.req.query("from")) : undefined,
+            to: c.req.query("to") ? new Date(c.req.query("to")) : undefined,
+            limit: c.req.query("limit") ? Number(c.req.query("limit")) : 50,
+        });
+        return c.json({ data: entries });
+    });
+    /**
+     * GET /api/audit/:entityType/:entityId
+     * List audit history for a specific entity.
+     */
+    router.use("/:entityType/:entityId", requirePerm("audit:read"));
+    router.openapi(listEntityAuditRoute, async (c) => {
+        const actor = c.get("actor");
+        const orgId = resolveOrgId(actor);
+        const entries = await kernel.services.audit.listForEntity({
+            organizationId: orgId,
+            entityType: c.req.param("entityType"),
+            entityId: c.req.param("entityId"),
+        });
+        return c.json({ data: entries });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/carts.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv } from "../utils.js";
+export declare function cartRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=carts.d.ts.map

package/dist/interfaces/rest/routes/carts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carts.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/carts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,EAAE,KAAK,MAAM,EAAwC,MAAM,aAAa,CAAC;AAEhF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,gCA6FxC"}

package/dist/interfaces/rest/routes/carts.js

@@ -0,0 +1,61 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute } from "../schemas/carts.js";
+import { mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+export function cartRoutes(kernel) {
+    const router = new OpenAPIHono();
+    // @ts-expect-error -- openapi() enforces strict response typing but our handler
+    // returns union responses (201 | 400 | 422). The route definition documents the
+    // contract; the handler returns dynamic status.
+    router.openapi(createCartRoute, async (c) => {
+        const actor = c.get("actor");
+        const result = await kernel.services.cart.create(c.req.valid("json"), actor);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value }, 201);
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getCartRoute, async (c) => {
+        const actor = c.get("actor");
+        // Guest carts are gated by the cart secret; clients pass it as either
+        // ?secret=... or X-Cart-Secret. Customer carts ignore the secret and
+        // require ownership instead.
+        const secretParam = c.req.query("secret");
+        const secretHeader = c.req.header("x-cart-secret") ?? c.req.header("X-Cart-Secret");
+        const secret = secretParam ?? secretHeader ?? undefined;
+        const result = await kernel.services.cart.getById(c.req.param("id"), actor, undefined, secret);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    // @ts-expect-error -- openapi() enforces strict response typing but our handler
+    // returns union responses (201 | 400 | 422). The route definition documents the
+    // contract; the handler returns dynamic status.
+    router.openapi(addCartItemRoute, async (c) => {
+        const result = await kernel.services.cart.addItem({ ...c.req.valid("json"), cartId: c.req.param("id") }, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value }, 201);
+    });
+    // @ts-expect-error -- openapi() enforces strict response typing but our handler
+    // returns union responses (200 | 400 | 422). The route definition documents the
+    // contract; the handler returns dynamic status.
+    router.openapi(updateCartItemQuantityRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.cart.updateQuantity({
+            cartId: c.req.param("id"),
+            itemId: c.req.param("itemId"),
+            quantity: body.quantity,
+        }, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(removeCartItemRoute, async (c) => {
+        const result = await kernel.services.cart.removeItem(c.req.param("id"), c.req.param("itemId"), c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: { deleted: true } });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/catalog.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv } from "../utils.js";
+export declare function catalogRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/interfaces/rest/routes/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AA4CzD,OAAO,EACL,KAAK,MAAM,EAMZ,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,gCAqc3C"}