@porulle/core 0.1.0

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,116 @@
+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 listPromotionsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Promotions"],
+  summary: "List promotions",
+  description: "Lists promotions. Filter by status: active (currently valid), inactive (deactivated), expired (past validUntil), scheduled (future validFrom). Omit status to return all.",
+  request: {
+    query: z.object({
+      status: z.enum(["active", "inactive", "expired", "scheduled"]).optional().openapi({ example: "active" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Promotions list",
+    },
+  },
+});
+
+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,
+  },
+});

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

@@ -0,0 +1,96 @@
+/**
+ * Typed response schemas derived from Drizzle table definitions.
+ *
+ * Uses drizzle-zod's createSelectSchema() to generate Zod schemas that
+ * match the exact database column types. These replace z.any() in route
+ * response definitions, making the OpenAPI spec show real field names
+ * and types instead of empty {}.
+ */
+
+import { createSelectSchema } from "drizzle-zod";
+import { z } from "@hono/zod-openapi";
+import { orders, orderLineItems } from "../../../modules/orders/schema.js";
+import { carts, cartLineItems } from "../../../modules/cart/schema.js";
+import { customers, customerAddresses } from "../../../modules/customers/schema.js";
+import { sellableEntities } from "../../../modules/catalog/schema.js";
+import { commerceJobs } from "../../../kernel/jobs/schema.js";
+
+// ─── Orders ──────────────────────────────────────────────────────────────────
+
+export const OrderSchema = createSelectSchema(orders, {
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("Order");
+
+export const OrderLineItemSchema = createSelectSchema(orderLineItems, {
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("OrderLineItem");
+
+export const OrderWithItemsSchema = z.object({
+  ...OrderSchema.shape,
+  lineItems: z.array(OrderLineItemSchema).optional(),
+}).openapi("OrderWithItems");
+
+// ─── Carts ───────────────────────────────────────────────────────────────────
+
+export const CartSchema = createSelectSchema(carts, {
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("Cart");
+
+export const CartLineItemSchema = createSelectSchema(cartLineItems, {
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CartLineItem");
+
+export const CartWithItemsSchema = z.object({
+  ...CartSchema.shape,
+  lineItems: z.array(CartLineItemSchema).optional(),
+}).openapi("CartWithItems");
+
+// ─── Customers ───────────────────────────────────────────────────────────────
+
+export const CustomerSchema = createSelectSchema(customers).openapi("Customer");
+
+export const CustomerAddressSchema = createSelectSchema(customerAddresses).openapi("CustomerAddress");
+
+// ─── Catalog ─────────────────────────────────────────────────────────────────
+
+export const CatalogEntitySchema = createSelectSchema(sellableEntities, {
+  // Override jsonb → narrow to object (drizzle-zod maps jsonb to a wide union)
+  metadata: z.record(z.string(), z.unknown()).openapi({ example: { weight: 200, material: "cotton" } }),
+}).openapi("CatalogEntity");
+
+// ─── Jobs ────────────────────────────────────────────────────────────────────
+
+export const JobSchema = createSelectSchema(commerceJobs).openapi("Job");
+
+// ─── Wrapped Response Helpers ────────────────────────────────────────────────
+// These wrap a schema in { data: T } for consistent API response format.
+
+export function dataResponse<T extends z.ZodType>(schema: T, name: string) {
+  return z.object({ data: schema }).openapi(name);
+}
+
+export function dataArrayResponse<T extends z.ZodType>(schema: T, name: string) {
+  return z.object({ data: z.array(schema) }).openapi(name);
+}
+
+export function paginatedResponse<T extends z.ZodType>(schema: T, name: string) {
+  return z.object({
+    data: z.array(schema),
+    meta: z.object({
+      page: z.number(),
+      limit: z.number(),
+      total: z.number().optional(),
+    }).optional(),
+  }).openapi(name);
+}
+
+// ─── Pre-built Response Schemas ──────────────────────────────────────────────
+
+export const OrderResponse = dataResponse(OrderSchema, "OrderResponse");
+export const OrderListResponse = paginatedResponse(OrderSchema, "OrderListResponse");
+export const CartResponse = dataResponse(CartWithItemsSchema, "CartResponse");
+export const CustomerResponse = dataResponse(CustomerSchema, "CustomerResponse");
+export const CustomerAddressListResponse = dataArrayResponse(CustomerAddressSchema, "CustomerAddressListResponse");
+export const CatalogEntityResponse = dataResponse(CatalogEntitySchema, "CatalogEntityResponse");
+export const CatalogEntityListResponse = paginatedResponse(CatalogEntitySchema, "CatalogEntityListResponse");
+export const JobListResponse = dataArrayResponse(JobSchema, "JobListResponse");

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

@@ -0,0 +1,58 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { CatalogEntitySchema } from "./responses.js";
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const searchRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Search"],
+  summary: "Search catalog entities",
+  request: {
+    query: z.object({
+      q: z.string().max(500).optional(),
+      type: z.string().max(100).optional(),
+      category: z.string().max(200).optional(),
+      brand: z.string().max(200).optional(),
+      status: z.string().max(50).optional(),
+      page: z.string().max(10).optional(),
+      limit: z.string().max(10).optional(),
+      facets: z.string().max(500).optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({
+        data: z.array(CatalogEntitySchema),
+        meta: z.object({
+          pagination: z.object({
+            page: z.number(),
+            limit: z.number(),
+            total: z.number().optional(),
+          }),
+        }).optional(),
+      }) } },
+      description: "Search results",
+    },
+  },
+});
+
+export const suggestRoute = createRoute({
+  method: "get",
+  path: "/suggest",
+  tags: ["Search"],
+  summary: "Get search suggestions",
+  request: {
+    query: z.object({
+      prefix: z.string().max(200).optional(),
+      type: z.string().max(100).optional(),
+      limit: z.string().max(10).optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.object({ id: z.string(), slug: z.string(), title: z.string().optional() })) }) } },
+      description: "Suggestions",
+    },
+  },
+});

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

@@ -0,0 +1,62 @@
+import { z } from "@hono/zod-openapi";
+
+// ─── Error Response ──────────────────────────────────────────────────────────
+
+export const ErrorSchema = z.object({
+  error: z.object({
+    code: z.string().openapi({ example: "VALIDATION_FAILED" }),
+    message: z.string().openapi({ example: "cartId: Invalid uuid" }),
+  }),
+}).openapi("Error");
+
+// ─── Pagination ──────────────────────────────────────────────────────────────
+
+export const PaginationQuerySchema = z.object({
+  page: z.string().optional().openapi({ example: "1" }),
+  limit: z.string().optional().openapi({ example: "20" }),
+});
+
+export const PaginationMetaSchema = z.object({
+  page: z.number(),
+  limit: z.number(),
+  total: z.number().optional(),
+}).openapi("PaginationMeta");
+
+// ─── Common Params ───────────────────────────────────────────────────────────
+
+export const UuidParamSchema = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+export const IdOrSlugParamSchema = z.object({
+  idOrSlug: z.string().min(1).openapi({ example: "my-product" }),
+});
+
+// ─── Common Responses ────────────────────────────────────────────────────────
+
+export const DeletedResponseSchema = z.object({
+  data: z.object({ deleted: z.literal(true) }),
+}).openapi("DeletedResponse");
+
+export const errorResponses = {
+  400: {
+    content: { "application/json": { schema: ErrorSchema } },
+    description: "Business logic error.",
+  },
+  401: {
+    content: { "application/json": { schema: ErrorSchema } },
+    description: "Authentication required.",
+  },
+  403: {
+    content: { "application/json": { schema: ErrorSchema } },
+    description: "Insufficient permissions.",
+  },
+  404: {
+    content: { "application/json": { schema: ErrorSchema } },
+    description: "Resource not found.",
+  },
+  422: {
+    content: { "application/json": { schema: ErrorSchema } },
+    description: "Validation error.",
+  },
+} as const;

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

@@ -0,0 +1,68 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses } from "./shared.js";
+
+// ─── Request Schema ──────────────────────────────────────────────────────────
+
+export const CreateWebhookEndpointBodySchema = z.object({
+  url: z.string().url().openapi({ example: "https://example.com/webhooks" }),
+  events: z.array(z.string()).openapi({ example: ["order.created", "order.fulfilled"] }),
+  secret: z.string().optional().openapi({ example: "whsec_abc123" }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateWebhookEndpointRequest");
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listWebhookEndpointsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Webhooks"],
+  summary: "List webhook endpoints",
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Webhook endpoints",
+    },
+  },
+});
+
+export const deleteWebhookEndpointRoute = createRoute({
+  method: "delete",
+  path: "/{id}",
+  tags: ["Webhooks"],
+  summary: "Delete a webhook endpoint",
+  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: "Webhook endpoint deleted.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const createWebhookEndpointRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Webhooks"],
+  summary: "Create a webhook endpoint",
+  description: "Registers a new webhook endpoint that will receive event notifications.",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: CreateWebhookEndpointBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Webhook endpoint created.",
+    },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/utils.ts

