@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/core/data-access/user-owned-data.registry.js

@@ -0,0 +1,140 @@
+"use strict";
+// =============================================================================
+// User-owned data registry (issue #688 PP-1.9, moved to core by #699)
+// =============================================================================
+//
+// Every Prisma model holding a foreign key to `User` is registered here, with
+// the role of each such key (OWNER: the row belongs to the user; ACTOR: the
+// row only names a user who acted), what happens to the row when the user's
+// data is purged, and whether the user's data export includes it.
+//
+// Two things read it:
+//
+//   - the `userOwnedData` conformance suite (`@marinoscar/platform-api/testing`):
+//     fails when a model gains a `User` relation without an entry, when an
+//     entry names a model or field that does not exist, or when a purge policy
+//     contradicts the relation's `onDelete`;
+//   - the scoped client (./scoped-client.ts): confines a scoped client's
+//     queries on a registered owner model to the scope's user, and refuses
+//     every other model.
+//
+// ⚠ FRAMEWORK-FREE ON PURPOSE, like the registry primitive: seeds and
+// standalone scripts may read it without a Nest container. The app fills it
+// from one manifest (platform entries, then its own); a packaged slice
+// registers its own models when it is extracted.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userOwnedModelRegistry = void 0;
+exports.registerUserOwnedModels = registerUserOwnedModels;
+exports.ownerFieldOf = ownerFieldOf;
+exports.ownerRelationOf = ownerRelationOf;
+const registry_1 = require("../registry/registry");
+function validate(def) {
+    const actors = def.actorFields ?? [];
+    if (def.ownerField === undefined && actors.length === 0) {
+        throw new Error('declare an ownerField, actorFields, or both');
+    }
+    if (def.ownerField !== undefined && def.ownerField.trim() === '') {
+        throw new Error('ownerField must not be empty');
+    }
+    if (actors.some((field) => typeof field !== 'string' || field.trim() === '')) {
+        throw new Error('actorFields must be non-empty strings');
+    }
+    if (new Set(actors).size !== actors.length) {
+        throw new Error('actorFields must not repeat a field');
+    }
+    if (def.ownerField !== undefined && actors.includes(def.ownerField)) {
+        throw new Error(`"${def.ownerField}" cannot be both the ownerField and an actor field`);
+    }
+    if (def.ownerRelation !== undefined && def.ownerField === undefined) {
+        throw new Error('ownerRelation requires an ownerField');
+    }
+    if (!['delete', 'detach', 'retain'].includes(def.purge)) {
+        throw new Error(`purge must be 'delete', 'detach' or 'retain', not ${JSON.stringify(def.purge)}`);
+    }
+    if (def.purge === 'retain' && def.ownerField !== undefined) {
+        throw new Error("purge 'retain' is only for actor-only models: a user's own rows are deleted or detached");
+    }
+    if (!['include', 'exclude'].includes(def.export)) {
+        throw new Error(`export must be 'include' or 'exclude', not ${JSON.stringify(def.export)}`);
+    }
+    if (def.exportOmit !== undefined && def.export === 'exclude' && def.exportOmit.length > 0) {
+        throw new Error("exportOmit is meaningless when export is 'exclude'");
+    }
+    if (typeof def.rationale !== 'string' || def.rationale.trim() === '') {
+        throw new Error('rationale is required');
+    }
+}
+/**
+ * The static registry of models holding a foreign key to `User`, keyed by
+ * model name. One per process: the app fills it from a manifest imported
+ * before bootstrap, and `RegistryFreezeService` freezes it with every other
+ * `defineRegistry` registry.
+ *
+ * @stability experimental
+ * @extensionPoint registry
+ * @example
+ * ```ts
+ * // apps/api/src/prisma/ownership/user-owned-model.manifest.ts
+ * registerUserOwnedModels(PLATFORM_USER_OWNED_MODELS);
+ * registerUserOwnedModels(APP_USER_OWNED_MODELS);
+ *
+ * userOwnedModelRegistry.get('UserCredential')?.ownerField; // 'userId'
+ * ```
+ */
+exports.userOwnedModelRegistry = (0, registry_1.defineRegistry)({
+    name: 'user-owned-models',
+    idOf: (def) => def.model,
+    // A Prisma model name: PascalCase identifier.
+    idPattern: /^[A-Z][A-Za-z0-9_]*$/,
+    validate,
+});
+/**
+ * Registers a batch of definitions in {@link userOwnedModelRegistry}, all or
+ * nothing.
+ *
+ * @param defs - the definitions; an app may type them with its own model names.
+ * @throws RegistryError `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * registerUserOwnedModels([
+ *   { model: 'Workout', ownerField: 'userId', purge: 'delete', export: 'include', rationale: "The user's own log." },
+ * ]);
+ * ```
+ */
+function registerUserOwnedModels(defs) {
+    exports.userOwnedModelRegistry.registerAll(defs);
+}
+/**
+ * The owner field of a registered model, or `undefined` (actor-only or
+ * unregistered).
+ *
+ * @param model - the Prisma model name.
+ * @stability experimental
+ * @example
+ * ```ts
+ * ownerFieldOf('StorageObject'); // 'uploadedById'
+ * ```
+ */
+function ownerFieldOf(model) {
+    return exports.userOwnedModelRegistry.get(model)?.ownerField;
+}
+/**
+ * The relation field backing a definition's owner field: `ownerRelation`
+ * when given, otherwise the owner field without its trailing `Id`.
+ *
+ * @param def - a registered (or candidate) definition.
+ * @stability experimental
+ * @example
+ * ```ts
+ * ownerRelationOf({ model: 'WorkerNode', ownerField: 'createdById', purge: 'delete', export: 'exclude', rationale: 'x' }); // 'createdBy'
+ * ```
+ */
+function ownerRelationOf(def) {
+    if (def.ownerField === undefined)
+        return undefined;
+    return def.ownerRelation ?? def.ownerField.replace(/Id$/, '');
+}
+//# sourceMappingURL=user-owned-data.registry.js.map

