http-response-kit 1.1.0 → 2.0.0

package/dist/index.d.mts

@@ -1,282 +1,5 @@
-/**
- * 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;
-}
-/**
- * Configuration options for HttpError
- */
-interface HttpErrorOptions {
-    /** Custom error message */
-    message?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-    /** Original error cause */
-    cause?: Error;
-    /** Retry-after time in seconds */
-    retryAfter?: number;
-}
-/**
- * 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>;
-}
-/**
- * Configuration for error responses
- */
-interface ErrorResponseConfig {
-    /** Include stack trace in response */
-    includeStack?: boolean;
-    /** Additional fields to include */
-    additionalFields?: Record<string, unknown>;
-    /** Fallback status code for unknown errors */
-    fallbackCode?: number;
-}
-/**
- * Global library configuration
- */
-interface LibraryConfig {
-    /** Enable development mode (includes stack traces) */
-    isDevelopment?: boolean;
-    /** Include timestamp in responses */
-    includeTimestamp?: boolean;
-    /** Custom default messages per error code */
-    customMessages?: Partial<Record<number, string>>;
-    /** Custom response transformer */
-    responseTransformer?: (response: Record<string, unknown>) => 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;
-    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;
-    retry_after?: number;
-    error: {
-        type: string;
-        title: string;
-        message: string;
-        details?: string;
-        stack?: string;
-    };
-    metadata?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-/**
- * Input parameters for 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;
-}
-
-/**
- * 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
-}
+import { a as HttpErrorInfo, b as HttpSuccessInfo, c as HttpErrorOptions, H as HttpError, C as CatalogEntry, P as ProblemDetails, d as ProblemOptions } from './kit-nHfihlKE.mjs';
+export { e as CursorPaginationInput, E as ErrorResponse, f as ErrorResponseConfig, g as HttpClientErrorCode, h as HttpErrorCode, i as HttpErrorLike, j as HttpInfoCode, k as HttpRedirectCode, l as HttpServerErrorCode, m as HttpSuccessCode, K as KitConfig, n as PaginationInput, o as PaginationMeta, p as ResponseCasing, q as ResponseFormat, R as ResponseKit, S as SuccessResponse, r as SuccessResponseConfig, V as ValidationIssue, s as createResponseKit, t as isErrorResponse, u as isSuccessResponse } from './kit-nHfihlKE.mjs';
 
 /**
  * HTTP Response Kit - Error Definitions
@@ -315,284 +38,109 @@ declare const HttpInfoDefinitions: Record<number, HttpSuccessInfo>;
 declare function getSuccessDefinition(code: number): HttpSuccessInfo;
 
 /**
- * HTTP Response Kit - HttpError Class
- * @module errors/HttpError
+ * HTTP Response Kit - Domain Error Catalog
+ *
+ * Enterprises need stable, machine-readable application error codes
+ * (e.g. "USER_NOT_FOUND", "PLAN_LIMIT_REACHED") that are independent from
+ * HTTP status codes. A catalog turns a declarative map into typed factories.
+ *
+ * @module errors/catalog
  */
 
+/** A factory produced by {@link createErrorCatalog} */
+type CatalogFactory = (message?: string, options?: Omit<HttpErrorOptions, 'errorCode'>) => HttpError;
 /**
- * Custom HTTP Error class that extends the native Error class.
- * Provides structured error information for HTTP responses.
+ * Create a typed catalog of domain errors.
+ *
+ * Each key becomes the stable `errorCode` (serialized as `error.code` in
+ * responses and as the `code` extension in Problem Details).
  *
  * @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
- * throw new HttpError(400, {
- *   message: 'Validation failed',
- *   metadata: { fields: ['email', 'password'] }
+ * export const Errors = createErrorCatalog({
+ *   USER_NOT_FOUND: { status: 404, message: 'User does not exist' },
+ *   PLAN_LIMIT_REACHED: { status: 402, message: 'Upgrade your plan' },
+ *   PAYMENT_GATEWAY_DOWN: { status: 502, expose: false },
  * });
  *
- * // Using factory methods
- * throw HttpError.notFound('Resource not found');
- * throw HttpError.badRequest('Invalid input');
+ * throw Errors.USER_NOT_FOUND();                    // default message
+ * throw Errors.USER_NOT_FOUND('No user with id 42'); // override message
  * ```
  */
-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 */
-    readonly cause?: Error;
-    /** Retry-after time in seconds (if applicable) */
-    readonly retryAfter?: number;
-    /**
-     * 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);
-    /**
-     * Convert error to plain object for JSON serialization
-     */
-    toJSON(): Record<string, unknown>;
-    /** 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;
-    /** 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 a status code with default definition values.
-     * Semantic alias for `new HttpError(code)`.
-     */
-    static fromStatus(code: HttpClientErrorCode | HttpServerErrorCode | number, options?: HttpErrorOptions): HttpError;
-    /**
-     * Create an HttpError from an unknown error
-     */
-    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;
-}
-
-/**
- * HTTP Response Kit - HttpResponse Class
- * @module responses/HttpResponse
- */
+declare function createErrorCatalog<T extends Record<string, CatalogEntry>>(catalog: T): {
+    [K in keyof T]: CatalogFactory;
+};
 
 /**
- * Utility class for formatting HTTP responses.
- * Provides consistent structure for both success and error responses.
+ * HTTP Response Kit - System/socket error mapping
  *
- * @example
- * ```ts
- * // Success response
- * const response = HttpResponse.success({
- *   data: { id: 1, name: 'John' },
- *   message: 'User created successfully',
- *   statusCode: 201
- * });
+ * Maps Node.js system errors (socket, DNS, timeout - including the undici
+ * codes thrown by Node 18+ global `fetch`) to the semantically correct
+ * 5xx HTTP status:
  *
- * // Error response
- * const error = new HttpError(404, { message: 'User not found' });
- * const errorResponse = HttpResponse.error(error);
+ * - upstream refused / reset / unreachable -> 502 Bad Gateway
+ * - upstream timed out                     -> 504 Gateway Timeout
+ * - temporary local exhaustion / DNS retry -> 503 Service Unavailable
  *
- * // Express integration
- * app.get('/user/:id', (req, res) => {
- *   try {
- *     const user = findUser(req.params.id);
- *     const response = HttpResponse.success({ data: user });
- *     res.status(response.status_code).json(response);
- *   } catch (err) {
- *     const response = HttpResponse.error(HttpError.fromError(err));
- *     res.status(response.status_code).json(response);
- *   }
- * });
- * ```
+ * These are NOT new HTTP statuses: socket errors are causes, and this module
+ * translates them into the right response. Mapped errors are always
+ * `expose: false` (the raw message stays on the instance for logging) and
+ * carry the syscall code as `errorCode` for telemetry.
+ *
+ * @module errors/system-errors
  */
