@unifiedcommerce/core 0.2.0 → 0.2.2

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

@@ -0,0 +1,85 @@
+/**
+ * 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).openapi("Order");
+
+export const OrderLineItemSchema = createSelectSchema(orderLineItems).openapi("OrderLineItem");
+
+export const OrderWithItemsSchema = z.object({
+  ...OrderSchema.shape,
+  lineItems: z.array(OrderLineItemSchema).optional(),
+}).openapi("OrderWithItems");
+
+// ─── Carts ───────────────────────────────────────────────────────────────────
+
+export const CartSchema = createSelectSchema(carts).openapi("Cart");
+
+export const CartLineItemSchema = createSelectSchema(cartLineItems).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).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().optional(),
+      type: z.string().optional(),
+      category: z.string().optional(),
+      brand: z.string().optional(),
+      status: z.string().optional(),
+      page: z.string().optional(),
+      limit: z.string().optional(),
+      facets: z.string().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().optional(),
+      type: z.string().optional(),
+      limit: z.string().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 "@unifiedcommerce/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,
+  };
+}

package/src/kernel/compensation/executor.ts

@@ -0,0 +1,61 @@
+import type { CompensationContext, Step } from "./types.js";
+import type { Result } from "../result.js";
+
+/**
+ * AnyStep erases the output type parameter so that heterogeneous step
+ * arrays can be passed to runCompensationChain without variance issues
+ * under exactOptionalPropertyTypes.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- erases output type for heterogeneous step arrays; unknown breaks contravariance on compensate()
+type AnyStep<TInput> = Step<TInput, any>;
+
+/**
+ * Runs a list of steps in order. If any step fails, compensates all
+ * previously completed steps in reverse. Steps share the same input
+ * object (they may mutate it to enrich downstream steps, following
+ * the same pattern established by BeforeHooks).
+ *
+ * Compensation failures are logged but do not override the original error.
+ * A failed compensation is a separate operational concern that requires
+ * manual review — it should never mask the root cause returned to the caller.
+ */
+export async function runCompensationChain<TInput>(
+  steps: ReadonlyArray<AnyStep<TInput>>,
+  input: TInput,
+  ctx: CompensationContext,
+): Promise<Result<TInput>> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches AnyStep output erasure
+  const completed: Array<{ step: AnyStep<TInput>; output: any }> = [];
+
+  for (const step of steps) {
+    const result = await step.run(input, ctx);
+
+    if (!result.ok) {
+      ctx.hook.logger.error(
+        `Compensation chain failed at step "${step.id}". ` +
+          `Running ${completed.length} compensation(s).`,
+        { error: result.error },
+      );
+
+      // Compensate in reverse order — most recently completed step first
+      for (const done of [...completed].reverse()) {
+        if (!done.step.compensate) continue;
+        try {
+          await done.step.compensate(done.output, ctx);
+          ctx.hook.logger.info(`Compensated step "${done.step.id}"`);
+        } catch (compensateError) {
+          ctx.hook.logger.error(
+            `Compensation for step "${done.step.id}" failed. Manual review required.`,
+            { compensateError },
+          );
+        }
+      }
+
+      return result;
+    }
+
+    completed.push({ step, output: result.value });
+  }
+
+  return { ok: true, value: input };
+}

package/src/kernel/compensation/types.ts

@@ -0,0 +1,26 @@
+import type { TxContext } from "../database/tx-context.js";
+import type { HookContext } from "../hooks/types.js";
+import type { Result } from "../result.js";
+
+/**
+ * CompensationContext carries the transaction and hook context into
+ * both the run and compensate functions. Steps have access to services,
+ * the actor, and the logger through ctx.hook.
+ */
+export interface CompensationContext {
+  tx: TxContext | null;
+  hook: HookContext;
+}
+
+/**
+ * A Step is one unit of work in a compensation chain.
+ *
+ * TInput is the data the step receives (typically the shared checkout data object).
+ * TOutput is what the step produces. This same value is passed to compensate()
+ * so the compensate function has everything it needs to reverse the work.
+ */
+export interface Step<TInput, TOutput> {
+  id: string;
+  run: (input: TInput, ctx: CompensationContext) => Promise<Result<TOutput>>;
+  compensate?: (output: TOutput, ctx: CompensationContext) => Promise<void>;
+}

package/src/kernel/database/adapter.ts

