@unifiedcommerce/core 0.3.4 → 0.4.0

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,36 @@ export async function createServer(config: CommerceConfig) {
         version: config.version ?? "0.0.1",
         description: "Headless commerce engine REST API. Includes core and plugin endpoints.",
       },
+      tags: [
+        // ── Storefront ──
+        { name: "Catalog", description: "Products, categories, brands, variants, and option types" },
+        { 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 tagGroups = [
+      { 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));