@unifiedcommerce/core 0.4.4 → 0.5.0

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

@@ -0,0 +1,216 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { checkoutRoute } from "../schemas/checkout.js";
+import { applyPromotionCodes, authorizePayment, calculateShipping, calculateTax, checkInventoryAvailability, completeCheckout, recordAnalyticsEvent, resolveCurrentPrices, validateCartNotEmpty, validatePaymentMethod, } from "../../../hooks/checkout.js";
+import { runAfterHooks, runBeforeHooks } from "../../../kernel/hooks/executor.js";
+import { createHookContext } from "../../../kernel/hooks/create-context.js";
+import { mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { isCommerceError } from "../../../kernel/errors.js";
+import { makeId } from "../../../utils/id.js";
+export function checkoutRoutes(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 defaultHook handles Zod validation; the handler returns dynamic status.
+    router.openapi(checkoutRoute, async (c) => {
+        const body = c.req.valid("json");
+        const actor = c.get("actor");
+        const checkoutData = {
+            checkoutId: makeId(),
+            cartId: body.cartId,
+            currency: body.currency ?? "USD",
+            paymentMethodId: body.paymentMethodId,
+            lineItems: [],
+            subtotal: 0,
+            discountTotal: 0,
+            taxTotal: 0,
+            shippingTotal: 0,
+            total: 0,
+            ...(body.customerId !== undefined ? { customerId: body.customerId } : {}),
+            ...(body.customerGroupIds !== undefined
+                ? { customerGroupIds: body.customerGroupIds }
+                : {}),
+            ...(body.promotionCodes !== undefined
+                ? { promotionCodes: body.promotionCodes }
+                : {}),
+            ...(body.shippingAddress != null
+                ? {
+                    shippingAddress: {
+                        line1: body.shippingAddress.line1,
+                        city: body.shippingAddress.city,
+                        postalCode: body.shippingAddress.postalCode,
+                        country: body.shippingAddress.country,
+                        ...(body.shippingAddress.line2 != null ? { line2: body.shippingAddress.line2 } : {}),
+                        ...(body.shippingAddress.state != null ? { state: body.shippingAddress.state } : {}),
+                    },
+                }
+                : {}),
+        };
+        // ── Phase 1: Validate & Calculate (inside DB transaction — fast SQL only) ──
+        const validationHooks = [
+            validateCartNotEmpty,
+            resolveCurrentPrices,
+            checkInventoryAvailability,
+            applyPromotionCodes,
+            calculateTax,
+            calculateShipping,
+            ...kernel.hooks.resolve("checkout.beforePayment"),
+            validatePaymentMethod,
+        ];
+        // ── Phase 2: Payment Authorization (outside transaction — external API call) ──
+        const paymentHooks = [
+            authorizePayment,
+            ...kernel.hooks.resolve("checkout.beforeCreate"),
+        ];
+        const afterHooks = [
+            completeCheckout,
+            recordAnalyticsEvent,
+            ...kernel.hooks.resolve("checkout.afterCreate"),
+        ];
+        const context = createHookContext({
+            actor,
+            logger: kernel.logger,
+            services: kernel.services,
+            context: { moduleName: "checkout" },
+            origin: "rest",
+            kernel: { database: { db: kernel.database.db } },
+        });
+        try {
+            // Phase 1: DB transaction for validation — releases connection immediately after
+            const validated = await kernel.database.transaction(async (_tx) => {
+                context.tx = _tx;
+                return runBeforeHooks(validationHooks, checkoutData, "create", context);
+            });
+            // Phase 2: Payment authorization — NO DB connection held while calling Stripe/etc.
+            // If Stripe takes 5s, the DB connection pool is not affected.
+            context.tx = null;
+            const processed = await runBeforeHooks(paymentHooks, validated, "create", context);
+            // Resolve customer profile UUID from customerId (may be a profile UUID or a Better Auth user_id)
+            let customerUuid = undefined;
+            if (processed.customerId) {
+                const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+                if (uuidRe.test(processed.customerId)) {
+                    // Looks like a profile UUID — try direct lookup (no auto-create)
+                    const byIdResult = await kernel.services.customers.getById(processed.customerId, actor);
+                    if (byIdResult.ok) {
+                        customerUuid = byIdResult.value.id;
+                    }
+                }
+                if (!customerUuid) {
+                    // Fall back to user_id lookup (auto-creates customer profile if needed)
+                    const byUserIdResult = await kernel.services.customers.getByUserId(processed.customerId, actor);
+                    if (byUserIdResult.ok) {
+                        customerUuid = byUserIdResult.value.id;
+                    }
+                }
+                // If both lookups fail, we still allow guest checkout (customerUuid remains undefined)
+            }
+            const orderPayload = {
+                currency: processed.currency,
+                subtotal: processed.subtotal,
+                taxTotal: processed.taxTotal,
+                shippingTotal: processed.shippingTotal,
+                discountTotal: processed.discountTotal,
+                grandTotal: processed.total,
+                paymentIntentId: processed.paymentIntentId,
+                paymentMethodId: processed.paymentMethodId,
+                metadata: {
+                    // H2 fix: Merge hook-injected metadata (e.g., BNPL fee) before core fields
+                    ...(typeof processed.metadata === "object" && processed.metadata !== null
+                        ? processed.metadata
+                        : {}),
+                    cartId: processed.cartId,
+                    paymentIntentId: processed.paymentIntentId,
+                    checkoutId: processed.checkoutId,
+                    promotionCodes: processed.promotionCodes,
+                    appliedPromotions: processed.appliedPromotions,
+                    shippingAddress: processed.shippingAddress,
+                },
+                lineItems: processed.lineItems.map((lineItem) => {
+                    const payload = {
+                        entityId: lineItem.entityId,
+                        entityType: lineItem.entityType ?? "product",
+                        title: lineItem.title ?? lineItem.entityId,
+                        quantity: lineItem.quantity,
+                        unitPrice: lineItem.resolvedUnitPrice ?? 0,
+                        totalPrice: lineItem.resolvedTotal ?? 0,
+                    };
+                    return lineItem.variantId !== undefined
+                        ? { ...payload, variantId: lineItem.variantId }
+                        : payload;
+                }),
+                ...(customerUuid !== undefined
+                    ? { customerId: customerUuid }
+                    : {}),
+            };
+            const order = await kernel.services.orders.create(orderPayload, actor);
+            if (!order.ok) {
+                return c.json(mapErrorToResponse(order.error), mapErrorToStatus(order.error));
+            }
+            if (order.ok && (processed.appliedPromotions?.length ?? 0) > 0) {
+                await kernel.services.promotions.recordUsage({
+                    promotions: processed.appliedPromotions ?? [],
+                    orderId: order.value.id,
+                    ...(customerUuid !== undefined
+                        ? { customerId: customerUuid }
+                        : {}),
+                });
+            }
+            if (order.ok) {
+                await kernel.services.tax.reportTransaction({
+                    transactionId: order.value.id,
+                    transactionDate: new Date(),
+                    currency: processed.currency,
+                    amount: processed.subtotal -
+                        processed.discountTotal +
+                        processed.shippingTotal,
+                    shipping: processed.shippingTotal,
+                    salesTax: processed.taxTotal,
+                    lineItems: processed.lineItems.map((lineItem, index) => ({
+                        id: lineItem.id ?? `${order.value.id}-${index + 1}`,
+                        entityId: lineItem.entityId,
+                        description: lineItem.title ?? lineItem.entityId,
+                        quantity: lineItem.quantity,
+                        unitPrice: lineItem.resolvedUnitPrice ?? 0,
+                        ...(lineItem.discountAmount !== undefined
+                            ? { discount: lineItem.discountAmount }
+                            : {}),
+                    })),
+                    ...(customerUuid !== undefined
+                        ? { customerId: customerUuid }
+                        : {}),
+                    ...(processed.shippingAddress !== undefined
+                        ? { toAddress: processed.shippingAddress }
+                        : {}),
+                });
+            }
+            // Stash paymentMethodId for completeCheckout compensation chain
+            context.context.paymentMethodId = processed.paymentMethodId;
+            const afterReport = await runAfterHooks(afterHooks, null, order.value, "create", context);
+            await kernel.services.cart.markAsCheckedOut(body.cartId, actor);
+            return c.json({
+                data: {
+                    ...order.value,
+                    // Stripe Elements requires clientSecret to collect card details on the frontend
+                    ...(processed.paymentClientSecret
+                        ? { paymentClientSecret: processed.paymentClientSecret }
+                        : {}),
+                },
+                meta: afterReport.hasErrors
+                    ? { hookErrors: afterReport.errors }
+                    : undefined,
+            }, 201);
+        }
+        catch (error) {
+            const message = isCommerceError(error)
+                ? error.message
+                : "Checkout failed.";
+            return c.json({
+                error: {
+                    code: "CHECKOUT_FAILED",
+                    message,
+                },
+            }, 422);
+        }
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/customers.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 customerRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=customers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"customers.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/customers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAQzD,OAAO,EAAE,KAAK,MAAM,EAAsE,MAAM,aAAa,CAAC;AAE9G,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,gCAwF5C"}

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

@@ -0,0 +1,78 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { listCustomersRoute, getCustomerRoute, updateCustomerRoute, getCustomerOrdersRoute, getCustomerAddressesRoute, } from "../schemas/customers.js";
+import { mapErrorToResponse, mapErrorToStatus, parsePagination, requirePerm } from "../utils.js";
+export function customerRoutes(kernel) {
+    const router = new OpenAPIHono();
+    // All customer admin routes require authentication + customers:read
+    router.use("/*", requirePerm("customers:read"));
+    router.use("/", requirePerm("customers:read"));
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(listCustomersRoute, async (c) => {
+        const actor = c.get("actor");
+        const { page, limit } = parsePagination(c.req.query());
+        const result = await kernel.services.customers.list(actor);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        const all = result.value;
+        const total = all.length;
+        const start = (page - 1) * limit;
+        const paged = all.slice(start, start + limit);
+        return c.json({
+            data: paged,
+            meta: {
+                pagination: { page, limit, total, totalPages: Math.ceil(total / limit) },
+            },
+        });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getCustomerRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const actor = c.get("actor");
+        const result = await kernel.services.customers.getById(id, actor);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    // PATCH requires customers:update (checked in handler since middleware can't distinguish methods)
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(updateCustomerRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const body = c.req.valid("json");
+        const actor = c.get("actor");
+        // Strip undefined values — exactOptionalPropertyTypes requires omission, not undefined
+        const updates = {};
+        for (const [k, v] of Object.entries(body)) {
+            if (v !== undefined)
+                updates[k] = v;
+        }
+        const result = await kernel.services.customers.update(id, updates, 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(getCustomerOrdersRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const actor = c.get("actor");
+        const { page, limit } = parsePagination(c.req.query());
+        const status = c.req.query("status") || undefined;
+        const result = await kernel.services.orders.listByCustomer(id, { page, limit, ...(status ? { status } : {}) }, actor);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value.items, meta: { pagination: result.value.pagination } });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getCustomerAddressesRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const actor = c.get("actor");
+        // Get customer first, then use their userId for address lookup
+        const customerResult = await kernel.services.customers.getById(id, actor);
+        if (!customerResult.ok)
+            return c.json(mapErrorToResponse(customerResult.error), mapErrorToStatus(customerResult.error));
+        const addressResult = await kernel.services.customers.getAddresses(customerResult.value.userId, actor);
+        if (!addressResult.ok)
+            return c.json(mapErrorToResponse(addressResult.error), mapErrorToStatus(addressResult.error));
+        return c.json({ data: addressResult.value });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/entity-aliases.d.ts

@@ -0,0 +1,18 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import type { AppEnv } from "../utils.js";
+/**
+ * Register URL rewrite aliases for entity types that define `alias` in config.
+ *
+ * E.g., `entities.product.alias = "products"` rewrites:
+ *   /api/products         → /api/catalog/entities?type=product
+ *   /api/products/:id     → /api/catalog/entities/:id
+ *   /api/products/:id/... → /api/catalog/entities/:id/...
+ *
+ * This is a thin rewrite layer — no handler duplication. The original
+ * catalog routes handle all logic, validation, and OpenAPI schema.
+ *
+ * The `type` filter is injected automatically on list requests.
+ */
+export declare function registerEntityAliases(router: OpenAPIHono<AppEnv>, kernel: Kernel): void;
+//# sourceMappingURL=entity-aliases.d.ts.map

package/dist/interfaces/rest/routes/entity-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-aliases.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/entity-aliases.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAC3B,MAAM,EAAE,MAAM,GACb,IAAI,CA4BN"}

package/dist/interfaces/rest/routes/entity-aliases.js

@@ -0,0 +1,39 @@
+/**
+ * Register URL rewrite aliases for entity types that define `alias` in config.
+ *
+ * E.g., `entities.product.alias = "products"` rewrites:
+ *   /api/products         → /api/catalog/entities?type=product
+ *   /api/products/:id     → /api/catalog/entities/:id
+ *   /api/products/:id/... → /api/catalog/entities/:id/...
+ *
+ * This is a thin rewrite layer — no handler duplication. The original
+ * catalog routes handle all logic, validation, and OpenAPI schema.
+ *
+ * The `type` filter is injected automatically on list requests.
+ */
+export function registerEntityAliases(router, kernel) {
+    const entities = kernel.config.entities ?? {};
+    for (const [entityType, entityConfig] of Object.entries(entities)) {
+        if (!entityConfig.alias)
+            continue;
+        const alias = entityConfig.alias;
+        // /api/{alias} → /api/catalog/entities?type={entityType}
+        router.all(`/${alias}`, (c) => {
+            const url = new URL(c.req.url);
+            url.pathname = "/api/catalog/entities";
+            // Inject type filter for list requests
+            if (c.req.method === "GET") {
+                url.searchParams.set("type", entityType);
+            }
+            const newReq = new Request(url.toString(), c.req.raw);
+            return router.fetch(newReq);
+        });
+        // /api/{alias}/:rest → /api/catalog/entities/:rest
+        router.all(`/${alias}/*`, (c) => {
+            const url = new URL(c.req.url);
+            url.pathname = url.pathname.replace(`/api/${alias}`, "/api/catalog/entities");
+            const newReq = new Request(url.toString(), c.req.raw);
+            return router.fetch(newReq);
+        });
+    }
+}

package/dist/interfaces/rest/routes/inventory.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 inventoryRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=inventory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/inventory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAUzD,OAAO,EAAE,KAAK,MAAM,EAAqD,MAAM,aAAa,CAAC;AAE7F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,gCA4E7C"}

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

@@ -0,0 +1,74 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { inventoryAdjustRoute, inventoryReserveRoute, inventoryReleaseRoute, createWarehouseRoute, inventoryCheckRoute, listWarehousesRoute, listInventoryLevelsRoute, } from "../schemas/inventory.js";
+import { mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+export function inventoryRoutes(kernel) {
+    const router = new OpenAPIHono();
+    // Inventory levels listing requires inventory:read
+    router.use("/levels", requirePerm("inventory:read"));
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(listInventoryLevelsRoute, async (c) => {
+        const actor = c.get("actor");
+        const warehouseId = c.req.query("warehouseId");
+        const entityId = c.req.query("entityId");
+        const result = await kernel.services.inventory.listLevels({
+            ...(warehouseId ? { warehouseId } : {}),
+            ...(entityId ? { entityId } : {}),
+        }, 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(inventoryCheckRoute, async (c) => {
+        const entityIds = (c.req.query("entityIds") ?? "")
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        const result = await kernel.services.inventory.checkMultiple(entityIds);
+        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(inventoryAdjustRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.inventory.adjust(body, 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(inventoryReserveRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.inventory.reserve(body, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: { reserved: true } });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(inventoryReleaseRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.inventory.release(body, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: { released: true } });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(createWarehouseRoute, async (c) => {
+        const body = c.req.valid("json");
+        const actor = c.get("actor");
+        const result = await kernel.services.inventory.createWarehouse(body, 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(listWarehousesRoute, async (c) => {
+        const actor = c.get("actor");
+        const result = await kernel.services.inventory.listWarehouses(actor);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/media.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 mediaRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=media.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/media.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,EAAqD,MAAM,aAAa,CAAC;AAE7F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,gCA+EzC"}

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

@@ -0,0 +1,65 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { attachMediaRoute, getMediaRoute, deleteMediaRoute } from "../schemas/media.js";
+import { mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+export function mediaRoutes(kernel) {
+    const router = new OpenAPIHono();
+    // Upload requires authentication + media:write permission
+    router.use("/upload", requirePerm("media:write"));
+    router.post("/upload", async (c) => {
+        const body = await c.req.parseBody();
+        const file = body.file;
+        if (!file) {
+            return c.json({ error: { code: "VALIDATION_FAILED", message: "file is required" } }, 422);
+        }
+        const buffer = await file.arrayBuffer();
+        const actor = c.get("actor");
+        const result = await kernel.services.media.upload({
+            filename: file.name,
+            contentType: file.type,
+            data: buffer,
+            alt: String(body.alt ?? ""),
+        }, actor);
+        if (!result.ok) {
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        }
+        return c.json({ data: result.value }, 201);
+    });
+    router.openapi(getMediaRoute, async (c) => {
+        const signed = c.req.query("signed") === "true";
+        // Signed URLs require authentication
+        if (signed && !c.get("actor")) {
+            return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required for signed URLs." } }, 401);
+        }
+        const result = signed
+            ? await kernel.services.media.getSignedUrl(c.req.param("id"))
+            : await kernel.services.media.getUrl(c.req.param("id"));
+        if (!result.ok) {
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        }
+        return c.redirect(result.value, 302);
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(deleteMediaRoute, async (c) => {
+        const actor = c.get("actor");
+        if (!actor || (!actor.permissions.includes("media:write") && !actor.permissions.includes("*:*"))) {
+            return c.json({ error: { code: "FORBIDDEN", message: "media:write permission required." } }, 403);
+        }
+        const result = await kernel.services.media.delete(c.req.param("id"));
+        if (!result.ok) {
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        }
+        return c.json({ data: { deleted: true } });
+    });
+    // Attach requires media:write
+    router.use("/attach", requirePerm("media:write"));
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(attachMediaRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.media.attachToEntity(body);
+        if (!result.ok) {
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        }
+        return c.json({ data: { attached: true } }, 201);
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/orders.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 orderRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=orders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/orders.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,EAAiE,MAAM,aAAa,CAAC;AAEzG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,gCAwEzC"}

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

@@ -0,0 +1,64 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { changeOrderStatusRoute, listOrdersRoute, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders.js";
+import { isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
+export function orderRoutes(kernel) {
+    const router = new OpenAPIHono();
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(listOrdersRoute, async (c) => {
+        const pagination = parsePagination(c.req.query());
+        const status = c.req.query("status");
+        const result = await kernel.services.orders.list({
+            page: pagination.page,
+            limit: pagination.limit,
+            ...(status !== undefined ? { status } : {}),
+        }, c.get("actor"));
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({
+            data: result.value.items,
+            meta: {
+                pagination: result.value.pagination,
+            },
+        });
+    });
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getOrderRoute, async (c) => {
+        const idOrNumber = c.req.param("idOrNumber");
+        const result = isUUID(idOrNumber)
+            ? await kernel.services.orders.getById(idOrNumber, c.get("actor"))
+            : await kernel.services.orders.getByNumber(idOrNumber, 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() enforces strict response typing but our handler
+    // returns union responses (200 | 400 | 404). The route definition documents the
+    // contract; the handler returns dynamic status.
+    router.openapi(changeOrderStatusRoute, async (c) => {
+        const body = c.req.valid("json");
+        const result = await kernel.services.orders.changeStatus({
+            orderId: c.req.param("id"),
+            newStatus: body.status,
+            ...(body.reason !== undefined ? { reason: body.reason } : {}),
+        }, 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(getOrderFulfillmentsRoute, async (c) => {
+        const orderId = c.req.param("id");
+        const actor = c.get("actor");
+        // Verify the order exists and the actor has access before returning fulfillments
+        const orderResult = isUUID(orderId)
+            ? await kernel.services.orders.getById(orderId, actor)
+            : await kernel.services.orders.getByNumber(orderId, actor);
+        if (!orderResult.ok)
+            return c.json(mapErrorToResponse(orderResult.error), mapErrorToStatus(orderResult.error));
+        const result = await kernel.services.fulfillment.getByOrderId(orderResult.value.id);
+        if (!result.ok)
+            return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+    });
+    return router;
+}

package/dist/interfaces/rest/routes/payments.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 paymentRoutes(kernel: Kernel): OpenAPIHono<AppEnv, {}, "/">;
+//# sourceMappingURL=payments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payments.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/routes/payments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,KAAK,MAAM,EAAwC,MAAM,aAAa,CAAC;AAKhF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,gCAmD3C"}