@cosmicdrift/kumiko-framework 0.1.0

package/src/errors/classes.ts

@@ -0,0 +1,249 @@
+import { type ErrorOpts, KumikoError } from "./kumiko-error";
+
+// Per-field validation issue. Shared shape between Zod-derived and
+// hook-derived validation errors so the client sees one list.
+export type ValidationFieldIssue = {
+  readonly path: string;
+  readonly code: string;
+  readonly i18nKey: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+};
+
+export type ValidationDetails = {
+  readonly fields: readonly ValidationFieldIssue[];
+};
+
+export class ValidationError extends KumikoError {
+  readonly code = "validation_error";
+  readonly httpStatus = 400;
+
+  constructor(details: ValidationDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">) {
+    // The wire `message` stays a short human-readable fallback — Zod's own
+    // `error.message` is a multi-line JSON blob that would look awful in any
+    // UI. Per-field details belong in `details.fields` (structured, i18nable);
+    // the full ZodError is preserved in `cause` for forensics in the log.
+    super({
+      message: "Validation failed",
+      i18nKey: opts?.i18nKey ?? "errors.validation.failed",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+// Raised by the dispatcher when a handler belongs to a feature that is
+// globally disabled. Separate from AccessDenied so clients can distinguish
+// "this feature is off" (retry pointless until ops flips it on) from
+// "you don't have permission" (potentially retryable with a different user).
+export type FeatureDisabledDetails = {
+  readonly reason: "feature_disabled";
+  readonly feature: string;
+  readonly handler: string;
+};
+
+export class FeatureDisabledError extends KumikoError {
+  readonly code = "feature_disabled";
+  readonly httpStatus = 403;
+
+  constructor(feature: string, handler: string, opts?: Pick<ErrorOpts, "cause">) {
+    super({
+      message: `feature ${feature} is disabled`,
+      i18nKey: "errors.feature.disabled",
+      i18nParams: { feature },
+      details: { reason: "feature_disabled", feature, handler } satisfies FeatureDisabledDetails,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+export class AccessDeniedError extends KumikoError {
+  readonly code = "access_denied";
+  readonly httpStatus = 403;
+
+  constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">) {
+    super({
+      message: opts?.message ?? "access denied",
+      i18nKey: opts?.i18nKey ?? "errors.access.denied",
+      ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
+      ...(opts?.details !== undefined && { details: opts.details }),
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+export type NotFoundDetails = {
+  readonly entity: string;
+  readonly id?: string;
+};
+
+export class NotFoundError extends KumikoError {
+  readonly code = "not_found";
+  readonly httpStatus = 404;
+
+  constructor(
+    entity: string,
+    id?: string | number,
+    opts?: Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause">,
+  ) {
+    const idStr = id !== undefined ? String(id) : undefined;
+    // The reason string follows `<snake_entity>_not_found` — keeps a stable,
+    // client-friendly tag that survives wire serialization even if the entity
+    // name is later renamed for display purposes.
+    const reason = `${toSnake(entity)}_not_found`;
+    const details: NotFoundDetails & { reason: string } = { reason, entity, id: idStr };
+    super({
+      message: idStr !== undefined ? `${entity} ${idStr} not found` : `${entity} not found`,
+      i18nKey: opts?.i18nKey ?? "errors.notFound",
+      i18nParams: { entity, id: idStr, ...opts?.i18nParams },
+      details,
+      cause: opts?.cause,
+    });
+  }
+}
+
+// Accepts camelCase OR kebab-case entity names and produces snake_case for
+// the reason tag. New code uses kebab; legacy camelCase still flows through.
+function toSnake(s: string): string {
+  return s
+    .replace(/-/g, "_")
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+// Generic 409. Features that need a narrower shape should subclass (see
+// VersionConflictError) — this way the HTTP layer stays uniform while callers
+// can still instanceof on the concrete subtype in handlers.
+export class ConflictError extends KumikoError {
+  // Widened to `string` so subclasses (VersionConflictError) can refine the
+  // value without TS blocking the override. The base class still enforces
+  // "some code is set"; concrete classes pick their own literal.
+  readonly code: string = "conflict";
+  readonly httpStatus = 409;
+
+  constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">) {
+    super({
+      message: opts?.message ?? "conflict",
+      i18nKey: opts?.i18nKey ?? "errors.conflict",
+      ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
+      ...(opts?.details !== undefined && { details: opts.details }),
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+export type VersionConflictDetails = {
+  readonly entityId: number | string;
+  readonly expectedVersion: number;
+  readonly currentVersion: number;
+};
+
+export class VersionConflictError extends ConflictError {
+  override readonly code: string = "version_conflict";
+
+  constructor(details: VersionConflictDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">) {
+    super({
+      message: `version conflict for entity ${details.entityId}`,
+      i18nKey: opts?.i18nKey ?? "errors.versionConflict",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+// Entity-level unique-index violation. Distinct from VersionConflictError:
+// version_conflict means "two writers raced on the events_aggregate_version
+// _uq index" (optimistic-concurrency); unique_violation means "you tried to
+// insert a row that violates an app-declared unique-index" (e.g. duplicate
+// email on a User entity, duplicate (tenantId, slug) on Article). Same 409
+// because both are conflicts the client can resolve by retrying with
+// different data, but distinct codes so UI can show the right message.
+//
+// constraintName comes from the PG error and is the *physical* DB constraint
+// (e.g. "users_tenant_email_uniq"). Apps that want to map it to a friendly
+// field name should do so in their own error-handler, not here.
+export type UniqueViolationDetails = {
+  readonly entityName: string;
+  readonly constraintName?: string;
+};
+
+export class UniqueViolationError extends ConflictError {
+  override readonly code: string = "unique_violation";
+
+  constructor(details: UniqueViolationDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">) {
+    super({
+      message: `unique constraint violated on entity ${details.entityName}${
+        details.constraintName ? ` (${details.constraintName})` : ""
+      }`,
+      i18nKey: opts?.i18nKey ?? "errors.uniqueViolation",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+// Business-rule violation. The human-readable reason lives in details.reason
+// so the client can key off it without overloading the top-level code.
+export type UnprocessableOpts = Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause"> & {
+  readonly details?: Readonly<Record<string, unknown>>;
+};
+
+export class UnprocessableError extends KumikoError {
+  readonly code = "unprocessable";
+  readonly httpStatus = 422;
+
+  constructor(reason: string, opts?: UnprocessableOpts) {
+    super({
+      message: `unprocessable: ${reason}`,
+      i18nKey: opts?.i18nKey ?? "errors.unprocessable",
+      ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
+      details: { reason, ...opts?.details },
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
+// Auto-wrap target for unexpected throws. Never exposes .details to the client
+// — the serializer drops it. Stack + cause live in the log only.
+export class InternalError extends KumikoError {
+  readonly code = "internal_error";
+  readonly httpStatus = 500;
+
+  constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">) {
+    super({
+      message: opts?.message ?? "internal error",
+      i18nKey: opts?.i18nKey ?? "errors.internal",
+      ...(opts?.i18nParams !== undefined && { i18nParams: opts.i18nParams }),
+      ...(opts?.details !== undefined && { details: opts.details }),
+      ...(opts?.cause !== undefined && { cause: opts.cause }),
+    });
+  }
+}
+
+// Rate-limit hit. The bucket details (limit, window, current state) live
+// in `details` so a client can show "try again in N seconds" without a
+// second request. Headers `Retry-After`, `X-RateLimit-*` are filled in
+// by the HTTP layer from these same fields.
+export type RateLimitDetails = {
+  readonly bucket: string;
+  readonly limit: number;
+  readonly windowSeconds: number;
+  readonly remaining: number;
+  readonly retryAfterSeconds: number;
+  readonly resetAt: string;
+};
+
+export class RateLimitError extends KumikoError {
+  readonly code = "rate_limited";
+  readonly httpStatus = 429;
+  readonly details: RateLimitDetails;
+
+  constructor(details: RateLimitDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">) {
+    super({
+      message: `rate limited: ${details.bucket} (limit ${details.limit} per ${details.windowSeconds}s)`,
+      i18nKey: opts?.i18nKey ?? "errors.rate_limited",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+    this.details = details;
+  }
+}

package/src/errors/i18n/de.yaml

@@ -0,0 +1,83 @@
+# i18n-Texte für FrameworkReasons (deutsch).
+#
+# Schema pro Reason-Key (snake_case, identisch mit Wert in reasons.ts
+# FrameworkReasons):
+#
+#   <reason_key>:
+#     endUser: |
+#       Was der End-User in der App-UI sieht.
+#       Verständliche Sprache, Handlungs-Aufforderung wenn anwendbar.
+#     developer: |
+#       Technischer Hintergrund + Hinweise zum Konfigurieren / Verhindern.
+#       Für App-Owner und Designer-Nutzer.
+
+stale_state:
+  endUser: |
+    Jemand anderes hat dieses Element zwischenzeitlich geändert.
+    Bitte Seite neu laden und nochmal speichern.
+  developer: |
+    `ConflictError` tritt auf wenn ein atomic UPDATE den Optimistic-Locking-
+    Race verloren hat — ein anderer Writer hat die Row zwischen Snapshot
+    und WHERE-Clause bewegt.
+
+    Standard-Verhalten im Client-SDK: Toast mit "Bitte neu laden" anzeigen
+    und Entity neu fetchen.
+
+    Wenn du Conflict-Handling pro Entity anpassen willst, siehe
+    [Optimistic-Locking-Konfiguration](/de/architecture/optimistic-locking/).
+
+invalid_transition:
+  endUser: |
+    Diese Aktion ist im aktuellen Status nicht möglich.
+    Der Datensatz muss sich in einem bestimmten Zustand befinden,
+    damit dieser Schritt erlaubt ist.
+  developer: |
+    `UnprocessableError` beim `guardTransition`: ein State-Machine-Übergang
+    wurde abgelehnt weil der aktuelle Zustand nicht zu den erlaubten
+    Quell-Zuständen gehört.
+
+    `details.from`, `details.to` und `details.validTargets` enthalten die
+    Diagnose. Definiere erlaubte Übergänge in
+    [`r.entity({ stateMachine: ... })`](/de/architecture/state-machine/),
+    oder prüfe vor dem Aufruf den aktuellen Zustand.
+
+field_access_denied:
+  endUser: |
+    Du darfst dieses Feld nicht ändern.
+    Wende dich an einen Administrator wenn du diese Berechtigung brauchst.
+  developer: |
+    `AccessDeniedError` beim Field-Level-Write-Check des Dispatchers: ein
+    Schreibversuch auf ein Feld wurde abgelehnt weil die aktuelle Rolle
+    keinen Zugriff hat.
+
+    `details.field` und `details.handler` enthalten die Diagnose.
+    Konfiguriere Field-Access in der Entity-Definition
+    (siehe [Permissions](/de/architecture/permissions/)) oder fordere die
+    nötige Rolle an.
+
+delete_restricted:
+  endUser: |
+    Dieser Eintrag kann nicht gelöscht werden weil andere Datensätze noch
+    darauf verweisen.
+    Lösche zuerst die abhängigen Einträge.
+  developer: |
+    `ConflictError` beim Cascade-Delete-Guard: das Löschen wurde verhindert
+    weil dependent Rows existieren.
+
+    `details.blockingEntity`, `details.entity` und `details.entityId` zeigen
+    welche Relation blockiert. Setze `relation.onDelete` auf `"cascade"`
+    oder `"setNull"` wenn automatisches Aufräumen gewünscht ist, oder lösche
+    die abhängigen Rows zuerst.
+
+feature_disabled:
+  endUser: |
+    Diese Funktion ist aktuell nicht verfügbar.
+    Versuche es später noch einmal oder kontaktiere den Administrator.
+  developer: |
+    `FeatureDisabledError`: das Feature des aufgerufenen Handlers wurde
+    global deaktiviert. Distinct von `access_denied` — Clients sollten
+    "Funktion gerade nicht verfügbar" zeigen, nicht "keine Berechtigung".
+
+    `details.feature` und `details.handler` zeigen welches Feature/Handler.
+    Aktiviere das Feature via Feature-Toggle oder Routing-Config (siehe
+    [Feature-Toggles](/de/features/feature-toggles/)).

package/src/errors/i18n/en.yaml

@@ -0,0 +1,80 @@
+# i18n texts for FrameworkReasons (english).
+#
+# Schema per reason key (snake_case, matches the value in
+# reasons.ts FrameworkReasons):
+#
+#   <reason_key>:
+#     endUser: |
+#       What the end-user sees in the app UI.
+#       Plain language, call-to-action where applicable.
+#     developer: |
+#       Technical background + hints on how to configure / prevent.
+#       For app owners and designer users.
+
+stale_state:
+  endUser: |
+    Someone else modified this item in the meantime.
+    Please reload the page and try saving again.
+  developer: |
+    `ConflictError` fires when an atomic UPDATE lost the optimistic-
+    locking race — another writer moved the row between our snapshot and
+    our WHERE clause.
+
+    Default client SDK behavior: toast a "please reload" message and
+    re-fetch the entity.
+
+    To customize conflict handling per entity, see
+    [optimistic locking configuration](/en/architecture/optimistic-locking/).
+
+invalid_transition:
+  endUser: |
+    This action isn't allowed in the current state.
+    The record needs to be in a specific status before this step can happen.
+  developer: |
+    `UnprocessableError` from `guardTransition`: a state-machine transition
+    was rejected because the current state isn't in the allowed source
+    states.
+
+    `details.from`, `details.to` and `details.validTargets` carry the
+    diagnostics. Define allowed transitions in
+    [`r.entity({ stateMachine: ... })`](/en/architecture/state-machine/),
+    or check the current state before calling.
+
+field_access_denied:
+  endUser: |
+    You don't have permission to edit this field.
+    Please contact an administrator if you need this access.
+  developer: |
+    `AccessDeniedError` from the dispatcher's field-level write check: a
+    write to a field was rejected because the current role lacks access.
+
+    `details.field` and `details.handler` contain the diagnostics.
+    Configure field-level access in the entity definition (see
+    [Permissions](/en/architecture/permissions/)) or request the required
+    role.
+
+delete_restricted:
+  endUser: |
+    This entry can't be deleted because other records still reference it.
+    Delete the dependent entries first.
+  developer: |
+    `ConflictError` from the cascade-delete guard: the delete was prevented
+    because dependent rows exist.
+
+    `details.blockingEntity`, `details.entity` and `details.entityId` show
+    which relation is blocking. Set `relation.onDelete` to `"cascade"` or
+    `"setNull"` if automatic cleanup is desired, or delete the dependent
+    rows first.
+
+feature_disabled:
+  endUser: |
+    This feature is currently unavailable.
+    Please try again later or contact an administrator.
+  developer: |
+    `FeatureDisabledError`: the feature owning the called handler is
+    globally disabled. Distinct from `access_denied` — clients should show
+    "feature currently unavailable" rather than "no permission".
+
+    `details.feature` and `details.handler` indicate which feature and
+    handler. Enable the feature via feature toggle or routing config (see
+    [Feature Toggles](/en/features/feature-toggles/)).

package/src/errors/index.ts

@@ -0,0 +1,41 @@
+export type {
+  FeatureDisabledDetails,
+  NotFoundDetails,
+  RateLimitDetails,
+  UniqueViolationDetails,
+  UnprocessableOpts,
+  ValidationDetails,
+  ValidationFieldIssue,
+  VersionConflictDetails,
+} from "./classes";
+export {
+  AccessDeniedError,
+  ConflictError,
+  FeatureDisabledError,
+  InternalError,
+  NotFoundError,
+  RateLimitError,
+  UniqueViolationError,
+  UnprocessableError,
+  ValidationError,
+  VersionConflictError,
+} from "./classes";
+export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error";
+export { isKumikoError, KumikoError } from "./kumiko-error";
+export type { FrameworkReason } from "./reasons";
+export { FrameworkReasons } from "./reasons";
+export type { ErrorLogEntry, ErrorResponseBody } from "./serialize";
+export { buildErrorLog, serializeError } from "./serialize";
+export type { InvalidTransitionDetails } from "./transition-details";
+export { buildInvalidTransitionDetails } from "./transition-details";
+export type { WriteErrorInfo, WriteFailure } from "./write-error-info";
+
+export {
+  failNotFound,
+  failTransition,
+  failUnprocessable,
+  reraiseAsKumikoError,
+  toWriteErrorInfo,
+  writeFailure,
+} from "./write-error-info";
+export { validationErrorFromZod } from "./zod-bridge";

package/src/errors/kumiko-error.ts

@@ -0,0 +1,67 @@
+// Base class for every error the framework recognizes as a contract.
+// Anything that isn't a KumikoError is treated as an unexpected crash and
+// auto-wrapped into InternalError by the dispatcher — so the HTTP layer never
+// has to guess the status or the client-facing shape.
+
+export type ErrorOpts = {
+  readonly message?: string;
+  readonly i18nKey?: string;
+  readonly i18nParams?: Readonly<Record<string, unknown>>;
+  readonly details?: unknown;
+  readonly cause?: Error;
+};
+
+export type ErrorCtorInput = {
+  readonly message: string;
+  readonly i18nKey: string;
+  readonly i18nParams?: Readonly<Record<string, unknown>>;
+  readonly details?: unknown;
+  readonly cause?: Error;
+};
+
+// Default-Doku-URL für Self-Service-Errors. Kann via env-var
+// `KUMIKO_DOCS_URL` überschrieben werden — z.B. für Self-Hosted-Kunden
+// die ihre eigene Doku-Instanz hosten.
+const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.so";
+
+function docsBaseUrl(): string {
+  return process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
+}
+
+export abstract class KumikoError extends Error {
+  abstract readonly code: string;
+  abstract readonly httpStatus: number;
+  readonly i18nKey: string;
+  readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
+  readonly details: unknown;
+
+  constructor(input: ErrorCtorInput) {
+    super(input.message, input.cause ? { cause: input.cause } : undefined);
+    this.name = new.target.name;
+    this.i18nKey = input.i18nKey;
+    this.i18nParams = input.i18nParams;
+    this.details = input.details;
+  }
+
+  // Doku-URL für Self-Service. Pro-Reason-Slug aus `details.reason` wenn
+  // vorhanden (z.B. ConflictError → "stale_state"), sonst Fallback auf
+  // den Error-Code (z.B. "not_found", "validation_error"). Default-Renderer
+  // im Client zeigt "Mehr erfahren →" Link auf diese URL.
+  get docsUrl(): string {
+    return `${docsBaseUrl()}/errors/${this.reasonSlug}`;
+  }
+
+  private get reasonSlug(): string {
+    if (this.details && typeof this.details === "object") {
+      // @cast-boundary error-details — KumikoError.details ist per-error
+      // typed, hier reines reflection-shape für reasonSlug-Lookup.
+      const r = (this.details as Record<string, unknown>)["reason"];
+      if (typeof r === "string") return r;
+    }
+    return this.code;
+  }
+}
+
+export function isKumikoError(e: unknown): e is KumikoError {
+  return e instanceof KumikoError;
+}

package/src/errors/reasons.ts

@@ -0,0 +1,36 @@
+// Centralized registry of the reason codes the framework itself surfaces via
+// `details.reason`. Declaring them here keeps them typed + greppable, and
+// gives features a single source of truth when they need to branch on the
+// framework-level reason (e.g. "is this a stale-state race? retry once").
+//
+// Features add their own local Reasons objects (see `samples/errors/` or
+// `packages/bundled-features/src/tenant/constants.ts` → TenantErrors). The
+// framework deliberately does NOT enforce uniqueness across features — two
+// features may use the same reason string if the semantics match. The
+// convention: snake_case, no spaces, no feature prefix for framework reasons.
+
+export const FrameworkReasons = {
+  // ConflictError: atomic UPDATE lost the race (another writer moved the row
+  // between our snapshot and our WHERE clause). Client SDK default: toast +
+  // re-fetch.
+  staleState: "stale_state",
+
+  // UnprocessableError: guardTransition rejected a state-machine transition.
+  // Details carry `from`, `to`, and `validTargets` for debugging.
+  invalidTransition: "invalid_transition",
+
+  // AccessDeniedError: dispatcher's field-level write check blocked a field.
+  // Details carry `field` and `handler`.
+  fieldAccessDenied: "field_access_denied",
+
+  // ConflictError: cascade-delete guard refused because dependent rows exist.
+  // Details carry `blockingEntity`, `entity`, `entityId`.
+  deleteRestricted: "delete_restricted",
+
+  // FeatureDisabledError: handler's owning feature is globally disabled.
+  // Distinct from access-denied — clients should surface "feature X is
+  // currently unavailable" not "you don't have permission".
+  featureDisabled: "feature_disabled",
+} as const;
+
+export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];