@unifiedcommerce/core 0.3.4 → 0.4.1

package/src/interfaces/rest/routes/entity-aliases.ts

@@ -0,0 +1,346 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { z, createRoute } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import type { CreateEntityInput, UpdateEntityInput } from "../../../modules/catalog/schemas.js";
+import {
+  type AppEnv,
+  mapErrorToResponse,
+  mapErrorToStatus,
+  parseInclude,
+  parsePagination,
+  parseSort,
+} from "../utils.js";
+import { errorResponses } from "../schemas/shared.js";
+
+/**
+ * Generate ergonomic alias routes for an entity type.
+ *
+ * E.g., if config has `entities.product.alias = "products"`, this creates:
+ *   GET    /api/products
+ *   GET    /api/products/:idOrSlug
+ *   POST   /api/products
+ *   PATCH  /api/products/:id
+ *   DELETE /api/products/:id
+ *   POST   /api/products/:id/publish
+ *   POST   /api/products/:id/archive
+ *   GET    /api/products/:id/variants
+ *   POST   /api/products/:id/variants
+ *   GET    /api/products/:id/options
+ *   GET    /api/products/:id/attributes/:locale
+ *   PUT    /api/products/:id/attributes/:locale
+ *
+ * All delegate to the same catalog service with `type` pre-injected.
+ */
+export function entityAliasRoutes(kernel: Kernel): OpenAPIHono<AppEnv>[] {
+  const routers: OpenAPIHono<AppEnv>[] = [];
+  const entities = kernel.config.entities ?? {};
+
+  for (const [entityType, entityConfig] of Object.entries(entities)) {
+    if (!entityConfig.alias) continue;
+
+    const alias = entityConfig.alias;
+    const tag = alias.charAt(0).toUpperCase() + alias.slice(1);
+    const router = new OpenAPIHono<AppEnv>();
+
+    // ─── LIST ─────────────────────────────────────────────────
+    const listRoute = createRoute({
+      method: "get",
+      path: "/",
+      tags: [tag],
+      summary: `List ${alias}`,
+      description: `Alias for GET /api/catalog/entities?type=${entityType}`,
+      request: {
+        query: z.object({
+          status: z.string().optional(),
+          category: z.string().optional(),
+          brand: z.string().optional(),
+          include: z.string().optional(),
+          sort: z.string().optional(),
+          page: z.string().optional(),
+          limit: z.string().optional(),
+        }),
+      },
+      responses: {
+        200: {
+          content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())), meta: z.record(z.string(), z.unknown()) }) } },
+          description: `${tag} list`,
+        },
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(listRoute, async (c) => {
+      const include = parseInclude(c.req.query("include"));
+      const pagination = parsePagination(c.req.query());
+      const filter: Record<string, string> = { type: entityType };
+      const status = c.req.query("status");
+      const category = c.req.query("category");
+      const brand = c.req.query("brand");
+      if (status) filter.status = status;
+      if (category) filter.category = category;
+      if (brand) filter.brand = brand;
+
+      const payload: Record<string, unknown> = { filter, pagination };
+      const sort = parseSort(c.req.query("sort"));
+      if (sort) payload.sort = sort;
+
+      const result = await kernel.services.catalog.list(payload, c.get("actor"));
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+
+      let items = result.value.items;
+      if (include.size > 0) {
+        const opts = {
+          includeAttributes: include.has("attributes"),
+          includeVariants: include.has("variants"),
+          includeOptionTypes: include.has("optionTypes"),
+          includeCategories: include.has("categories"),
+          includeBrands: include.has("brands"),
+          includeMedia: include.has("media"),
+          includeInventory: include.has("inventory"),
+          includePricing: include.has("pricing"),
+        };
+        items = await Promise.all(
+          items.map(async (item) => {
+            const full = await kernel.services.catalog.getById(item.id, opts);
+            return full.ok ? full.value : item;
+          }),
+        );
+      }
+
+      return c.json({ data: items, meta: { pagination: result.value.pagination } });
+    });
+
+    // ─── GET BY ID/SLUG ───────────────────────────────────────
+    const getRoute = createRoute({
+      method: "get",
+      path: "/{idOrSlug}",
+      tags: [tag],
+      summary: `Get ${alias.slice(0, -1)} by ID or slug`,
+      request: {
+        params: z.object({ idOrSlug: z.string() }),
+        query: z.object({ include: z.string().optional() }),
+      },
+      responses: {
+        200: { content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } }, description: `${tag} detail` },
+        ...errorResponses,
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getRoute, async (c) => {
+      const idOrSlug = c.req.valid("param").idOrSlug;
+      const include = parseInclude(c.req.query("include"));
+      const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(idOrSlug);
+      const opts = {
+        includeAttributes: include.has("attributes"),
+        includeVariants: include.has("variants"),
+        includeOptionTypes: include.has("optionTypes"),
+        includeCategories: include.has("categories"),
+        includeBrands: include.has("brands"),
+        includeMedia: include.has("media"),
+        includeInventory: include.has("inventory"),
+        includePricing: include.has("pricing"),
+      };
+
+      const result = isUUID
+        ? await kernel.services.catalog.getById(idOrSlug, opts)
+        : await kernel.services.catalog.getBySlug(idOrSlug, opts);
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json({ data: result.value });
+    });
+
+    // ─── CREATE ───────────────────────────────────────────────
+    const createEntityRoute = createRoute({
+      method: "post",
+      path: "/",
+      tags: [tag],
+      summary: `Create ${alias.slice(0, -1)}`,
+      request: {
+        body: { content: { "application/json": { schema: z.object({ slug: z.string().optional(), title: z.string().optional(), description: z.string().optional(), metadata: z.record(z.string(), z.unknown()).optional() }).openapi(`Create${tag}Request`) } } },
+      },
+      responses: {
+        201: { content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } }, description: `${tag} created` },
+        ...errorResponses,
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(createEntityRoute, async (c) => {
+      const body = c.req.valid("json");
+      const input: CreateEntityInput = { type: entityType, ...body };
+      const result = await kernel.services.catalog.create(input, c.get("actor"));
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json({ data: result.value }, 201);
+    });
+
+    // ─── UPDATE ───────────────────────────────────────────────
+    const updateRoute = createRoute({
+      method: "patch",
+      path: "/{id}",
+      tags: [tag],
+      summary: `Update ${alias.slice(0, -1)}`,
+      request: {
+        params: z.object({ id: z.string().uuid() }),
+        body: { content: { "application/json": { schema: z.object({ slug: z.string().optional(), title: z.string().optional(), description: z.string().optional(), metadata: z.record(z.string(), z.unknown()).optional() }).openapi(`Update${tag}Request`) } } },
+      },
+      responses: {
+        200: { content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } }, description: `${tag} updated` },
+        ...errorResponses,
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(updateRoute, async (c) => {
+      const { id } = c.req.valid("param");
+      const body = c.req.valid("json");
+      const input: UpdateEntityInput = { ...body };
+      const result = await kernel.services.catalog.update(id, input, c.get("actor"));
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json({ data: result.value });
+    });
+
+    // ─── DELETE ────────────────────────────────────────────────
+    const deleteRoute = createRoute({
+      method: "delete",
+      path: "/{id}",
+      tags: [tag],
+      summary: `Delete ${alias.slice(0, -1)}`,
+      request: { params: z.object({ id: z.string().uuid() }) },
+      responses: {
+        200: { content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } }, description: "Deleted" },
+        ...errorResponses,
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(deleteRoute, async (c) => {
+      const { id } = c.req.valid("param");
+      const result = await kernel.services.catalog.delete(id, c.get("actor"));
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json({ data: { deleted: true as const } });
+    });
+
+    // ─── PUBLISH / ARCHIVE ────────────────────────────────────
+    for (const action of ["publish", "archive"] as const) {
+      const actionRoute = createRoute({
+        method: "post",
+        path: `/{id}/${action}`,
+        tags: [tag],
+        summary: `${action.charAt(0).toUpperCase() + action.slice(1)} ${alias.slice(0, -1)}`,
+        request: { params: z.object({ id: z.string().uuid() }) },
+        responses: {
+          200: { content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } }, description: `${tag} ${action}ed` },
+          ...errorResponses,
+        },
+      });
+
+      // @ts-expect-error -- openapi handler union return type
+      router.openapi(actionRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const result = await kernel.services.catalog[action](id, c.get("actor"));
+        if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value });
+      });
+    }
+
+    // ─── ATTRIBUTES ───────────────────────────────────────────
+    const getAttrsRoute = createRoute({
+      method: "get",
+      path: "/{id}/attributes/{locale}",
+      tags: [tag],
+      summary: `Get ${alias.slice(0, -1)} attributes`,
+      request: { params: z.object({ id: z.string().uuid(), locale: z.string() }) },
+      responses: {
+        200: { content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } }, description: "Attributes" },
+        ...errorResponses,
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(getAttrsRoute, async (c) => {
+      const { id, locale } = c.req.valid("param");
+      const result = await kernel.services.catalog.getAttributes(id, locale);
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json({ data: result.value });
+    });
+
+    const setAttrsRoute = createRoute({
+      method: "put",
+      path: "/{id}/attributes/{locale}",
+      tags: [tag],
+      summary: `Set ${alias.slice(0, -1)} attributes`,
+      request: {
+        params: z.object({ id: z.string().uuid(), locale: z.string() }),
+        body: { content: { "application/json": { schema: z.record(z.string(), z.unknown()).openapi(`Set${tag}AttributesRequest`) } } },
+      },
+      responses: {
+        200: { content: { "application/json": { schema: z.object({ data: z.object({ updated: z.literal(true) }) }) } }, description: "Attributes set" },
+        ...errorResponses,
+      },
+    });
+
+    // @ts-expect-error -- openapi handler union return type
+    router.openapi(setAttrsRoute, async (c) => {
+      const { id, locale } = c.req.valid("param");
+      const body = c.req.valid("json");
+      const result = await kernel.services.catalog.setAttributes(id, locale, body);
+      if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json({ data: { updated: true as const } });
+    });
+
+    // ─── VARIANTS ─────────────────────────────────────────────
+    if (entityConfig.variants.enabled) {
+      const createVariantRoute = createRoute({
+        method: "post",
+        path: "/{id}/variants",
+        tags: [tag],
+        summary: `Create variant for ${alias.slice(0, -1)}`,
+        request: {
+          params: z.object({ id: z.string().uuid() }),
+          body: { content: { "application/json": { schema: z.object({ sku: z.string().optional(), options: z.record(z.string(), z.string()).optional(), metadata: z.record(z.string(), z.unknown()).optional() }).openapi(`Create${tag}VariantRequest`) } } },
+        },
+        responses: {
+          201: { content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } }, description: "Variant created" },
+          ...errorResponses,
+        },
+      });
+
+      // @ts-expect-error -- openapi handler union return type
+      router.openapi(createVariantRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const body = c.req.valid("json");
+        const result = await kernel.services.catalog.createVariant({ entityId: id, ...body }, c.get("actor"));
+        if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value }, 201);
+      });
+
+      const listOptionsRoute = createRoute({
+        method: "get",
+        path: "/{id}/options",
+        tags: [tag],
+        summary: `List option types for ${alias.slice(0, -1)}`,
+        request: { params: z.object({ id: z.string().uuid() }) },
+        responses: {
+          200: { content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } }, description: "Option types" },
+          ...errorResponses,
+        },
+      });
+
+      // @ts-expect-error -- openapi handler union return type
+      router.openapi(listOptionsRoute, async (c) => {
+        const { id } = c.req.valid("param");
+        const result = await kernel.services.catalog.getById(id, { includeOptionTypes: true });
+        if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+        return c.json({ data: result.value.optionTypes ?? [] });
+      });
+    }
+
+    // Store alias → entityType for the tag group
+    (router as unknown as Record<string, string>).__aliasTag = tag;
+    (router as unknown as Record<string, string>).__aliasPath = alias;
+
+    routers.push(router);
+  }
+
+  return routers;
+}

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

