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

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

@@ -0,0 +1,115 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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);
+};
+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.
+ *
+ * `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 })
+ * ```
+ */
+class ErrorDto {
+    /** HTTP status code, repeated in the body. */
+    statusCode;
+    /** Machine-readable code: status-derived by default, or a registered domain code. */
+    code;
+    /** Human-readable description of what went wrong. */
+    message;
+    /** Endpoint-specific structured data, when the failure carried any. */
+    details;
+    /** When the error was produced, ISO 8601 UTC. */
+    timestamp;
+    /** Request path that produced the error. */
+    path;
+}
+exports.ErrorDto = ErrorDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'HTTP status code, repeated in the body so a logged payload is self-describing.',
+        example: 409,
+    }),
+    __metadata("design:type", Number)
+], ErrorDto.prototype, "statusCode", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        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',
+        // 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);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Human-readable description of what went wrong.',
+        example: 'Email already in allowlist',
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "message", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Endpoint-specific structured data — the only place a custom field survives the exception ' +
+            'filter. Omitted when the failure carried none. Shape varies by endpoint and is documented ' +
+            'on the operation that returns it.',
+        example: { field: 'email' },
+    }),
+    __metadata("design:type", Object)
+], ErrorDto.prototype, "details", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'When the error was produced, ISO 8601 UTC.',
+        example: '2026-08-17T04:37:58.000Z',
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "timestamp", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Request path that produced the error.',
+        example: '/api/allowlist',
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "path", void 0);
+//# sourceMappingURL=error.dto.js.map

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

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