package/dist/core/data-access/user-owned-data.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-owned-data.registry.js","sourceRoot":"","sources":["../../../src/core/data-access/user-owned-data.registry.ts"],"names":[],"mappings":"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"}

package/dist/core/database-url.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The subset of the environment this builder reads.
+ *
+ * @stability stable
+ */
+export interface DatabaseEnv {
+    /** An explicit connection string; wins untouched when set. */
+    DATABASE_URL?: string | undefined;
+    /** Host; default `localhost`. */
+    POSTGRES_HOST?: string | undefined;
+    /** Port; default `5432`. */
+    POSTGRES_PORT?: string | undefined;
+    /** Role; default `postgres`. Percent-encoded. */
+    POSTGRES_USER?: string | undefined;
+    /** Password; default `postgres`. Percent-encoded. */
+    POSTGRES_PASSWORD?: string | undefined;
+    /** Database; default `appdb`. */
+    POSTGRES_DB?: string | undefined;
+    /** Exactly `'true'` adds `?sslmode=require`. */
+    POSTGRES_SSL?: string | undefined;
+}
+/**
+ * Builds the PostgreSQL connection string.
+ *
+ * Two rules, both of which every caller now shares:
+ *
+ *  1. An already-set DATABASE_URL WINS and is returned untouched. It is the
+ *     escape hatch for a connection this formula cannot express — a socket
+ *     path, a pgbouncer URL, extra query parameters — and re-deriving over the
+ *     top of it would silently discard the operator's intent.
+ *  2. The user and the password are BOTH percent-encoded. The password is the
+ *     one that bites in practice, but a username can contain `@` too, and
+ *     encoding only one of them is how this class of bug comes back.
+ *
+ * @stability stable
+ */
+export declare function buildDatabaseUrl(env?: DatabaseEnv): string;
+//# sourceMappingURL=database-url.d.ts.map

package/dist/core/database-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-url.d.ts","sourceRoot":"","sources":["../../src/core/database-url.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,iCAAiC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,WAAyB,GAAG,MAAM,CAsBvE"}

package/dist/core/database-url.js