@@ -7,12 +7,29 @@ import {
   createWarehouseRoute,
   inventoryCheckRoute,
   listWarehousesRoute,
+  listInventoryLevelsRoute,
 } from "../schemas/inventory.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
 
 export function inventoryRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  // @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") ?? "")

package/src/interfaces/rest/schemas/customers.ts

@@ -0,0 +1,155 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+export const listCustomersRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Customers"],
+  summary: "List customers",
+  request: {
+    query: z.object({
+      page: z.string().optional().openapi({ example: "1" }),
+      limit: z.string().optional().openapi({ example: "20" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            data: z.array(z.record(z.string(), z.unknown())),
+            meta: z.object({
+              pagination: z.object({
+                page: z.number(),
+                limit: z.number(),
+                total: z.number(),
+                totalPages: z.number(),
+              }),
+            }),
+          }),
+        },
+      },
+      description: "Customer list",
+    },
+  },
+});
+
+export const getCustomerRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Customers"],
+  summary: "Get customer by ID",
+  request: {
+    params: z.object({
+      id: z.string().uuid().openapi({ example: "b482a588-..." }),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ data: z.record(z.string(), z.unknown()) }),
+        },
+      },
+      description: "Customer detail",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateCustomerRoute = createRoute({
+  method: "patch",
+  path: "/{id}",
+  tags: ["Customers"],
+  summary: "Update a customer",
+  request: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            firstName: z.string().optional(),
+            lastName: z.string().optional(),
+            email: z.string().email().optional(),
+            phone: z.string().optional(),
+            metadata: z.record(z.string(), z.unknown()).optional(),
+          }).openapi("UpdateCustomerRequest"),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ data: z.record(z.string(), z.unknown()) }),
+        },
+      },
+      description: "Customer updated",
+    },
+    ...errorResponses,
+  },
+});
+
+export const getCustomerOrdersRoute = createRoute({
+  method: "get",
+  path: "/{id}/orders",
+  tags: ["Customers"],
+  summary: "List orders for a customer",
+  request: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+    query: z.object({
+      status: z.string().optional(),
+      page: z.string().optional().openapi({ example: "1" }),
+      limit: z.string().optional().openapi({ example: "20" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            data: z.array(z.record(z.string(), z.unknown())),
+            meta: z.object({
+              pagination: z.object({
+                page: z.number(),
+                limit: z.number(),
+                total: z.number(),
+                totalPages: z.number(),
+              }),
+            }),
+          }),
+        },
+      },
+      description: "Customer orders",
+    },
+    ...errorResponses,
+  },
+});
+
+export const getCustomerAddressesRoute = createRoute({
+  method: "get",
+  path: "/{id}/addresses",
+  tags: ["Customers"],
+  summary: "List addresses for a customer",
+  request: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }),
+        },
+      },
+      description: "Customer addresses",
+    },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/schemas/inventory.ts