@@ -0,0 +1,100 @@
+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 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 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
+ * (`PlatformHostCoreModule` does). Mappers come from `{ errorMappers }` of
+ * `PlatformHostCoreModule.forRoot`, or from the constructor.
+ *
+ * @stability stable
+ * @extensionPoint component
+ * @example
+ * ```ts
+ * import { APP_FILTER } from '@nestjs/core';
+ * import { HttpExceptionFilter } from '@marinoscar/platform-api/core';
+ *
+ * @Module({ providers: [{ provide: APP_FILTER, useClass: HttpExceptionFilter }] })
+ * export class AppModule {}
+ * ```
+ */
+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 `thrown`
+     * on the HTTP reply of `host`. Called by Nest, not by application code.
+     *
+     * @param thrown - Whatever was thrown.
+     * @param host - The Nest arguments host of the failed request (HTTP only).
+     */
+    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
+     * skip logging — a device-flow `slow_down` storm has to be visible in the
+     * logs like any other 4xx.
+     */
+    private logOutcome;
+    /**
+     * A short log-only description of a verbatim body.
+     *
+     * Reading `error` here is for the LOG LINE ONLY and shapes nothing — an RFC
+     * body's `error` is the single most useful thing to see in operations
+     * (`slow_down` and `access_denied` mean very different things at 3am), and
+     * without it every device-flow failure logs as an indistinguishable 400. The
+     * body itself is never stringified into the log: a verbatim payload is
+     * whatever the spec says it is, and this filter should not assume the rest of
+     * it is safe to print.
+     */
+    private summarize;
+    /**
+     * 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

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

@@ -0,0 +1,263 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 = 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 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 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
+ * (`PlatformHostCoreModule` does). Mappers come from `{ errorMappers }` of
+ * `PlatformHostCoreModule.forRoot`, or from the constructor.
+ *
+ * @stability stable
+ * @extensionPoint component
+ * @example
+ * ```ts
+ * import { APP_FILTER } from '@nestjs/core';
+ * import { HttpExceptionFilter } from '@marinoscar/platform-api/core';
+ *
+ * @Module({ providers: [{ provide: APP_FILTER, useClass: HttpExceptionFilter }] })
+ * export class AppModule {}
+ * ```
+ */
+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 `thrown`
+     * on the HTTP reply of `host`. Called by Nest, not by application code.
+     *
+     * @param thrown - Whatever was thrown.
+     * @param host - The Nest arguments host of the failed request (HTTP only).
+     */
+    catch(thrown, host) {
+        const ctx = host.switchToHttp();
+        const response = ctx.getResponse();
+        const request = ctx.getRequest();
+        let status = common_1.HttpStatus.INTERNAL_SERVER_ERROR;
+        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();
+            // ---------------------------------------------------------------------
+            // Verbatim bodies (#153) — checked FIRST, and returns immediately.
+            // ---------------------------------------------------------------------
+            // A branded exception carries a body dictated by an external spec, not by
+            // us: today that is `POST /auth/device/token`, whose RFC 8628 §3.5 body is
+            // `{ error, error_description }`. Sending it through the envelope below
+            // destroys it — the envelope reads only `message`, `code` and `details`,
+            // so all four RFC outcomes used to arrive as the same generic 400 and a
+            // polling client could not tell them apart. See
+            // `./verbatim-error-body.exception.ts` for why the opt-out
+            // is an explicit brand rather than the filter sniffing for an `error` key.
+            //
+            // Nothing is merged in — not `statusCode`, not `timestamp`, not `path`.
+            // Extra keys would not upset a tolerant parser, but they would put fields
+            // the RFC never defines into a protocol response, and a body that is
+            // "mostly the spec" is exactly the kind of thing a strict client rejects
+            // and a reader stops trusting. The status line still carries the code.
+            //
+            // The object guard matters: a string payload has nothing to send
+            // verbatim, so such an exception falls through to the envelope rather than
+            // putting a bare JSON string on the wire.
+            if ((0, verbatim_error_body_exception_1.hasVerbatimErrorBody)(exception) &&
+                typeof exceptionResponse === 'object' &&
+                exceptionResponse !== null) {
+                this.logOutcome(request, status, this.summarize(exceptionResponse), logged);
+                response.code(status).send(exceptionResponse);
+                return;
+            }
+            if (typeof exceptionResponse === 'string') {
+                message = exceptionResponse;
+            }
+            else if (typeof exceptionResponse === 'object') {
+                const resp = exceptionResponse;
+                message = resp.message || message;
+                details = resp.details;
+            }
+            // A body/query that failed the global `ZodValidationPipe` names the
+            // failing fields under `details.issues` (`{ path, message }` each). Only
+            // the path and Zod's (or the schema's own) message are published — never
+            // the submitted value, which may be personal data or free text.
+            if (exception instanceof nestjs_zod_1.ZodValidationException && details === undefined) {
+                details = zodIssueDetails(exception.getZodError());
+            }
+            // `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`).
+            //
+            // Endpoint-specific machine-readable data still belongs under `details`; an
+            // externally-specified body belongs behind the verbatim brand above.
+            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;
+            // Don't expose stack traces in production
+            if (process.env.NODE_ENV !== 'production') {
+                details = exception.stack;
+            }
+        }
+        const errorResponse = {
+            statusCode: status,
+            code,
+            message,
+            timestamp: new Date().toISOString(),
+            path: request.url,
+        };
+        if (details) {
+            errorResponse.details = details;
+        }
+        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
+        // so a client that honours it never retries early.
+        const retryAfterSeconds = status === 429 ? retryAfterSecondsOf(details) : undefined;
+        if (retryAfterSeconds !== undefined) {
+            response.header('Retry-After', String(retryAfterSeconds));
+        }
+        // Fastify response - use code() and send()
+        response.code(status).send(errorResponse);
+    }
+    /**
+     * One log line per handled failure, identical for enveloped and verbatim
+     * responses. Extracted so the verbatim early-return above cannot silently
+     * skip logging — a device-flow `slow_down` storm has to be visible in the
+     * logs like any other 4xx.
+     */
+    logOutcome(request, status, summary, exception) {
+        if (status >= 500) {
+            this.logger.error(`${request.method} ${request.url} - ${status}`, exception instanceof Error ? exception.stack : exception);
+        }
+        else {
+            this.logger.warn(`${request.method} ${request.url} - ${status}: ${summary}`);
+        }
+    }
+    /**
+     * A short log-only description of a verbatim body.
+     *
+     * Reading `error` here is for the LOG LINE ONLY and shapes nothing — an RFC
+     * body's `error` is the single most useful thing to see in operations
+     * (`slow_down` and `access_denied` mean very different things at 3am), and
+     * without it every device-flow failure logs as an indistinguishable 400. The
+     * body itself is never stringified into the log: a verbatim payload is
+     * whatever the spec says it is, and this filter should not assume the rest of
+     * it is safe to print.
+     */
+    summarize(body) {
+        const label = body.error ?? body.message;
+        return typeof label === 'string' ? label : 'verbatim error body';
+    }
+    /**
+     * 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)(),
+    __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) {
+    if (details === null || typeof details !== 'object')
+        return undefined;
+    const ms = details.retryAfterMs;
+    return typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? Math.max(1, Math.ceil(ms / 1000)) : undefined;
+}
+/** `{ issues: [{ path: 'readings.0.unit', message }] }`, or undefined. */
+function zodIssueDetails(error) {
+    const issues = error?.issues;
+    if (!Array.isArray(issues) || issues.length === 0) {
+        return undefined;
+    }
+    return {
+        issues: issues.map((issue) => ({
+            path: Array.isArray(issue.path) ? issue.path.map(String).join('.') : '',
+            message: typeof issue.message === 'string' ? issue.message : 'Invalid value',
+        })),
+    };
+}
+//# sourceMappingURL=http-exception.filter.js.map

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

