@unifiedcommerce/core 0.2.0 → 0.2.1

package/src/kernel/database/plugin-types.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonical database types for plugin service constructors.
+ *
+ * Replaces the copy-pasted type definitions in every plugin's types.ts:
+ *   type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>
+ *
+ * Import from core instead:
+ *   import type { PluginDb, PluginTxFn } from "@unifiedcommerce/core";
+ */
+
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+
+/**
+ * Database instance type for plugin services.
+ * This is the Drizzle PgDatabase with an opaque schema record.
+ */
+export type PluginDb = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+
+/**
+ * Transaction function type for plugin services that need
+ * transactional guarantees (e.g., POS transaction complete,
+ * gift card debit, inventory reservation).
+ *
+ * Usage:
+ *   constructor(private db: PluginDb, private txFn: PluginTxFn) {}
+ *
+ *   async doWork() {
+ *     return this.txFn(async (tx) => {
+ *       await tx.insert(...).values(...);
+ *       await tx.update(...).set(...);
+ *     });
+ *   }
+ */
+export type PluginTxFn = <T>(fn: (tx: PluginDb) => Promise<T>) => Promise<T>;

package/src/kernel/database/schema.ts

@@ -0,0 +1,49 @@
+/**
+ * Combined schema barrel for Drizzle.
+ *
+ * Single source of truth for all core table definitions. Both drizzle-kit
+ * (via drizzle.config.ts) and the TypeScript type system consume this file.
+ *
+ * Drizzle-kit resolves re-exports, so pointing the config schema option
+ * at this one file discovers every core table. Plugin schemas live in
+ * their own packages and are referenced via glob patterns.
+ */
+
+// Auth (Better Auth generated tables)
+export * from "../../auth/auth-schema.js";
+
+// Catalog module
+export * from "../../modules/catalog/schema.js";
+
+// Inventory module
+export * from "../../modules/inventory/schema.js";
+
+// Cart module
+export * from "../../modules/cart/schema.js";
+
+// Orders module
+export * from "../../modules/orders/schema.js";
+
+// Customers module
+export * from "../../modules/customers/schema.js";
+
+// Pricing module
+export * from "../../modules/pricing/schema.js";
+
+// Promotions module
+export * from "../../modules/promotions/schema.js";
+
+// Media module
+export * from "../../modules/media/schema.js";
+
+// Webhooks module
+export * from "../../modules/webhooks/schema.js";
+
+// Fulfillment module
+export * from "../../modules/fulfillment/schema.js";
+
+// Jobs (kernel)
+export * from "../jobs/schema.js";
+
+// Audit module
+export * from "../../modules/audit/schema.js";

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

