@unifiedcommerce/core 0.1.0 → 0.2.0

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

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

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

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

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

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

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

@@ -1,242 +0,0 @@
-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);
-      }
-      return query as unknown as Promise<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

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

@@ -1,88 +0,0 @@
-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 };
-}