@@ -0,0 +1,52 @@
+"use strict";
+// =============================================================================
+// The one place a PostgreSQL connection string is built (issue #172; packaged
+// by #740)
+// =============================================================================
+//
+// DATABASE_URL is not a primary input in the platform: it is derived from the
+// individual POSTGRES_* variables. Three hand-written copies of this
+// derivation once disagreed about percent-encoding (a password containing `@`,
+// `/` or `%` connected for migrations and then not for the application), which
+// is why every caller goes through this function. The reference app's
+// `common/database-url.ts` re-exports it, and its spec holds it together with
+// the CommonJS copy in `apps/api/scripts/prisma-env.js` over a table of
+// awkward inputs.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDatabaseUrl = buildDatabaseUrl;
+/**
+ * Builds the PostgreSQL connection string.
+ *
+ * Two rules, both of which every caller now shares:
+ *
+ *  1. An already-set DATABASE_URL WINS and is returned untouched. It is the
+ *     escape hatch for a connection this formula cannot express — a socket
+ *     path, a pgbouncer URL, extra query parameters — and re-deriving over the
+ *     top of it would silently discard the operator's intent.
+ *  2. The user and the password are BOTH percent-encoded. The password is the
+ *     one that bites in practice, but a username can contain `@` too, and
+ *     encoding only one of them is how this class of bug comes back.
+ *
+ * @stability stable
+ */
+function buildDatabaseUrl(env = process.env) {
+    const existing = env.DATABASE_URL;
+    if (existing !== undefined && existing !== '') {
+        return existing;
+    }
+    const host = env.POSTGRES_HOST || 'localhost';
+    const port = env.POSTGRES_PORT || '5432';
+    const user = env.POSTGRES_USER || 'postgres';
+    const password = env.POSTGRES_PASSWORD || 'postgres';
+    const database = env.POSTGRES_DB || 'appdb';
+    // Exact string comparison, deliberately: 'TRUE', '1' and 'yes' are NOT true
+    // here, because that is the rule the other two builders already used and
+    // widening it would change the meaning of existing .env files.
+    const ssl = env.POSTGRES_SSL === 'true';
+    const sslParam = ssl ? '?sslmode=require' : '';
+    const encodedUser = encodeURIComponent(user);
+    const encodedPassword = encodeURIComponent(password);
+    return `postgresql://${encodedUser}:${encodedPassword}@${host}:${port}/${database}${sslParam}`;
+}
+//# sourceMappingURL=database-url.js.map

package/dist/core/database-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-url.js","sourceRoot":"","sources":["../../src/core/database-url.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,8EAA8E;AAC9E,WAAW;AACX,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,qEAAqE;AACrE,+EAA+E;AAC/E,+EAA+E;AAC/E,sEAAsE;AACtE,8EAA8E;AAC9E,wEAAwE;AACxE,kBAAkB;AAClB,gFAAgF;;AAuChF,4CAsBC;AArCD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,gBAAgB,CAAC,MAAmB,OAAO,CAAC,GAAG;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,WAAW,CAAC;IAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,MAAM,CAAC;IACzC,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,UAAU,CAAC;IAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,iBAAiB,IAAI,UAAU,CAAC;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC;IAE5C,4EAA4E;IAC5E,yEAAyE;IACzE,+DAA+D;IAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,KAAK,MAAM,CAAC;IACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/C,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,eAAe,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAErD,OAAO,gBAAgB,WAAW,IAAI,eAAe,IAAI,IAAI,IAAI,IAAI,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;AACjG,CAAC"}

package/dist/core/errors/database-seed.exception.d.ts