@@ -0,0 +1,68 @@
+/**
+ * Scoped DB Proxy
+ *
+ * Wraps a Drizzle PgDatabase instance so that INSERT operations on
+ * org-scoped tables automatically include the actor's organizationId.
+ *
+ * Plugin route handlers receive this scoped db via the router() builder.
+ * They write normal Drizzle inserts without ever mentioning organizationId:
+ *
+ *   const [card] = await db.insert(giftCards)
+ *     .values({ code: "ABC", balance: 5000 })
+ *     .returning();
+ *   // organizationId is auto-set from the actor context
+ *
+ * SELECT/UPDATE/DELETE scoping is handled at the repository/service layer
+ * via resolveOrgId(). The proxy focuses on INSERT auto-stamping because
+ * that is the operation most commonly forgotten by plugin developers.
+ */
+
+import { getTableColumns } from "drizzle-orm";
+import type { PgTable } from "drizzle-orm/pg-core";
+
+function isOrgScoped(table: PgTable): boolean {
+  const columns = getTableColumns(table);
+  return "organizationId" in columns;
+}
+
+export function createScopedDb<TDb>(rawDb: TDb, organizationId: string): TDb {
+  if (!rawDb || typeof rawDb !== "object") return rawDb;
+
+  return new Proxy(rawDb as Record<string, unknown>, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+
+      if (prop === "insert" && typeof value === "function") {
+        return (table: PgTable) => {
+          const builder = value.call(target, table);
+          if (!isOrgScoped(table)) return builder;
+
+          // Wrap .values() to auto-inject organizationId
+          const originalValues = (builder as Record<string, unknown>).values;
+          if (typeof originalValues !== "function") return builder;
+
+          return new Proxy(builder as Record<string, unknown>, {
+            get(t, p, r) {
+              if (p === "values") {
+                return (data: unknown) => {
+                  const stamp = (row: Record<string, unknown>) => ({
+                    ...row,
+                    organizationId,
+                  });
+                  const stamped = Array.isArray(data)
+                    ? data.map(stamp)
+                    : stamp(data as Record<string, unknown>);
+                  return originalValues.call(t, stamped);
+                };
+              }
+              const v = Reflect.get(t, p, r);
+              return typeof v === "function" ? v.bind(t) : v;
+            },
+          });
+        };
+      }
+
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as TDb;
+}

package/src/kernel/database/tx-context.ts

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+import type { Actor } from "../../auth/types.js";
+import type { DatabaseAdapter } from "./adapter.js";
+
+export interface TxContext<TTx = unknown> {
+  tx: TTx;
+  actor: Actor | null;
+  requestId: string;
+}
+
+export interface WithTransactionOptions {
+  actor: Actor | null;
+  requestId?: string;
+}
+
+export function createTxContext<TTx>(
+  tx: TTx,
+  options: WithTransactionOptions,
+): TxContext<TTx> {
+  return {
+    tx,
+    actor: options.actor,
+    requestId: options.requestId ?? randomUUID(),
+  };
+}
+
+export async function withTransaction<TDb, TTx, TResult>(
+  database: DatabaseAdapter<TDb, TTx>,
+  options: WithTransactionOptions,
+  fn: (ctx: TxContext<TTx>) => Promise<TResult>,
+): Promise<TResult> {
+  return database.transaction(async (tx) => {
+    return fn(createTxContext(tx, options));
+  });
+}
+
+export function reuseOrCreateTxContext<TTx>(
+  tx: TTx,
+  options: WithTransactionOptions,
+  existing?: TxContext<TTx> | null,
+): TxContext<TTx> {
+  if (existing) {
+    return existing;
+  }
+  return createTxContext(tx, options);
+}

package/src/kernel/error-mapper.ts

@@ -0,0 +1,15 @@
+import { toCommerceError } from "./errors.js";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+const statusByCode: Record<string, ContentfulStatusCode> = {
+  NOT_FOUND: 404,
+  VALIDATION_FAILED: 422,
+  FORBIDDEN: 403,
+  CONFLICT: 409,
+  INVALID_TRANSITION: 422,
+};
+
+export function mapErrorToStatus(error: unknown): ContentfulStatusCode {
+  const normalized = toCommerceError(error);
+  return statusByCode[normalized.code] ?? 500;
+}

package/src/kernel/errors.ts

@@ -0,0 +1,89 @@
+export interface CommerceError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+export interface FieldError {
+  field: string;
+  message: string;
+}
+
+export class CommerceNotFoundError extends Error implements CommerceError {
+  code = "NOT_FOUND" as const;
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceNotFoundError";
+  }
+}
+
+export class CommerceValidationError extends Error implements CommerceError {
+  code = "VALIDATION_FAILED" as const;
+  constructor(
+    message: string,
+    public fieldErrors?: FieldError[],
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceValidationError";
+  }
+}
+
+export class CommerceForbiddenError extends Error implements CommerceError {
+  code = "FORBIDDEN" as const;
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceForbiddenError";
+  }
+}
+
+export class CommerceConflictError extends Error implements CommerceError {
+  code = "CONFLICT" as const;
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceConflictError";
+  }
+}
+
+export class CommerceInvalidTransitionError extends Error implements CommerceError {
+  code = "INVALID_TRANSITION" as const;
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceInvalidTransitionError";
+  }
+}
+
+export function isCommerceError(value: unknown): value is CommerceError {
+  if (!value || typeof value !== "object") return false;
+  return "code" in value && "message" in value;
+}
+
+export function toCommerceError(error: unknown): CommerceError {
+  if (isCommerceError(error)) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return {
+      code: "INTERNAL_ERROR",
+      message: error.message,
+      details: { name: error.name },
+    };
+  }
+  return {
+    code: "INTERNAL_ERROR",
+    message: "Unexpected server error",
+    details: error,
+  };
+}

package/src/kernel/factory/repository-factory.ts

