@unifiedcommerce/core 0.1.1 → 0.2.1

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

@@ -0,0 +1,195 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+import { CustomerResponse, OrderResponse, OrderListResponse, CustomerAddressListResponse, CartResponse } from "./responses.js";
+
+const GenericDataResponse = z.object({ data: z.record(z.string(), z.unknown()) });
+
+// ─── GET Route Definitions ─────────────────────────────────────────────────
+
+export const getProfileRoute = createRoute({
+  method: "get",
+  path: "/profile",
+  tags: ["Customer Portal"],
+  summary: "Get customer profile",
+  responses: {
+    200: { content: { "application/json": { schema: CustomerResponse } }, description: "Customer profile" },
+    ...errorResponses,
+  },
+});
+
+export const listAddressesRoute = createRoute({
+  method: "get",
+  path: "/addresses",
+  tags: ["Customer Portal"],
+  summary: "List customer addresses",
+  responses: {
+    200: { content: { "application/json": { schema: CustomerAddressListResponse } }, description: "Addresses" },
+  },
+});
+
+export const listCustomerOrdersRoute = createRoute({
+  method: "get",
+  path: "/orders",
+  tags: ["Customer Portal"],
+  summary: "List customer orders",
+  request: {
+    query: z.object({
+      status: z.string().optional(),
+      page: z.string().optional(),
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: OrderListResponse } }, description: "Orders" },
+  },
+});
+
+export const getCustomerOrderRoute = createRoute({
+  method: "get",
+  path: "/orders/{idOrNumber}",
+  tags: ["Customer Portal"],
+  summary: "Get a specific customer order",
+  request: {
+    params: z.object({
+      idOrNumber: z.string().min(1).openapi({ example: "ORD-001" }),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: OrderResponse } }, description: "Order details" },
+    ...errorResponses,
+  },
+});
+
+export const getOrderTrackingRoute = createRoute({
+  method: "get",
+  path: "/orders/{idOrNumber}/tracking",
+  tags: ["Customer Portal"],
+  summary: "Get tracking info for an order",
+  request: {
+    params: z.object({
+      idOrNumber: z.string().min(1).openapi({ example: "ORD-001" }),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: GenericDataResponse } }, description: "Tracking info" },
+    ...errorResponses,
+  },
+});
+
+export const getOrderDownloadsRoute = createRoute({
+  method: "get",
+  path: "/orders/{orderId}/downloads",
+  tags: ["Customer Portal"],
+  summary: "Get digital downloads for an order",
+  request: {
+    params: z.object({
+      orderId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: GenericDataResponse } }, description: "Downloads" },
+    ...errorResponses,
+  },
+});
+
+export const listCoursesRoute = createRoute({
+  method: "get",
+  path: "/courses",
+  tags: ["Customer Portal"],
+  summary: "List customer course access",
+  responses: {
+    200: { content: { "application/json": { schema: GenericDataResponse } }, description: "Courses" },
+  },
+});
+
+// ─── DELETE Route Definitions ──────────────────────────────────────────────
+
+export const deleteAddressRoute = createRoute({
+  method: "delete",
+  path: "/addresses/{id}",
+  tags: ["Customer Portal"],
+  summary: "Delete a customer address",
+  request: {
+    params: z.object({
+      id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } }, description: "Deleted" },
+    ...errorResponses,
+  },
+});
+
+// ─── POST Route Definitions (no body or special) ───────────────────────────
+
+export const reorderRoute = createRoute({
+  method: "post",
+  path: "/orders/{orderId}/reorder",
+  tags: ["Customer Portal"],
+  summary: "Reorder items from a previous order",
+  request: {
+    params: z.object({
+      orderId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+  },
+  responses: {
+    201: { content: { "application/json": { schema: CartResponse } }, description: "Reorder cart created" },
+    ...errorResponses,
+  },
+});
+
+// ─── Mutation Route Definitions ─────────────────────────────────────────────
+
+const UpdateProfileBodySchema = z.object({
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  phone: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("UpdateProfileBody");
+
+const CreateAddressBodySchema = z.object({
+  type: z.enum(["shipping", "billing"]).openapi({ example: "shipping" }),
+  firstName: z.string().openapi({ example: "John" }),
+  lastName: z.string().openapi({ example: "Doe" }),
+  line1: z.string().openapi({ example: "123 Main St" }),
+  line2: z.string().optional(),
+  city: z.string().openapi({ example: "New York" }),
+  state: z.string().optional(),
+  postalCode: z.string().optional(),
+  country: z.string().openapi({ example: "US" }),
+  phone: z.string().optional(),
+}).openapi("CreateAddressBody");
+
+export const updateProfileRoute = createRoute({
+  method: "patch",
+  path: "/profile",
+  tags: ["Customer Portal"],
+  summary: "Update customer profile",
+  request: {
+    body: {
+      content: { "application/json": { schema: UpdateProfileBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: CustomerResponse } }, description: "Updated" },
+    ...errorResponses,
+  },
+});
+
+export const createAddressRoute = createRoute({
+  method: "post",
+  path: "/addresses",
+  tags: ["Customer Portal"],
+  summary: "Create a customer address",
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateAddressBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: GenericDataResponse } }, description: "Created" },
+    ...errorResponses,
+  },
+});

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