@@ -0,0 +1,104 @@
+import type { CommerceError } from "../../kernel/errors.js";
+import { mapErrorToStatus } from "../../kernel/error-mapper.js";
+import { toCommerceError } from "../../kernel/errors.js";
+import type { Actor } from "../../auth/types.js";
+
+/**
+ * Shared Hono environment type for all sub-routers.
+ * Matches the Variables set by middleware in the top-level server app.
+ */
+export type AppEnv = {
+  Variables: {
+    actor: Actor | null;
+    requestId: string;
+    logger: unknown;
+    kernel: unknown;
+  };
+};
+
+const MAX_PAGE_LIMIT = 100;
+
+export function parsePagination(query: Record<string, string | undefined>): {
+  page: number;
+  limit: number;
+} {
+  const page = Number.parseInt(query.page ?? "1", 10);
+  const limit = Number.parseInt(query.limit ?? "20", 10);
+  return {
+    page: Number.isFinite(page) && page > 0 ? page : 1,
+    limit: Math.min(MAX_PAGE_LIMIT, Number.isFinite(limit) && limit > 0 ? limit : 20),
+  };
+}
+
+export function parseInclude(value?: string): Set<string> {
+  if (!value) return new Set();
+  return new Set(
+    value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Map an error to a safe client response. Internal errors are sanitized
+ * to prevent leaking SQL, schema, or stack trace details.
+ */
+export function mapErrorToResponse(error: unknown): { error: { code: string; message: string } } {
+  const ce = toCommerceError(error);
+  if (ce.code === "INTERNAL_ERROR") {
+    // Sanitize internal errors -- do not expose raw messages to clients
+    return { error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } };
+  }
+  return { error: { code: ce.code, message: ce.message } };
+}
+
+export { mapErrorToStatus };
+
+/**
+ * Hono middleware that requires a specific permission on the actor.
+ * Returns 401 if no actor, 403 if permission denied.
+ * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
+ */
+export function requirePerm(permission: string) {
+  return async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
+    const actor = c.get("actor") as { permissions?: string[] } | null;
+    if (!actor) {
+      return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+    }
+    const perms = actor.permissions ?? [];
+    if (perms.includes(permission) || perms.includes("*:*")) {
+      await next();
+      return;
+    }
+    // Check resource-level wildcard (e.g., "catalog:*" matches "catalog:create")
+    const [resource] = permission.split(":");
+    if (resource && perms.includes(`${resource}:*`)) {
+      await next();
+      return;
+    }
+    return c.json({ error: { code: "FORBIDDEN", message: `Permission '${permission}' is required.` } }, 403);
+  };
+}
+
+export function parseSort(
+  value?: string,
+):
+  | {
+  field: "createdAt" | "updatedAt" | "slug";
+  direction: "asc" | "desc";
+}
+  | undefined {
+  if (!value) return undefined;
+  const [fieldRaw, directionRaw] = value.split(":");
+  const selectedField = fieldRaw ?? "createdAt";
+  const field = ["createdAt", "updatedAt", "slug"].includes(selectedField)
+    ? (selectedField as "createdAt" | "updatedAt" | "slug")
+    : "createdAt";
+  const direction = directionRaw === "asc" ? "asc" : "desc";
+  return { field, direction };
+}
+
+export function isUUID(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}