@@ -0,0 +1,21 @@
+/**
+ * Database adapter interface for the commerce engine.
+ *
+ * Generic defaults to `unknown` so that any driver-specific adapter
+ * (postgres-js, PGlite, etc.) can implement it without type conflicts.
+ * Internal code narrows to `PluginDb` at the consumption site — see
+ * PluginContext in manifest.ts and createHookContext.
+ */
+export interface DatabaseAdapter<TDatabase = unknown, TTransaction = unknown> {
+  provider: string;
+  db: TDatabase;
+  transaction<T>(fn: (tx: TTransaction) => Promise<T>): Promise<T>;
+}
+
+export interface DatabaseConnectionFactoryInput {
+  adapter: DatabaseAdapter;
+}
+
+export function createDatabaseConnection(input: DatabaseConnectionFactoryInput): DatabaseAdapter {
+  return input.adapter;
+}

package/src/kernel/database/drizzle-db.ts

@@ -0,0 +1,56 @@
+/**
+ * Drizzle Database Type Definitions
+ *
+ * This module provides type-safe, driver-agnostic database access for
+ * PostgreSQL repositories.
+ *
+ * We use `PgDatabase` from `drizzle-orm/pg-core` — the base class that all
+ * PostgreSQL drivers extend (postgres-js, pglite, node-postgres, bun-sql).
+ * This means:
+ *
+ * - Repositories accept any PG driver without casts
+ * - PGlite in tests and postgres-js in production use the same type
+ * - Row types are fully inferred from pgTable schema definitions
+ * - No coupling to any specific driver package
+ */
+
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import * as schema from "./schema.js";
+
+/**
+ * Combined schema type for type inference
+ */
+export type Schema = typeof schema;
+
+/**
+ * Driver-agnostic PostgreSQL database instance with full schema type
+ * information.
+ *
+ * Both `PostgresJsDatabase<Schema>` and `PgliteDatabase<Schema>` are
+ * assignable to this type, so repositories work identically in production
+ * and tests without any casts.
+ */
+export type DrizzleDatabase = PgDatabase<PgQueryResultHKT, Schema>;
+
+/**
+ * Transaction type extracted from the database type.
+ * Used when operating within a transaction context.
+ *
+ * This type is derived from the transaction callback parameter:
+ * db.transaction(async (tx) => { ... })
+ *                       ^^-- This is DrizzleTx
+ */
+export type DrizzleTx = Parameters<
+  Parameters<DrizzleDatabase["transaction"]>[0]
+>[0];
+
+/**
+ * Union type for database or transaction - repositories can accept either.
+ * Both have the same query builder interface.
+ */
+export type DbOrTx = DrizzleDatabase | DrizzleTx;
+
+/**
+ * Re-export schema for convenience
+ */
+export { schema };

package/src/kernel/database/migrate.ts

@@ -0,0 +1,76 @@
+/**
+ * Programmatic database schema management.
+ *
+ * For npm consumers who don't have access to the raw .ts schema files,
+ * this module provides:
+ *
+ * 1. `getSchemaFiles()` — returns schema module paths for use in drizzle.config.ts
+ * 2. `getSchema()` — returns the combined Drizzle schema object
+ * 3. `pushSchema()` — programmatic push (creates tables if not exist)
+ *
+ * Usage in consumer's drizzle.config.ts:
+ *
+ *   import { getSchema } from "@unifiedcommerce/core";
+ *   import { defineConfig } from "drizzle-kit";
+ *
+ *   export default defineConfig({
+ *     dialect: "postgresql",
+ *     schema: getSchema(),
+ *     dbCredentials: { url: process.env.DATABASE_URL! },
+ *   });
+ */
+
+import type { CommerceConfig } from "../../config/types.js";
+import * as schema from "./schema.js";
+
+/**
+ * Returns the combined Drizzle schema object with all table definitions.
+ * Use this in your own drizzle.config.ts or for programmatic schema inspection.
+ */
+export function getSchema() {
+  return schema;
+}
+
+/**
+ * Returns core schema merged with all plugin schemas from `config.customSchemas[]`.
+ * Throws if a plugin table name collides with a core table name.
+ */
+export function buildSchema(config?: CommerceConfig): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...schema };
+
+  if (!config?.customSchemas?.length) return merged;
+
+  const coreKeys = new Set(Object.keys(schema));
+
+  for (const pluginSchema of config.customSchemas) {
+    for (const [key, value] of Object.entries(pluginSchema)) {
+      if (coreKeys.has(key)) {
+        throw new Error(
+          `Plugin schema name collision: "${key}" already exists in core schema`,
+        );
+      }
+      if (key in merged) {
+        throw new Error(
+          `Plugin schema name collision: "${key}" is defined by multiple plugins`,
+        );
+      }
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Returns a list of all schema table names defined by the commerce engine.
+ */
+export function getTableNames(): string[] {
+  return Object.entries(schema)
+    .filter(
+      ([_, value]) =>
+        value != null &&
+        typeof value === "object" &&
+        "getSQL" in (value as object),
+    )
+    .map(([key]) => key);
+}