@@ -0,0 +1 @@
+{"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/errors/verbatim-error-body.exception.d.ts

@@ -0,0 +1,46 @@
+import { HttpException } from '@nestjs/common';
+/**
+ * Mark an exception so `HttpExceptionFilter` sends its payload to the client
+ * exactly as given, instead of rebuilding it as
+ * `{ statusCode, code, message, … }`.
+ *
+ * Returns the same exception instance, so the class identity is untouched:
+ * `withVerbatimErrorBody(new BadRequestException(…))` is still a
+ * `BadRequestException` and still carries status 400. That matters — guards,
+ * interceptors and existing tests that branch on the exception type keep
+ * working, and the opt-out stays a single orthogonal fact about the response
+ * body rather than a parallel exception hierarchy.
+ *
+ * The payload MUST be an object; a string payload has nothing to send verbatim
+ * and the filter falls back to the envelope for it.
+ *
+ * Only for a body an external standard dictates (RFC 8628's
+ * `{ error, error_description }` is the one use in the reference app); see
+ * the header of this file.
+ *
+ * @param exception - The exception to brand; returned as is.
+ * @returns The same exception instance.
+ * @stability stable
+ * @example
+ * ```ts
+ * throw withVerbatimErrorBody(
+ *   new BadRequestException({ error: 'slow_down', error_description: 'Polling too fast' }),
+ * );
+ * ```
+ */
+export declare function withVerbatimErrorBody<T extends HttpException>(exception: T): T;
+/**
+ * Whether an exception opted out of the envelope. Read only by
+ * `HttpExceptionFilter`.
+ *
+ * @param exception - Anything thrown.
+ * @returns `true` only for an `HttpException` branded by
+ *   {@link withVerbatimErrorBody}.
+ * @stability stable
+ * @example
+ * ```ts
+ * hasVerbatimErrorBody(withVerbatimErrorBody(new BadRequestException({ error: 'x' }))); // true
+ * ```
+ */
+export declare function hasVerbatimErrorBody(exception: unknown): boolean;
+//# sourceMappingURL=verbatim-error-body.exception.d.ts.map

package/dist/core/errors/verbatim-error-body.exception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbatim-error-body.exception.d.ts","sourceRoot":"","sources":["../../../src/core/errors/verbatim-error-body.exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AA2E/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,aAAa,EAC3D,SAAS,EAAE,CAAC,GACX,CAAC,CAYH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAOhE"}