@@ -0,0 +1,138 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses } from "./shared.js";
+
+// ─── Request Schemas ─────────────────────────────────────────────────────────
+
+import { InventoryAdjustBodySchema, InventoryReserveBodySchema, InventoryReleaseBodySchema } from "../../../modules/inventory/schemas.js";
+export { InventoryAdjustBodySchema, InventoryReserveBodySchema, InventoryReleaseBodySchema };
+
+export const CreateWarehouseBodySchema = z.object({
+  name: z.string().openapi({ example: "Main Warehouse" }),
+  code: z.string().optional().openapi({ example: "WH-MAIN" }),
+  address: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateWarehouseRequest");
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const inventoryCheckRoute = createRoute({
+  method: "get",
+  path: "/check",
+  tags: ["Inventory"],
+  summary: "Check inventory for entities",
+  request: {
+    query: z.object({
+      entityIds: z.string().optional().openapi({ example: "uuid1,uuid2" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Inventory levels",
+    },
+  },
+});
+
+export const listWarehousesRoute = createRoute({
+  method: "get",
+  path: "/warehouses",
+  tags: ["Inventory"],
+  summary: "List all warehouses",
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Warehouses",
+    },
+  },
+});
+
+export const inventoryAdjustRoute = createRoute({
+  method: "post",
+  path: "/adjust",
+  tags: ["Inventory"],
+  summary: "Adjust inventory levels",
+  description: "Adjusts the on-hand quantity for a given entity/variant in a warehouse.",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: InventoryAdjustBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Inventory adjusted.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const inventoryReserveRoute = createRoute({
+  method: "post",
+  path: "/reserve",
+  tags: ["Inventory"],
+  summary: "Reserve inventory",
+  description: "Reserves inventory quantity for an order.",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: InventoryReserveBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ reserved: z.literal(true) }) }) } },
+      description: "Inventory reserved.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const inventoryReleaseRoute = createRoute({
+  method: "post",
+  path: "/release",
+  tags: ["Inventory"],
+  summary: "Release reserved inventory",
+  description: "Releases previously reserved inventory back to available stock.",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: InventoryReleaseBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ released: z.literal(true) }) }) } },
+      description: "Inventory released.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const createWarehouseRoute = createRoute({
+  method: "post",
+  path: "/warehouses",
+  tags: ["Inventory"],
+  summary: "Create a warehouse",
+  description: "Creates a new warehouse for inventory management.",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: CreateWarehouseBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Warehouse created.",
+    },
+    ...errorResponses,
+  },
+});

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

@@ -0,0 +1,75 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses } from "./shared.js";
+
+// ─── Request Schema ──────────────────────────────────────────────────────────
+
+export const AttachMediaBodySchema = z.object({
+  mediaAssetId: z.string().openapi({ example: "asset-uuid" }),
+  entityId: z.string().openapi({ example: "product-uuid" }),
+  role: z.enum(["primary", "gallery", "thumbnail", "video", "document"]).openapi({ example: "primary" }),
+  variantId: z.string().optional(),
+  sortOrder: z.number().optional().openapi({ example: 0 }),
+}).openapi("AttachMediaRequest");
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const getMediaRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Media"],
+  summary: "Get a media asset (redirects to URL)",
+  request: {
+    params: z.object({
+      id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+    query: z.object({
+      signed: z.string().optional().openapi({ example: "true" }),
+    }),
+  },
+  responses: {
+    302: { description: "Redirect to media URL" },
+    ...errorResponses,
+  },
+});
+
+export const deleteMediaRoute = createRoute({
+  method: "delete",
+  path: "/{id}",
+  tags: ["Media"],
+  summary: "Delete a media asset",
+  request: {
+    params: z.object({
+      id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } },
+      description: "Media deleted.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const attachMediaRoute = createRoute({
+  method: "post",
+  path: "/attach",
+  tags: ["Media"],
+  summary: "Attach a media asset to an entity",
+  description: "Links an uploaded media asset to a catalog entity (product, variant, etc.).",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: AttachMediaBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: z.object({ data: z.object({ attached: z.literal(true) }) }) } },
+      description: "Media attached to entity.",
+    },
+    ...errorResponses,
+  },
+});

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

