http-response-kit 1.0.0 → 2.0.0

package/dist/kit-nHfihlKE.d.ts

@@ -0,0 +1,753 @@
+/**
+ * HTTP Response Kit - Type Definitions
+ * @module types
+ */
+/**
+ * Information structure for HTTP errors
+ */
+interface HttpErrorInfo {
+    /** Lowercase identifier for the error type */
+    type: string;
+    /** Human-readable title */
+    title: string;
+    /** HTTP status code */
+    code: number;
+    /** Default error description */
+    details: string;
+    /** Optional retry-after time in seconds */
+    retryAfter?: number;
+    /** Optional resolution suggestion */
+    resolution?: string;
+}
+/**
+ * A single validation issue, used for structured 422/400 responses.
+ * Mirrors the common `errors[]` extension of RFC 9457.
+ */
+interface ValidationIssue {
+    /** The field/path that failed validation (e.g. "email", "items[0].qty") */
+    field: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Optional stable machine-readable code (e.g. "too_short") */
+    code?: string;
+}
+/**
+ * Configuration options for HttpError
+ */
+interface HttpErrorOptions {
+    /** Custom error message */
+    message?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Original error cause (also set as the native ES2022 `Error.cause`) */
+    cause?: Error;
+    /** Retry-after time in seconds */
+    retryAfter?: number;
+    /**
+     * Whether the error message is safe to expose to clients.
+     * Defaults to `true` for 4xx and `false` for 5xx (security best practice:
+     * internal server error messages are never leaked unless explicitly allowed).
+     */
+    expose?: boolean;
+    /**
+     * Stable application-level error code, independent from the HTTP status
+     * (e.g. "USER_NOT_FOUND", "ERR-1042"). Serialized as `error.code`.
+     */
+    errorCode?: string;
+    /** Structured validation issues (serialized as `error.errors`) */
+    validationErrors?: ValidationIssue[];
+    /** Extra HTTP headers to send with the error (merged into `getHeaders()`) */
+    headers?: Record<string, string>;
+    /** RFC 9457 `instance`: URI identifying this specific occurrence */
+    instance?: string;
+}
+/**
+ * Information structure for HTTP success responses
+ */
+interface HttpSuccessInfo {
+    /** HTTP status code */
+    code: number;
+    /** Description of the status */
+    description: string;
+}
+/**
+ * Configuration for success responses
+ */
+interface SuccessResponseConfig<T = unknown> {
+    /** Response data payload */
+    data?: T;
+    /** Custom success message */
+    message?: string;
+    /** HTTP status code (default: 200) */
+    statusCode?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Correlation/request id echoed as `request_id` */
+    requestId?: string;
+}
+/**
+ * Configuration for error responses
+ */
+interface ErrorResponseConfig {
+    /** Include stack trace in response (overrides dev-mode default) */
+    includeStack?: boolean;
+    /** Additional fields to include */
+    additionalFields?: Record<string, unknown>;
+    /** Fallback status code for unknown errors */
+    fallbackCode?: number;
+    /** Correlation/request id echoed as `request_id` */
+    requestId?: string;
+    /** RFC 9457 `instance` override for this response */
+    instance?: string;
+    /** Force-expose (or hide) the error message regardless of `error.expose` */
+    expose?: boolean;
+}
+/** Output key casing for generated responses */
+type ResponseCasing = 'snake' | 'camel';
+/** Output format: proprietary envelope or RFC 9457 Problem Details */
+type ResponseFormat = 'standard' | 'problem';
+/**
+ * Per-instance kit configuration (there is no global configuration:
+ * every `createResponseKit()` call owns an isolated copy of this).
+ */
+interface KitConfig {
+    /** Enable development mode (includes stack traces) */
+    isDevelopment?: boolean;
+    /** Include timestamp in responses (default: true) */
+    includeTimestamp?: boolean;
+    /** Custom default messages per error code */
+    customMessages?: Partial<Record<number, string>>;
+    /** Custom response transformer (applied last) */
+    responseTransformer?: (response: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Error output format (default: 'standard').
+     * 'problem' emits RFC 9457 Problem Details bodies from `error()`.
+     */
+    format?: ResponseFormat;
+    /** Key casing of generated responses (default: 'snake') */
+    casing?: ResponseCasing;
+    /**
+     * Base URI used to build RFC 9457 `type` URIs
+     * (e.g. "https://errors.example.com" -> "https://errors.example.com/not_found").
+     * Defaults to "about:blank" semantics when unset.
+     */
+    problemTypeBase?: string;
+    /**
+     * Message resolver hook (i18n / localization).
+     * Return a string to override the outgoing message, or undefined to keep it.
+     */
+    messageResolver?: (error: HttpErrorLike) => string | undefined;
+    /**
+     * Sanitizer applied to metadata before serialization
+     * (strip PII, secrets, internal fields...).
+     */
+    metadataSanitizer?: (metadata: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Expose 5xx error messages to clients by default (default: false).
+     * Strongly discouraged in production.
+     */
+    exposeServerErrors?: boolean;
+}
+/**
+ * Minimal structural view of HttpError used in config hooks
+ * (avoids circular type imports).
+ */
+interface HttpErrorLike {
+    code: number;
+    type: string;
+    title: string;
+    message: string;
+    errorCode?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Standard success response structure.
+ * The index signature `[key: string]: unknown` allows additional fields via
+ * `additionalFields`, but extra properties will be typed as `unknown` at compile time.
+ */
+interface SuccessResponse<T = unknown> {
+    success: true;
+    status_code: number;
+    timestamp?: string;
+    request_id?: string;
+    data?: T;
+    message?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Standard error response structure.
+ * The index signature `[key: string]: unknown` allows additional fields via
+ * `additionalFields`, but extra properties will be typed as `unknown` at compile time.
+ */
+interface ErrorResponse {
+    success: false;
+    status_code: number;
+    timestamp?: string;
+    request_id?: string;
+    retry_after?: number;
+    error: {
+        type: string;
+        title: string;
+        message: string;
+        code?: string;
+        details?: string;
+        errors?: ValidationIssue[];
+        stack?: string;
+        causes?: string[];
+    };
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * RFC 9457 (obsoletes RFC 7807) Problem Details object.
+ * Serve with `Content-Type: application/problem+json`.
+ */
+interface ProblemDetails {
+    /** URI reference identifying the problem type (default "about:blank") */
+    type: string;
+    /** Short human-readable summary of the problem type */
+    title: string;
+    /** HTTP status code */
+    status: number;
+    /** Human-readable explanation specific to this occurrence */
+    detail?: string;
+    /** URI reference identifying this specific occurrence */
+    instance?: string;
+    /** Extension: stable application error code */
+    code?: string;
+    /** Extension: validation issues */
+    errors?: ValidationIssue[];
+    /** Extension: correlation/request id */
+    request_id?: string;
+    /** Extension members */
+    [key: string]: unknown;
+}
+/** Options for building a Problem Details object */
+interface ProblemOptions {
+    /** Base URI for the `type` member (overrides config) */
+    typeBase?: string;
+    /** `instance` member */
+    instance?: string;
+    /** Correlation/request id */
+    requestId?: string;
+    /** Extra extension members */
+    extensions?: Record<string, unknown>;
+    /** Force-expose (or hide) the error message */
+    expose?: boolean;
+}
+/**
+ * Input parameters for offset-based paginated responses
+ */
+interface PaginationInput {
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    limit: number;
+    /** Total number of items */
+    total: number;
+    /** Optional pre-computed total pages (overrides auto-calculation) */
+    totalPages?: number;
+}
+/**
+ * Pagination metadata included in paginated responses
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+}
+/**
+ * Input parameters for cursor-based paginated responses
+ */
+interface CursorPaginationInput {
+    /** Cursor pointing to the next page (absent/undefined = no next page) */
+    nextCursor?: string;
+    /** Cursor pointing to the previous page */
+    prevCursor?: string;
+    /** Items per page */
+    limit?: number;
+    /** Optional total count, when known */
+    total?: number;
+}
+/** Definition of a single domain error in a catalog */
+interface CatalogEntry {
+    /** HTTP status code (e.g. 404) */
+    status: number;
+    /** Default client-facing message */
+    message?: string;
+    /** Optional title override */
+    title?: string;
+    /** Whether the message is exposable (defaults to status < 500) */
+    expose?: boolean;
+    /** Default metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * HTTP Response Kit - Status Code Enums
+ * @module constants/status-codes
+ */
+/**
+ * HTTP 4xx Client Error codes
+ */
+declare enum HttpClientErrorCode {
+    BAD_REQUEST = 400,
+    UNAUTHORIZED = 401,
+    PAYMENT_REQUIRED = 402,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    METHOD_NOT_ALLOWED = 405,
+    NOT_ACCEPTABLE = 406,
+    PROXY_AUTHENTICATION_REQUIRED = 407,
+    REQUEST_TIMEOUT = 408,
+    CONFLICT = 409,
+    GONE = 410,
+    LENGTH_REQUIRED = 411,
+    PRECONDITION_FAILED = 412,
+    PAYLOAD_TOO_LARGE = 413,
+    URI_TOO_LONG = 414,
+    UNSUPPORTED_MEDIA_TYPE = 415,
+    RANGE_NOT_SATISFIABLE = 416,
+    EXPECTATION_FAILED = 417,
+    IM_A_TEAPOT = 418,
+    MISDIRECTED_REQUEST = 421,
+    UNPROCESSABLE_ENTITY = 422,
+    LOCKED = 423,
+    FAILED_DEPENDENCY = 424,
+    TOO_EARLY = 425,
+    UPGRADE_REQUIRED = 426,
+    PRECONDITION_REQUIRED = 428,
+    TOO_MANY_REQUESTS = 429,
+    REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
+    UNAVAILABLE_FOR_LEGAL_REASONS = 451
+}
+/**
+ * HTTP 5xx Server Error codes
+ */
+declare enum HttpServerErrorCode {
+    INTERNAL_SERVER_ERROR = 500,
+    NOT_IMPLEMENTED = 501,
+    BAD_GATEWAY = 502,
+    SERVICE_UNAVAILABLE = 503,
+    GATEWAY_TIMEOUT = 504,
+    HTTP_VERSION_NOT_SUPPORTED = 505,
+    VARIANT_ALSO_NEGOTIATES = 506,
+    INSUFFICIENT_STORAGE = 507,
+    LOOP_DETECTED = 508,
+    BANDWIDTH_LIMIT_EXCEEDED = 509,
+    NOT_EXTENDED = 510,
+    NETWORK_AUTHENTICATION_REQUIRED = 511
+}
+/**
+ * All HTTP Error codes (4xx + 5xx)
+ */
+declare const HttpErrorCode: {
+    readonly [x: number]: string;
+    readonly INTERNAL_SERVER_ERROR: HttpServerErrorCode.INTERNAL_SERVER_ERROR;
+    readonly NOT_IMPLEMENTED: HttpServerErrorCode.NOT_IMPLEMENTED;
+    readonly BAD_GATEWAY: HttpServerErrorCode.BAD_GATEWAY;
+    readonly SERVICE_UNAVAILABLE: HttpServerErrorCode.SERVICE_UNAVAILABLE;
+    readonly GATEWAY_TIMEOUT: HttpServerErrorCode.GATEWAY_TIMEOUT;
+    readonly HTTP_VERSION_NOT_SUPPORTED: HttpServerErrorCode.HTTP_VERSION_NOT_SUPPORTED;
+    readonly VARIANT_ALSO_NEGOTIATES: HttpServerErrorCode.VARIANT_ALSO_NEGOTIATES;
+    readonly INSUFFICIENT_STORAGE: HttpServerErrorCode.INSUFFICIENT_STORAGE;
+    readonly LOOP_DETECTED: HttpServerErrorCode.LOOP_DETECTED;
+    readonly BANDWIDTH_LIMIT_EXCEEDED: HttpServerErrorCode.BANDWIDTH_LIMIT_EXCEEDED;
+    readonly NOT_EXTENDED: HttpServerErrorCode.NOT_EXTENDED;
+    readonly NETWORK_AUTHENTICATION_REQUIRED: HttpServerErrorCode.NETWORK_AUTHENTICATION_REQUIRED;
+    readonly BAD_REQUEST: HttpClientErrorCode.BAD_REQUEST;
+    readonly UNAUTHORIZED: HttpClientErrorCode.UNAUTHORIZED;
+    readonly PAYMENT_REQUIRED: HttpClientErrorCode.PAYMENT_REQUIRED;
+    readonly FORBIDDEN: HttpClientErrorCode.FORBIDDEN;
+    readonly NOT_FOUND: HttpClientErrorCode.NOT_FOUND;
+    readonly METHOD_NOT_ALLOWED: HttpClientErrorCode.METHOD_NOT_ALLOWED;
+    readonly NOT_ACCEPTABLE: HttpClientErrorCode.NOT_ACCEPTABLE;
+    readonly PROXY_AUTHENTICATION_REQUIRED: HttpClientErrorCode.PROXY_AUTHENTICATION_REQUIRED;
+    readonly REQUEST_TIMEOUT: HttpClientErrorCode.REQUEST_TIMEOUT;
+    readonly CONFLICT: HttpClientErrorCode.CONFLICT;
+    readonly GONE: HttpClientErrorCode.GONE;
+    readonly LENGTH_REQUIRED: HttpClientErrorCode.LENGTH_REQUIRED;
+    readonly PRECONDITION_FAILED: HttpClientErrorCode.PRECONDITION_FAILED;
+    readonly PAYLOAD_TOO_LARGE: HttpClientErrorCode.PAYLOAD_TOO_LARGE;
+    readonly URI_TOO_LONG: HttpClientErrorCode.URI_TOO_LONG;
+    readonly UNSUPPORTED_MEDIA_TYPE: HttpClientErrorCode.UNSUPPORTED_MEDIA_TYPE;
+    readonly RANGE_NOT_SATISFIABLE: HttpClientErrorCode.RANGE_NOT_SATISFIABLE;
+    readonly EXPECTATION_FAILED: HttpClientErrorCode.EXPECTATION_FAILED;
+    readonly IM_A_TEAPOT: HttpClientErrorCode.IM_A_TEAPOT;
+    readonly MISDIRECTED_REQUEST: HttpClientErrorCode.MISDIRECTED_REQUEST;
+    readonly UNPROCESSABLE_ENTITY: HttpClientErrorCode.UNPROCESSABLE_ENTITY;
+    readonly LOCKED: HttpClientErrorCode.LOCKED;
+    readonly FAILED_DEPENDENCY: HttpClientErrorCode.FAILED_DEPENDENCY;
+    readonly TOO_EARLY: HttpClientErrorCode.TOO_EARLY;
+    readonly UPGRADE_REQUIRED: HttpClientErrorCode.UPGRADE_REQUIRED;
+    readonly PRECONDITION_REQUIRED: HttpClientErrorCode.PRECONDITION_REQUIRED;
+    readonly TOO_MANY_REQUESTS: HttpClientErrorCode.TOO_MANY_REQUESTS;
+    readonly REQUEST_HEADER_FIELDS_TOO_LARGE: HttpClientErrorCode.REQUEST_HEADER_FIELDS_TOO_LARGE;
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: HttpClientErrorCode.UNAVAILABLE_FOR_LEGAL_REASONS;
+};
+type HttpErrorCode = HttpClientErrorCode | HttpServerErrorCode;
+/**
+ * HTTP 2xx Success codes
+ */
+declare enum HttpSuccessCode {
+    OK = 200,
+    CREATED = 201,
+    ACCEPTED = 202,
+    NON_AUTHORITATIVE_INFORMATION = 203,
+    NO_CONTENT = 204,
+    RESET_CONTENT = 205,
+    PARTIAL_CONTENT = 206,
+    MULTI_STATUS = 207,
+    ALREADY_REPORTED = 208,
+    IM_USED = 226
+}
+/**
+ * HTTP 3xx Redirect codes
+ */
+declare enum HttpRedirectCode {
+    MULTIPLE_CHOICES = 300,
+    MOVED_PERMANENTLY = 301,
+    FOUND = 302,
+    SEE_OTHER = 303,
+    NOT_MODIFIED = 304,
+    USE_PROXY = 305,
+    TEMPORARY_REDIRECT = 307,
+    PERMANENT_REDIRECT = 308
+}
+/**
+ * HTTP 1xx Informational codes
+ */
+declare enum HttpInfoCode {
+    CONTINUE = 100,
+    SWITCHING_PROTOCOLS = 101,
+    PROCESSING = 102,
+    EARLY_HINTS = 103
+}
+
+/**
+ * HTTP Response Kit - HttpError Class
+ * @module errors/HttpError
+ */
+
+/**
+ * Custom HTTP Error class that extends the native Error class.
+ * Provides structured error information for HTTP responses.
+ *
+ * Security model: `expose` controls whether `message` may be sent to clients.
+ * It defaults to `true` for 4xx and `false` for 5xx, so internal server error
+ * messages are never leaked unless explicitly allowed. The full message is
+ * always available on the instance for logging.
+ *
+ * @example
+ * ```ts
+ * // Basic usage with status code
+ * throw new HttpError(404);
+ * throw new HttpError(HttpErrorCode.NOT_FOUND);
+ *
+ * // With custom message
+ * throw new HttpError(404, { message: 'User not found' });
+ *
+ * // With metadata + stable application code
+ * throw new HttpError(400, {
+ *   message: 'Validation failed',
+ *   errorCode: 'VALIDATION_FAILED',
+ *   metadata: { fields: ['email', 'password'] }
+ * });
+ *
+ * // Using factory methods
+ * throw HttpError.notFound('Resource not found');
+ * throw HttpError.validation([{ field: 'email', message: 'Invalid email' }]);
+ * ```
+ */
+declare class HttpError extends Error {
+    /** HTTP status code */
+    readonly code: number;
+    /** Lowercase error type identifier */
+    readonly type: string;
+    /** Human-readable error title */
+    readonly title: string;
+    /** Default error description from definition */
+    readonly details: string;
+    /** Additional error metadata */
+    readonly metadata?: Record<string, unknown>;
+    /** Original error cause (also available as native `Error.cause`) */
+    readonly cause?: Error;
+    /** Retry-after time in seconds (if applicable) */
+    readonly retryAfter?: number;
+    /** Whether `message` is safe to send to clients (4xx: true, 5xx: false by default) */
+    readonly expose: boolean;
+    /** Stable application-level error code (e.g. "USER_NOT_FOUND") */
+    readonly errorCode?: string;
+    /** Structured validation issues */
+    readonly validationErrors?: ValidationIssue[];
+    /** Extra HTTP headers associated with this error */
+    readonly headers?: Record<string, string>;
+    /** RFC 9457 `instance` URI for this specific occurrence */
+    readonly instance?: string;
+    /**
+     * Creates a new HttpError instance
+     *
+     * @param code - HTTP status code (e.g., 404, 500)
+     * @param options - Optional configuration
+     */
+    constructor(code: HttpClientErrorCode | HttpServerErrorCode | number, options?: HttpErrorOptions);
+    /**
+     * The message that is safe to send to clients.
+     * Falls back to the generic definition message when `expose` is false.
+     */
+    get safeMessage(): string;
+    /**
+     * HTTP headers that should accompany this error response
+     * (e.g. `Retry-After` for 429/503, plus any custom headers).
+     */
+    getHeaders(): Record<string, string>;
+    /**
+     * Convert error to plain object for JSON serialization.
+     * Note: contains the full (non-sanitized) message - intended for logging.
+     * Use `kit.error()` / `toProblemDetails()` for client output.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Build an RFC 9457 Problem Details object for this error.
+     * Serve it with `Content-Type: application/problem+json`.
+     *
+     * @example
+     * ```ts
+     * const problem = HttpError.notFound('User not found').toProblemDetails({
+     *   typeBase: 'https://errors.example.com',
+     *   instance: '/users/42',
+     * });
+     * // { type: 'https://errors.example.com/not_found', title: 'Not Found',
+     * //   status: 404, detail: 'User not found', instance: '/users/42' }
+     * ```
+     */
+    toProblemDetails(options?: ProblemOptions): ProblemDetails;
+    /** 400 Bad Request */
+    static badRequest(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 401 Unauthorized */
+    static unauthorized(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 402 Payment Required */
+    static paymentRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 403 Forbidden */
+    static forbidden(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 404 Not Found */
+    static notFound(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 405 Method Not Allowed */
+    static methodNotAllowed(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 406 Not Acceptable */
+    static notAcceptable(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 407 Proxy Authentication Required */
+    static proxyAuthenticationRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 408 Request Timeout */
+    static requestTimeout(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 409 Conflict */
+    static conflict(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 410 Gone */
+    static gone(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 411 Length Required */
+    static lengthRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 412 Precondition Failed */
+    static preconditionFailed(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 413 Payload Too Large */
+    static payloadTooLarge(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 414 URI Too Long */
+    static uriTooLong(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 415 Unsupported Media Type */
+    static unsupportedMediaType(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 416 Range Not Satisfiable */
+    static rangeNotSatisfiable(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 417 Expectation Failed */
+    static expectationFailed(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 418 I'm a Teapot */
+    static imATeapot(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 421 Misdirected Request */
+    static misdirectedRequest(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 422 Unprocessable Entity */
+    static unprocessableEntity(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /**
+     * 422 Unprocessable Entity with structured validation issues.
+     *
+     * @example
+     * ```ts
+     * throw HttpError.validation([
+     *   { field: 'email', message: 'Invalid email format', code: 'invalid_format' },
+     *   { field: 'age', message: 'Must be >= 18', code: 'too_small' },
+     * ]);
+     * ```
+     */
+    static validation(errors: ValidationIssue[], message?: string, code?: number): HttpError;
+    /** 423 Locked */
+    static locked(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 424 Failed Dependency */
+    static failedDependency(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 425 Too Early */
+    static tooEarly(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 426 Upgrade Required */
+    static upgradeRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 428 Precondition Required */
+    static preconditionRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 429 Too Many Requests */
+    static tooManyRequests(message?: string, retryAfter?: number, metadata?: Record<string, unknown>): HttpError;
+    /** 431 Request Header Fields Too Large */
+    static requestHeaderFieldsTooLarge(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 451 Unavailable For Legal Reasons */
+    static unavailableForLegalReasons(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 500 Internal Server Error */
+    static internalServerError(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 501 Not Implemented */
+    static notImplemented(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 502 Bad Gateway */
+    static badGateway(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 503 Service Unavailable */
+    static serviceUnavailable(message?: string, retryAfter?: number, metadata?: Record<string, unknown>): HttpError;
+    /** 504 Gateway Timeout */
+    static gatewayTimeout(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 505 HTTP Version Not Supported */
+    static httpVersionNotSupported(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 506 Variant Also Negotiates */
+    static variantAlsoNegotiates(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 507 Insufficient Storage */
+    static insufficientStorage(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 508 Loop Detected */
+    static loopDetected(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 509 Bandwidth Limit Exceeded */
+    static bandwidthLimitExceeded(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 510 Not Extended */
+    static notExtended(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 511 Network Authentication Required */
+    static networkAuthenticationRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /**
+     * Create an HttpError from an unknown error.
+     *
+     * Security: wrapped errors are marked `expose: false` when the resulting
+     * status is 5xx, so unexpected internal messages (DB errors, stack info,
+     * connection strings...) are never sent to clients. The original message
+     * and cause are preserved on the instance for logging.
+     *
+     * System/socket errors (ECONNREFUSED, ETIMEDOUT, undici fetch codes...)
+     * are automatically mapped to the semantically correct 502/503/504 -
+     * including codes buried in the `cause` chain (e.g. Node's
+     * `fetch failed` TypeError) - with the syscall code as `errorCode`.
+     */
+    static fromError(error: unknown, fallbackCode?: number): HttpError;
+    /**
+     * Check if an error is an HttpError
+     */
+    static isHttpError(error: unknown): error is HttpError;
+    /**
+     * Check if error is a client error (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * Check if error is a server error (5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * Flattened chain of cause messages (most recent first).
+     * Useful for structured logging; never serialized to clients in production.
+     */
+    getCauseChain(): string[];
+}
+
+/**
+ * HTTP Response Kit - ResponseKit
+ *
+ * The single, definitive way to format responses: create an isolated kit
+ * with `createResponseKit()`. Every kit owns its configuration - there is
+ * no global mutable state anywhere in this library.
+ *
+ * @module kit
+ */
+
+/** Type guard: is this a success response? */
+declare function isSuccessResponse(response: SuccessResponse | ErrorResponse): response is SuccessResponse;
+/** Type guard: is this an error response? */
+declare function isErrorResponse(response: SuccessResponse | ErrorResponse): response is ErrorResponse;
+/**
+ * An isolated response formatter with its own configuration.
+ * Create one with {@link createResponseKit}.
+ */
+declare class ResponseKit {
+    private readonly config;
+    constructor(config?: KitConfig);
+    /** Merge partial configuration into this instance */
+    configure(config: Partial<KitConfig>): void;
+    /** Snapshot of the current configuration */
+    getConfig(): Readonly<KitConfig>;
+    /** Whether dev mode is active (stack traces, cause chains) */
+    isDevelopment(): boolean;
+    private finalize;
+    /**
+     * Resolve the outgoing client-facing message for an error.
+     *
+     * Priority: messageResolver > explicit message (if exposed)
+     * > customMessages[code] > generic status description.
+     */
+    private resolveMessage;
+    /** Format a success response */
+    success<T = unknown>(config?: SuccessResponseConfig<T>): SuccessResponse<T>;
+    /**
+     * Format an error response.
+     *
+     * Security: when the error is not exposable (5xx by default), the outgoing
+     * message falls back to the generic status description (or the configured
+     * custom message for that code) and `metadata` is omitted. The original
+     * message stays available on the error instance for logging.
+     */
+    error(error: HttpError, config?: ErrorResponseConfig): ErrorResponse;
+    /** Format a response from any error (converts to HttpError first) */
+    fromError(error: unknown, config?: ErrorResponseConfig): ErrorResponse;
+    /**
+     * Build an RFC 9457 Problem Details body from any error.
+     * Serve it with `Content-Type: application/problem+json`
+     * (see `PROBLEM_CONTENT_TYPE`).
+     */
+    problem(error: unknown, options?: ProblemOptions): ProblemDetails;
+    /** 200 OK */
+    ok<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
+    /** 201 Created */
+    created<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
+    /** 202 Accepted */
+    accepted<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
+    /** 204 No Content */
+    noContent(): SuccessResponse<never>;
+    /** 206 Partial Content */
+    partialContent<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
+    /** 304 Not Modified */
+    notModified(): SuccessResponse<never>;
+    /** Create an offset-based paginated success response */
+    paginated<T = unknown>(data: T[], pagination: PaginationInput, message?: string): SuccessResponse<T[]>;
+    /**
+     * Create a cursor-based paginated success response.
+     *
+     * @example
+     * ```ts
+     * kit.paginatedCursor(items, { nextCursor: 'eyJpZCI6NDJ9', limit: 20 });
+     * // metadata.pagination: { next_cursor, limit, has_next: true, has_prev: false }
+     * ```
+     */
+    paginatedCursor<T = unknown>(data: T[], cursor: CursorPaginationInput, message?: string): SuccessResponse<T[]>;
+}
+/**
+ * Create an isolated ResponseKit instance with its own configuration.
+ * This is the entry point of the library.
+ *
+ * @example
+ * ```ts
+ * const api = createResponseKit({
+ *   isDevelopment: process.env.NODE_ENV === 'development',
+ *   format: 'problem',
+ *   problemTypeBase: 'https://errors.example.com',
+ * });
+ *
+ * api.ok(user);
+ * api.error(HttpError.notFound('No such user'), { requestId: req.id });
+ * ```
+ */
+declare function createResponseKit(config?: KitConfig): ResponseKit;
+
+export { type CatalogEntry as C, type ErrorResponse as E, HttpError as H, type KitConfig as K, type ProblemDetails as P, ResponseKit as R, type SuccessResponse as S, type ValidationIssue as V, type HttpErrorInfo as a, type HttpSuccessInfo as b, type HttpErrorOptions as c, type ProblemOptions as d, type CursorPaginationInput as e, type ErrorResponseConfig as f, HttpClientErrorCode as g, HttpErrorCode as h, type HttpErrorLike as i, HttpInfoCode as j, HttpRedirectCode as k, HttpServerErrorCode as l, HttpSuccessCode as m, type PaginationInput as n, type PaginationMeta as o, type ResponseCasing as p, type ResponseFormat as q, type SuccessResponseConfig as r, createResponseKit as s, isErrorResponse as t, isSuccessResponse as u };