@@ -0,0 +1,23 @@
+import { InternalServerErrorException } from '@nestjs/common';
+/**
+ * Exception thrown when required database seed data is missing.
+ * This indicates the database migrations have been run but seeds have not.
+ *
+ * A 500 whose envelope `details` carries `missingData`, `seedCommand` and
+ * operator `instructions`; the response `code` is `INTERNAL_ERROR` like any
+ * other 500 (see {@link HttpExceptionFilter}).
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * if (!defaultRole) throw new DatabaseSeedException('default role "Viewer"');
+ * ```
+ */
+export declare class DatabaseSeedException extends InternalServerErrorException {
+    /**
+     * @param missingData - What is missing, for the message and `details.missingData`.
+     * @param seedCommand - The command that seeds it; defaults to `npm run prisma:seed`.
+     */
+    constructor(missingData: string, seedCommand?: string);
+}
+//# sourceMappingURL=database-seed.exception.d.ts.map

package/dist/core/errors/database-seed.exception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-seed.exception.d.ts","sourceRoot":"","sources":["../../../src/core/errors/database-seed.exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,SAAQ,4BAA4B;IACrE;;;OAGG;gBACS,WAAW,EAAE,MAAM,EAAE,WAAW,SAAwB;CAuBrE"}

package/dist/core/errors/database-seed.exception.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseSeedException = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Exception thrown when required database seed data is missing.
+ * This indicates the database migrations have been run but seeds have not.
+ *
+ * A 500 whose envelope `details` carries `missingData`, `seedCommand` and
+ * operator `instructions`; the response `code` is `INTERNAL_ERROR` like any
+ * other 500 (see {@link HttpExceptionFilter}).
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * if (!defaultRole) throw new DatabaseSeedException('default role "Viewer"');
+ * ```
+ */
+class DatabaseSeedException extends common_1.InternalServerErrorException {
+    /**
+     * @param missingData - What is missing, for the message and `details.missingData`.
+     * @param seedCommand - The command that seeds it; defaults to `npm run prisma:seed`.
+     */
+    constructor(missingData, seedCommand = 'npm run prisma:seed') {
+        const message = `Database seed data missing: ${missingData}. Please run: ${seedCommand}`;
+        super({
+            // NOT on the wire. `HttpExceptionFilter` always derives the response's
+            // `code` from the HTTP status (500 -> INTERNAL_ERROR) and ignores any
+            // `code` on the payload — that is the published contract in
+            // `./error.dto.ts`, whose `code` is a closed enum of the
+            // status-derived values. Kept here as the internal name for this failure,
+            // which is what the log line and `details.missingData` identify it by.
+            // Do not add a client that branches on seeing it in a response (#153).
+            code: 'DATABASE_SEED_REQUIRED',
+            message,
+            details: {
+                missingData,
+                seedCommand,
+                instructions: [
+                    'Database migrations have been run but seed data is missing',
+                    `Run the following command: ${seedCommand}`,
+                    'This will populate required data like roles and permissions',
+                ],
+            },
+        });
+    }
+}
+exports.DatabaseSeedException = DatabaseSeedException;
+//# sourceMappingURL=database-seed.exception.js.map

package/dist/core/errors/database-seed.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-seed.exception.js","sourceRoot":"","sources":["../../../src/core/errors/database-seed.exception.ts"],"names":[],"mappings":";;;AAAA,2CAA8D;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAa,qBAAsB,SAAQ,qCAA4B;IACrE;;;OAGG;IACH,YAAY,WAAmB,EAAE,WAAW,GAAG,qBAAqB;QAClE,MAAM,OAAO,GAAG,+BAA+B,WAAW,iBAAiB,WAAW,EAAE,CAAC;QACzF,KAAK,CAAC;YACJ,uEAAuE;YACvE,sEAAsE;YACtE,4DAA4D;YAC5D,yDAAyD;YACzD,0EAA0E;YAC1E,uEAAuE;YACvE,uEAAuE;YACvE,IAAI,EAAE,wBAAwB;YAC9B,OAAO;YACP,OAAO,EAAE;gBACP,WAAW;gBACX,WAAW;gBACX,YAAY,EAAE;oBACZ,4DAA4D;oBAC5D,8BAA8B,WAAW,EAAE;oBAC3C,6DAA6D;iBAC9D;aACF;SACF,CAAC,CAAC;IACL,CAAC;CACF;AA5BD,sDA4BC"}

package/dist/core/errors/error-codes.d.ts

@@ -0,0 +1,114 @@
+import type { HttpException } from '@nestjs/common';
+import { type Registry } from '../registry/registry';
+/**
+ * The pattern an error code matches: UPPER_SNAKE, 3 to 64 characters, starting
+ * with a letter (`NOTE_TITLE_TAKEN`).
+ *
+ * @stability experimental
+ */
+export declare const ERROR_CODE_PATTERN: RegExp;
+/**
+ * The code of a failure whose status has no registered default (for example a
+ * 503). Never registered: it has no single status.
+ *
+ * @stability experimental
+ */
+export declare const FALLBACK_ERROR_CODE = "ERROR";
+/**
+ * One registered error code.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const def: ErrorCodeDef = { code: 'NOTE_TITLE_TAKEN', status: 409, description: 'A note with this title already exists.' };
+ * ```
+ */
+export interface ErrorCodeDef {
+    /** The code. See {@link ERROR_CODE_PATTERN}. */
+    readonly code: string;
+    /** The HTTP status the code is for (an integer from 400 to 599). The filter passes the code through only for an exception of this status. */
+    readonly status: number;
+    /** One sentence for the API docs: when a client sees this code. */
+    readonly description: string;
+}
+/**
+ * The platform's status-derived codes, in the order the OpenAPI examples list
+ * them. The FIRST entry for a status is the default `code` of that status.
+ *
+ * @stability experimental
+ */
+export declare const BUILTIN_ERROR_CODES: readonly ErrorCodeDef[];
+/**
+ * Every registered error code: the platform's ten first, then the app's.
+ * Frozen once the application has bootstrapped.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const errorCodeRegistry: Registry<ErrorCodeDef>;
+/**
+ * Registers a domain error code. Call it at module load, before the
+ * application is created; a duplicate code (including a built-in one) throws.
+ *
+ * A code is for ONE status. To let the filter pass it through, throw an
+ * `HttpException` of that status whose payload carries `code`.
+ *
+ * @param def - the code, its status and a description.
+ * @throws RegistryError `INVALID_ID`, `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+ *
+ * @example
+ * ```ts
+ * registerErrorCode({ code: 'NOTE_TITLE_TAKEN', status: 409, description: 'A note with this title already exists.' });
+ * // in a service:
+ * throw new ConflictException({ code: 'NOTE_TITLE_TAKEN', message: 'Title already used', details: { field: 'title' } });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerErrorCode(def: ErrorCodeDef): void;
+/**
+ * The default code of an HTTP status: the first registered code for it, else
+ * {@link FALLBACK_ERROR_CODE}.
+ *
+ * @param status - an HTTP status.
+ * @returns the code the envelope carries when the exception names none.
+ *
+ * @stability experimental
+ */
+export declare function defaultErrorCodeForStatus(status: number): string;
+/**
+ * Whether `code` may appear in the envelope of an exception with `status`: it
+ * is registered, for that status.
+ *
+ * @param code - a payload `code`, as thrown.
+ * @param status - the exception's HTTP status.
+ * @returns `true` only for a registered code of that status.
+ *
+ * @stability experimental
+ */
+export declare function isErrorCodeForStatus(code: unknown, status: number): code is string;
+/**
+ * Turns an error the platform does not know (a Prisma error, an SDK error) into
+ * an `HttpException`, or returns `null` to pass. Mappers run, in order, only for
+ * values that are NOT already an `HttpException`; the first to return one wins.
+ *
+ * ⚠ Build the result's `message` and `details` yourself and keep them free of
+ * the original error's text: a Prisma or SDK message can carry SQL, table names,
+ * hostnames or credentials. The filter never copies a mapped error's message,
+ * and logs the original server-side only.
+ *
+ * @param error - whatever was thrown.
+ * @returns the exception to respond with, or `null` when this mapper does not handle it.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const uniqueViolation: ErrorMapper = (error) =>
+ *   isPrismaError(error, 'P2002')
+ *     ? new ConflictException({ code: 'ALREADY_EXISTS', message: 'Already exists', details: { fields: error.meta?.target } })
+ *     : null;
+ * ```
+ */
+export type ErrorMapper = (error: unknown) => HttpException | null;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/core/errors/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../src/core/errors/error-codes.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAA2B,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6IAA6I;IAC7I,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAWrD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,YAAY,CAenD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,IAAI,MAAM,CAElF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,aAAa,GAAG,IAAI,CAAC"}