@@ -0,0 +1,104 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses } from "./shared.js";
+import { OrderResponse, OrderListResponse } from "./responses.js";
+
+// ─── Request Schemas ────────────────────────────────────────────────────────
+
+export const ChangeOrderStatusBodySchema = z.object({
+  // Accept any string — custom state machines (e.g., BNPL) add states like
+  // "payment_initiated", "shipped", "delivered" etc. The order service's
+  // state machine validates valid transitions at runtime.
+  status: z.string().min(1).openapi({ example: "confirmed" }),
+  reason: z.string().optional().openapi({ example: "Payment verified" }),
+}).openapi("ChangeOrderStatusRequest");
+
+// ─── Response Schemas ───────────────────────────────────────────────────────
+
+export const OrderDataResponseSchema = OrderResponse;
+
+// ─── Path Params ────────────────────────────────────────────────────────────
+
+const OrderIdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listOrdersRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Orders"],
+  summary: "List orders",
+  request: {
+    query: z.object({
+      status: z.string().optional(),
+      page: z.string().optional(),
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderListResponse } },
+      description: "Success",
+    },
+  },
+});
+
+export const getOrderRoute = createRoute({
+  method: "get",
+  path: "/{idOrNumber}",
+  tags: ["Orders"],
+  summary: "Get an order by ID or order number",
+  request: {
+    params: z.object({
+      idOrNumber: z.string().min(1).openapi({ example: "ORD-001" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Success",
+    },
+    ...errorResponses,
+  },
+});
+
+export const getOrderFulfillmentsRoute = createRoute({
+  method: "get",
+  path: "/{id}/fulfillments",
+  tags: ["Orders"],
+  summary: "Get fulfillments for an order",
+  request: {
+    params: OrderIdParam,
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Success",
+    },
+    ...errorResponses,
+  },
+});
+
+export const changeOrderStatusRoute = createRoute({
+  method: "patch",
+  path: "/{id}/status",
+  tags: ["Orders"],
+  summary: "Change the status of an order",
+  request: {
+    params: OrderIdParam,
+    body: {
+      content: {
+        "application/json": { schema: ChangeOrderStatusBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Order status updated.",
+    },
+    ...errorResponses,
+  },
+});

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

@@ -0,0 +1,80 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses } from "./shared.js";
+
+// ─── Request Schemas ────────────────────────────────────────────────────────
+
+import { SetBasePriceBodySchema, CreateModifierBodySchema } from "../../../modules/pricing/schemas.js";
+export { SetBasePriceBodySchema, CreateModifierBodySchema };
+
+// ─── Response Schemas ───────────────────────────────────────────────────────
+
+export const PricingResponseSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+}).openapi("PricingResponse");
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listPricesRoute = createRoute({
+  method: "get",
+  path: "/prices",
+  tags: ["Pricing"],
+  summary: "List prices",
+  request: {
+    query: z.object({
+      entityId: z.string().optional(),
+      variantId: z.string().optional(),
+      currency: z.string().optional(),
+      customerGroupId: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PricingResponseSchema } },
+      description: "Prices",
+    },
+  },
+});
+
+export const setBasePriceRoute = createRoute({
+  method: "post",
+  path: "/prices",
+  tags: ["Pricing"],
+  summary: "Set a base price for a product or variant",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: SetBasePriceBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: PricingResponseSchema } },
+      description: "Base price set successfully.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const createModifierRoute = createRoute({
+  method: "post",
+  path: "/modifiers",
+  tags: ["Pricing"],
+  summary: "Create a price modifier",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: CreateModifierBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: PricingResponseSchema } },
+      description: "Price modifier created successfully.",
+    },
+    ...errorResponses,
+  },
+});

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

@@ -0,0 +1,110 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses, UuidParamSchema } from "./shared.js";
+
+// ─── Request Schemas ────────────────────────────────────────────────────────
+
+import { CreatePromotionBodySchema } from "../../../modules/promotions/schemas.js";
+export { CreatePromotionBodySchema };
+
+export const ValidatePromotionBodySchema = z.object({
+  code: z.string().openapi({ example: "SUMMER10" }),
+  currency: z.string().length(3).openapi({ example: "USD" }),
+  subtotal: z.number().openapi({ example: 100 }),
+  lineItems: z.array(z.object({
+    entityId: z.string(),
+    entityType: z.string(),
+    quantity: z.number().int(),
+    unitPrice: z.number(),
+    totalPrice: z.number(),
+  })),
+  customerId: z.string().optional(),
+  customerGroupIds: z.array(z.string()).optional(),
+}).openapi("ValidatePromotionRequest");
+
+// ─── Response Schemas ───────────────────────────────────────────────────────
+
+export const PromotionResponseSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+}).openapi("PromotionResponse");
+
+// ─── Path Params ────────────────────────────────────────────────────────────
+
+const PromotionIdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listActivePromotionsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Promotions"],
+  summary: "List active promotions",
+  responses: {
+    200: {
+      content: { "application/json": { schema: PromotionResponseSchema } },
+      description: "Active promotions",
+    },
+  },
+});
+
+export const createPromotionRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Promotions"],
+  summary: "Create a new promotion",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: CreatePromotionBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: PromotionResponseSchema } },
+      description: "Promotion created successfully.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const validatePromotionRoute = createRoute({
+  method: "post",
+  path: "/validate",
+  tags: ["Promotions"],
+  summary: "Validate a promotion code against a cart",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: ValidatePromotionBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PromotionResponseSchema } },
+      description: "Promotion validation result.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const deactivatePromotionRoute = createRoute({
+  method: "post",
+  path: "/{id}/deactivate",
+  tags: ["Promotions"],
+  summary: "Deactivate a promotion",
+  request: {
+    params: PromotionIdParam,
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PromotionResponseSchema } },
+      description: "Promotion deactivated.",
+    },
+    ...errorResponses,
+  },
+});