@@ -14,6 +14,27 @@ export const CreateWarehouseBodySchema = z.object({
 
 // ─── Route Definitions ──────────────────────────────────────────────────────
 
+export const listInventoryLevelsRoute = createRoute({
+  method: "get",
+  path: "/levels",
+  tags: ["Inventory"],
+  summary: "List inventory levels",
+  description: "Lists all inventory levels, optionally filtered by warehouse or entity.",
+  request: {
+    query: z.object({
+      warehouseId: z.string().uuid().optional().openapi({ example: "uuid" }),
+      entityId: z.string().uuid().optional().openapi({ example: "uuid" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Inventory levels",
+    },
+    ...errorResponses,
+  },
+});
+
 export const inventoryCheckRoute = createRoute({
   method: "get",
   path: "/check",

package/src/modules/customers/service.ts

@@ -43,6 +43,15 @@ export class CustomerService {
     return customer;
   }
 
+  async list(
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Customer[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const customers = await this.repo.findAll(orgId, ctx);
+    return Ok(customers);
+  }
+
   async getById(
     id: string,
     actor?: Actor | null,
@@ -64,6 +73,22 @@ export class CustomerService {
     return Ok(customer);
   }
 
+  async update(
+    id: string,
+    updates: Partial<
+      Omit<Customer, "id" | "userId" | "createdAt" | "updatedAt">
+    >,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Customer>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.repo.findById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Customer not found."));
+    const updated = await this.repo.update(id, updates, ctx);
+    if (!updated) return Err(new CommerceNotFoundError("Customer not found."));
+    return Ok(updated);
+  }
+
   async updateByUserId(
     userId: string,
     updates: Partial<

package/src/modules/inventory/service.ts

@@ -110,6 +110,23 @@ export class InventoryService {
     return Ok(available);
   }
 
+  async listLevels(
+    params?: { warehouseId?: string; entityId?: string },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<InventoryLevel[]>> {
+    if (params?.entityId) {
+      const levels = await this.repo.findLevelsByEntityId(params.entityId, ctx);
+      return Ok(levels);
+    }
+    if (params?.warehouseId) {
+      const levels = await this.repo.findLevelsByWarehouseId(params.warehouseId, ctx);
+      return Ok(levels);
+    }
+    const levels = await this.repo.findAllLevels(ctx);
+    return Ok(levels);
+  }
+
   async checkMultiple(
     entityIds: string[],
     ctx?: TxContext,

package/src/runtime/server.ts

@@ -267,6 +267,47 @@ export async function createServer(config: CommerceConfig) {
         version: config.version ?? "0.0.1",
         description: "Headless commerce engine REST API. Includes core and plugin endpoints.",
       },
+      tags: [
+        // ── Entity aliases (generated from config.entities[type].alias) ──
+        ...Object.entries(config.entities ?? {})
+          .filter(([, cfg]) => cfg.alias)
+          .map(([type, cfg]) => {
+            const name = cfg.alias!.charAt(0).toUpperCase() + cfg.alias!.slice(1);
+            return { name, description: `Ergonomic alias for ${type} entities — CRUD, variants, attributes` };
+          }),
+        // ── Storefront ──
+        { name: "Catalog", description: "Products, categories, brands, variants, and option types (unified entity API)" },
+        { name: "Search", description: "Full-text search and typeahead suggestions" },
+        { name: "Pricing", description: "Base prices, price modifiers, and customer group pricing" },
+        { name: "Carts", description: "Shopping cart lifecycle — create, add items, update quantities" },
+        { name: "Checkout", description: "Convert a cart into a paid order" },
+        { name: "Promotions", description: "Discount codes, validation, and usage tracking" },
+        // ── Admin ──
+        { name: "Orders", description: "Order management — list, detail, status transitions, fulfillments" },
+        { name: "Customers", description: "Customer profiles, addresses, groups, and order history" },
+        { name: "Inventory", description: "Stock levels, warehouse management, adjustments, and reservations" },
+        { name: "Media", description: "File uploads, entity attachments, and signed URLs" },
+        { name: "Payments", description: "Payment provider webhooks and event processing" },
+        // ── Operations ──
+        { name: "Webhooks", description: "Outbound webhook endpoint registration and management" },
+        { name: "Audit", description: "Immutable audit log — who changed what and when" },
+        { name: "Admin Jobs", description: "Background job queue — view failed jobs and retry" },
+      ],
+    });
+
+    // Serve enriched spec with x-tagGroups vendor extension (Scalar/Redocly sidebar grouping)
+    const aliasTags = Object.values(config.entities ?? {})
+      .filter((cfg) => cfg.alias)
+      .map((cfg) => cfg.alias!.charAt(0).toUpperCase() + cfg.alias!.slice(1));
+    const tagGroups = [
+      ...(aliasTags.length > 0 ? [{ name: "Quick Access", tags: aliasTags }] : []),
+      { name: "Storefront", tags: ["Catalog", "Search", "Pricing", "Carts", "Checkout", "Promotions"] },
+      { name: "Admin", tags: ["Orders", "Customers", "Inventory", "Media", "Payments"] },
+      { name: "Operations", tags: ["Webhooks", "Audit", "Admin Jobs"] },
+    ];
+    app.get("/api/doc-ext", (c) => {
+      const spec = app.getOpenAPIDocument({ openapi: "3.0.0", info: { title: "UnifiedCommerce API", version: config.version ?? "0.0.1" } });
+      return c.json({ ...spec, "x-tagGroups": tagGroups });
     });
   } else {
     app.get("/api/doc", (c) => c.json({ error: { code: "NOT_FOUND", message: "Not found." } }, 404));