@unifiedcommerce/core 0.2.0 → 0.2.1

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

@@ -0,0 +1,93 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { rateLimiter } from "hono-rate-limiter";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { createPromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listActivePromotionsRoute } from "../schemas/promotions.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+import { resolveOrgId } from "../../../auth/org.js";
+
+export function promotionRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // Rate limit promo code validation — prevents brute-force code enumeration
+  router.use(
+    "/validate",
+    rateLimiter({
+      windowMs: 60 * 1000,
+      limit: 10,
+      keyGenerator: (c) => {
+        // Node.js Request has a socket property; Hono types it as unknown.
+        const socket = (c.req.raw as { socket?: { remoteAddress?: string } }).socket;
+        return socket?.remoteAddress ?? "unknown";
+      },
+    }),
+  );
+
+  router.use("/", requirePerm("promotions:manage"));
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (201 | 400 | 422). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(createPromotionRoute, async (c) => {
+    const body = c.req.valid("json");
+    const actor = c.get("actor");
+    const result = await kernel.services.promotions.create(body, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  // List active promotions — requires auth
+  router.use("/active", requirePerm("promotions:read"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listActivePromotionsRoute, async (_c) => {
+    const actor = _c.get("actor");
+    const result = await kernel.services.promotions.listActive(actor);
+    if (!result.ok) {
+      return _c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return _c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (200 | 400 | 404). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(validatePromotionRoute, async (c) => {
+    const payload = c.req.valid("json");
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+
+    const result = await kernel.services.promotions.validate(payload.code, {
+      orgId,
+      currency: payload.currency,
+      subtotal: payload.subtotal,
+      lineItems: payload.lineItems,
+      ...(payload.customerId !== undefined ? { customerId: payload.customerId } : {}),
+      ...(payload.customerGroupIds !== undefined ? { customerGroupIds: payload.customerGroupIds } : {}),
+    });
+
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+
+    return c.json({ data: result.value });
+  });
+
+  router.use("/:id/deactivate", requirePerm("promotions:manage"));
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (200 | 400 | 404). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(deactivatePromotionRoute, async (c) => {
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+    const result = await kernel.services.promotions.deactivate(orgId, c.req.param("id"));
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

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

@@ -0,0 +1,71 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { searchRoute, suggestRoute } from "../schemas/search.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+
+export function searchRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(searchRoute, async (c) => {
+    const q = c.req.query("q") ?? "";
+    const type = c.req.query("type");
+    const category = c.req.query("category");
+    const brand = c.req.query("brand");
+    const status = c.req.query("status");
+    const page = Number.parseInt(c.req.query("page") ?? "1", 10);
+    const limit = Number.parseInt(c.req.query("limit") ?? "20", 10);
+    const facets = (c.req.query("facets") ?? "")
+      .split(",")
+      .map((facet) => facet.trim())
+      .filter(Boolean);
+
+    const result = await kernel.services.search.query({
+      query: q,
+      page,
+      limit,
+      filters: {
+        ...(type ? { type } : {}),
+        ...(category ? { category } : {}),
+        ...(brand ? { brand } : {}),
+        ...(status ? { status } : {}),
+      },
+      ...(facets.length > 0 ? { facets } : {}),
+    }, { actor: c.get("actor"), tx: null, requestId: "" });
+
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+
+    return c.json({
+      data: result.value.hits,
+      meta: {
+        total: result.value.total,
+        page: result.value.page,
+        limit: result.value.limit,
+        facets: result.value.facets,
+      },
+    });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(suggestRoute, async (c) => {
+    const prefix = c.req.query("prefix") ?? "";
+    const type = c.req.query("type");
+    const limit = Number.parseInt(c.req.query("limit") ?? "10", 10);
+
+    const result = await kernel.services.search.suggest({
+      prefix,
+      ...(type ? { type } : {}),
+      limit,
+    }, { actor: c.get("actor"), tx: null, requestId: "" });
+
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

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

@@ -0,0 +1,46 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { createWebhookEndpointRoute, listWebhookEndpointsRoute, deleteWebhookEndpointRoute } from "../schemas/webhooks.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function webhookRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/*", requirePerm("webhooks:manage"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createWebhookEndpointRoute, async (c) => {
+    const body = c.req.valid("json") as Parameters<typeof kernel.services.webhooks.createEndpoint>[0];
+    // Generate a default secret if none provided (Zod schema marks it optional for API convenience)
+    if (!body.secret) {
+      body.secret = `whsec_${crypto.randomUUID().replace(/-/g, "")}`;
+    }
+    const actor = c.get("actor");
+    const result = await kernel.services.webhooks.createEndpoint(body, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listWebhookEndpointsRoute, async (c) => {
+    const result = await kernel.services.webhooks.listEndpoints();
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    const sanitized = result.value.map(({ secret: _secret, ...rest }) => rest);
+    return c.json({ data: sanitized });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteWebhookEndpointRoute, async (c) => {
+    const result = await kernel.services.webhooks.deleteEndpoint(c.req.param("id"));
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: { deleted: true } });
+  });
+
+  return router;
+}

package/src/interfaces/rest/schemas/admin-jobs.ts

@@ -0,0 +1,40 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { JobListResponse } from "./responses.js";
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listFailedJobsRoute = createRoute({
+  method: "get",
+  path: "/jobs/failed",
+  tags: ["Admin Jobs"],
+  summary: "List failed jobs",
+  request: {
+    query: z.object({
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: JobListResponse } },
+      description: "Failed jobs",
+    },
+  },
+});
+
+export const retryJobRoute = createRoute({
+  method: "post",
+  path: "/jobs/{id}/retry",
+  tags: ["Admin Jobs"],
+  summary: "Retry a failed job",
+  request: {
+    params: z.object({
+      id: z.string().min(1).openapi({ example: "job-uuid" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ retried: z.literal(true) }) }) } },
+      description: "Job retried",
+    },
+  },
+});

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

@@ -0,0 +1,46 @@
+import { z, createRoute } from "@hono/zod-openapi";
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listAuditRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Audit"],
+  summary: "List audit entries",
+  request: {
+    query: z.object({
+      entityType: z.string().optional(),
+      entityId: z.string().optional(),
+      event: z.string().optional(),
+      actorId: z.string().optional(),
+      from: z.string().optional(),
+      to: z.string().optional(),
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Audit entries",
+    },
+  },
+});
+
+export const listEntityAuditRoute = createRoute({
+  method: "get",
+  path: "/{entityType}/{entityId}",
+  tags: ["Audit"],
+  summary: "List audit history for a specific entity",
+  request: {
+    params: z.object({
+      entityType: z.string().min(1).openapi({ example: "order" }),
+      entityId: z.string().min(1).openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Entity audit history",
+    },
+  },
+});

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

@@ -0,0 +1,125 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses, UuidParamSchema, DeletedResponseSchema } from "./shared.js";
+import { CartResponse } from "./responses.js";
+import {
+  CreateCartBodySchema,
+  AddCartItemBodySchema,
+  UpdateCartItemQuantityBodySchema,
+} from "../../../modules/cart/schemas.js";
+
+export { CreateCartBodySchema, AddCartItemBodySchema, UpdateCartItemQuantityBodySchema };
+
+// ─── Response Schemas ───────────────────────────────────────────────────────
+
+export const CartResponseSchema = CartResponse;
+
+// ─── Path Params ────────────────────────────────────────────────────────────
+
+const CartIdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+const CartItemParams = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  itemId: z.uuid().openapi({ example: "660e8400-e29b-41d4-a716-446655440000" }),
+});
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const getCartRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Carts"],
+  summary: "Get a cart by ID",
+  request: { params: CartIdParam },
+  responses: {
+    200: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Cart retrieved.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const removeCartItemRoute = createRoute({
+  method: "delete",
+  path: "/{id}/items/{itemId}",
+  tags: ["Carts"],
+  summary: "Remove an item from a cart",
+  request: { params: CartItemParams },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DeletedResponseSchema } },
+      description: "Item removed.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const createCartRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Carts"],
+  summary: "Create a new cart",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: CreateCartBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Cart created successfully.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const addCartItemRoute = createRoute({
+  method: "post",
+  path: "/{id}/items",
+  tags: ["Carts"],
+  summary: "Add an item to a cart",
+  request: {
+    params: CartIdParam,
+    body: {
+      content: {
+        "application/json": { schema: AddCartItemBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Item added to cart.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateCartItemQuantityRoute = createRoute({
+  method: "patch",
+  path: "/{id}/items/{itemId}",
+  tags: ["Carts"],
+  summary: "Update the quantity of a cart line item",
+  request: {
+    params: CartItemParams,
+    body: {
+      content: {
+        "application/json": { schema: UpdateCartItemQuantityBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Cart item quantity updated.",
+    },
+    ...errorResponses,
+  },
+});