@unifiedcommerce/core 0.0.1

package/src/interfaces/rest/routes/checkout.ts

@@ -0,0 +1,283 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel";
+import { checkoutRoute } from "../schemas/checkout";
+import {
+  applyPromotionCodes,
+  authorizePayment,
+  calculateShipping,
+  calculateTax,
+  checkInventoryAvailability,
+  completeCheckout,
+  recordAnalyticsEvent,
+  resolveCurrentPrices,
+  validateCartNotEmpty,
+  validatePaymentMethod,
+  type CheckoutData,
+  type OrderResult,
+} from "../../../hooks/checkout";
+import { runAfterHooks, runBeforeHooks } from "../../../kernel/hooks/executor";
+import { createHookContext } from "../../../kernel/hooks/create-context";
+import type { AfterHook, BeforeHook, ServiceContainer } from "../../../kernel/hooks/types";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils";
+import { isCommerceError } from "../../../kernel/errors";
+import { makeId } from "../../../utils/id";
+import type { ShippingAddress } from "../../../modules/shipping/calculator";
+
+export function checkoutRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // @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: 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: BeforeHook<CheckoutData>[] = [
+      validateCartNotEmpty,
+      resolveCurrentPrices,
+      checkInventoryAvailability,
+      applyPromotionCodes,
+      calculateTax,
+      calculateShipping,
+      ...(kernel.hooks.resolve("checkout.beforePayment") as BeforeHook<CheckoutData>[]),
+      validatePaymentMethod,
+    ];
+
+    // ── Phase 2: Payment Authorization (outside transaction — external API call) ──
+    const paymentHooks: BeforeHook<CheckoutData>[] = [
+      authorizePayment,
+      ...(kernel.hooks.resolve("checkout.beforeCreate") as BeforeHook<CheckoutData>[]),
+    ];
+
+    const afterHooks: AfterHook<OrderResult>[] = [
+      completeCheckout,
+      recordAnalyticsEvent,
+      ...(kernel.hooks.resolve("checkout.afterCreate") as AfterHook<OrderResult>[]),
+    ];
+
+    const context = createHookContext({
+      actor,
+      logger: kernel.logger,
+      services: kernel.services as ServiceContainer,
+      context: { moduleName: "checkout" },
+      origin: "rest",
+      kernel: kernel as unknown as { database: { db: import("../../../kernel/database/plugin-types").PluginDb } },
+    });
+
+    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: string | undefined = 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/src/interfaces/rest/routes/inventory.ts

@@ -0,0 +1,70 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel";
+import {
+  inventoryAdjustRoute,
+  inventoryReserveRoute,
+  inventoryReleaseRoute,
+  createWarehouseRoute,
+  inventoryCheckRoute,
+  listWarehousesRoute,
+} from "../schemas/inventory";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils";
+
+export function inventoryRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // @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") as Parameters<typeof kernel.services.inventory.createWarehouse>[0];
+    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/src/interfaces/rest/routes/media.ts

@@ -0,0 +1,86 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel";
+import type { AttachMediaInput } from "../../../modules/media/service";
+import { attachMediaRoute, getMediaRoute, deleteMediaRoute } from "../schemas/media";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils";
+
+export function mediaRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // 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 as 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") as AttachMediaInput;
+    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/src/interfaces/rest/routes/orders.ts

@@ -0,0 +1,78 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel";
+import { changeOrderStatusRoute, listOrdersRoute, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders";
+import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils";
+
+export function orderRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // @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/src/interfaces/rest/routes/payments.ts

@@ -0,0 +1,60 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type { Kernel } from "../../../runtime/kernel";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils";
+import { processedWebhookEvents } from "../../../modules/webhooks/schema";
+
+type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+
+export function paymentRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.post("/webhook", async (c) => {
+    const result = await kernel.services.payments.verifyWebhook(c.req.raw);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+
+    const event = result.value;
+    const db = kernel.database.db as Db;
+
+    // Atomic idempotency: INSERT ... ON CONFLICT DO NOTHING ... RETURNING
+    // If the row already exists, RETURNING yields zero rows → duplicate.
+    // If the row is new, RETURNING yields one row → process the event.
+    // No TOCTOU race: the UNIQUE constraint on event_id is the single source of truth.
+    const [inserted] = await db
+      .insert(processedWebhookEvents)
+      .values({
+        eventId: event.id,
+        provider: "stripe",
+        eventType: event.type,
+      })
+      .onConflictDoNothing()
+      .returning({ id: processedWebhookEvents.id });
+
+    if (!inserted) {
+      // Row already existed — this is a duplicate delivery
+      return c.json({ data: { received: true, duplicate: true } });
+    }
+
+    // Process the event (first time only)
+    if (event.type === "payment_intent.succeeded") {
+      const data = event.data as Record<string, unknown> | undefined;
+      const metadata = data?.metadata as Record<string, unknown> | undefined;
+      if (typeof metadata?.orderId === "string") {
+        await kernel.services.orders.changeStatus(
+          {
+            orderId: metadata.orderId,
+            newStatus: "confirmed",
+            reason: "stripe_webhook_payment_intent_succeeded",
+          },
+          null,
+        );
+      }
+    }
+
+    return c.json({ data: { received: true } });
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/pricing.ts

@@ -0,0 +1,57 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel";
+import { setBasePriceRoute, createModifierRoute, listPricesRoute } from "../schemas/pricing";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils";
+
+export function pricingRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/prices", requirePerm("pricing:manage"));
+
+  // @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(setBasePriceRoute, async (c) => {
+    const actor = c.get("actor");
+    const result = await kernel.services.pricing.setBasePrice(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(listPricesRoute, async (c) => {
+    const entityId = c.req.query("entityId");
+    const variantId = c.req.query("variantId");
+    const currency = c.req.query("currency");
+    const customerGroupId = c.req.query("customerGroupId");
+
+    const result = await kernel.services.pricing.listPrices({
+      ...(entityId !== undefined ? { entityId } : {}),
+      ...(variantId !== undefined ? { variantId } : {}),
+      ...(currency !== undefined ? { currency } : {}),
+      ...(customerGroupId !== undefined ? { customerGroupId } : {}),
+    });
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  router.use("/modifiers", requirePerm("pricing:manage"));
+
+  // @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(createModifierRoute, async (c) => {
+    const actor = c.get("actor");
+    const result = await kernel.services.pricing.createModifier(c.req.valid("json"), actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  return router;
+}