@nage-api/core 1.0.0-beta.2

package/dist/decorators/version.decorators.d.ts

@@ -0,0 +1,34 @@
+/**
+ * API-version decorators (PLAN.md §16.2, feature inventory row 21).
+ *
+ * Retained from the legacy framework, which selected handlers by an
+ * `x-application-version` header. Nest's built-in `@Version()` only matches
+ * exact versions, so ranges (`from` / `till` / `between`) are expressed as a
+ * rule read by `ApiVersionGuard`.
+ */
+import { type CustomDecorator } from '@nestjs/common';
+export type VersionRule = {
+    readonly kind: 'exact';
+    readonly versions: readonly number[];
+} | {
+    readonly kind: 'from';
+    readonly from: number;
+} | {
+    readonly kind: 'till';
+    readonly till: number;
+} | {
+    readonly kind: 'between';
+    readonly from: number;
+    readonly till: number;
+};
+/** Serve this route only to the listed versions. */
+export declare const ForVersion: (...versions: readonly number[]) => CustomDecorator;
+/** Serve this route from `version` onwards (inclusive). */
+export declare const FromVersion: (version: number) => CustomDecorator;
+/** Serve this route up to `version` (inclusive) — how a route is retired. */
+export declare const TillVersion: (version: number) => CustomDecorator;
+/** Serve this route for `from`..`till` inclusive. */
+export declare const BetweenVersions: (from: number, till: number) => CustomDecorator;
+/** Does `version` satisfy `rule`? Exported for testing and for the CLI's docs. */
+export declare function versionSatisfies(rule: VersionRule, version: number): boolean;
+//# sourceMappingURL=version.decorators.d.ts.map

package/dist/decorators/version.decorators.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * API-version decorators (PLAN.md §16.2, feature inventory row 21).
+ *
+ * Retained from the legacy framework, which selected handlers by an
+ * `x-application-version` header. Nest's built-in `@Version()` only matches
+ * exact versions, so ranges (`from` / `till` / `between`) are expressed as a
+ * rule read by `ApiVersionGuard`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BetweenVersions = exports.TillVersion = exports.FromVersion = exports.ForVersion = void 0;
+exports.versionSatisfies = versionSatisfies;
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+/** Serve this route only to the listed versions. */
+const ForVersion = (...versions) => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.versionRule, { kind: 'exact', versions });
+exports.ForVersion = ForVersion;
+/** Serve this route from `version` onwards (inclusive). */
+const FromVersion = (version) => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.versionRule, { kind: 'from', from: version });
+exports.FromVersion = FromVersion;
+/** Serve this route up to `version` (inclusive) — how a route is retired. */
+const TillVersion = (version) => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.versionRule, { kind: 'till', till: version });
+exports.TillVersion = TillVersion;
+/** Serve this route for `from`..`till` inclusive. */
+const BetweenVersions = (from, till) => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.versionRule, { kind: 'between', from, till });
+exports.BetweenVersions = BetweenVersions;
+/** Does `version` satisfy `rule`? Exported for testing and for the CLI's docs. */
+function versionSatisfies(rule, version) {
+    switch (rule.kind) {
+        case 'exact':
+            return rule.versions.includes(version);
+        case 'from':
+            return version >= rule.from;
+        case 'till':
+            return version <= rule.till;
+        case 'between':
+            return version >= rule.from && version <= rule.till;
+    }
+}
+//# sourceMappingURL=version.decorators.js.map