package/dist/core/errors/error-codes.js

@@ -0,0 +1,140 @@
+"use strict";
+// =============================================================================
+// The error code registry and the error mapper contract (PP-14.14)
+// =============================================================================
+//
+// `code` in the error envelope (`ErrorDto`) used to be one of ten values derived
+// from the HTTP status, with a thrown payload's own `code` ignored. It is now an
+// open vocabulary:
+//
+//   * the status-derived codes (`BAD_REQUEST`, `CONFLICT`, ...) are the
+//     platform's registrations, made through the same `registerErrorCode` an app
+//     uses, and stay the DEFAULT for every status;
+//   * an app registers a DOMAIN code (`NOTE_TITLE_TAKEN`, 409) and throws an
+//     `HttpException` whose payload carries it; the filter passes a payload
+//     `code` through ONLY when it is registered AND registered for the
+//     exception's own status. Anything else falls back to the status-derived
+//     code, so an unregistered, misspelt or mismatched code can never reach the
+//     wire and the published list is exactly the registry.
+//
+// `ErrorMapper`s turn FOREIGN errors (Prisma, SDKs) into an `HttpException`
+// with a code the app chose; see `HttpExceptionFilterOptions`.
+//
+// FRAMEWORK-FREE except for the `HttpException` type.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorCodeRegistry = exports.BUILTIN_ERROR_CODES = exports.FALLBACK_ERROR_CODE = exports.ERROR_CODE_PATTERN = void 0;
+exports.registerErrorCode = registerErrorCode;
+exports.defaultErrorCodeForStatus = defaultErrorCodeForStatus;
+exports.isErrorCodeForStatus = isErrorCodeForStatus;
+const registry_1 = require("../registry/registry");
+/**
+ * The pattern an error code matches: UPPER_SNAKE, 3 to 64 characters, starting
+ * with a letter (`NOTE_TITLE_TAKEN`).
+ *
+ * @stability experimental
+ */
+exports.ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]{2,63}$/;
+/**
+ * The code of a failure whose status has no registered default (for example a
+ * 503). Never registered: it has no single status.
+ *
+ * @stability experimental
+ */
+exports.FALLBACK_ERROR_CODE = 'ERROR';
+/**
+ * The platform's status-derived codes, in the order the OpenAPI examples list
+ * them. The FIRST entry for a status is the default `code` of that status.
+ *
+ * @stability experimental
+ */
+exports.BUILTIN_ERROR_CODES = Object.freeze([
+    { code: 'BAD_REQUEST', status: 400, description: 'The request is malformed or failed validation.' },
+    { code: 'UNAUTHORIZED', status: 401, description: 'No valid credential was presented.' },
+    { code: 'FORBIDDEN', status: 403, description: 'The credential is valid but may not do this.' },
+    { code: 'NOT_FOUND', status: 404, description: 'The resource does not exist, or is not visible to the caller.' },
+    { code: 'CONFLICT', status: 409, description: 'The request conflicts with the current state, or a version precondition failed.' },
+    { code: 'PRECONDITION_FAILED', status: 412, description: 'An HTTP precondition header did not match.' },
+    { code: 'PAYLOAD_TOO_LARGE', status: 413, description: 'The request body is larger than the endpoint accepts.' },
+    { code: 'UNPROCESSABLE_ENTITY', status: 422, description: 'The request is well formed but cannot be processed.' },
+    { code: 'TOO_MANY_REQUESTS', status: 429, description: 'The caller is rate limited; see `Retry-After`.' },
+    { code: 'INTERNAL_ERROR', status: 500, description: 'An unexpected failure on the server.' },
+]);
+/**
+ * Every registered error code: the platform's ten first, then the app's.
+ * Frozen once the application has bootstrapped.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+exports.errorCodeRegistry = (0, registry_1.defineRegistry)({
+    name: 'core.error-codes',
+    idOf: (def) => def.code,
+    idPattern: exports.ERROR_CODE_PATTERN,
+    validate: (def) => {
+        if (!Number.isInteger(def.status) || def.status < 400 || def.status > 599) {
+            throw new Error(`error code "${def.code}": status must be an integer from 400 to 599, got ${JSON.stringify(def.status)}`);
+        }
+        if (typeof def.description !== 'string' || def.description.trim() === '') {
+            throw new Error(`error code "${def.code}": description must be a non-empty string`);
+        }
+        if (def.code === exports.FALLBACK_ERROR_CODE) {
+            throw new Error(`error code "${def.code}" is the fallback for unmapped statuses and cannot be registered`);
+        }
+    },
+});
+/**
+ * Registers a domain error code. Call it at module load, before the
+ * application is created; a duplicate code (including a built-in one) throws.
+ *
+ * A code is for ONE status. To let the filter pass it through, throw an
+ * `HttpException` of that status whose payload carries `code`.
+ *
+ * @param def - the code, its status and a description.
+ * @throws RegistryError `INVALID_ID`, `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+ *
+ * @example
+ * ```ts
+ * registerErrorCode({ code: 'NOTE_TITLE_TAKEN', status: 409, description: 'A note with this title already exists.' });
+ * // in a service:
+ * throw new ConflictException({ code: 'NOTE_TITLE_TAKEN', message: 'Title already used', details: { field: 'title' } });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerErrorCode(def) {
+    exports.errorCodeRegistry.register(def);
+}
+/**
+ * The default code of an HTTP status: the first registered code for it, else
+ * {@link FALLBACK_ERROR_CODE}.
+ *
+ * @param status - an HTTP status.
+ * @returns the code the envelope carries when the exception names none.
+ *
+ * @stability experimental
+ */
+function defaultErrorCodeForStatus(status) {
+    for (const def of exports.BUILTIN_ERROR_CODES) {
+        if (def.status === status)
+            return def.code;
+    }
+    return exports.FALLBACK_ERROR_CODE;
+}
+/**
+ * Whether `code` may appear in the envelope of an exception with `status`: it
+ * is registered, for that status.
+ *
+ * @param code - a payload `code`, as thrown.
+ * @param status - the exception's HTTP status.
+ * @returns `true` only for a registered code of that status.
+ *
+ * @stability experimental
+ */
+function isErrorCodeForStatus(code, status) {
+    return typeof code === 'string' && exports.errorCodeRegistry.get(code)?.status === status;
+}
+for (const def of exports.BUILTIN_ERROR_CODES)
+    registerErrorCode(def);
+//# sourceMappingURL=error-codes.js.map