-declare class HttpResponse {
-    /**
-     * Format a success response
-     *
-     * @param config - Success response configuration
-     * @returns Formatted success response object
-     */
-    static success<T = unknown>(config?: SuccessResponseConfig<T>): SuccessResponse<T>;
-    /**
-     * Format an error response
-     *
-     * @param error - HttpError instance
-     * @param config - Optional error response configuration
-     * @returns Formatted error response object
-     */
-    static error(error: HttpError, config?: ErrorResponseConfig): ErrorResponse;
-    /**
-     * Format a response from any error (converts to HttpError first)
-     *
-     * @param error - Any error type
-     * @param config - Optional error response configuration
-     * @returns Formatted error response object
-     */
-    static fromError(error: unknown, config?: ErrorResponseConfig): ErrorResponse;
-    /** 200 OK */
-    static ok<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
-    /** 201 Created */
-    static created<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
-    /** 202 Accepted */
-    static accepted<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
-    /** 204 No Content */
-    static noContent(): SuccessResponse<never>;
-    /** 206 Partial Content */
-    static partialContent<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
-    /** 304 Not Modified — Note: 304 is a 3xx redirect code, included here as a convenience method */
-    static notModified(): SuccessResponse<never>;
-    /**
-     * Check if a response is a success response
-     */
-    static isSuccess(response: SuccessResponse | ErrorResponse): response is SuccessResponse;
-    /**
-     * Check if a response is an error response
-     */
-    static isError(response: SuccessResponse | ErrorResponse): response is ErrorResponse;
-    /**
-     * Create a paginated success response
-     */
-    static paginated<T = unknown>(data: T[], pagination: PaginationInput, message?: string): SuccessResponse<T[]>;
-}
 
 /**
- * HTTP Response Kit - Library Configuration
- * @module config
+ * Mapping from Node.js / undici error codes to HTTP status codes.
+ * Exported so consumers can inspect or extend their own logic on top.
  */
