@unifiedcommerce/core 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedcommerce/core",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": {

package/src/config/types.ts

@@ -47,6 +47,8 @@ export interface EntityConfig {
   variants: EntityVariantConfig;
   fulfillment: string;
   hooks?: EntityHooks;
+  /** Optional URL alias. Generates ergonomic CRUD routes at `/api/{alias}` that delegate to the catalog service with `type` pre-injected. E.g., `alias: "products"` creates `GET /api/products`, `POST /api/products`, etc. */
+  alias?: string;
 }
 
 /**

package/src/interfaces/rest/index.ts

@@ -17,6 +17,7 @@ import { searchRoutes } from "./routes/search.js";
 import { auditRoutes } from "./routes/audit.js";
 import { adminJobRoutes } from "./routes/admin-jobs.js";
 import { customerRoutes } from "./routes/customers.js";
+import { entityAliasRoutes } from "./routes/entity-aliases.js";
 
 export function createRestRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>({
@@ -66,6 +67,38 @@ export function createRestRoutes(kernel: Kernel) {
   router.route("/audit", auditRoutes(kernel));
   router.route("/admin", adminJobRoutes(kernel));
 
+  // ─── Entity alias routes (e.g., /api/products → /api/catalog/entities?type=product) ──
+  for (const aliasRouter of entityAliasRoutes(kernel)) {
+    const aliasPath = (aliasRouter as unknown as Record<string, string>).__aliasPath;
+    if (aliasPath) {
+      router.route(`/${aliasPath}`, aliasRouter);
+    }
+  }
+
+  // ─── Static shortcut aliases ───────────────────────────────
+  // /api/categories → forwards to /api/catalog/categories
+  router.all("/categories/*", (c) => {
+    const url = new URL(c.req.url);
+    url.pathname = url.pathname.replace("/api/categories", "/api/catalog/categories");
+    return router.fetch(new Request(url.toString(), c.req.raw));
+  });
+  router.all("/categories", (c) => {
+    const url = new URL(c.req.url);
+    url.pathname = "/api/catalog/categories";
+    return router.fetch(new Request(url.toString(), c.req.raw));
+  });
+  // /api/brands → forwards to /api/catalog/brands
+  router.all("/brands/*", (c) => {
+    const url = new URL(c.req.url);
+    url.pathname = url.pathname.replace("/api/brands", "/api/catalog/brands");
+    return router.fetch(new Request(url.toString(), c.req.raw));
+  });
+  router.all("/brands", (c) => {
+    const url = new URL(c.req.url);
+    url.pathname = "/api/catalog/brands";
+    return router.fetch(new Request(url.toString(), c.req.raw));
+  });
+
   // API Reference (Scalar) — disabled in production unless config.exposeOpenApiSpec is true
   const exposeSpec = kernel.config.exposeOpenApiSpec ?? (process.env.NODE_ENV !== "production");
   if (exposeSpec) {

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/runtime/server.ts

@@ -268,8 +268,15 @@ export async function createServer(config: CommerceConfig) {
         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" },
+        { 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" },
@@ -289,7 +296,11 @@ export async function createServer(config: CommerceConfig) {
     });
 
     // 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"] },