package/dist/core/errors/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../../src/core/errors/error-codes.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,mEAAmE;AACnE,gFAAgF;AAChF,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,mBAAmB;AACnB,EAAE;AACF,wEAAwE;AACxE,iFAAiF;AACjF,mDAAmD;AACnD,6EAA6E;AAC7E,4EAA4E;AAC5E,uEAAuE;AACvE,6EAA6E;AAC7E,gFAAgF;AAChF,2DAA2D;AAC3D,EAAE;AACF,4EAA4E;AAC5E,+DAA+D;AAC/D,EAAE;AACF,sDAAsD;AACtD,gFAAgF;;;AAuGhF,8CAEC;AAWD,8DAKC;AAYD,oDAEC;AAnID,mDAAqE;AAErE;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,wBAAwB,CAAC;AAE3D;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG,OAAO,CAAC;AAoB3C;;;;;GAKG;AACU,QAAA,mBAAmB,GAA4B,MAAM,CAAC,MAAM,CAAC;IACxE,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,gDAAgD,EAAE;IACnG,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,oCAAoC,EAAE;IACxF,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,8CAA8C,EAAE;IAC/F,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,+DAA+D,EAAE;IAChH,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,iFAAiF,EAAE;IACjI,EAAE,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,4CAA4C,EAAE;IACvG,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,uDAAuD,EAAE;IAChH,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,qDAAqD,EAAE;IACjH,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,gDAAgD,EAAE;IACzG,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,sCAAsC,EAAE;CAC7F,CAAC,CAAC;AAEH;;;;;;GAMG;AACU,QAAA,iBAAiB,GAA2B,IAAA,yBAAc,EAAe;IACpF,IAAI,EAAE,kBAAkB;IACxB,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI;IACvB,SAAS,EAAE,0BAAkB;IAC7B,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;QAChB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YAC1E,MAAM,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,IAAI,qDAAqD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5H,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,IAAI,2CAA2C,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,GAAG,CAAC,IAAI,KAAK,2BAAmB,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,IAAI,kEAAkE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,iBAAiB,CAAC,GAAiB;IACjD,yBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,yBAAyB,CAAC,MAAc;IACtD,KAAK,MAAM,GAAG,IAAI,2BAAmB,EAAE,CAAC;QACtC,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;YAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IAC7C,CAAC;IACD,OAAO,2BAAmB,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,oBAAoB,CAAC,IAAa,EAAE,MAAc;IAChE,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,yBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AACpF,CAAC;AA0BD,KAAK,MAAM,GAAG,IAAI,2BAAmB;IAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC"}