-
+declare const SystemErrorStatusMap: Readonly<Record<string, number>>;
 /**
- * Configure the library globally
+ * Map a Node.js system/socket error to the appropriate HttpError
+ * (502/503/504), or return `undefined` when the error is not a
+ * recognized system error.
  *
- * @param config - Partial configuration to merge with current settings
+ * The resulting error is never exposable: clients get the generic status
+ * description, while the original message and cause stay available for
+ * logging. The syscall code is set as `errorCode` for telemetry.
  *
  * @example
  * ```ts
- * configure({
- *   isDevelopment: true,
- *   includeTimestamp: false,
- *   customMessages: {
- *     404: 'Oops! This page went on vacation 🏝️',
- *     500: 'Well, this is embarrassing... 🤖'
- *   },
- * });
+ * try {
+ *   await fetch('http://upstream.internal/api');
+ * } catch (err) {
+ *   throw mapSystemError(err) ?? HttpError.fromError(err);
+ * }
+ * // ECONNREFUSED -> 502 { error: { code: 'ECONNREFUSED', message: <generic> } }
  * ```
  */
-declare function configure(config: Partial<LibraryConfig>): void;
+declare function mapSystemError(error: unknown): HttpError | undefined;
+
 /**
- * Get the current library configuration
+ * HTTP Response Kit - RFC 9457 Problem Details helpers
+ * @module responses/problem
  */
-declare function getConfig(): Readonly<LibraryConfig>;
+
+/**
+ * The media type for RFC 9457 Problem Details responses.
+ * Set it as `Content-Type` when sending problem bodies.
+ */
+declare const PROBLEM_CONTENT_TYPE = "application/problem+json";
 /**
- * Reset configuration to defaults
+ * Build an RFC 9457 Problem Details object from any error.
+ *
+ * @example
+ * ```ts
+ * res
+ *   .status(problem.status)
+ *   .set('Content-Type', PROBLEM_CONTENT_TYPE)
+ *   .json(toProblem(err, { typeBase: 'https://errors.example.com' }));
+ * ```
  */
-declare function resetConfig(): void;
+declare function toProblem(error: unknown, options?: ProblemOptions): ProblemDetails;
 /**
- * Check if running in development mode
+ * Type guard for Problem Details objects
  */
-declare function isDevelopment(): boolean;
+declare function isProblemDetails(value: unknown): value is ProblemDetails;
 
-export { type ErrorResponse, type ErrorResponseConfig, HttpClientErrorCode, HttpError, HttpErrorCode, HttpErrorDefinitions, type HttpErrorInfo, type HttpErrorOptions, HttpInfoCode, HttpInfoDefinitions, HttpRedirectCode, HttpRedirectDefinitions, HttpResponse, HttpServerErrorCode, HttpSuccessCode, HttpSuccessDefinitions, type HttpSuccessInfo, type LibraryConfig, type PaginationInput, type PaginationMeta, type SuccessResponse, type SuccessResponseConfig, configure, getConfig, getErrorDefinition, getSuccessDefinition, isDevelopment, resetConfig };
+export { CatalogEntry, type CatalogFactory, HttpError, HttpErrorDefinitions, HttpErrorInfo, HttpErrorOptions, HttpInfoDefinitions, HttpRedirectDefinitions, HttpSuccessDefinitions, HttpSuccessInfo, PROBLEM_CONTENT_TYPE, ProblemDetails, ProblemOptions, SystemErrorStatusMap, createErrorCatalog, getErrorDefinition, getSuccessDefinition, isProblemDetails, mapSystemError, toProblem };