@@ -0,0 +1,244 @@
+import {
+  eq,
+  and,
+  isNull,
+  sql,
+  getTableColumns,
+  type SQL,
+  type Column,
+  type InferSelectModel,
+  type InferInsertModel,
+} from "drizzle-orm";
+import type { PgTableWithColumns, TableConfig } from "drizzle-orm/pg-core";
+import { PgTable } from "drizzle-orm/pg-core";
+import type { TxContext } from "../database/tx-context.js";
+import type { DrizzleDatabase, DbOrTx } from "../database/drizzle-db.js";
+import { CommerceNotFoundError } from "../errors.js";
+
+/**
+ * Filter type — partial record of column values to match with eq().
+ * Only keys that exist on TRow and have non-undefined values are used.
+ */
+export type Filters<TRow> = Partial<TRow>;
+
+/**
+ * Options for findMany / findAndCount queries.
+ */
+export interface FindOptions {
+  limit?: number;
+  offset?: number;
+  orderBy?: Array<{ column: string; direction: "asc" | "desc" }>;
+  withDeleted?: boolean;
+}
+
+/**
+ * Standard CRUD operations derived from a Drizzle pgTable schema.
+ * All methods support optional TxContext for transaction participation.
+ */
+export interface BaseRepository<TRow, TInsert> {
+  findById(id: string, ctx?: TxContext): Promise<TRow | undefined>;
+  findMany(
+    filters?: Filters<TRow>,
+    options?: FindOptions,
+    ctx?: TxContext,
+  ): Promise<TRow[]>;
+  findAndCount(
+    filters?: Filters<TRow>,
+    options?: FindOptions,
+    ctx?: TxContext,
+  ): Promise<{ rows: TRow[]; total: number }>;
+  create(data: TInsert, ctx?: TxContext): Promise<TRow>;
+  createMany(data: TInsert[], ctx?: TxContext): Promise<TRow[]>;
+  update(id: string, data: Partial<TInsert>, ctx?: TxContext): Promise<TRow>;
+  delete(id: string, ctx?: TxContext): Promise<void>;
+}
+
+/**
+ * Extended repository for tables with a `deleted_at` column.
+ * Adds softDelete and restore operations.
+ */
+export interface SoftDeletableRepository<TRow, TInsert>
+  extends BaseRepository<TRow, TInsert> {
+  softDelete(id: string, ctx?: TxContext): Promise<void>;
+  restore(id: string, ctx?: TxContext): Promise<TRow>;
+}
+
+/**
+ * Type-level check: does the table config have a `deletedAt` or `deleted_at` column?
+ */
+type HasDeletedAt<T extends PgTableWithColumns<TableConfig>> =
+  "deletedAt" extends keyof T ? true : "deleted_at" extends keyof T ? true : false;
+
+/**
+ * Conditional repository type: if the table has a deleted_at column,
+ * return SoftDeletableRepository; otherwise BaseRepository.
+ */
+export type RepositoryFor<T extends PgTableWithColumns<TableConfig>> =
+  HasDeletedAt<T> extends true
+    ? SoftDeletableRepository<InferSelectModel<T>, InferInsertModel<T>>
+    : BaseRepository<InferSelectModel<T>, InferInsertModel<T>>;
+
+/**
+ * Creates a typed repository with standard CRUD operations from a Drizzle table schema.
+ *
+ * Usage:
+ * ```typescript
+ * const repo = createRepository(schema.promotions, db)
+ * const row = await repo.findById("abc-123")
+ * const rows = await repo.findMany({ status: "active" }, { limit: 10 })
+ * ```
+ *
+ * Tables with a `deletedAt` column automatically get `softDelete()` and `restore()`.
+ * Domain-specific queries should remain in dedicated repository classes that
+ * delegate standard CRUD to the factory-created instance.
+ */
+export function createRepository<T extends PgTableWithColumns<TableConfig>>(
+  table: T,
+  db: DrizzleDatabase,
+): RepositoryFor<T> {
+  // Use getTableColumns for type-safe column access
+  const columns = getTableColumns(table) as Record<string, Column>;
+
+  // Runtime check for soft-delete column
+  const hasSoftDelete = "deletedAt" in columns || "deleted_at" in columns;
+  const deletedAtColumn: Column | null =
+    columns["deletedAt"] ?? columns["deleted_at"] ?? null;
+  const idColumn = columns["id"]!;
+
+  // Drizzle's generic types require PgTable at the boundary.
+  // We cast once here rather than at every call site.
+  const pgTable = table as PgTable;
+
+  function getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? db;
+  }
+
+  function buildWhereConditions(
+    filters?: Filters<InferSelectModel<T>>,
+    includeDeleted = false,
+  ): SQL[] {
+    const conditions: SQL[] = [];
+
+    // Automatically exclude soft-deleted rows unless explicitly requested
+    if (hasSoftDelete && !includeDeleted && deletedAtColumn) {
+      conditions.push(isNull(deletedAtColumn));
+    }
+
+    if (filters) {
+      for (const [key, value] of Object.entries(filters)) {
+        const col = columns[key];
+        if (value !== undefined && col) {
+          conditions.push(eq(col, value));
+        }
+      }
+    }
+
+    return conditions;
+  }
+
+  const repo: BaseRepository<InferSelectModel<T>, InferInsertModel<T>> = {
+    async findById(id, ctx) {
+      const conditions = buildWhereConditions(undefined, false);
+      conditions.push(eq(idColumn, id));
+      const rows = await getDb(ctx)
+        .select()
+        .from(pgTable)
+        .where(and(...conditions));
+      return rows[0] as InferSelectModel<T> | undefined;
+    },
+
+    async findMany(filters, options = {}, ctx) {
+      const conditions = buildWhereConditions(filters, options.withDeleted);
+      let query = getDb(ctx).select().from(pgTable).$dynamic();
+      if (conditions.length > 0) {
+        query = query.where(and(...conditions));
+      }
+      if (options.limit !== undefined) {
+        query = query.limit(options.limit);
+      }
+      if (options.offset !== undefined) {
+        query = query.offset(options.offset);
+      }
+      // Drizzle's $dynamic() erases the row type when using PgTable.
+      // Use .then() to narrow the resolved array type with a single cast.
+      return query.then((rows) => rows as InferSelectModel<T>[]);
+    },
+
+    async findAndCount(filters, options = {}, ctx) {
+      const rows = await repo.findMany(filters, options, ctx);
+      const conditions = buildWhereConditions(filters, options.withDeleted);
+      let countQuery = getDb(ctx)
+        .select({ count: sql<number>`count(*)::int` })
+        .from(pgTable)
+        .$dynamic();
+      if (conditions.length > 0) {
+        countQuery = countQuery.where(and(...conditions));
+      }
+      const countResult = await countQuery;
+      return { rows, total: countResult[0]?.count ?? 0 };
+    },
+
+    async create(data, ctx) {
+      const rows = await getDb(ctx)
+        .insert(pgTable)
+        .values(data as Record<string, unknown>)
+        .returning();
+      return rows[0] as InferSelectModel<T>;
+    },
+
+    async createMany(data, ctx) {
+      if (data.length === 0) return [];
+      const rows = await getDb(ctx)
+        .insert(pgTable)
+        .values(data as Record<string, unknown>[])
+        .returning();
+      return rows as InferSelectModel<T>[];
+    },
+
+    async update(id, data, ctx) {
+      const rows = await getDb(ctx)
+        .update(pgTable)
+        .set(data as Record<string, unknown>)
+        .where(eq(idColumn, id))
+        .returning();
+      if (!rows[0]) {
+        throw new CommerceNotFoundError(`Record ${id} not found.`);
+      }
+      return rows[0] as InferSelectModel<T>;
+    },
+
+    async delete(id, ctx) {
+      await getDb(ctx).delete(pgTable).where(eq(idColumn, id));
+    },
+  };
+
+  if (hasSoftDelete && deletedAtColumn) {
+    const softRepo = repo as SoftDeletableRepository<
+      InferSelectModel<T>,
+      InferInsertModel<T>
+    >;
+
+    softRepo.softDelete = async (id, ctx) => {
+      await getDb(ctx)
+        .update(pgTable)
+        .set({ deletedAt: new Date() } as Record<string, unknown>)
+        .where(eq(idColumn, id));
+    };
+
+    softRepo.restore = async (id, ctx) => {
+      const rows = await getDb(ctx)
+        .update(pgTable)
+        .set({ deletedAt: null } as Record<string, unknown>)
+        .where(eq(idColumn, id))
+        .returning();
+      if (!rows[0]) {
+        throw new CommerceNotFoundError(`Record ${id} not found.`);
+      }
+      return rows[0] as InferSelectModel<T>;
+    };
+
+    return softRepo as RepositoryFor<T>;
+  }
+
+  return repo as RepositoryFor<T>;
+}