package/dist/core/errors/error.dto.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The error body this API returns for every endpoint but one.
+ *
+ * `HttpExceptionFilter` rebuilds error responses from a fixed key allowlist —
+ * `statusCode`, `code`, `message`, `details`, `timestamp`, `path` and nothing
+ * else — so this class is not an approximation of the wire format, it is the
+ * complete set of keys that can appear. In particular a custom top-level field
+ * on a thrown `HttpException` payload is silently dropped; endpoint-specific
+ * data belongs under {@link details}.
+ *
+ * THE ONE EXCEPTION (#153): an endpoint whose error body is fixed by an
+ * external standard can opt out of this envelope entirely, by branding its
+ * exception with `withVerbatimErrorBody`
+ * (`./verbatim-error-body.exception.ts`). Its body is then sent
+ * exactly as thrown, with none of the keys below. Today the only user is
+ * `POST /auth/device/token`, which RFC 8628 §3.5 requires to answer with
+ * `{ error, error_description }` — see `DeviceTokenErrorDto`, which the
+ * operation declares for its 400 and 401 responses. That opt-out is deliberately
+ * hard to reach and rare; assume this envelope unless an operation documents
+ * otherwise.
+ *
+ * Kept as an `@ApiProperty` class rather than a zod DTO because nothing
+ * validates it — it is documentation-only, produced by the filter and never
+ * parsed on the way in. The OpenAPI schema name is `ErrorDto`; it is
+ * published, so the class name does not change.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * @ApiResponse({ status: 409, description: 'Already exists', type: ErrorDto })
+ * ```
+ */
+export declare class ErrorDto {
+    /** HTTP status code, repeated in the body. */
+    statusCode: number;
+    /** Machine-readable code: status-derived by default, or a registered domain code. */
+    code: string;
+    /** Human-readable description of what went wrong. */
+    message: string;
+    /** Endpoint-specific structured data, when the failure carried any. */
+    details?: unknown;
+    /** When the error was produced, ISO 8601 UTC. */
+    timestamp: string;
+    /** Request path that produced the error. */
+    path: string;
+}
+//# sourceMappingURL=error.dto.d.ts.map

package/dist/core/errors/error.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.dto.d.ts","sourceRoot":"","sources":["../../../src/core/errors/error.dto.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,QAAQ;IACnB,8CAA8C;IAK9C,UAAU,EAAG,MAAM,CAAC;IAEpB,qFAAqF;IAerF,IAAI,EAAG,MAAM,CAAC;IAEd,qDAAqD;IAKrD,OAAO,EAAG,MAAM,CAAC;IAEjB,uEAAuE;IAQvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,iDAAiD;IAKjD,SAAS,EAAG,MAAM,CAAC;IAEnB,4CAA4C;IAK5C,IAAI,EAAG,MAAM,CAAC;CACf"}