@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.4

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":"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"}

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

@@ -33,7 +33,7 @@
 export declare class ErrorDto {
     /** HTTP status code, repeated in the body. */
     statusCode: number;
-    /** Status-derived machine-readable code (closed enum, see the property's `@ApiProperty`). */
+    /** Machine-readable code: status-derived by default, or a registered domain code. */
     code: string;
     /** Human-readable description of what went wrong. */
     message: string;

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

@@ -1 +1 @@
-{"version":3,"file":"error.dto.d.ts","sourceRoot":"","sources":["../../../src/core/errors/error.dto.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,QAAQ;IACnB,8CAA8C;IAK9C,UAAU,EAAG,MAAM,CAAC;IAEpB,6FAA6F;IAsB7F,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"}
+{"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"}

package/dist/core/errors/error.dto.js

@@ -11,6 +11,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorDto = void 0;
 const swagger_1 = require("@nestjs/swagger");
+const error_codes_1 = require("./error-codes");
 /**
  * The error body this API returns for every endpoint but one.
  *
@@ -46,7 +47,7 @@ const swagger_1 = require("@nestjs/swagger");
 class ErrorDto {
     /** HTTP status code, repeated in the body. */
     statusCode;
-    /** Status-derived machine-readable code (closed enum, see the property's `@ApiProperty`). */
+    /** Machine-readable code: status-derived by default, or a registered domain code. */
     code;
     /** Human-readable description of what went wrong. */
     message;
@@ -67,24 +68,17 @@ __decorate([
 ], ErrorDto.prototype, "statusCode", void 0);
 __decorate([
     (0, swagger_1.ApiProperty)({
-        description: 'Stable machine-readable code. Derived from the status by the exception filter, which ' +
-            'overwrites any `code` a thrown exception supplied — so it is always one of the values ' +
-            'below. Prefer branching on this over matching `message`, which is prose and may change.',
+        type: String,
+        description: 'Stable machine-readable code. By default derived from the status by the exception filter ' +
+            '(`BAD_REQUEST`, `CONFLICT`, ...); an endpoint may answer with a domain code the application ' +
+            'registered for that status (`registerErrorCode`). An open string, not an enum: the `examples` ' +
+            'list the codes registered when the document was generated. Prefer branching on this over ' +
+            'matching `message`, which is prose and may change.',
         example: 'CONFLICT',
-        // Mirrors `HttpExceptionFilter.getCodeFromStatus`: the mapped statuses,
-        // plus the `ERROR` fallback an unmapped status produces.
-        enum: [
-            'BAD_REQUEST',
-            'UNAUTHORIZED',
-            'FORBIDDEN',
-            'NOT_FOUND',
-            'CONFLICT',
-            'PRECONDITION_FAILED',
-            'UNPROCESSABLE_ENTITY',
-            'TOO_MANY_REQUESTS',
-            'INTERNAL_ERROR',
-            'ERROR',
-        ],
+        // The platform's own codes (mirrors `BUILTIN_ERROR_CODES` plus the `ERROR`
+        // fallback); `enrichOpenApiDocument` replaces it with every REGISTERED code
+        // when it builds a document, so an app's domain codes are listed too.
+        examples: [...error_codes_1.BUILTIN_ERROR_CODES.map((def) => def.code), error_codes_1.FALLBACK_ERROR_CODE],
     }),
     __metadata("design:type", String)
 ], ErrorDto.prototype, "code", void 0);

package/dist/core/errors/error.dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.dto.js","sourceRoot":"","sources":["../../../src/core/errors/error.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6CAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,QAAQ;IACnB,8CAA8C;IAK9C,UAAU,CAAU;IAEpB,6FAA6F;IAsB7F,IAAI,CAAU;IAEd,qDAAqD;IAKrD,OAAO,CAAU;IAEjB,uEAAuE;IAQvE,OAAO,CAAW;IAElB,iDAAiD;IAKjD,SAAS,CAAU;IAEnB,4CAA4C;IAK5C,IAAI,CAAU;CACf;AA9DD,4BA8DC;AAxDC;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,gFAAgF;QAC7F,OAAO,EAAE,GAAG;KACb,CAAC;;4CACkB;AAwBpB;IArBC,IAAA,qBAAW,EAAC;QACX,WAAW,EACT,uFAAuF;YACvF,wFAAwF;YACxF,yFAAyF;QAC3F,OAAO,EAAE,UAAU;QACnB,wEAAwE;QACxE,yDAAyD;QACzD,IAAI,EAAE;YACJ,aAAa;YACb,cAAc;YACd,WAAW;YACX,WAAW;YACX,UAAU;YACV,qBAAqB;YACrB,sBAAsB;YACtB,mBAAmB;YACnB,gBAAgB;YAChB,OAAO;SACR;KACF,CAAC;;sCACY;AAOd;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,gDAAgD;QAC7D,OAAO,EAAE,4BAA4B;KACtC,CAAC;;yCACe;AAUjB;IAPC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EACT,2FAA2F;YAC3F,4FAA4F;YAC5F,mCAAmC;QACrC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;KAC5B,CAAC;;yCACgB;AAOlB;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,4CAA4C;QACzD,OAAO,EAAE,0BAA0B;KACpC,CAAC;;2CACiB;AAOnB;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,uCAAuC;QACpD,OAAO,EAAE,gBAAgB;KAC1B,CAAC;;sCACY"}
+{"version":3,"file":"error.dto.js","sourceRoot":"","sources":["../../../src/core/errors/error.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6CAAmE;AAEnE,+CAAyE;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,QAAQ;IACnB,8CAA8C;IAK9C,UAAU,CAAU;IAEpB,qFAAqF;IAerF,IAAI,CAAU;IAEd,qDAAqD;IAKrD,OAAO,CAAU;IAEjB,uEAAuE;IAQvE,OAAO,CAAW;IAElB,iDAAiD;IAKjD,SAAS,CAAU;IAEnB,4CAA4C;IAK5C,IAAI,CAAU;CACf;AAvDD,4BAuDC;AAjDC;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,gFAAgF;QAC7F,OAAO,EAAE,GAAG;KACb,CAAC;;4CACkB;AAiBpB;IAdC,IAAA,qBAAW,EAAC;QACX,IAAI,EAAE,MAAM;QACZ,WAAW,EACT,2FAA2F;YAC3F,8FAA8F;YAC9F,gGAAgG;YAChG,2FAA2F;YAC3F,oDAAoD;QACtD,OAAO,EAAE,UAAU;QACnB,2EAA2E;QAC3E,4EAA4E;QAC5E,sEAAsE;QACtE,QAAQ,EAAE,CAAC,GAAG,iCAAmB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,iCAAmB,CAAC;KAC/E,CAAC;;sCACY;AAOd;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,gDAAgD;QAC7D,OAAO,EAAE,4BAA4B;KACtC,CAAC;;yCACe;AAUjB;IAPC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EACT,2FAA2F;YAC3F,4FAA4F;YAC5F,mCAAmC;QACrC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;KAC5B,CAAC;;yCACgB;AAOlB;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,4CAA4C;QACzD,OAAO,EAAE,0BAA0B;KACpC,CAAC;;2CACiB;AAOnB;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,uCAAuC;QACpD,OAAO,EAAE,gBAAgB;KAC1B,CAAC;;sCACY"}

package/dist/core/errors/http-exception.filter.d.ts

@@ -1,22 +1,47 @@
 import { ExceptionFilter, ArgumentsHost } from '@nestjs/common';
+import { type ErrorMapper } from './error-codes';
+/**
+ * Injection token of {@link HttpExceptionFilterOptions}. `PlatformHostCoreModule.forRoot({ errorMappers })`
+ * binds it; a filter built without it (`new HttpExceptionFilter()`) maps nothing.
+ *
+ * @stability experimental
+ */
+export declare const HTTP_EXCEPTION_FILTER_OPTIONS: unique symbol;
+/**
+ * Options of {@link HttpExceptionFilter}.
+ *
+ * @stability experimental
+ */
+export interface HttpExceptionFilterOptions {
+    /**
+     * Mappers for foreign errors, tried in order. Each sees only a value that is
+     * not already an `HttpException`; the first non-`null` result is rendered as
+     * if it had been thrown. A mapper that throws is logged and skipped.
+     */
+    readonly mappers?: readonly ErrorMapper[];
+}
 /**
  * The application-wide exception filter: turns every thrown value into the one
  * error envelope (`{ statusCode, code, message, details?, timestamp, path }`,
  * documented by {@link ErrorDto}) on a Fastify reply, and logs one line per
  * failure (`warn` below 500, `error` with the stack from 500 up).
  *
- * `code` is always derived from the HTTP status; a `code` on the thrown
- * payload is ignored. `details` is the only place endpoint-specific data
+ * `code` is derived from the HTTP status, unless the thrown payload carries a
+ * `code` that is registered (`registerErrorCode`) for that same status; any other
+ * payload `code` is ignored. `details` is the only place endpoint-specific data
  * survives. An exception branded with {@link withVerbatimErrorBody} skips the
  * envelope and is sent exactly as thrown. A 429 whose `details.retryAfterMs`
  * is a positive number also gets a `Retry-After` header (whole seconds,
  * rounded up). A `ZodValidationException` without explicit details answers
  * `details.issues` (`[{ path, message }]`), never the submitted value. A
- * non-`HttpException` error is a 500 whose `details` carries the stack unless
- * `NODE_ENV` is `production`.
+ * non-`HttpException` error is first offered to the configured
+ * {@link ErrorMapper}s (a mapped error is rendered as the exception the mapper
+ * returned, never with the original message); an unmapped one is a 500 whose
+ * `details` carries the stack unless `NODE_ENV` is `production`.
  *
- * Register it once, as an `APP_FILTER` provider of the root module. There is
- * no module to import and nothing to configure.
+ * Register it once, as an `APP_FILTER` provider of the root module
+ * (`PlatformHostCoreModule` does). Mappers come from `{ errorMappers }` of
+ * `PlatformHostCoreModule.forRoot`, or from the constructor.
  *
  * @stability stable
  * @extensionPoint component
@@ -31,14 +56,21 @@ import { ExceptionFilter, ArgumentsHost } from '@nestjs/common';
  */
 export declare class HttpExceptionFilter implements ExceptionFilter {
     private readonly logger;
+    private readonly mappers;
+    /**
+     * @param options - mappers for foreign errors. Optional: Nest injects
+     *   {@link HTTP_EXCEPTION_FILTER_OPTIONS} when bound, and a bare
+     *   `new HttpExceptionFilter()` maps nothing.
+     */
+    constructor(options?: HttpExceptionFilterOptions);
     /**
-     * Nest's `ExceptionFilter` hook: write the error response for `exception`
+     * Nest's `ExceptionFilter` hook: write the error response for `thrown`
      * on the HTTP reply of `host`. Called by Nest, not by application code.
      *
-     * @param exception - Whatever was thrown.
+     * @param thrown - Whatever was thrown.
      * @param host - The Nest arguments host of the failed request (HTTP only).
      */
-    catch(exception: unknown, host: ArgumentsHost): void;
+    catch(thrown: unknown, host: ArgumentsHost): void;
     /**
      * One log line per handled failure, identical for enveloped and verbatim
      * responses. Extracted so the verbatim early-return above cannot silently
@@ -58,6 +90,11 @@ export declare class HttpExceptionFilter implements ExceptionFilter {
      * it is safe to print.
      */
     private summarize;
-    private getCodeFromStatus;
+    /**
+     * The first mapper's result for a foreign error. A mapper that throws, or
+     * returns anything but an `HttpException`, is skipped (a broken mapper must
+     * not turn one failure into two).
+     */
+    private map;
 }
 //# sourceMappingURL=http-exception.filter.d.ts.map

package/dist/core/errors/http-exception.filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-exception.filter.d.ts","sourceRoot":"","sources":["../../../src/core/errors/http-exception.filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAEf,aAAa,EAId,MAAM,gBAAgB,CAAC;AAaxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBACa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAE/D;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa;IAmI7C;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAkBlB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,iBAAiB;CAe1B"}
+{"version":3,"file":"http-exception.filter.d.ts","sourceRoot":"","sources":["../../../src/core/errors/http-exception.filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAEf,aAAa,EAMd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAGvB;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,OAAO,MAA8E,CAAC;AAElI;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBACa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;;;;OAIG;gBAC4D,OAAO,CAAC,EAAE,0BAA0B;IAInG;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa;IA8H1C;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAkBlB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;OAIG;IACH,OAAO,CAAC,GAAG;CAiBZ"}

package/dist/core/errors/http-exception.filter.js

@@ -5,30 +5,48 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 var HttpExceptionFilter_1;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpExceptionFilter = void 0;
+exports.HttpExceptionFilter = exports.HTTP_EXCEPTION_FILTER_OPTIONS = void 0;
 const common_1 = require("@nestjs/common");
 const nestjs_zod_1 = require("nestjs-zod");
+const error_codes_1 = require("./error-codes");
 const verbatim_error_body_exception_1 = require("./verbatim-error-body.exception");
+/**
+ * Injection token of {@link HttpExceptionFilterOptions}. `PlatformHostCoreModule.forRoot({ errorMappers })`
+ * binds it; a filter built without it (`new HttpExceptionFilter()`) maps nothing.
+ *
+ * @stability experimental
+ */
+exports.HTTP_EXCEPTION_FILTER_OPTIONS = Symbol.for('@marinoscar/platform/core/HTTP_EXCEPTION_FILTER_OPTIONS');
 /**
  * The application-wide exception filter: turns every thrown value into the one
  * error envelope (`{ statusCode, code, message, details?, timestamp, path }`,
  * documented by {@link ErrorDto}) on a Fastify reply, and logs one line per
  * failure (`warn` below 500, `error` with the stack from 500 up).
  *
- * `code` is always derived from the HTTP status; a `code` on the thrown
- * payload is ignored. `details` is the only place endpoint-specific data
+ * `code` is derived from the HTTP status, unless the thrown payload carries a
+ * `code` that is registered (`registerErrorCode`) for that same status; any other
+ * payload `code` is ignored. `details` is the only place endpoint-specific data
  * survives. An exception branded with {@link withVerbatimErrorBody} skips the
  * envelope and is sent exactly as thrown. A 429 whose `details.retryAfterMs`
  * is a positive number also gets a `Retry-After` header (whole seconds,
  * rounded up). A `ZodValidationException` without explicit details answers
  * `details.issues` (`[{ path, message }]`), never the submitted value. A
- * non-`HttpException` error is a 500 whose `details` carries the stack unless
- * `NODE_ENV` is `production`.
+ * non-`HttpException` error is first offered to the configured
+ * {@link ErrorMapper}s (a mapped error is rendered as the exception the mapper
+ * returned, never with the original message); an unmapped one is a 500 whose
+ * `details` carries the stack unless `NODE_ENV` is `production`.
  *
- * Register it once, as an `APP_FILTER` provider of the root module. There is
- * no module to import and nothing to configure.
+ * Register it once, as an `APP_FILTER` provider of the root module
+ * (`PlatformHostCoreModule` does). Mappers come from `{ errorMappers }` of
+ * `PlatformHostCoreModule.forRoot`, or from the constructor.
  *
  * @stability stable
  * @extensionPoint component
@@ -43,14 +61,23 @@ const verbatim_error_body_exception_1 = require("./verbatim-error-body.exception
  */
 let HttpExceptionFilter = HttpExceptionFilter_1 = class HttpExceptionFilter {
     logger = new common_1.Logger(HttpExceptionFilter_1.name);
+    mappers;
+    /**
+     * @param options - mappers for foreign errors. Optional: Nest injects
+     *   {@link HTTP_EXCEPTION_FILTER_OPTIONS} when bound, and a bare
+     *   `new HttpExceptionFilter()` maps nothing.
+     */
+    constructor(options) {
+        this.mappers = Object.freeze([...(options?.mappers ?? [])]);
+    }
     /**
-     * Nest's `ExceptionFilter` hook: write the error response for `exception`
+     * Nest's `ExceptionFilter` hook: write the error response for `thrown`
      * on the HTTP reply of `host`. Called by Nest, not by application code.
      *
-     * @param exception - Whatever was thrown.
+     * @param thrown - Whatever was thrown.
      * @param host - The Nest arguments host of the failed request (HTTP only).
      */
-    catch(exception, host) {
+    catch(thrown, host) {
         const ctx = host.switchToHttp();
         const response = ctx.getResponse();
         const request = ctx.getRequest();
@@ -58,6 +85,12 @@ let HttpExceptionFilter = HttpExceptionFilter_1 = class HttpExceptionFilter {
         let code = 'INTERNAL_ERROR';
         let message = 'An unexpected error occurred';
         let details;
+        // A foreign error (not an HttpException) is offered to the mappers first. A
+        // mapped one is rendered as the HttpException the mapper built; the original
+        // is kept for the server-side log line only.
+        const mapped = thrown instanceof common_1.HttpException ? null : this.map(thrown);
+        const exception = mapped ?? thrown;
+        const logged = thrown;
         if (exception instanceof common_1.HttpException) {
             status = exception.getStatus();
             const exceptionResponse = exception.getResponse();
@@ -85,7 +118,7 @@ let HttpExceptionFilter = HttpExceptionFilter_1 = class HttpExceptionFilter {
             if ((0, verbatim_error_body_exception_1.hasVerbatimErrorBody)(exception) &&
                 typeof exceptionResponse === 'object' &&
                 exceptionResponse !== null) {
-                this.logOutcome(request, status, this.summarize(exceptionResponse), exception);
+                this.logOutcome(request, status, this.summarize(exceptionResponse), logged);
                 response.code(status).send(exceptionResponse);
                 return;
             }
@@ -104,34 +137,21 @@ let HttpExceptionFilter = HttpExceptionFilter_1 = class HttpExceptionFilter {
             if (exception instanceof nestjs_zod_1.ZodValidationException && details === undefined) {
                 details = zodIssueDetails(exception.getZodError());
             }
-            // `code` is ALWAYS derived from the status, and a `code` on the thrown
-            // payload is deliberately ignored.
+            // `code` defaults to the one derived from the status. A `code` on the thrown
+            // payload is honoured ONLY when it is registered (`registerErrorCode`) for
+            // THIS status: an unregistered, misspelt or mismatched code can never reach
+            // the wire, so the published list (`ErrorDto`'s examples) is exactly the
+            // registry. Nothing registered by default differs from the status-derived
+            // code, so every built-in response is unchanged, including
+            // `DatabaseSeedException`, whose `DATABASE_SEED_REQUIRED` stays ignored
+            // (its identifying data is in `details`).
             //
-            // This line used to be preceded by `code = (resp.code as string) ||
-            // this.getCodeFromStatus(status)`, which this one immediately overwrote —
-            // dead since it was written, so no exception in the app could ever set its
-            // own code (#153). The dead line was removed rather than made to work,
-            // because honouring a payload `code` is a real behaviour change on the
-            // wire and the current behaviour is the one the API actually promises:
-            //
-            //   * `./error.dto.ts` publishes `code` as a CLOSED ENUM of the
-            //     nine status-derived values, and says in so many words that the
-            //     filter overwrites any `code` an exception supplied. That DTO is the
-            //     `default` error response on every operation in the OpenAPI document,
-            //     so it is a published contract, not a comment.
-            //   * `test/core/http-exception.filter.spec.ts` asserts it ("The filter overrides
-            //     custom code with standard code mapping"). The behaviour is tested,
-            //     not accidental.
-            //   * One exception does pass a `code`: `DatabaseSeedException` sends
-            //     `DATABASE_SEED_REQUIRED`. Reviving the dead line would have changed
-            //     that response's `code` from `INTERNAL_ERROR` to a value outside the
-            //     published enum — a silent contract break in the one place nobody
-            //     would think to check. Its identifying data is already in `details`,
-            //     which the envelope carries through.
-            //
-            // Endpoint-specific machine-readable data belongs under `details`; an
+            // Endpoint-specific machine-readable data still belongs under `details`; an
             // externally-specified body belongs behind the verbatim brand above.
-            code = this.getCodeFromStatus(status);
+            const payloadCode = typeof exceptionResponse === 'object' && exceptionResponse !== null
+                ? exceptionResponse.code
+                : undefined;
+            code = (0, error_codes_1.isErrorCodeForStatus)(payloadCode, status) ? payloadCode : (0, error_codes_1.defaultErrorCodeForStatus)(status);
         }
         else if (exception instanceof Error) {
             message = exception.message;
@@ -150,7 +170,7 @@ let HttpExceptionFilter = HttpExceptionFilter_1 = class HttpExceptionFilter {
         if (details) {
             errorResponse.details = details;
         }
-        this.logOutcome(request, status, message, exception);
+        this.logOutcome(request, status, message, logged);
         // A 429 that says when to come back (`details.retryAfterMs` — every
         // `AiError('AI_RATE_LIMITED')` that knows, including the AI rate limits of
         // #450) also says so in the standard header, in whole seconds rounded UP
@@ -191,25 +211,34 @@ let HttpExceptionFilter = HttpExceptionFilter_1 = class HttpExceptionFilter {
         const label = body.error ?? body.message;
         return typeof label === 'string' ? label : 'verbatim error body';
     }
-    getCodeFromStatus(status) {
-        const codeMap = {
-            400: 'BAD_REQUEST',
-            401: 'UNAUTHORIZED',
-            403: 'FORBIDDEN',
-            404: 'NOT_FOUND',
-            409: 'CONFLICT',
-            412: 'PRECONDITION_FAILED',
-            413: 'PAYLOAD_TOO_LARGE',
-            422: 'UNPROCESSABLE_ENTITY',
-            429: 'TOO_MANY_REQUESTS',
-            500: 'INTERNAL_ERROR',
-        };
-        return codeMap[status] || 'ERROR';
+    /**
+     * The first mapper's result for a foreign error. A mapper that throws, or
+     * returns anything but an `HttpException`, is skipped (a broken mapper must
+     * not turn one failure into two).
+     */
+    map(error) {
+        for (const mapper of this.mappers) {
+            try {
+                const result = mapper(error);
+                if (result instanceof common_1.HttpException)
+                    return result;
+                if (result !== null && result !== undefined) {
+                    this.logger.warn('An error mapper returned something other than an HttpException or null; ignored.');
+                }
+            }
+            catch (failure) {
+                this.logger.error('An error mapper threw; skipped.', failure instanceof Error ? failure.stack : String(failure));
+            }
+        }
+        return null;
     }
 };
 exports.HttpExceptionFilter = HttpExceptionFilter;
 exports.HttpExceptionFilter = HttpExceptionFilter = HttpExceptionFilter_1 = __decorate([
-    (0, common_1.Catch)()
+    (0, common_1.Catch)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(exports.HTTP_EXCEPTION_FILTER_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
 ], HttpExceptionFilter);
 /** `details.retryAfterMs` as a `Retry-After` delta-seconds value (at least 1), or `undefined`. */
 function retryAfterSecondsOf(details) {

package/dist/core/errors/http-exception.filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-exception.filter.js","sourceRoot":"","sources":["../../../src/core/errors/http-exception.filter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http-exception.filter.js","sourceRoot":"","sources":["../../../src/core/errors/http-exception.filter.ts"],"names":[],"mappings":"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"}

package/dist/core/host/platform-host.d.ts

@@ -16,6 +16,15 @@ export interface PlatformAccessPort {
     requirePermissions(permissions: readonly string[]): MethodDecorator & ClassDecorator;
     /** Decorators that authenticate the caller with no specific permission. */
     requireAuthenticated(): MethodDecorator & ClassDecorator;
+    /**
+     * Optional: the app's marker for a DELIBERATELY public route (the reference
+     * app binds its `@Public()`), so its route inventory and conformance checks
+     * see the route as public on purpose rather than unguarded by accident. A
+     * slice applies it only to a route its README documents as public (the
+     * sharing slice's link resolution, #730) and authenticates that route by
+     * other means. A slice that needs it and finds it absent leaves the route out.
+     */
+    allowPublic?(): MethodDecorator & ClassDecorator;
 }
 /**
  * Everything a packaged slice needs from the app at decorator time. Built once
@@ -31,8 +40,8 @@ export interface PlatformHost {
  * Validates and freezes the app's platform host.
  *
  * Checks that `access.requirePermissions` and `access.requireAuthenticated`
- * are functions and that each returns a decorator (both are called once, with
- * a probe permission, to find out). The returned host wraps them so a later
+ * (and the optional `access.allowPublic`) are functions and that each returns
+ * a decorator (each is called once, with a probe permission, to find out). The returned host wraps them so a later
  * call that returns something else, or `requirePermissions([])`, throws too.
  * Passing an already-defined host returns it unchanged.
  *

package/dist/core/host/platform-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-host.d.ts","sourceRoot":"","sources":["../../../src/core/host/platform-host.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,GAAG,cAAc,CAAC;IACrF,2EAA2E;IAC3E,oBAAoB,IAAI,eAAe,GAAG,cAAc,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CA+BnE"}
+{"version":3,"file":"platform-host.d.ts","sourceRoot":"","sources":["../../../src/core/host/platform-host.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,GAAG,cAAc,CAAC;IACrF,2EAA2E;IAC3E,oBAAoB,IAAI,eAAe,GAAG,cAAc,CAAC;IACzD;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,eAAe,GAAG,cAAc,CAAC;CAClD;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CA2CnE"}