package/src/kernel/hooks/create-context.ts

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+import type { Actor } from "../../auth/types.js";
+import type { JobsAdapter } from "../jobs/adapter.js";
+import { NullJobsAdapter } from "../jobs/adapter.js";
+import type { PluginDb } from "../database/plugin-types.js";
+import type { HookContext, HookOrigin, Logger, ServiceContainer } from "./types.js";
+
+export interface CreateHookContextArgs {
+  actor: Actor | null;
+  tx?: unknown;
+  logger: Logger;
+  services: ServiceContainer;
+  context?: Record<string, unknown>;
+  requestId?: string;
+  origin?: HookOrigin;
+  jobs?: JobsAdapter;
+  db?: PluginDb;
+  kernel?: { database: { db: PluginDb } };
+}
+
+const nullJobs = new NullJobsAdapter();
+
+/**
+ * Creates a HookContext with sensible defaults.
+ */
+export function createHookContext(args: CreateHookContextArgs): HookContext {
+  // Resolve db: prefer explicit db arg, fall back to kernel.database.db
+  const db = args.db ?? args.kernel?.database?.db ?? null;
+
+  const ctx: HookContext = {
+    actor: args.actor,
+    tx: args.tx ?? null,
+    logger: args.logger,
+    services: args.services,
+    context: args.context ?? {},
+    requestId: args.requestId ?? randomUUID(),
+    origin: args.origin ?? "rest",
+    jobs: args.jobs ?? nullJobs,
+    db: db as PluginDb,
+  };
+
+  return ctx;
+}

