@unifiedcommerce/core 0.0.4 → 0.1.1

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

@@ -1,85 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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

@@ -1,104 +0,0 @@
-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

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,56 +0,0 @@
-/**
- * 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

@@ -1,76 +0,0 @@
-/**
- * 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);
-}