http-response-kit 1.0.0 → 2.0.0

package/dist/hono.js

@@ -0,0 +1,1139 @@
+'use strict';
+
+// src/constants/error-definitions.ts
+var HttpErrorDefinitions = {
+  // ========================================================================
+  // 4xx Client Errors
+  // ========================================================================
+  [400 /* BAD_REQUEST */]: {
+    type: "bad_request",
+    title: "Bad Request",
+    code: 400,
+    details: "The request cannot be processed due to invalid syntax or missing parameters."
+  },
+  [401 /* UNAUTHORIZED */]: {
+    type: "unauthorized",
+    title: "Unauthorized",
+    code: 401,
+    details: "Authentication is required and has failed or not yet been provided."
+  },
+  [402 /* PAYMENT_REQUIRED */]: {
+    type: "payment_required",
+    title: "Payment Required",
+    code: 402,
+    details: "Payment is required to access this resource."
+  },
+  [403 /* FORBIDDEN */]: {
+    type: "forbidden",
+    title: "Forbidden",
+    code: 403,
+    details: "The server understood the request but refuses to authorize it."
+  },
+  [404 /* NOT_FOUND */]: {
+    type: "not_found",
+    title: "Not Found",
+    code: 404,
+    details: "The requested resource could not be found."
+  },
+  [405 /* METHOD_NOT_ALLOWED */]: {
+    type: "method_not_allowed",
+    title: "Method Not Allowed",
+    code: 405,
+    details: "The method specified in the request is not allowed for the resource."
+  },
+  [406 /* NOT_ACCEPTABLE */]: {
+    type: "not_acceptable",
+    title: "Not Acceptable",
+    code: 406,
+    details: "The resource is not available in a format acceptable to the client."
+  },
+  [407 /* PROXY_AUTHENTICATION_REQUIRED */]: {
+    type: "proxy_authentication_required",
+    title: "Proxy Authentication Required",
+    code: 407,
+    details: "Authentication with the proxy is required."
+  },
+  [408 /* REQUEST_TIMEOUT */]: {
+    type: "request_timeout",
+    title: "Request Timeout",
+    code: 408,
+    details: "The server timed out waiting for the request."
+  },
+  [409 /* CONFLICT */]: {
+    type: "conflict",
+    title: "Conflict",
+    code: 409,
+    details: "The request conflicts with the current state of the resource."
+  },
+  [410 /* GONE */]: {
+    type: "gone",
+    title: "Gone",
+    code: 410,
+    details: "The requested resource is no longer available and will not be available again."
+  },
+  [411 /* LENGTH_REQUIRED */]: {
+    type: "length_required",
+    title: "Length Required",
+    code: 411,
+    details: "The request did not specify the length of its content, which is required."
+  },
+  [412 /* PRECONDITION_FAILED */]: {
+    type: "precondition_failed",
+    title: "Precondition Failed",
+    code: 412,
+    details: "One or more conditions in the request header fields evaluated to false."
+  },
+  [413 /* PAYLOAD_TOO_LARGE */]: {
+    type: "payload_too_large",
+    title: "Payload Too Large",
+    code: 413,
+    details: "The request payload is larger than the server is willing to process."
+  },
+  [414 /* URI_TOO_LONG */]: {
+    type: "uri_too_long",
+    title: "URI Too Long",
+    code: 414,
+    details: "The URI provided was too long for the server to process."
+  },
+  [415 /* UNSUPPORTED_MEDIA_TYPE */]: {
+    type: "unsupported_media_type",
+    title: "Unsupported Media Type",
+    code: 415,
+    details: "The media format of the requested data is not supported by the server."
+  },
+  [416 /* RANGE_NOT_SATISFIABLE */]: {
+    type: "range_not_satisfiable",
+    title: "Range Not Satisfiable",
+    code: 416,
+    details: "The range specified in the request header cannot be fulfilled."
+  },
+  [417 /* EXPECTATION_FAILED */]: {
+    type: "expectation_failed",
+    title: "Expectation Failed",
+    code: 417,
+    details: "The server cannot meet the requirements of the Expect request-header field."
+  },
+  [418 /* IM_A_TEAPOT */]: {
+    type: "im_a_teapot",
+    title: "I'm a Teapot",
+    code: 418,
+    details: "The server refuses to brew coffee because it is, permanently, a teapot."
+  },
+  [421 /* MISDIRECTED_REQUEST */]: {
+    type: "misdirected_request",
+    title: "Misdirected Request",
+    code: 421,
+    details: "The request was directed at a server that is not able to produce a response."
+  },
+  [422 /* UNPROCESSABLE_ENTITY */]: {
+    type: "unprocessable_entity",
+    title: "Unprocessable Entity",
+    code: 422,
+    details: "The request was well-formed but was unable to be followed due to semantic errors."
+  },
+  [423 /* LOCKED */]: {
+    type: "locked",
+    title: "Locked",
+    code: 423,
+    details: "The resource that is being accessed is locked."
+  },
+  [424 /* FAILED_DEPENDENCY */]: {
+    type: "failed_dependency",
+    title: "Failed Dependency",
+    code: 424,
+    details: "The request failed because it depended on another request that failed."
+  },
+  [425 /* TOO_EARLY */]: {
+    type: "too_early",
+    title: "Too Early",
+    code: 425,
+    details: "The server is unwilling to risk processing a request that might be replayed."
+  },
+  [426 /* UPGRADE_REQUIRED */]: {
+    type: "upgrade_required",
+    title: "Upgrade Required",
+    code: 426,
+    details: "The client should switch to a different protocol."
+  },
+  [428 /* PRECONDITION_REQUIRED */]: {
+    type: "precondition_required",
+    title: "Precondition Required",
+    code: 428,
+    details: "The origin server requires the request to be conditional."
+  },
+  [429 /* TOO_MANY_REQUESTS */]: {
+    type: "too_many_requests",
+    title: "Too Many Requests",
+    code: 429,
+    details: "The user has sent too many requests in a given amount of time.",
+    retryAfter: 60
+  },
+  [431 /* REQUEST_HEADER_FIELDS_TOO_LARGE */]: {
+    type: "request_header_fields_too_large",
+    title: "Request Header Fields Too Large",
+    code: 431,
+    details: "The server is unwilling to process the request because its header fields are too large."
+  },
+  [451 /* UNAVAILABLE_FOR_LEGAL_REASONS */]: {
+    type: "unavailable_for_legal_reasons",
+    title: "Unavailable For Legal Reasons",
+    code: 451,
+    details: "The resource is unavailable due to legal demands."
+  },
+  // ========================================================================
+  // 5xx Server Errors
+  // ========================================================================
+  [500 /* INTERNAL_SERVER_ERROR */]: {
+    type: "internal_server_error",
+    title: "Internal Server Error",
+    code: 500,
+    details: "An unexpected error occurred on the server."
+  },
+  [501 /* NOT_IMPLEMENTED */]: {
+    type: "not_implemented",
+    title: "Not Implemented",
+    code: 501,
+    details: "The server does not support the functionality required to fulfill the request."
+  },
+  [502 /* BAD_GATEWAY */]: {
+    type: "bad_gateway",
+    title: "Bad Gateway",
+    code: 502,
+    details: "The server received an invalid response from an upstream server."
+  },
+  [503 /* SERVICE_UNAVAILABLE */]: {
+    type: "service_unavailable",
+    title: "Service Unavailable",
+    code: 503,
+    details: "The server is currently unable to handle the request due to temporary overloading or maintenance.",
+    retryAfter: 60,
+    resolution: "Try again after a short period or contact support."
+  },
+  [504 /* GATEWAY_TIMEOUT */]: {
+    type: "gateway_timeout",
+    title: "Gateway Timeout",
+    code: 504,
+    details: "The server did not receive a timely response from an upstream server."
+  },
+  [505 /* HTTP_VERSION_NOT_SUPPORTED */]: {
+    type: "http_version_not_supported",
+    title: "HTTP Version Not Supported",
+    code: 505,
+    details: "The server does not support the HTTP protocol version used in the request."
+  },
+  [506 /* VARIANT_ALSO_NEGOTIATES */]: {
+    type: "variant_also_negotiates",
+    title: "Variant Also Negotiates",
+    code: 506,
+    details: "The server has an internal configuration error during content negotiation."
+  },
+  [507 /* INSUFFICIENT_STORAGE */]: {
+    type: "insufficient_storage",
+    title: "Insufficient Storage",
+    code: 507,
+    details: "The server is unable to store the representation needed to complete the request."
+  },
+  [508 /* LOOP_DETECTED */]: {
+    type: "loop_detected",
+    title: "Loop Detected",
+    code: 508,
+    details: "The server detected an infinite loop while processing the request."
+  },
+  [509 /* BANDWIDTH_LIMIT_EXCEEDED */]: {
+    type: "bandwidth_limit_exceeded",
+    title: "Bandwidth Limit Exceeded",
+    code: 509,
+    details: "The server has exceeded the bandwidth limit."
+  },
+  [510 /* NOT_EXTENDED */]: {
+    type: "not_extended",
+    title: "Not Extended",
+    code: 510,
+    details: "Further extensions to the request are required for the server to fulfill it."
+  },
+  [511 /* NETWORK_AUTHENTICATION_REQUIRED */]: {
+    type: "network_authentication_required",
+    title: "Network Authentication Required",
+    code: 511,
+    details: "The client needs to authenticate to gain network access."
+  }
+};
+Object.freeze(HttpErrorDefinitions);
+function getErrorDefinition(code) {
+  if (code < 400 || code > 599) {
+    throw new RangeError(
+      `Invalid HTTP error code: ${code}. Must be between 400 and 599.`
+    );
+  }
+  if (HttpErrorDefinitions[code]) {
+    return HttpErrorDefinitions[code];
+  }
+  const isClientError = code >= 400 && code < 500;
+  return {
+    type: isClientError ? "unknown_client_error" : "unknown_server_error",
+    title: isClientError ? "Unknown Client Error" : "Unknown Server Error",
+    code,
+    details: isClientError ? "An unknown client error occurred." : "An unknown server error occurred."
+  };
+}
+
+// src/errors/system-errors.ts
+var SystemErrorStatusMap = Object.freeze({
+  // Connection-level failures -> 502 Bad Gateway
+  ECONNREFUSED: 502,
+  ECONNRESET: 502,
+  ECONNABORTED: 502,
+  EPIPE: 502,
+  EHOSTUNREACH: 502,
+  ENETUNREACH: 502,
+  ENETDOWN: 502,
+  ENOTFOUND: 502,
+  // DNS: host does not resolve
+  EPROTO: 502,
+  // TLS/protocol failure
+  ERR_TLS_CERT_ALTNAME_INVALID: 502,
+  // Timeouts -> 504 Gateway Timeout
+  ETIMEDOUT: 504,
+  ESOCKETTIMEDOUT: 504,
+  // Temporary conditions -> 503 Service Unavailable
+  EAI_AGAIN: 503,
+  // DNS: temporary resolution failure
+  EMFILE: 503,
+  // too many open files (fd exhaustion)
+  ENFILE: 503,
+  ENOBUFS: 503,
+  // undici / Node 18+ global fetch
+  UND_ERR_CONNECT_TIMEOUT: 504,
+  UND_ERR_HEADERS_TIMEOUT: 504,
+  UND_ERR_BODY_TIMEOUT: 504,
+  UND_ERR_SOCKET: 502,
+  UND_ERR_DESTROYED: 502,
+  UND_ERR_CLOSED: 502
+});
+var MAX_CAUSE_DEPTH = 5;
+function findSystemErrorCode(error) {
+  let current = error;
+  let depth = 0;
+  while (current !== null && typeof current === "object" && depth < MAX_CAUSE_DEPTH) {
+    const code = current.code;
+    if (typeof code === "string" && code in SystemErrorStatusMap) {
+      return code;
+    }
+    current = current.cause;
+    depth++;
+  }
+  return void 0;
+}
+function mapSystemError(error) {
+  const code = findSystemErrorCode(error);
+  if (code === void 0) {
+    return void 0;
+  }
+  const status = SystemErrorStatusMap[code];
+  return new HttpError(status, {
+    message: error instanceof Error ? error.message : String(error),
+    cause: error instanceof Error ? error : void 0,
+    expose: false,
+    errorCode: code
+  });
+}
+
+// src/errors/HttpError.ts
+var HttpError = class _HttpError extends Error {
+  /** HTTP status code */
+  code;
+  /** Lowercase error type identifier */
+  type;
+  /** Human-readable error title */
+  title;
+  /** Default error description from definition */
+  details;
+  /** Additional error metadata */
+  metadata;
+  /** Original error cause (also available as native `Error.cause`) */
+  cause;
+  /** Retry-after time in seconds (if applicable) */
+  retryAfter;
+  /** Whether `message` is safe to send to clients (4xx: true, 5xx: false by default) */
+  expose;
+  /** Stable application-level error code (e.g. "USER_NOT_FOUND") */
+  errorCode;
+  /** Structured validation issues */
+  validationErrors;
+  /** Extra HTTP headers associated with this error */
+  headers;
+  /** RFC 9457 `instance` URI for this specific occurrence */
+  instance;
+  /**
+   * Creates a new HttpError instance
+   *
+   * @param code - HTTP status code (e.g., 404, 500)
+   * @param options - Optional configuration
+   */
+  constructor(code, options = {}) {
+    const errorInfo = getErrorDefinition(code);
+    const finalMessage = options.message ?? errorInfo.details;
+    super(finalMessage);
+    this.name = "HttpError";
+    this.code = errorInfo.code;
+    this.type = errorInfo.type;
+    this.title = errorInfo.title;
+    this.details = errorInfo.details;
+    this.metadata = options.metadata;
+    this.retryAfter = options.retryAfter ?? errorInfo.retryAfter;
+    this.expose = options.expose ?? errorInfo.code < 500;
+    this.errorCode = options.errorCode;
+    this.validationErrors = options.validationErrors;
+    this.headers = options.headers;
+    this.instance = options.instance;
+    if (options.cause !== void 0) {
+      this.cause = options.cause;
+    }
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, _HttpError);
+    }
+  }
+  /**
+   * The message that is safe to send to clients.
+   * Falls back to the generic definition message when `expose` is false.
+   */
+  get safeMessage() {
+    return this.expose ? this.message : this.details;
+  }
+  /**
+   * HTTP headers that should accompany this error response
+   * (e.g. `Retry-After` for 429/503, plus any custom headers).
+   */
+  getHeaders() {
+    const headers = { ...this.headers };
+    if (this.retryAfter !== void 0) {
+      headers["Retry-After"] = String(this.retryAfter);
+    }
+    return headers;
+  }
+  /**
+   * 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() {
+    return {
+      name: this.name,
+      code: this.code,
+      type: this.type,
+      title: this.title,
+      message: this.message,
+      details: this.details,
+      errorCode: this.errorCode,
+      metadata: this.metadata,
+      retryAfter: this.retryAfter,
+      expose: this.expose,
+      validationErrors: this.validationErrors
+    };
+  }
+  /**
+   * 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 = {}) {
+    const exposed = options.expose ?? this.expose;
+    const problem = {
+      type: options.typeBase ? `${options.typeBase.replace(/\/$/, "")}/${this.type}` : "about:blank",
+      title: this.title,
+      status: this.code,
+      detail: exposed ? this.message : this.details
+    };
+    if (options.instance ?? this.instance) {
+      problem.instance = options.instance ?? this.instance;
+    }
+    if (this.errorCode) {
+      problem.code = this.errorCode;
+    }
+    if (this.validationErrors?.length) {
+      problem.errors = this.validationErrors;
+    }
+    if (options.requestId) {
+      problem.request_id = options.requestId;
+    }
+    if (options.extensions) {
+      for (const [key, value] of Object.entries(options.extensions)) {
+        if (!(key in problem)) {
+          problem[key] = value;
+        }
+      }
+    }
+    return problem;
+  }
+  // ========================================================================
+  // Factory Methods - 4xx Client Errors
+  // ========================================================================
+  /** 400 Bad Request */
+  static badRequest(message, metadata) {
+    return new _HttpError(400, { message, metadata });
+  }
+  /** 401 Unauthorized */
+  static unauthorized(message, metadata) {
+    return new _HttpError(401, { message, metadata });
+  }
+  /** 402 Payment Required */
+  static paymentRequired(message, metadata) {
+    return new _HttpError(402, { message, metadata });
+  }
+  /** 403 Forbidden */
+  static forbidden(message, metadata) {
+    return new _HttpError(403, { message, metadata });
+  }
+  /** 404 Not Found */
+  static notFound(message, metadata) {
+    return new _HttpError(404, { message, metadata });
+  }
+  /** 405 Method Not Allowed */
+  static methodNotAllowed(message, metadata) {
+    return new _HttpError(405, { message, metadata });
+  }
+  /** 406 Not Acceptable */
+  static notAcceptable(message, metadata) {
+    return new _HttpError(406, { message, metadata });
+  }
+  /** 407 Proxy Authentication Required */
+  static proxyAuthenticationRequired(message, metadata) {
+    return new _HttpError(407, { message, metadata });
+  }
+  /** 408 Request Timeout */
+  static requestTimeout(message, metadata) {
+    return new _HttpError(408, { message, metadata });
+  }
+  /** 409 Conflict */
+  static conflict(message, metadata) {
+    return new _HttpError(409, { message, metadata });
+  }
+  /** 410 Gone */
+  static gone(message, metadata) {
+    return new _HttpError(410, { message, metadata });
+  }
+  /** 411 Length Required */
+  static lengthRequired(message, metadata) {
+    return new _HttpError(411, { message, metadata });
+  }
+  /** 412 Precondition Failed */
+  static preconditionFailed(message, metadata) {
+    return new _HttpError(412, { message, metadata });
+  }
+  /** 413 Payload Too Large */
+  static payloadTooLarge(message, metadata) {
+    return new _HttpError(413, { message, metadata });
+  }
+  /** 414 URI Too Long */
+  static uriTooLong(message, metadata) {
+    return new _HttpError(414, { message, metadata });
+  }
+  /** 415 Unsupported Media Type */
+  static unsupportedMediaType(message, metadata) {
+    return new _HttpError(415, { message, metadata });
+  }
+  /** 416 Range Not Satisfiable */
+  static rangeNotSatisfiable(message, metadata) {
+    return new _HttpError(416, { message, metadata });
+  }
+  /** 417 Expectation Failed */
+  static expectationFailed(message, metadata) {
+    return new _HttpError(417, { message, metadata });
+  }
+  /** 418 I'm a Teapot */
+  static imATeapot(message, metadata) {
+    return new _HttpError(418, { message, metadata });
+  }
+  /** 421 Misdirected Request */
+  static misdirectedRequest(message, metadata) {
+    return new _HttpError(421, { message, metadata });
+  }
+  /** 422 Unprocessable Entity */
+  static unprocessableEntity(message, metadata) {
+    return new _HttpError(422, { message, metadata });
+  }
+  /**
+   * 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, message = "Validation failed", code = 422) {
+    return new _HttpError(code, { message, validationErrors: errors, errorCode: "VALIDATION_FAILED" });
+  }
+  /** 423 Locked */
+  static locked(message, metadata) {
+    return new _HttpError(423, { message, metadata });
+  }
+  /** 424 Failed Dependency */
+  static failedDependency(message, metadata) {
+    return new _HttpError(424, { message, metadata });
+  }
+  /** 425 Too Early */
+  static tooEarly(message, metadata) {
+    return new _HttpError(425, { message, metadata });
+  }
+  /** 426 Upgrade Required */
+  static upgradeRequired(message, metadata) {
+    return new _HttpError(426, { message, metadata });
+  }
+  /** 428 Precondition Required */
+  static preconditionRequired(message, metadata) {
+    return new _HttpError(428, { message, metadata });
+  }
+  /** 429 Too Many Requests */
+  static tooManyRequests(message, retryAfter, metadata) {
+    return new _HttpError(429, { message, metadata, retryAfter });
+  }
+  /** 431 Request Header Fields Too Large */
+  static requestHeaderFieldsTooLarge(message, metadata) {
+    return new _HttpError(431, { message, metadata });
+  }
+  /** 451 Unavailable For Legal Reasons */
+  static unavailableForLegalReasons(message, metadata) {
+    return new _HttpError(451, { message, metadata });
+  }
+  // ========================================================================
+  // Factory Methods - 5xx Server Errors
+  // ========================================================================
+  /** 500 Internal Server Error */
+  static internalServerError(message, metadata) {
+    return new _HttpError(500, { message, metadata });
+  }
+  /** 501 Not Implemented */
+  static notImplemented(message, metadata) {
+    return new _HttpError(501, { message, metadata });
+  }
+  /** 502 Bad Gateway */
+  static badGateway(message, metadata) {
+    return new _HttpError(502, { message, metadata });
+  }
+  /** 503 Service Unavailable */
+  static serviceUnavailable(message, retryAfter, metadata) {
+    return new _HttpError(503, { message, metadata, retryAfter });
+  }
+  /** 504 Gateway Timeout */
+  static gatewayTimeout(message, metadata) {
+    return new _HttpError(504, { message, metadata });
+  }
+  /** 505 HTTP Version Not Supported */
+  static httpVersionNotSupported(message, metadata) {
+    return new _HttpError(505, { message, metadata });
+  }
+  /** 506 Variant Also Negotiates */
+  static variantAlsoNegotiates(message, metadata) {
+    return new _HttpError(506, { message, metadata });
+  }
+  /** 507 Insufficient Storage */
+  static insufficientStorage(message, metadata) {
+    return new _HttpError(507, { message, metadata });
+  }
+  /** 508 Loop Detected */
+  static loopDetected(message, metadata) {
+    return new _HttpError(508, { message, metadata });
+  }
+  /** 509 Bandwidth Limit Exceeded */
+  static bandwidthLimitExceeded(message, metadata) {
+    return new _HttpError(509, { message, metadata });
+  }
+  /** 510 Not Extended */
+  static notExtended(message, metadata) {
+    return new _HttpError(510, { message, metadata });
+  }
+  /** 511 Network Authentication Required */
+  static networkAuthenticationRequired(message, metadata) {
+    return new _HttpError(511, { message, metadata });
+  }
+  // ========================================================================
+  // Utility Methods
+  // ========================================================================
+  /**
+   * 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, fallbackCode = 500) {
+    if (error instanceof _HttpError) {
+      return error;
+    }
+    if (fallbackCode < 400 || fallbackCode > 599) {
+      throw new RangeError(
+        `fallbackCode must be between 400 and 599, got ${fallbackCode}`
+      );
+    }
+    const systemError = mapSystemError(error);
+    if (systemError !== void 0) {
+      return systemError;
+    }
+    if (error instanceof Error) {
+      return new _HttpError(fallbackCode, {
+        message: error.message,
+        cause: error,
+        expose: fallbackCode < 500
+      });
+    }
+    return new _HttpError(fallbackCode, {
+      message: String(error),
+      expose: fallbackCode < 500
+    });
+  }
+  /**
+   * Check if an error is an HttpError
+   */
+  static isHttpError(error) {
+    return error instanceof _HttpError;
+  }
+  /**
+   * Check if error is a client error (4xx)
+   */
+  isClientError() {
+    return this.code >= 400 && this.code < 500;
+  }
+  /**
+   * Check if error is a server error (5xx)
+   */
+  isServerError() {
+    return this.code >= 500 && this.code < 600;
+  }
+  /**
+   * Flattened chain of cause messages (most recent first).
+   * Useful for structured logging; never serialized to clients in production.
+   */
+  getCauseChain() {
+    const chain = [];
+    let current = this.cause;
+    let depth = 0;
+    while (current instanceof Error && depth < 10) {
+      chain.push(`${current.name}: ${current.message}`);
+      current = current.cause;
+      depth++;
+    }
+    return chain;
+  }
+};
+
+// src/constants/success-definitions.ts
+var HttpSuccessDefinitions = {
+  [200 /* OK */]: {
+    code: 200,
+    description: "The request has succeeded."
+  },
+  [201 /* CREATED */]: {
+    code: 201,
+    description: "The request has been fulfilled and resulted in a new resource being created."
+  },
+  [202 /* ACCEPTED */]: {
+    code: 202,
+    description: "The request has been accepted for processing, but the processing has not been completed."
+  },
+  [203 /* NON_AUTHORITATIVE_INFORMATION */]: {
+    code: 203,
+    description: "The returned meta-information is from a local or third-party copy."
+  },
+  [204 /* NO_CONTENT */]: {
+    code: 204,
+    description: "The server successfully processed the request and is not returning any content."
+  },
+  [205 /* RESET_CONTENT */]: {
+    code: 205,
+    description: "The server successfully processed the request and requires the requester to reset the document view."
+  },
+  [206 /* PARTIAL_CONTENT */]: {
+    code: 206,
+    description: "The server is delivering only part of the resource due to a range header sent by the client."
+  },
+  [207 /* MULTI_STATUS */]: {
+    code: 207,
+    description: "The message body contains multiple status codes for multiple independent operations."
+  },
+  [208 /* ALREADY_REPORTED */]: {
+    code: 208,
+    description: "The members of a DAV binding have already been enumerated in a preceding part of the response."
+  },
+  [226 /* IM_USED */]: {
+    code: 226,
+    description: "The server has fulfilled a GET request and the response is a representation of the result of one or more instance-manipulations."
+  }
+};
+Object.freeze(HttpSuccessDefinitions);
+var HttpRedirectDefinitions = {
+  [300 /* MULTIPLE_CHOICES */]: {
+    code: 300,
+    description: "The request has more than one possible response."
+  },
+  [301 /* MOVED_PERMANENTLY */]: {
+    code: 301,
+    description: "The URL of the requested resource has been changed permanently."
+  },
+  [302 /* FOUND */]: {
+    code: 302,
+    description: "The URI of the requested resource has been changed temporarily."
+  },
+  [303 /* SEE_OTHER */]: {
+    code: 303,
+    description: "The response can be found under another URI using the GET method."
+  },
+  [304 /* NOT_MODIFIED */]: {
+    code: 304,
+    description: "The resource has not been modified since the version specified by the request headers."
+  },
+  [305 /* USE_PROXY */]: {
+    code: 305,
+    description: "The requested resource must be accessed through the proxy."
+  },
+  [307 /* TEMPORARY_REDIRECT */]: {
+    code: 307,
+    description: "The request should be repeated with another URI but future requests should use the original URI."
+  },
+  [308 /* PERMANENT_REDIRECT */]: {
+    code: 308,
+    description: "The request and all future requests should be repeated using another URI."
+  }
+};
+Object.freeze(HttpRedirectDefinitions);
+var HttpInfoDefinitions = {
+  [100 /* CONTINUE */]: {
+    code: 100,
+    description: "The initial part of a request has been received and has not yet been rejected by the server."
+  },
+  [101 /* SWITCHING_PROTOCOLS */]: {
+    code: 101,
+    description: "The server is switching protocols as requested by the client."
+  },
+  [102 /* PROCESSING */]: {
+    code: 102,
+    description: "The server has received and is processing the request, but no response is available yet."
+  },
+  [103 /* EARLY_HINTS */]: {
+    code: 103,
+    description: "The server is sending some response headers before the final response."
+  }
+};
+Object.freeze(HttpInfoDefinitions);
+function getSuccessDefinition(code) {
+  const definedInfo = HttpSuccessDefinitions[code] || HttpRedirectDefinitions[code] || HttpInfoDefinitions[code];
+  if (definedInfo) {
+    return definedInfo;
+  }
+  return {
+    code,
+    description: "The request was processed with a non-standard status code."
+  };
+}
+
+// src/kit.ts
+function snakeToCamel(key) {
+  return key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function camelizeResponse(response) {
+  const out = {};
+  for (const [key, value] of Object.entries(response)) {
+    out[snakeToCamel(key)] = value;
+  }
+  const metadata = out.metadata;
+  if (metadata && typeof metadata === "object" && metadata.pagination && typeof metadata.pagination === "object") {
+    const pagination = {};
+    for (const [key, value] of Object.entries(metadata.pagination)) {
+      pagination[snakeToCamel(key)] = value;
+    }
+    out.metadata = { ...metadata, pagination };
+  }
+  return out;
+}
+var ResponseKit = class {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      includeTimestamp: true,
+      format: "standard",
+      casing: "snake",
+      exposeServerErrors: false,
+      ...config,
+      customMessages: { ...config.customMessages }
+    };
+  }
+  /** Merge partial configuration into this instance */
+  configure(config) {
+    Object.assign(this.config, {
+      ...config,
+      customMessages: { ...this.config.customMessages, ...config.customMessages }
+    });
+  }
+  /** Snapshot of the current configuration */
+  getConfig() {
+    return { ...this.config };
+  }
+  /** Whether dev mode is active (stack traces, cause chains) */
+  isDevelopment() {
+    return this.config.isDevelopment ?? process.env.NODE_ENV === "development";
+  }
+  finalize(response) {
+    let out = this.config.casing === "camel" ? camelizeResponse(response) : response;
+    const transformer = this.config.responseTransformer;
+    if (transformer) {
+      out = transformer(out);
+    }
+    return out;
+  }
+  /**
+   * Resolve the outgoing client-facing message for an error.
+   *
+   * Priority: messageResolver > explicit message (if exposed)
+   * > customMessages[code] > generic status description.
+   */
+  resolveMessage(error, exposed) {
+    const resolved = this.config.messageResolver?.(error);
+    if (resolved !== void 0) return resolved;
+    const customDefault = this.config.customMessages?.[error.code];
+    const hasExplicitMessage = error.message !== error.details;
+    if (exposed && hasExplicitMessage) return error.message;
+    return customDefault ?? error.details;
+  }
+  // ========================================================================
+  // Success
+  // ========================================================================
+  /** Format a success response */
+  success(config = {}) {
+    const { data, message, statusCode = 200 /* OK */, metadata = {}, requestId } = config;
+    const successInfo = getSuccessDefinition(statusCode);
+    const response = {
+      success: true,
+      status_code: successInfo.code
+    };
+    if (this.config.includeTimestamp ?? true) {
+      response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    if (requestId) {
+      response.request_id = requestId;
+    }
+    if (statusCode !== 204 /* NO_CONTENT */ && statusCode !== 205 /* RESET_CONTENT */ && statusCode !== 304 /* NOT_MODIFIED */) {
+      if (data !== null && data !== void 0) {
+        response.data = data;
+      }
+    }
+    if (message) {
+      response.message = message;
+    }
+    if (Object.keys(metadata).length > 0) {
+      response.metadata = metadata;
+    }
+    return this.finalize(response);
+  }
+  // ========================================================================
+  // Error
+  // ========================================================================
+  /**
+   * 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, config = {}) {
+    const { includeStack, additionalFields, requestId } = config;
+    const cfg = this.config;
+    const exposed = config.expose ?? (error.expose || error.isServerError() && cfg.exposeServerErrors === true);
+    const response = {
+      success: false,
+      status_code: error.code,
+      error: {
+        type: error.type,
+        title: error.title,
+        message: this.resolveMessage(error, exposed)
+      }
+    };
+    if (cfg.includeTimestamp ?? true) {
+      response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    if (requestId) {
+      response.request_id = requestId;
+    }
+    if (error.errorCode) {
+      response.error.code = error.errorCode;
+    }
+    if (error.details) {
+      response.error.details = error.details;
+    }
+    if (error.validationErrors?.length) {
+      response.error.errors = error.validationErrors;
+    }
+    if (includeStack ?? this.isDevelopment()) {
+      response.error.stack = error.stack;
+      const causes = error.getCauseChain();
+      if (causes.length > 0) {
+        response.error.causes = causes;
+      }
+    }
+    if (error.retryAfter) {
+      response.retry_after = error.retryAfter;
+    }
+    if (error.metadata && exposed) {
+      const sanitized = cfg.metadataSanitizer ? cfg.metadataSanitizer(error.metadata) : error.metadata;
+      if (Object.keys(sanitized).length > 0) {
+        response.metadata = sanitized;
+      }
+    }
+    if (additionalFields) {
+      const { success, status_code, error: _error, timestamp, metadata, retry_after, request_id, ...safeFields } = additionalFields;
+      Object.assign(response, safeFields);
+    }
+    return this.finalize(response);
+  }
+  /** Format a response from any error (converts to HttpError first) */
+  fromError(error, config = {}) {
+    const httpError = HttpError.fromError(error, config.fallbackCode);
+    return this.error(httpError, config);
+  }
+  /**
+   * Build an RFC 9457 Problem Details body from any error.
+   * Serve it with `Content-Type: application/problem+json`
+   * (see `PROBLEM_CONTENT_TYPE`).
+   */
+  problem(error, options = {}) {
+    const httpError = HttpError.fromError(error);
+    const exposed = options.expose ?? httpError.expose;
+    const problem = httpError.toProblemDetails({
+      typeBase: options.typeBase ?? this.config.problemTypeBase,
+      ...options
+    });
+    problem.detail = this.resolveMessage(httpError, exposed);
+    return problem;
+  }
+  // ========================================================================
+  // Convenience Methods
+  // ========================================================================
+  /** 200 OK */
+  ok(data, message) {
+    return this.success({ data, message, statusCode: 200 /* OK */ });
+  }
+  /** 201 Created */
+  created(data, message) {
+    return this.success({ data, message, statusCode: 201 /* CREATED */ });
+  }
+  /** 202 Accepted */
+  accepted(data, message) {
+    return this.success({ data, message, statusCode: 202 /* ACCEPTED */ });
+  }
+  /** 204 No Content */
+  noContent() {
+    return this.success({ statusCode: 204 /* NO_CONTENT */ });
+  }
+  /** 206 Partial Content */
+  partialContent(data, message) {
+    return this.success({ data, message, statusCode: 206 /* PARTIAL_CONTENT */ });
+  }
+  /** 304 Not Modified */
+  notModified() {
+    return this.success({ statusCode: 304 /* NOT_MODIFIED */ });
+  }
+  // ========================================================================
+  // Pagination
+  // ========================================================================
+  /** Create an offset-based paginated success response */
+  paginated(data, pagination, message) {
+    const effectiveLimit = pagination.limit > 0 ? pagination.limit : 1;
+    const totalPages = pagination.totalPages ?? Math.ceil(pagination.total / effectiveLimit);
+    return this.success({
+      data,
+      message,
+      metadata: {
+        pagination: {
+          page: pagination.page,
+          limit: effectiveLimit,
+          total: pagination.total,
+          total_pages: totalPages,
+          has_next: pagination.page < totalPages,
+          has_prev: pagination.page > 1
+        }
+      }
+    });
+  }
+  /**
+   * 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(data, cursor, message) {
+    const pagination = {
+      has_next: cursor.nextCursor !== void 0 && cursor.nextCursor !== null,
+      has_prev: cursor.prevCursor !== void 0 && cursor.prevCursor !== null
+    };
+    if (cursor.nextCursor !== void 0) pagination.next_cursor = cursor.nextCursor;
+    if (cursor.prevCursor !== void 0) pagination.prev_cursor = cursor.prevCursor;
+    if (cursor.limit !== void 0) pagination.limit = cursor.limit;
+    if (cursor.total !== void 0) pagination.total = cursor.total;
+    return this.success({ data, message, metadata: { pagination } });
+  }
+};
+
+// src/responses/problem.ts
+var PROBLEM_CONTENT_TYPE = "application/problem+json";
+
+// src/adapters/shared.ts
+var fallbackKit = new ResponseKit();
+function buildErrorPayload(err, requestId, options = {}) {
+  const kit = options.kit ?? fallbackKit;
+  const error = HttpError.fromError(err);
+  const useProblem = options.problem ?? kit.getConfig().format === "problem";
+  options.onError?.(error, requestId);
+  const headers = error.getHeaders();
+  if (useProblem) {
+    return {
+      status: error.code,
+      headers,
+      contentType: PROBLEM_CONTENT_TYPE,
+      body: kit.problem(error, { requestId }),
+      error
+    };
+  }
+  return {
+    status: error.code,
+    headers,
+    contentType: "application/json; charset=utf-8",
+    body: kit.error(error, { requestId, includeStack: options.includeStack }),
+    error
+  };
+}
+
+// src/adapters/hono.ts
+function honoErrorHandler(options = {}) {
+  return (err, c) => {
+    const requestId = c.req.header(options.requestIdHeader ?? "x-request-id");
+    const payload = buildErrorPayload(err, requestId, options);
+    return c.json(payload.body, payload.status, {
+      "Content-Type": payload.contentType,
+      ...payload.headers
+    });
+  };
+}
+
+exports.honoErrorHandler = honoErrorHandler;
+//# sourceMappingURL=hono.js.map
+//# sourceMappingURL=hono.js.map