package/src/kernel/hooks/executor.ts

@@ -0,0 +1,88 @@
+import type { AfterHook, BeforeHook, HookContext, HookOperation } from "./types.js";
+
+export interface HookError {
+  hookName: string;
+  message: string;
+}
+
+export interface HookReport {
+  errors: HookError[];
+  hasErrors: boolean;
+}
+
+/** Default hook timeout: 20 seconds */
+const HOOK_TIMEOUT_MS = 20_000;
+
+function withTimeout<T>(promiseOrValue: Promise<T> | T, timeoutMs: number, hookName: string): Promise<T> {
+  const promise = Promise.resolve(promiseOrValue);
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Hook "${hookName}" timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    promise.then(
+      (val) => { clearTimeout(timer); resolve(val); },
+      (err) => { clearTimeout(timer); reject(err); },
+    );
+  });
+}
+
+export async function runBeforeHooks<T>(
+  hooks: BeforeHook<T>[],
+  data: T,
+  operation: HookOperation,
+  context: HookContext,
+): Promise<T> {
+  let current = data;
+  for (const hook of hooks) {
+    const hookName = hook.name || "(anonymous beforeHook)";
+    try {
+      current = await withTimeout(
+        hook({ data: current, operation, context }),
+        HOOK_TIMEOUT_MS,
+        hookName,
+      );
+    } catch (error) {
+      context.logger.error(`Before-hook "${hookName}" failed during ${operation}`, {
+        error: error instanceof Error ? error.message : String(error),
+        requestId: context.requestId,
+      });
+      throw error; // Re-throw — beforeHooks MUST succeed
+    }
+  }
+  return current;
+}
+
+export async function runAfterHooks<T>(
+  hooks: AfterHook<T>[],
+  originalData: T | null,
+  committedResult: T,
+  operation: HookOperation,
+  context: HookContext,
+): Promise<HookReport> {
+  const errors: HookError[] = [];
+  for (const hook of hooks) {
+    const hookName = hook.name || "(anonymous afterHook)";
+    try {
+      await withTimeout(
+        hook({
+          data: originalData,
+          result: committedResult,
+          operation,
+          context,
+        }),
+        HOOK_TIMEOUT_MS,
+        hookName,
+      );
+    } catch (error) {
+      errors.push({
+        hookName,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      context.logger.error(`After-hook "${hookName}" failed`, {
+        error,
+      });
+    }
+  }
+  return { errors, hasErrors: errors.length > 0 };
+}