@porulle/core 0.1.0

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

@@ -0,0 +1,112 @@
+/**
+ * Scoped DB Proxy
+ *
+ * Wraps a Drizzle PgDatabase instance so that INSERT operations on
+ * org-scoped tables automatically include the actor's organizationId,
+ * and SELECT ... FROM org-scoped tables constrain rows to that organization.
+ *
+ * Plugin route handlers receive this scoped db via PluginContext.database.db
+ * (organization resolved per operation from AsyncLocalStorage when used from
+ * plugin routes) or a fixed string / getter from router() / tests.
+ */
+
+import { and, eq, getTableColumns } from "drizzle-orm";
+import type { SQL } from "drizzle-orm";
+import type { PgTable } from "drizzle-orm/pg-core";
+
+export type ScopedOrganizationId = string | (() => string);
+
+function resolveOrganizationId(source: ScopedOrganizationId): string {
+  return typeof source === "function" ? source() : source;
+}
+
+function tableHasOrganizationId(table: unknown): boolean {
+  if (table == null || typeof table !== "object") return false;
+  try {
+    const columns = getTableColumns(table as PgTable);
+    return "organizationId" in columns;
+  } catch {
+    return false;
+  }
+}
+
+export function createScopedDb<TDb>(rawDb: TDb, orgSource: ScopedOrganizationId): 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 (!tableHasOrganizationId(table)) return builder;
+
+          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 oid = resolveOrganizationId(orgSource);
+                  const stamp = (row: Record<string, unknown>) => ({
+                    ...row,
+                    organizationId: oid,
+                  });
+                  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;
+            },
+          });
+        };
+      }
+
+      if (prop === "select" && typeof value === "function") {
+        return (...args: unknown[]) => {
+          const selectBuilder = value.apply(target, args);
+          return new Proxy(selectBuilder as Record<string, unknown>, {
+            get(sbTarget, sbProp, sbReceiver) {
+              const sbVal = Reflect.get(sbTarget, sbProp, sbReceiver);
+              if (sbProp === "from" && typeof sbVal === "function") {
+                return (fromArg: unknown, ...fromRest: unknown[]) => {
+                  const chain = sbVal.call(sbTarget, fromArg, ...fromRest);
+                  if (!tableHasOrganizationId(fromArg)) return chain;
+
+                  const columns = getTableColumns(fromArg as PgTable);
+                  const orgCol = columns.organizationId;
+                  if (!orgCol) return chain;
+
+                  const orgEq = eq(orgCol, resolveOrganizationId(orgSource));
+                  const inner = chain as { where: (c: SQL | undefined) => unknown };
+                  const scoped = inner.where(orgEq);
+                  return new Proxy(scoped as Record<string, unknown>, {
+                    get(st, sp, sr) {
+                      const sv = Reflect.get(st, sp, sr);
+                      if (sp === "where" && typeof sv === "function") {
+                        return (condition?: unknown, ...wRest: unknown[]) => {
+                          const c = condition as SQL | undefined;
+                          const merged = c ? and(orgEq, c) : orgEq;
+                          return sv.call(st, merged, ...wRest);
+                        };
+                      }
+                      return typeof sv === "function" ? sv.bind(st) : sv;
+                    },
+                  });
+                };
+              }
+              return typeof sbVal === "function" ? sbVal.bind(sbTarget) : sbVal;
+            },
+          });
+        };
+      }
+
+      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,118 @@
+import { HTTPException } from "hono/http-exception";
+import { toCommerceError } from "./errors.js";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { Logger } from "../runtime/logger.js";
+
+const statusByCode: Record<string, ContentfulStatusCode> = {
+  NOT_FOUND: 404,
+  VALIDATION_FAILED: 422,
+  FORBIDDEN: 403,
+  CONFLICT: 409,
+  INVALID_TRANSITION: 422,
+  ORG_RESOLUTION_FAILED: 503,
+};
+
+export function mapErrorToStatus(error: unknown): ContentfulStatusCode {
+  const normalized = toCommerceError(error);
+  return statusByCode[normalized.code] ?? 500;
+}
+
+export interface ErrorMapping {
+  body: { error: { code: string; message: string } };
+  status: ContentfulStatusCode;
+}
+
+const httpStatusCodeMap: Record<number, string> = {
+  401: "UNAUTHORIZED",
+  403: "FORBIDDEN",
+  413: "PAYLOAD_TOO_LARGE",
+  429: "RATE_LIMITED",
+};
+
+function httpExceptionCode(status: number): string {
+  return httpStatusCodeMap[status] ?? "REQUEST_REJECTED";
+}
+
+export function mapErrorToResponse(
+  err: unknown,
+  isProd: boolean,
+  logger?: Logger,
+): ErrorMapping {
+  const message = err instanceof Error ? err.message : String(err);
+
+  // ZodError from @hono/zod-openapi validation (bypasses defaultHook)
+  if (
+    (err as { constructor?: { name: string } }).constructor?.name === "ZodError" ||
+    "issues" in (err as object)
+  ) {
+    if (isProd) {
+      return {
+        body: { error: { code: "VALIDATION_FAILED", message: "Invalid input." } },
+        status: 422,
+      };
+    }
+    const issues = (err as { issues?: Array<{ path: string[]; message: string }> }).issues ?? [];
+    return {
+      body: {
+        error: {
+          code: "VALIDATION_FAILED",
+          message: issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+        },
+      },
+      status: 422,
+    };
+  }
+
+  // Hono HTTPException — CSRF, body-limit, rate-limit, route guards
+  if (err instanceof HTTPException) {
+    return {
+      body: {
+        error: {
+          code: httpExceptionCode(err.status),
+          message: isProd ? "Request rejected." : (err.message || "Request rejected."),
+        },
+      },
+      status: err.status,
+    };
+  }
+
+  // Malformed JSON body from c.req.json()
+  if (err instanceof SyntaxError || /malformed json|unexpected token/i.test(message)) {
+    return {
+      body: { error: { code: "BAD_REQUEST", message: "Malformed JSON in request body." } },
+      status: 400,
+    };
+  }
+
+  // CommerceError subclasses → mapped status (403 / 404 / 409 / 422 / 503)
+  if (
+    err instanceof Error &&
+    "code" in err &&
+    typeof (err as { code?: unknown }).code === "string"
+  ) {
+    const status = mapErrorToStatus(err);
+    if (status !== 500) {
+      const errorCode = (err as { code: string }).code;
+      return {
+        body: {
+          error: {
+            code: errorCode,
+            message: isProd && status >= 500 ? "An error occurred." : err.message,
+          },
+        },
+        status,
+      };
+    }
+  }
+
+  logger?.error({ err }, "unhandled request error");
+  return {
+    body: {
+      error: {
+        code: "INTERNAL_ERROR",
+        message: isProd ? "An unexpected error occurred." : message,
+      },
+    },
+    status: 500,
+  };
+}

package/src/kernel/errors.ts

@@ -0,0 +1,100 @@
+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 class OrgResolutionError extends Error implements CommerceError {
+  code = "ORG_RESOLUTION_FAILED" as const;
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "OrgResolutionError";
+  }
+}
+
+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,52 @@
+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;
+  /** Prefer this over {@link CreateHookContextArgs.kernel}. */
+  database?: { db: PluginDb };
+  /**
+   * @deprecated Pass {@link CreateHookContextArgs.database} or {@link CreateHookContextArgs.db} instead.
+   */
+  kernel?: { database: { db: PluginDb } };
+}
+
+const nullJobs = new NullJobsAdapter();
+
+/**
+ * Creates a HookContext with sensible defaults.
+ */
+export function createHookContext(args: CreateHookContextArgs): HookContext {
+  const db =
+    args.db ?? args.database?.db ?? args.kernel?.database?.db ?? null;
+
+  if (db == null) {
+    throw new Error(
+      "createHookContext requires a database: pass `db`, `database: { db }`, or `kernel: { database: { db } }`.",
+    );
+  }
+
+  return {
+    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,
+  };
+}