package/src/interfaces/rest/webhook-router.ts

@@ -0,0 +1,50 @@
+/**
+ * webhookRouter() — route builder for external webhook receivers.
+ *
+ * Unlike router() which uses UC authentication (.auth(), .permission()),
+ * webhookRouter() uses HMAC signature verification. This is for routes
+ * that receive callbacks from external services (Shopify, WooCommerce,
+ * Stripe, BNPL providers) that authenticate via provider-specific signatures.
+ *
+ * Provides typed access to kernel.services, kernel.database.db, and
+ * kernel.logger without casting through `unknown`.
+ *
+ * Usage:
+ *
+ *   import { webhookRouter } from "@porulle/core";
+ *
+ *   export function createMyWebhookRoutes(kernel: Kernel) {
+ *     const { app, services, db, logger } = webhookRouter(kernel);
+ *
+ *     app.post("/product-updated", async (c) => {
+ *       const body = await c.req.json();
+ *       await services.catalog.update(body.id, { ... }, systemActor);
+ *       return c.json({ status: "ok" });
+ *     });
+ *
+ *     return app;
+ *   }
+ */
+
+import { Hono } from "hono";
+import type { Kernel } from "../../runtime/kernel.js";
+
+export interface WebhookRouterResult {
+  /** Raw Hono app — mount routes on this. No UC auth middleware attached. */
+  app: Hono;
+  /** Kernel services (catalog, inventory, orders, etc.). Typed properly. */
+  services: Kernel["services"];
+  /** Drizzle database instance for direct queries. */
+  db: Kernel["database"]["db"];
+  /** Structured Pino logger. */
+  logger: Kernel["logger"];
+}
+
+export function webhookRouter(kernel: Kernel): WebhookRouterResult {
+  return {
+    app: new Hono(),
+    services: kernel.services,
+    db: kernel.database.db,
+    logger: kernel.logger,
+  };
+}