package/dist/errors/catalog.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The concrete error catalog (PLAN.md §17.1).
+ *
+ * Each class fixes its stable `code` and its HTTP status, so mapping lives with
+ * the error rather than in a `switch` inside the filter, and clients can program
+ * against codes instead of messages.
+ */
+import type { AuthenticationErrorCode, AuthorizationErrorCode, ErrorCode, ErrorDetail } from '@nage-api/contracts';
+import { NageError, type NageErrorOptions } from './nage.error.js';
+/**
+ * Status for every code in the catalog. Also consumed by the OpenAPI generator
+ * (Phase 6) so documented error schemas cannot drift from runtime behaviour.
+ */
+export declare const ERROR_STATUS_BY_CODE: Readonly<Record<ErrorCode, number>>;
+/**
+ * Client-safe default message per code. Deliberately generic: an authentication
+ * failure never reveals whether it was the address or the password that was
+ * wrong.
+ */
+export declare const DEFAULT_SAFE_MESSAGE: Readonly<Record<ErrorCode, string>>;
+/** Base for errors whose code is fixed by the class. */
+declare abstract class FixedCodeError extends NageError {
+    protected constructor(code: ErrorCode, options?: NageErrorOptions);
+}
+/** 422 — the request body or params failed validation. */
+export declare class ValidationError extends FixedCodeError {
+    readonly code: "VALIDATION_FAILED";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+    /** Build from field-level feedback, the common case for a `ValidationPipe`. */
+    static fromDetails(details: readonly ErrorDetail[], message?: string): ValidationError;
+}
+/** 400 — the query DSL was malformed or referenced a disallowed field. */
+export declare class InvalidQueryError extends FixedCodeError {
+    readonly code: "INVALID_QUERY";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 400 — `limit` exceeded the model's `maxLimit` (no unbounded queries, §12). */
+export declare class QueryLimitExceededError extends FixedCodeError {
+    readonly maxLimit: number;
+    readonly code: "QUERY_LIMIT_EXCEEDED";
+    readonly httpStatus: number;
+    constructor(maxLimit: number, options?: NageErrorOptions);
+}
+/** 401/423 — the caller could not be authenticated. */
+export declare class AuthenticationError extends NageError {
+    readonly code: AuthenticationErrorCode;
+    readonly httpStatus: number;
+    constructor(code?: AuthenticationErrorCode, options?: NageErrorOptions);
+}
+/** 403 — the caller is known but not allowed. */
+export declare class AuthorizationError extends NageError {
+    readonly code: AuthorizationErrorCode;
+    readonly httpStatus: number;
+    constructor(code?: AuthorizationErrorCode, options?: NageErrorOptions);
+}
+/** 404 — the resource does not exist, or the caller may not know that it does. */
+export declare class NotFoundError extends FixedCodeError {
+    readonly code: "RESOURCE_NOT_FOUND";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 409 — the write conflicts with the current state (e.g. a unique constraint). */
+export declare class ConflictError extends FixedCodeError {
+    readonly code: "RESOURCE_CONFLICT";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 409 — the record changed since it was read (optimistic locking, §14.2). */
+export declare class OptimisticLockError extends FixedCodeError {
+    readonly code: "OPTIMISTIC_LOCK_CONFLICT";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 429 — throttled. Carries the retry hint for the `Retry-After` header. */
+export declare class RateLimitError extends FixedCodeError {
+    readonly retryAfterSeconds?: number | undefined;
+    readonly code: "RATE_LIMIT_EXCEEDED";
+    readonly httpStatus: number;
+    constructor(retryAfterSeconds?: number | undefined, options?: NageErrorOptions);
+}
+/**
+ * 504 — the handler exceeded the request timeout (§21).
+ *
+ * 504 rather than 503: the deployment is up and took the request, it was this
+ * request that ran out of time, and a client that retries a 503 immediately
+ * would make a slow dependency slower.
+ */
+export declare class RequestTimeoutError extends FixedCodeError {
+    readonly timeoutMs: number;
+    readonly code: "REQUEST_TIMEOUT";
+    readonly httpStatus: number;
+    constructor(timeoutMs: number, options?: NageErrorOptions);
+}
+/** 502 — an upstream dependency failed. Its body is logged, never returned. */
+export declare class ExternalServiceError extends FixedCodeError {
+    readonly service: string;
+    readonly code: "EXTERNAL_SERVICE_ERROR";
+    readonly httpStatus: number;
+    constructor(service: string, options?: NageErrorOptions);
+}
+/** 500 — the data layer failed. SQL and driver detail stay in the log. */
+export declare class DatabaseError extends FixedCodeError {
+    readonly code: "DATABASE_ERROR";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 500 — a `UnitOfWork` could not commit. */
+export declare class TransactionFailedError extends FixedCodeError {
+    readonly code: "TRANSACTION_FAILED";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/**
+ * 500 — invalid configuration. Thrown at boot so a misconfigured process fails
+ * fast rather than serving traffic insecurely (§21).
+ */
+export declare class ConfigurationError extends FixedCodeError {
+    readonly code: "CONFIGURATION_INVALID";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 501 — the selected driver does not implement this capability. */
+export declare class UnsupportedOperationError extends FixedCodeError {
+    readonly code: "UNSUPPORTED_OPERATION";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 500 — the catch-all. Anything unrecognised becomes this at the boundary. */
+export declare class InternalError extends FixedCodeError {
+    readonly code: "INTERNAL_ERROR";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 422 — a business rule rejected an otherwise well-formed request. */
+export declare class DomainError extends FixedCodeError {
+    readonly code: "DOMAIN_RULE_VIOLATED";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+/** 412 — a stated precondition did not hold. */
+export declare class PreconditionFailedError extends FixedCodeError {
+    readonly code: "PRECONDITION_FAILED";
+    readonly httpStatus: number;
+    constructor(options?: NageErrorOptions);
+}
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/errors/catalog.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * The concrete error catalog (PLAN.md §17.1).
+ *
+ * Each class fixes its stable `code` and its HTTP status, so mapping lives with
+ * the error rather than in a `switch` inside the filter, and clients can program
+ * against codes instead of messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreconditionFailedError = exports.DomainError = exports.InternalError = exports.UnsupportedOperationError = exports.ConfigurationError = exports.TransactionFailedError = exports.DatabaseError = exports.ExternalServiceError = exports.RequestTimeoutError = exports.RateLimitError = exports.OptimisticLockError = exports.ConflictError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QueryLimitExceededError = exports.InvalidQueryError = exports.ValidationError = exports.DEFAULT_SAFE_MESSAGE = exports.ERROR_STATUS_BY_CODE = void 0;
+const nage_error_js_1 = require("./nage.error.js");
+/**
+ * Status for every code in the catalog. Also consumed by the OpenAPI generator
+ * (Phase 6) so documented error schemas cannot drift from runtime behaviour.
+ */
+exports.ERROR_STATUS_BY_CODE = {
+    VALIDATION_FAILED: 422,
+    INVALID_QUERY: 400,
+    QUERY_LIMIT_EXCEEDED: 400,
+    PAYLOAD_TOO_LARGE: 413,
+    AUTH_INVALID_CREDENTIALS: 401,
+    AUTH_TOKEN_EXPIRED: 401,
+    AUTH_TOKEN_INVALID: 401,
+    AUTH_TOKEN_REUSED: 401,
+    AUTH_SESSION_REVOKED: 401,
+    AUTH_ACCOUNT_LOCKED: 423,
+    AUTH_OTP_INVALID: 401,
+    AUTH_OTP_EXPIRED: 401,
+    AUTH_REQUIRED: 401,
+    FORBIDDEN: 403,
+    INSUFFICIENT_ROLE: 403,
+    INSUFFICIENT_PERMISSION: 403,
+    POLICY_DENIED: 403,
+    RESOURCE_NOT_FOUND: 404,
+    RESOURCE_CONFLICT: 409,
+    RESOURCE_GONE: 410,
+    OPTIMISTIC_LOCK_CONFLICT: 409,
+    RATE_LIMIT_EXCEEDED: 429,
+    REQUEST_TIMEOUT: 504,
+    EXTERNAL_SERVICE_ERROR: 502,
+    DATABASE_ERROR: 500,
+    TRANSACTION_FAILED: 500,
+    CONFIGURATION_INVALID: 500,
+    UNSUPPORTED_OPERATION: 501,
+    INTERNAL_ERROR: 500,
+    DOMAIN_RULE_VIOLATED: 422,
+    PRECONDITION_FAILED: 412,
+};
+/**
+ * Client-safe default message per code. Deliberately generic: an authentication
+ * failure never reveals whether it was the address or the password that was
+ * wrong.
+ */
+exports.DEFAULT_SAFE_MESSAGE = {
+    VALIDATION_FAILED: 'Validation failed',
+    INVALID_QUERY: 'The query is not valid',
+    QUERY_LIMIT_EXCEEDED: 'The requested page size is too large',
+    PAYLOAD_TOO_LARGE: 'The request body is too large',
+    AUTH_INVALID_CREDENTIALS: 'Invalid credentials',
+    AUTH_TOKEN_EXPIRED: 'The token has expired',
+    AUTH_TOKEN_INVALID: 'The token is not valid',
+    AUTH_TOKEN_REUSED: 'The session has been revoked',
+    AUTH_SESSION_REVOKED: 'The session has been revoked',
+    AUTH_ACCOUNT_LOCKED: 'The account is temporarily locked',
+    AUTH_OTP_INVALID: 'The code is not valid',
+    AUTH_OTP_EXPIRED: 'The code has expired',
+    AUTH_REQUIRED: 'Authentication is required',
+    FORBIDDEN: 'You are not allowed to perform this action',
+    INSUFFICIENT_ROLE: 'You are not allowed to perform this action',
+    INSUFFICIENT_PERMISSION: 'You are not allowed to perform this action',
+    POLICY_DENIED: 'You are not allowed to perform this action',
+    RESOURCE_NOT_FOUND: 'The requested resource was not found',
+    RESOURCE_CONFLICT: 'The resource conflicts with the current state',
+    RESOURCE_GONE: 'The resource is no longer available',
+    OPTIMISTIC_LOCK_CONFLICT: 'The resource was modified by someone else',
+    RATE_LIMIT_EXCEEDED: 'Too many requests',
+    REQUEST_TIMEOUT: 'The request took too long to process',
+    EXTERNAL_SERVICE_ERROR: 'An upstream service failed',
+    DATABASE_ERROR: 'Internal server error',
+    TRANSACTION_FAILED: 'Internal server error',
+    CONFIGURATION_INVALID: 'Internal server error',
+    UNSUPPORTED_OPERATION: 'This operation is not supported',
+    INTERNAL_ERROR: 'Internal server error',
+    DOMAIN_RULE_VIOLATED: 'The request violates a business rule',
+    PRECONDITION_FAILED: 'A precondition for this request was not met',
+};
+/** Base for errors whose code is fixed by the class. */
+class FixedCodeError extends nage_error_js_1.NageError {
+    constructor(code, options = {}) {
+        super(exports.DEFAULT_SAFE_MESSAGE[code], options);
+    }
+}
+/** 422 — the request body or params failed validation. */
+class ValidationError extends FixedCodeError {
+    code = 'VALIDATION_FAILED';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.VALIDATION_FAILED;
+    constructor(options = {}) {
+        super('VALIDATION_FAILED', options);
+    }
+    /** Build from field-level feedback, the common case for a `ValidationPipe`. */
+    static fromDetails(details, message) {
+        return new ValidationError(message === undefined ? { details } : { details, message });
+    }
+}
+exports.ValidationError = ValidationError;
+/** 400 — the query DSL was malformed or referenced a disallowed field. */
+class InvalidQueryError extends FixedCodeError {
+    code = 'INVALID_QUERY';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.INVALID_QUERY;
+    constructor(options = {}) {
+        super('INVALID_QUERY', options);
+    }
+}
+exports.InvalidQueryError = InvalidQueryError;
+/** 400 — `limit` exceeded the model's `maxLimit` (no unbounded queries, §12). */
+class QueryLimitExceededError extends FixedCodeError {
+    maxLimit;
+    code = 'QUERY_LIMIT_EXCEEDED';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.QUERY_LIMIT_EXCEEDED;
+    constructor(maxLimit, options = {}) {
+        super('QUERY_LIMIT_EXCEEDED', {
+            ...options,
+            message: options.message ?? `The requested page size exceeds the maximum of ${maxLimit}`,
+        });
+        this.maxLimit = maxLimit;
+    }
+}
+exports.QueryLimitExceededError = QueryLimitExceededError;
+/** 401/423 — the caller could not be authenticated. */
+class AuthenticationError extends nage_error_js_1.NageError {
+    code;
+    httpStatus;
+    constructor(code = 'AUTH_REQUIRED', options = {}) {
+        super(exports.DEFAULT_SAFE_MESSAGE[code], options);
+        this.code = code;
+        this.httpStatus = exports.ERROR_STATUS_BY_CODE[code];
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/** 403 — the caller is known but not allowed. */
+class AuthorizationError extends nage_error_js_1.NageError {
+    code;
+    httpStatus;
+    constructor(code = 'FORBIDDEN', options = {}) {
+        super(exports.DEFAULT_SAFE_MESSAGE[code], options);
+        this.code = code;
+        this.httpStatus = exports.ERROR_STATUS_BY_CODE[code];
+    }
+}
+exports.AuthorizationError = AuthorizationError;
+/** 404 — the resource does not exist, or the caller may not know that it does. */
+class NotFoundError extends FixedCodeError {
+    code = 'RESOURCE_NOT_FOUND';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.RESOURCE_NOT_FOUND;
+    constructor(options = {}) {
+        super('RESOURCE_NOT_FOUND', options);
+    }
+}
+exports.NotFoundError = NotFoundError;
+/** 409 — the write conflicts with the current state (e.g. a unique constraint). */
+class ConflictError extends FixedCodeError {
+    code = 'RESOURCE_CONFLICT';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.RESOURCE_CONFLICT;
+    constructor(options = {}) {
+        super('RESOURCE_CONFLICT', options);
+    }
+}
+exports.ConflictError = ConflictError;
+/** 409 — the record changed since it was read (optimistic locking, §14.2). */
+class OptimisticLockError extends FixedCodeError {
+    code = 'OPTIMISTIC_LOCK_CONFLICT';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.OPTIMISTIC_LOCK_CONFLICT;
+    constructor(options = {}) {
+        super('OPTIMISTIC_LOCK_CONFLICT', options);
+    }
+}
+exports.OptimisticLockError = OptimisticLockError;
+/** 429 — throttled. Carries the retry hint for the `Retry-After` header. */
+class RateLimitError extends FixedCodeError {
+    retryAfterSeconds;
+    code = 'RATE_LIMIT_EXCEEDED';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.RATE_LIMIT_EXCEEDED;
+    constructor(retryAfterSeconds, options = {}) {
+        super('RATE_LIMIT_EXCEEDED', options);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * 504 — the handler exceeded the request timeout (§21).
+ *
+ * 504 rather than 503: the deployment is up and took the request, it was this
+ * request that ran out of time, and a client that retries a 503 immediately
+ * would make a slow dependency slower.
+ */
+class RequestTimeoutError extends FixedCodeError {
+    timeoutMs;
+    code = 'REQUEST_TIMEOUT';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.REQUEST_TIMEOUT;
+    constructor(timeoutMs, options = {}) {
+        super('REQUEST_TIMEOUT', {
+            ...options,
+            meta: { ...options.meta, timeoutMs },
+        });
+        this.timeoutMs = timeoutMs;
+    }
+}
+exports.RequestTimeoutError = RequestTimeoutError;
+/** 502 — an upstream dependency failed. Its body is logged, never returned. */
+class ExternalServiceError extends FixedCodeError {
+    service;
+    code = 'EXTERNAL_SERVICE_ERROR';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.EXTERNAL_SERVICE_ERROR;
+    constructor(service, options = {}) {
+        super('EXTERNAL_SERVICE_ERROR', {
+            ...options,
+            meta: { ...options.meta, service },
+        });
+        this.service = service;
+    }
+}
+exports.ExternalServiceError = ExternalServiceError;
+/** 500 — the data layer failed. SQL and driver detail stay in the log. */
+class DatabaseError extends FixedCodeError {
+    code = 'DATABASE_ERROR';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.DATABASE_ERROR;
+    constructor(options = {}) {
+        super('DATABASE_ERROR', options);
+    }
+}
+exports.DatabaseError = DatabaseError;
+/** 500 — a `UnitOfWork` could not commit. */
+class TransactionFailedError extends FixedCodeError {
+    code = 'TRANSACTION_FAILED';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.TRANSACTION_FAILED;
+    constructor(options = {}) {
+        super('TRANSACTION_FAILED', options);
+    }
+}
+exports.TransactionFailedError = TransactionFailedError;
+/**
+ * 500 — invalid configuration. Thrown at boot so a misconfigured process fails
+ * fast rather than serving traffic insecurely (§21).
+ */
+class ConfigurationError extends FixedCodeError {
+    code = 'CONFIGURATION_INVALID';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.CONFIGURATION_INVALID;
+    constructor(options = {}) {
+        super('CONFIGURATION_INVALID', options);
+    }
+}
+exports.ConfigurationError = ConfigurationError;
+/** 501 — the selected driver does not implement this capability. */
+class UnsupportedOperationError extends FixedCodeError {
+    code = 'UNSUPPORTED_OPERATION';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.UNSUPPORTED_OPERATION;
+    constructor(options = {}) {
+        super('UNSUPPORTED_OPERATION', options);
+    }
+}
+exports.UnsupportedOperationError = UnsupportedOperationError;
+/** 500 — the catch-all. Anything unrecognised becomes this at the boundary. */
+class InternalError extends FixedCodeError {
+    code = 'INTERNAL_ERROR';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.INTERNAL_ERROR;
+    constructor(options = {}) {
+        super('INTERNAL_ERROR', options);
+    }
+}
+exports.InternalError = InternalError;
+/** 422 — a business rule rejected an otherwise well-formed request. */
+class DomainError extends FixedCodeError {
+    code = 'DOMAIN_RULE_VIOLATED';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.DOMAIN_RULE_VIOLATED;
+    constructor(options = {}) {
+        super('DOMAIN_RULE_VIOLATED', options);
+    }
+}
+exports.DomainError = DomainError;
+/** 412 — a stated precondition did not hold. */
+class PreconditionFailedError extends FixedCodeError {
+    code = 'PRECONDITION_FAILED';
+    httpStatus = exports.ERROR_STATUS_BY_CODE.PRECONDITION_FAILED;
+    constructor(options = {}) {
+        super('PRECONDITION_FAILED', options);
+    }
+}
+exports.PreconditionFailedError = PreconditionFailedError;
+//# sourceMappingURL=catalog.js.map

package/dist/errors/index.d.ts

@@ -0,0 +1,3 @@
+export { NageError, isNageError, type NageErrorOptions } from './nage.error.js';
+export * from './catalog.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNageError = exports.NageError = void 0;
+var nage_error_js_1 = require("./nage.error.js");
+Object.defineProperty(exports, "NageError", { enumerable: true, get: function () { return nage_error_js_1.NageError; } });
+Object.defineProperty(exports, "isNageError", { enumerable: true, get: function () { return nage_error_js_1.isNageError; } });
+__exportStar(require("./catalog.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/errors/nage.error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base class of the typed error hierarchy (PLAN.md §17).
+ *
+ * Two audiences, deliberately separated:
+ *   - the **client** gets `code`, `safeMessage` and (for validation) `details`
+ *   - the **server log** gets everything else, including `meta` and the cause
+ *
+ * `meta` is never serialized into a response. That is the whole point: the
+ * legacy `ErrorResponse` echoed `error.message` on 500s, leaking SQL and
+ * upstream payloads to callers.
+ */
+import type { ErrorCode, ErrorDetail, ErrorMetadata, ErrorPayload } from '@nage-api/contracts';
+export interface NageErrorOptions {
+    /**
+     * Client-safe message, replacing the code's default. Only pass a string here
+     * that you would be content to see in a public API response.
+     */
+    readonly message?: string;
+    /**
+     * Operator-facing description: becomes `Error.message`, so it appears in
+     * stack traces and log lines, but never in a response. This is where the
+     * useful specifics go — which variable, which model, which secret.
+     */
+    readonly detail?: string;
+    /** Field-level feedback; the only detail ever sent to a client. */
+    readonly details?: readonly ErrorDetail[];
+    /** Server-only debugging context. Logged, never serialized. */
+    readonly meta?: ErrorMetadata;
+    readonly cause?: unknown;
+}
+export declare abstract class NageError extends Error {
+    abstract readonly code: ErrorCode;
+    abstract readonly httpStatus: number;
+    /** Message safe to return to the caller. */
+    readonly safeMessage: string;
+    readonly details?: readonly ErrorDetail[];
+    readonly meta?: ErrorMetadata;
+    protected constructor(safeMessage: string, options?: NageErrorOptions);
+    /** The client-facing projection. Note what it omits. */
+    toPayload(): ErrorPayload;
+}
+export declare function isNageError(value: unknown): value is NageError;
+//# sourceMappingURL=nage.error.d.ts.map

package/dist/errors/nage.error.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Base class of the typed error hierarchy (PLAN.md §17).
+ *
+ * Two audiences, deliberately separated:
+ *   - the **client** gets `code`, `safeMessage` and (for validation) `details`
+ *   - the **server log** gets everything else, including `meta` and the cause
+ *
+ * `meta` is never serialized into a response. That is the whole point: the
+ * legacy `ErrorResponse` echoed `error.message` on 500s, leaking SQL and
+ * upstream payloads to callers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageError = void 0;
+exports.isNageError = isNageError;
+class NageError extends Error {
+    /** Message safe to return to the caller. */
+    safeMessage;
+    details;
+    meta;
+    constructor(safeMessage, options = {}) {
+        // Error.message is the operator's view; safeMessage is the caller's. Keeping
+        // them separate is what lets an error say "Required secret JWT_PRIVATE_KEY
+        // is not set" in the log and "Internal server error" on the wire.
+        super(options.detail ?? options.message ?? safeMessage, options.cause === undefined ? {} : { cause: options.cause });
+        this.name = new.target.name;
+        this.safeMessage = options.message ?? safeMessage;
+        if (options.details !== undefined)
+            this.details = options.details;
+        if (options.meta !== undefined)
+            this.meta = options.meta;
+        Error.captureStackTrace(this, new.target);
+    }
+    /** The client-facing projection. Note what it omits. */
+    toPayload() {
+        return this.details === undefined
+            ? { code: this.code, message: this.safeMessage }
+            : { code: this.code, message: this.safeMessage, details: this.details };
+    }
+}
+exports.NageError = NageError;
+function isNageError(value) {
+    return value instanceof NageError;
+}
+//# sourceMappingURL=nage.error.js.map

package/dist/guards/api-version.guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Enforces the version rules declared by `@ForVersion` and friends
+ * (PLAN.md §16.2).
+ *
+ * A route that does not apply to the requested version is reported as **not
+ * found**, not as a validation error: from the client's point of view that
+ * endpoint does not exist in the version it asked for.
+ */
+import { type CanActivate, type ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { NageCoreConfig } from '@nage-api/contracts';
+import { RequestContextService } from '../context/request-context.service.js';
+export declare class ApiVersionGuard implements CanActivate {
+    private readonly reflector;
+    private readonly context;
+    private readonly config;
+    constructor(reflector: Reflector, context: RequestContextService, config: NageCoreConfig);
+    canActivate(context: ExecutionContext): boolean;
+}
+//# sourceMappingURL=api-version.guard.d.ts.map