@porulle/core 0.1.0

package/src/hooks/order-emails.ts

@@ -0,0 +1,62 @@
+/**
+ * Order lifecycle email notifications.
+ *
+ * Sends emails on status changes: confirmed, fulfilled, cancelled, refunded.
+ * Registered as an orders.afterStatusChange hook.
+ */
+
+import type { AfterHook } from "../kernel/hooks/types.js";
+
+interface StatusChangeResult {
+  orderId: string;
+  customerId?: string | null;
+  newStatus: string;
+  previousStatus: string;
+}
+
+export const sendOrderStatusEmail: AfterHook<StatusChangeResult> = async ({
+  result,
+  context,
+}) => {
+  const email = context.services.email as
+    | { send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void> }
+    | undefined;
+
+  if (!email?.send) return;
+
+  // Only send for customer-facing status changes
+  const notifiableStatuses = ["confirmed", "processing", "fulfilled", "cancelled", "refunded"];
+  if (!notifiableStatuses.includes(result.newStatus)) return;
+
+  // Look up customer email
+  const customerId = result.customerId;
+  if (!customerId) return;
+
+  const customers = context.services.customers as
+    | { getByUserId(id: string, actor?: unknown): Promise<{ ok: boolean; value?: { email?: string | null } }> }
+    | undefined;
+
+  if (!customers) return;
+
+  try {
+    const customer = await customers.getByUserId(customerId, context.actor);
+    if (!customer.ok || !customer.value?.email) return;
+
+    await email.send({
+      template: "order-status-change",
+      to: customer.value.email,
+      data: {
+        orderId: result.orderId,
+        newStatus: result.newStatus,
+        previousStatus: result.previousStatus,
+      },
+    });
+  } catch (err) {
+    // Email failure must not break the order flow
+    context.logger.warn("Order status email failed", {
+      orderId: result.orderId,
+      newStatus: result.newStatus,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+};

package/src/index.ts

@@ -0,0 +1,213 @@
+export { defineConfig } from "./config/define-config.js";
+export type {
+  CommerceConfig,
+  CommercePlugin,
+  ApiKeyScopeDefinition,
+} from "./config/types.js";
+export { defineCommercePlugin } from "./kernel/plugin/manifest.js";
+export type {
+  CommercePluginManifest,
+  PluginContext,
+  PluginHookRegistration,
+  PluginLogger,
+  PluginPermission,
+  PluginRouteRegistration,
+} from "./kernel/plugin/manifest.js";
+
+export { router } from "./interfaces/rest/router.js";
+export { webhookRouter, type WebhookRouterResult } from "./interfaces/rest/webhook-router.js";
+export { isPrivateUrl, isPrivateIp } from "./modules/webhooks/ssrf-guard.js";
+export { createServer } from "./runtime/server.js";
+export { createLogger } from "./runtime/logger.js";
+export type { Logger as PinoLogger } from "./runtime/logger.js";
+export { setupGracefulShutdown } from "./runtime/shutdown.js";
+export { createKernel } from "./runtime/kernel.js";
+export type { Kernel } from "./runtime/kernel.js";
+// Test utilities moved to @porulle/core/testing sub-path export.
+// Import from "@porulle/core/testing" instead of "@porulle/core".
+// This avoids pulling drizzle-kit/tsx/esbuild into Turbopack's bundle graph.
+
+export type { Actor } from "./auth/types.js";
+export { resolveOrgId, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org.js";
+export { OrganizationService } from "./modules/organization/service.js";
+export { createScopedDb } from "./kernel/database/scoped-db.js";
+export type { ScopedOrganizationId } from "./kernel/database/scoped-db.js";
+export { assertOwnership, assertPermission } from "./auth/permissions.js";
+export type { AccessResult, AccessContext, AccessFn, WhereClause } from "./auth/access.js";
+export {
+  accessOR,
+  accessAND,
+  conditional,
+  isAdmin,
+  isAuthenticated,
+  isDocumentOwner,
+  publicAccess,
+  denyAll,
+} from "./auth/access.js";
+
+export { HookRegistry } from "./kernel/hooks/registry.js";
+export type {
+  BeforeHook,
+  AfterHook,
+  HookContext,
+  HookOperation,
+  HookOrigin,
+  Logger,
+  ServiceContainer,
+} from "./kernel/hooks/types.js";
+export { runBeforeHooks, runAfterHooks } from "./kernel/hooks/executor.js";
+export { createHookContext } from "./kernel/hooks/create-context.js";
+export type { CreateHookContextArgs } from "./kernel/hooks/create-context.js";
+export type { JobsAdapter, EnqueueOptions } from "./kernel/jobs/adapter.js";
+export { NullJobsAdapter } from "./kernel/jobs/adapter.js";
+export { DrizzleJobsAdapter } from "./kernel/jobs/drizzle-adapter.js";
+export { runPendingJobs } from "./kernel/jobs/runner.js";
+export type { RunPendingJobsArgs } from "./kernel/jobs/runner.js";
+export type {
+  TaskDefinition,
+  TaskContext,
+  TaskJobMeta,
+  TaskRetryConfig,
+} from "./kernel/jobs/types.js";
+export { BUILTIN_JOB_TASK_SLUGS } from "./kernel/jobs/types.js";
+export {
+  staleJobReaperTask,
+  runStaleJobReaper,
+  getJobReapThresholdMs,
+  getJobsReaperIntervalMs,
+} from "./kernel/jobs/reaper.js";
+
+export { createLocalAPI, LocalAPI } from "./kernel/local-api.js";
+export type { CommerceLocalAPI, LocalAPIOptions } from "./kernel/local-api.js";
+export { createCommerce } from "./runtime/commerce.js";
+export type { CommerceInstance } from "./runtime/commerce.js";
+
+export { createAuditService, createNullAuditService } from "./modules/audit/service.js";
+export type {
+  AuditService,
+  AuditEntry,
+  RecordArgs,
+  ListForEntityArgs,
+} from "./modules/audit/service.js";
+
+export type { Result, PluginResult, PluginResultErr } from "./kernel/result.js";
+export { Ok, Err, PluginErr } from "./kernel/result.js";
+export type { PluginDb, PluginTxFn } from "./kernel/database/plugin-types.js";
+export type { ServiceRegistry } from "./kernel/service-registry.js";
+export { defineModule } from "./kernel/module/index.js";
+export type { AppModule, ModuleDeps, ServiceMap } from "./kernel/module/index.js";
+export { toHttpError, type HttpErrorResponse } from "./kernel/http-error.js";
+export { withTiming } from "./kernel/service-timing.js";
+
+export {
+  CommerceNotFoundError,
+  CommerceValidationError,
+  CommerceForbiddenError,
+  CommerceConflictError,
+  CommerceInvalidTransitionError,
+  OrgResolutionError,
+} from "./kernel/errors.js";
+
+export { mapErrorToStatus } from "./kernel/error-mapper.js";
+
+export {
+  canTransition,
+  assertTransition,
+  orderStateMachine,
+  extendOrderStateMachine,
+} from "./kernel/state-machine/machine.js";
+
+export type {
+  PaymentAdapter,
+  PaymentCapture,
+  PaymentIntent,
+  PaymentRefund,
+  PaymentWebhookEvent,
+} from "./modules/payments/adapter.js";
+export type { StorageAdapter } from "./modules/media/adapter.js";
+export type {
+  SearchAdapter,
+  SearchDocument,
+  SearchFilters,
+  SearchHit,
+  SearchQueryParams,
+  SearchQueryResult,
+  SearchSuggestParams,
+} from "./modules/search/adapter.js";
+export type { DatabaseAdapter } from "./kernel/database/adapter.js";
+export {
+  createTxContext,
+  reuseOrCreateTxContext,
+  withTransaction,
+} from "./kernel/database/tx-context.js";
+export type {
+  TxContext,
+  WithTransactionOptions,
+} from "./kernel/database/tx-context.js";
+export type {
+  TaxAdapter,
+  TaxAddress,
+  TaxCalculationParams,
+  TaxCalculationResult,
+  TaxLineItem,
+  TaxReportParams,
+  TaxVoidParams,
+} from "./modules/tax/adapter.js";
+
+export { getSchema, buildSchema, getTableNames } from "./kernel/database/migrate.js";
+export { consoleEmailAdapter } from "./adapters/console-email.js";
+
+export { runCompensationChain } from "./kernel/compensation/executor.js";
+export type {
+  CompensationContext,
+  Step,
+} from "./kernel/compensation/types.js";
+
+export { createRepository } from "./kernel/factory/repository-factory.js";
+export type {
+  BaseRepository,
+  SoftDeletableRepository,
+  RepositoryFor,
+  Filters,
+  FindOptions,
+} from "./kernel/factory/repository-factory.js";
+
+export type { CartItemMatcher } from "./modules/cart/matcher.js";
+export { defaultCartItemMatcher } from "./modules/cart/matcher.js";
+export { canAccessCart } from "./modules/cart/access.js";
+
+export { QueryRegistry } from "./kernel/query/registry.js";
+export { executeQuery } from "./kernel/query/executor.js";
+export type {
+  RelationDefinition,
+  EntityDefinition,
+} from "./kernel/query/registry.js";
+export type { QueryInput, QueryResult } from "./kernel/query/executor.js";
+
+export type { CommerceModuleTypes } from "./types/commerce-types.js";
+
+export { staleOrderCleanupTask } from "./modules/orders/stale-order-cleanup.js";
+export { COMMERCE_AGENT_SYSTEM_PROMPT } from "./utils/agent-prompt.js";
+
+export { DrizzleAnalyticsAdapter } from "./modules/analytics/drizzle-adapter.js";
+export { BUILTIN_ANALYTICS_MODELS } from "./modules/analytics/models.js";
+export { buildAnalyticsScope } from "./modules/analytics/types.js";
+export type {
+  AnalyticsAdapter,
+  AnalyticsQueryParams,
+  AnalyticsQueryResult,
+  AnalyticsMeta,
+  AnalyticsModelDefinition,
+  AnalyticsScope,
+  AnalyticsModel,
+  AnalyticsScopeRule,
+  AnalyticsMeasure,
+  AnalyticsDimension,
+  AnalyticsJoin,
+  // Deprecated aliases (remove in next major)
+  CubeScopeRule,
+  CubeDefinition,
+  MeasureDefinition,
+  DimensionDefinition,
+  JoinDefinition,
+} from "./modules/analytics/types.js";

package/src/interfaces/rest/customer-portal.ts

@@ -0,0 +1,299 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../runtime/kernel.js";
+import { assertPermission } from "../../auth/permissions.js";
+import type { Actor } from "../../auth/types.js";
+import type { AppEnv } from "./utils.js";
+import {
+  getProfileRoute,
+  listAddressesRoute,
+  listCustomerOrdersRoute,
+  getCustomerOrderRoute,
+  getOrderTrackingRoute,
+  getOrderDownloadsRoute,
+  listCoursesRoute,
+  deleteAddressRoute,
+  reorderRoute,
+  updateProfileRoute,
+  createAddressRoute,
+} from "./schemas/customer-portal.js";
+import { isUUID, mapErrorToStatus } from "./utils.js";
+
+export function createCustomerPortalRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("*", async (c, next) => {
+    if (!c.get("actor")) {
+      return c.json(
+        { error: { code: "FORBIDDEN", message: "Authentication required." } },
+        401,
+      );
+    }
+    await next();
+  });
+
+  /**
+   * Resolves an actor whose userId is the customer profile UUID (not the Better Auth user ID).
+   * Required so that `assertOwnership(actor, order.customerId)` compares UUIDs correctly,
+   * since orders.customer_id stores the customer profile UUID, not the Better Auth string ID.
+   */
+  async function resolveCustomerActor(actor: Actor): Promise<Actor | null> {
+    const customer = await kernel.services.customers.getByUserId(actor.userId, actor);
+    if (!customer.ok) return null;
+    return { ...actor, userId: customer.value.id };
+  }
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getProfileRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const customer = await kernel.services.customers.getByUserId(actor.userId, actor);
+    if (!customer.ok) return c.json({ error: customer.error }, 404);
+    return c.json({ data: customer.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateProfileRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    assertPermission(actor, "customers:update:self");
+    const result = await kernel.services.customers.updateByUserId(
+      actor.userId,
+      c.req.valid("json") as Parameters<typeof kernel.services.customers.updateByUserId>[1],
+      actor,
+    );
+    if (!result.ok) return c.json({ error: result.error }, 422);
+    return c.json({ data: result.value });
+  });
+
+  router.openapi(listAddressesRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const addresses = await kernel.services.customers.getAddresses(
+      actor.userId,
+      actor,
+    );
+    return c.json({ data: addresses.ok ? addresses.value : [] });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createAddressRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const result = await kernel.services.customers.addAddress(
+      actor.userId,
+      c.req.valid("json") as Parameters<typeof kernel.services.customers.addAddress>[1],
+      actor,
+    );
+    if (!result.ok) return c.json({ error: result.error }, 422);
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteAddressRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const result = await kernel.services.customers.deleteAddress(
+      actor.userId,
+      c.req.param("id"),
+      actor,
+    );
+    if (!result.ok) return c.json({ error: result.error }, 404);
+    return c.json({ data: { deleted: true } });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listCustomerOrdersRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const status = c.req.query("status");
+    // Resolve customer profile UUID from Better Auth userId
+    const customerResult = await kernel.services.customers.getByUserId(actor.userId, actor);
+    if (!customerResult.ok) return c.json({ data: [], meta: { total: 0, page: 1, limit: 20, totalPages: 0 } });
+    const result = await kernel.services.orders.listByCustomer(customerResult.value.id, {
+      page: Number.parseInt(c.req.query("page") ?? "1", 10),
+      limit: Number.parseInt(c.req.query("limit") ?? "20", 10),
+      ...(status !== undefined ? { status } : {}),
+    });
+    if (!result.ok) return c.json({ error: result.error }, 500);
+    return c.json({ data: result.value.items, meta: result.value.pagination });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getCustomerOrderRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const id = c.req.param("idOrNumber");
+    const customerActor = await resolveCustomerActor(actor);
+    if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
+    const result = isUUID(id)
+      ? await kernel.services.orders.getById(id, customerActor)
+      : await kernel.services.orders.getByNumber(id, customerActor);
+
+    if (!result.ok)
+      return c.json({ error: result.error }, mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getOrderTrackingRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const id = c.req.param("idOrNumber");
+    const customerActor = await resolveCustomerActor(actor);
+    if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
+
+    const orderResult = isUUID(id)
+      ? await kernel.services.orders.getById(id, customerActor)
+      : await kernel.services.orders.getByNumber(id, customerActor);
+
+    if (!orderResult.ok) {
+      return c.json(
+        { error: orderResult.error },
+        mapErrorToStatus(orderResult.error),
+      );
+    }
+
+    const fulfillments = await kernel.services.fulfillment.getByOrderId(
+      orderResult.value.id,
+    );
+    if (!fulfillments.ok) return c.json({ error: fulfillments.error }, 500);
+
+    return c.json({
+      data: fulfillments.value.map((item) => ({
+        fulfillmentId: item.id,
+        status: item.status,
+        carrier: item.carrier ?? null,
+        trackingNumber: item.trackingNumber ?? null,
+        trackingUrl: item.trackingUrl ?? null,
+        estimatedDelivery: item.estimatedDelivery ?? null,
+        shippedAt: item.shippedAt ?? null,
+        deliveredAt: item.deliveredAt ?? null,
+        lineItems: item.lineItems,
+      })),
+    });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getOrderDownloadsRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const customerActor = await resolveCustomerActor(actor);
+    if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
+    const orderResult = await kernel.services.orders.getById(
+      c.req.param("orderId"),
+      customerActor,
+    );
+    if (!orderResult.ok) {
+      return c.json(
+        { error: orderResult.error },
+        mapErrorToStatus(orderResult.error),
+      );
+    }
+
+    const digitalItems = orderResult.value.lineItems.filter(
+      (lineItem) => lineItem.entityType === "digitalDownload",
+    );
+
+    const downloads = await Promise.all(
+      digitalItems.map(async (lineItem) => {
+        const result = await kernel.services.fulfillment.getDownloadUrl(
+          orderResult.value.id,
+          lineItem.id,
+          actor.userId,
+          actor,
+        );
+
+        return {
+          lineItemId: lineItem.id,
+          title: lineItem.title,
+          downloadUrl: result.ok ? result.value.url : null,
+          downloadsRemaining: result.ok ? result.value.remaining : 0,
+          expiresAt: result.ok ? result.value.expiresAt : null,
+        };
+      }),
+    );
+
+    return c.json({ data: downloads });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listCoursesRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const result = await kernel.services.fulfillment.getDigitalAccess(
+      actor.userId,
+      "course",
+    );
+    if (!result.ok) return c.json({ error: result.error }, 500);
+
+    return c.json({
+      data: result.value.map((item) => ({
+        entityId: item.entityId,
+        title: item.title,
+        accessGrantedAt: item.grantedAt,
+        accessExpiresAt: item.expiresAt,
+        isActive: item.isActive,
+        orderId: item.orderId,
+      })),
+    });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(reorderRoute, async (c) => {
+    const actor = c.get("actor") as Actor;
+    const customerActor = await resolveCustomerActor(actor);
+    if (!customerActor) return c.json({ error: { code: "NOT_FOUND", message: "Customer profile not found." } }, 404);
+    const orderResult = await kernel.services.orders.getById(
+      c.req.param("orderId"),
+      customerActor,
+    );
+    if (!orderResult.ok) {
+      return c.json(
+        { error: orderResult.error },
+        mapErrorToStatus(orderResult.error),
+      );
+    }
+
+    const cartResult = await kernel.services.cart.create(
+      {
+        customerId: actor.userId,
+        currency: orderResult.value.currency,
+      },
+      actor,
+    );
+
+    if (!cartResult.ok) return c.json({ error: cartResult.error }, 500);
+
+    const addResults = await Promise.all(
+      orderResult.value.lineItems.map((lineItem) =>
+        kernel.services.cart.addItem(
+          {
+            cartId: cartResult.value.id,
+            entityId: lineItem.entityId,
+            quantity: lineItem.quantity,
+            unitPriceSnapshot: lineItem.unitPrice,
+            currency: orderResult.value.currency,
+            ...(lineItem.variantId != null
+              ? { variantId: lineItem.variantId }
+              : {}),
+          },
+          actor,
+        ),
+      ),
+    );
+
+    const failures = addResults
+      .map((item, index) =>
+        item.ok
+          ? null
+          : {
+              item: orderResult.value.lineItems[index]?.title ?? "unknown",
+              reason: item.error.message,
+            },
+      )
+      .filter(Boolean);
+
+    return c.json(
+      {
+        data: {
+          cartId: cartResult.value.id,
+          itemsAdded: addResults.filter((item) => item.ok).length,
+          itemsFailed: failures,
+        },
+      },
+      201,
+    );
+  });
+
+  return router;
+}

package/src/interfaces/rest/index.ts

@@ -0,0 +1,105 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Scalar } from "@scalar/hono-api-reference";
+import { sql } from "drizzle-orm";
+import type { Kernel } from "../../runtime/kernel.js";
+import type { AppEnv } from "./utils.js";
+import { mapErrorToResponse } from "../../kernel/error-mapper.js";
+import { catalogRoutes } from "./routes/catalog.js";
+import { inventoryRoutes } from "./routes/inventory.js";
+import { mediaRoutes } from "./routes/media.js";
+import { cartRoutes } from "./routes/carts.js";
+import { checkoutRoutes } from "./routes/checkout.js";
+import { orderRoutes } from "./routes/orders.js";
+import { paymentRoutes } from "./routes/payments.js";
+import { webhookRoutes } from "./routes/webhooks.js";
+import { pricingRoutes } from "./routes/pricing.js";
+import { promotionRoutes } from "./routes/promotions.js";
+import { searchRoutes } from "./routes/search.js";
+import { auditRoutes } from "./routes/audit.js";
+import { adminJobRoutes } from "./routes/admin-jobs.js";
+import { compensationFailureAdminRoutes } from "./routes/admin/compensation-failures.js";
+import { adminPermissionsRoutes } from "./routes/admin/permissions.js";
+import { customerRoutes } from "./routes/customers.js";
+export function createRestRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>({
+    // Standardize Zod validation error responses across all routes
+    defaultHook: (result, c) => {
+      if (!result.success) {
+        const isProd = process.env.NODE_ENV === "production";
+        return c.json({
+          error: {
+            code: "VALIDATION_FAILED",
+            // In production: generic message. In dev: detailed field errors.
+            message: isProd
+              ? "Invalid input."
+              : result.error.issues
+                  .map((i) => `${i.path.join(".")}: ${i.message}`)
+                  .join("; "),
+          },
+        }, 422);
+      }
+    },
+  });
+
+  // Global error boundary — catches unhandled exceptions from any route handler.
+  router.onError((error, c) => {
+    const isProd = process.env.NODE_ENV === "production";
+    const { body, status } = mapErrorToResponse(error, isProd);
+    return c.json(body, status);
+  });
+
+  // F5: Health check with database probe — minimal info for load balancers
+  router.get("/health", async (c) => {
+    try {
+      const db = kernel.database.db;
+      const timeout = new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error("health check timeout")), 5000),
+      );
+      await Promise.race([
+        (db as { execute: (q: unknown) => Promise<unknown> }).execute(sql`SELECT 1`),
+        timeout,
+      ]);
+      return c.json({ status: "ok" });
+    } catch {
+      return c.json({ status: "down" }, 503);
+    }
+  });
+
+  // ─── Domain routes ──────────────────────────────────────────────────
+  router.route("/catalog", catalogRoutes(kernel));
+  router.route("/inventory", inventoryRoutes(kernel));
+  router.route("/media", mediaRoutes(kernel));
+  router.route("/carts", cartRoutes(kernel));
+  router.route("/checkout", checkoutRoutes(kernel));
+  router.route("/orders", orderRoutes(kernel));
+  router.route("/payments", paymentRoutes(kernel));
+  router.route("/webhooks", webhookRoutes(kernel));
+  router.route("/pricing", pricingRoutes(kernel));
+  router.route("/promotions", promotionRoutes(kernel));
+  router.route("/search", searchRoutes(kernel));
+  router.route("/customers", customerRoutes(kernel));
+  router.route("/audit", auditRoutes(kernel));
+  router.route("/admin", adminJobRoutes(kernel));
+  router.route("/admin", compensationFailureAdminRoutes(kernel));
+  router.route("/admin", adminPermissionsRoutes(kernel));
+
+  // API Reference (Scalar) — disabled in production unless config.exposeOpenApiSpec is true
+  const exposeSpec = kernel.config.exposeOpenApiSpec ?? (process.env.NODE_ENV !== "production");
+  if (exposeSpec) {
+    router.get(
+      "/reference",
+      Scalar({
+        url: "/api/doc-ext",
+        theme: "kepler",
+        layout: "modern",
+        darkMode: true,
+        hideModels: true,
+        tagsSorter: "alpha",
+        defaultHttpClient: { targetKey: "js", clientKey: "fetch" },
+        metaData: { title: "UnifiedCommerce API Reference" },
+      }),
+    );
+  }
+
+  return router;
+}