http-response-kit 1.0.0 → 2.0.0

package/dist/index.js

@@ -1,45 +1,4 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  HttpClientErrorCode: () => HttpClientErrorCode,
-  HttpError: () => HttpError,
-  HttpErrorCode: () => HttpErrorCode,
-  HttpErrorDefinitions: () => HttpErrorDefinitions,
-  HttpInfoCode: () => HttpInfoCode,
-  HttpInfoDefinitions: () => HttpInfoDefinitions,
-  HttpRedirectCode: () => HttpRedirectCode,
-  HttpRedirectDefinitions: () => HttpRedirectDefinitions,
-  HttpResponse: () => HttpResponse,
-  HttpServerErrorCode: () => HttpServerErrorCode,
-  HttpSuccessCode: () => HttpSuccessCode,
-  HttpSuccessDefinitions: () => HttpSuccessDefinitions,
-  configure: () => configure,
-  getConfig: () => getConfig,
-  getErrorDefinition: () => getErrorDefinition,
-  getSuccessDefinition: () => getSuccessDefinition,
-  isDevelopment: () => isDevelopment,
-  resetConfig: () => resetConfig
-});
-module.exports = __toCommonJS(index_exports);
+'use strict';
 
 // src/constants/status-codes.ts
 var HttpClientErrorCode = /* @__PURE__ */ ((HttpClientErrorCode2) => {
@@ -383,8 +342,23 @@ var HttpErrorDefinitions = {
     details: "The client needs to authenticate to gain network access."
   }
 };
+Object.freeze(HttpErrorDefinitions);
 function getErrorDefinition(code) {
-  return HttpErrorDefinitions[code] || HttpErrorDefinitions[500];
+  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/constants/success-definitions.ts
@@ -430,6 +404,7 @@ var HttpSuccessDefinitions = {
     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,
@@ -464,6 +439,7 @@ var HttpRedirectDefinitions = {
     description: "The request and all future requests should be repeated using another URI."
   }
 };
+Object.freeze(HttpRedirectDefinitions);
 var HttpInfoDefinitions = {
   [100 /* CONTINUE */]: {
     code: 100,
@@ -482,66 +458,156 @@ var HttpInfoDefinitions = {
     description: "The server is sending some response headers before the final response."
   }
 };
+Object.freeze(HttpInfoDefinitions);
 function getSuccessDefinition(code) {
-  return HttpSuccessDefinitions[code] || HttpRedirectDefinitions[code] || HttpInfoDefinitions[code] || HttpSuccessDefinitions[200];
+  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/config/index.ts
-var defaultConfig = {
-  isDevelopment: process.env.NODE_ENV === "development",
-  includeTimestamp: true,
-  customMessages: {},
-  responseTransformer: void 0
-};
-var currentConfig = { ...defaultConfig };
-function configure(config) {
-  currentConfig = { ...currentConfig, ...config };
-}
-function getConfig() {
-  return { ...currentConfig };
-}
-function resetConfig() {
-  currentConfig = { ...defaultConfig };
-}
-function isDevelopment() {
-  return currentConfig.isDevelopment ?? false;
-}
-function shouldIncludeTimestamp() {
-  return currentConfig.includeTimestamp ?? true;
-}
-function getCustomMessage(code) {
-  return currentConfig.customMessages?.[code];
+// 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 getResponseTransformer() {
-  return currentConfig.responseTransformer;
+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 customMessage = getCustomMessage(code);
-    const finalMessage = options.message ?? customMessage ?? errorInfo.details;
+    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.cause = options.cause;
     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);
     }
   }
   /**
-   * Convert error to plain object for JSON serialization
+   * 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 {
@@ -550,9 +616,56 @@ var HttpError = class _HttpError extends Error {
       type: this.type,
       title: this.title,
       message: this.message,
+      details: this.details,
+      errorCode: this.errorCode,
       metadata: this.metadata,
-      retryAfter: this.retryAfter
+      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
@@ -641,6 +754,20 @@ var HttpError = class _HttpError extends Error {
   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 });
@@ -728,20 +855,41 @@ var HttpError = class _HttpError extends Error {
   // Utility Methods
   // ========================================================================
   /**
-   * Create an HttpError from an unknown error
+   * 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
+        cause: error,
+        expose: fallbackCode < 500
       });
     }
     return new _HttpError(fallbackCode, {
-      message: String(error)
+      message: String(error),
+      expose: fallbackCode < 500
     });
   }
   /**
@@ -762,32 +910,131 @@ var HttpError = class _HttpError extends Error {
   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/responses/HttpResponse.ts
-var HttpResponse = class _HttpResponse {
+// src/errors/catalog.ts
+function createErrorCatalog(catalog) {
+  const factories = {};
+  for (const key of Object.keys(catalog)) {
+    const entry = catalog[key];
+    factories[key] = (message, options = {}) => new HttpError(entry.status, {
+      ...options,
+      message: message ?? entry.message ?? options.message,
+      errorCode: String(key),
+      expose: options.expose ?? entry.expose,
+      metadata: options.metadata ?? entry.metadata
+    });
+  }
+  return factories;
+}
+
+// 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;
+}
+function isSuccessResponse(response) {
+  return response.success === true;
+}
+function isErrorResponse(response) {
+  return response.success === false;
+}
+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;
+  }
   /**
-   * Format a success response
-   * 
-   * @param config - Success response configuration
-   * @returns Formatted success response object
+   * Resolve the outgoing client-facing message for an error.
+   *
+   * Priority: messageResolver > explicit message (if exposed)
+   * > customMessages[code] > generic status description.
    */
-  static success(config = {}) {
-    const {
-      data = null,
-      message,
-      statusCode = 200 /* OK */,
-      metadata = {}
-    } = config;
+  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 (shouldIncludeTimestamp()) {
+    if (this.config.includeTimestamp ?? true) {
       response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     }
-    if (statusCode !== 204 /* NO_CONTENT */ && statusCode !== 205 /* RESET_CONTENT */) {
+    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;
       }
@@ -798,142 +1045,195 @@ var HttpResponse = class _HttpResponse {
     if (Object.keys(metadata).length > 0) {
       response.metadata = metadata;
     }
-    const transformer = getResponseTransformer();
-    if (transformer) {
-      return transformer(response);
-    }
-    return response;
+    return this.finalize(response);
   }
+  // ========================================================================
+  // Error
+  // ========================================================================
   /**
-   * Format an error response
-   * 
-   * @param error - HttpError instance
-   * @param config - Optional error response configuration
-   * @returns Formatted error response object
+   * 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.
    */
-  static error(error, config = {}) {
-    const { includeStack, additionalFields } = config;
+  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: error.message
+        message: this.resolveMessage(error, exposed)
       }
     };
-    if (shouldIncludeTimestamp()) {
+    if (cfg.includeTimestamp ?? true) {
       response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     }
-    if (includeStack ?? isDevelopment()) {
-      response.error.details = error.stack;
+    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) {
-      response.metadata = error.metadata;
+    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) {
-      Object.assign(response, additionalFields);
-    }
-    const transformer = getResponseTransformer();
-    if (transformer) {
-      return transformer(response);
+      const { success, status_code, error: _error, timestamp, metadata, retry_after, request_id, ...safeFields } = additionalFields;
+      Object.assign(response, safeFields);
     }
-    return response;
+    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);
   }
   /**
-   * 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
+   * Build an RFC 9457 Problem Details body from any error.
+   * Serve it with `Content-Type: application/problem+json`
+   * (see `PROBLEM_CONTENT_TYPE`).
    */
-  static fromError(error, config = {}) {
+  problem(error, options = {}) {
     const httpError = HttpError.fromError(error);
-    return _HttpResponse.error(httpError, config);
+    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 */
-  static ok(data, message) {
-    return _HttpResponse.success({ data, message, statusCode: 200 /* OK */ });
+  ok(data, message) {
+    return this.success({ data, message, statusCode: 200 /* OK */ });
   }
   /** 201 Created */
-  static created(data, message) {
-    return _HttpResponse.success({ data, message, statusCode: 201 /* CREATED */ });
+  created(data, message) {
+    return this.success({ data, message, statusCode: 201 /* CREATED */ });
   }
   /** 202 Accepted */
-  static accepted(data, message) {
-    return _HttpResponse.success({ data, message, statusCode: 202 /* ACCEPTED */ });
+  accepted(data, message) {
+    return this.success({ data, message, statusCode: 202 /* ACCEPTED */ });
   }
   /** 204 No Content */
-  static noContent() {
-    return _HttpResponse.success({ statusCode: 204 /* NO_CONTENT */ });
+  noContent() {
+    return this.success({ statusCode: 204 /* NO_CONTENT */ });
   }
   /** 206 Partial Content */
-  static partialContent(data, message) {
-    return _HttpResponse.success({ data, message, statusCode: 206 /* PARTIAL_CONTENT */ });
+  partialContent(data, message) {
+    return this.success({ data, message, statusCode: 206 /* PARTIAL_CONTENT */ });
   }
   /** 304 Not Modified */
-  static notModified() {
-    return _HttpResponse.success({ statusCode: 304 /* NOT_MODIFIED */ });
+  notModified() {
+    return this.success({ statusCode: 304 /* NOT_MODIFIED */ });
   }
   // ========================================================================
-  // Utility Methods
+  // Pagination
   // ========================================================================
-  /**
-   * Check if a response is a success response
-   */
-  static isSuccess(response) {
-    return response.success === true;
-  }
-  /**
-   * Check if a response is an error response
-   */
-  static isError(response) {
-    return response.success === false;
-  }
-  /**
-   * Create a paginated success response
-   */
-  static paginated(data, pagination, message) {
-    return _HttpResponse.success({
+  /** 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: pagination.limit,
+          limit: effectiveLimit,
           total: pagination.total,
-          total_pages: pagination.totalPages ?? Math.ceil(pagination.total / pagination.limit),
-          has_next: pagination.page < (pagination.totalPages ?? Math.ceil(pagination.total / pagination.limit)),
+          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 } });
+  }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  HttpClientErrorCode,
-  HttpError,
-  HttpErrorCode,
-  HttpErrorDefinitions,
-  HttpInfoCode,
-  HttpInfoDefinitions,
-  HttpRedirectCode,
-  HttpRedirectDefinitions,
-  HttpResponse,
-  HttpServerErrorCode,
-  HttpSuccessCode,
-  HttpSuccessDefinitions,
-  configure,
-  getConfig,
-  getErrorDefinition,
-  getSuccessDefinition,
-  isDevelopment,
-  resetConfig
-});
+function createResponseKit(config = {}) {
+  return new ResponseKit(config);
+}
+
+// src/responses/problem.ts
+var PROBLEM_CONTENT_TYPE = "application/problem+json";
+function toProblem(error, options = {}) {
+  const httpError = HttpError.fromError(error);
+  return httpError.toProblemDetails(options);
+}
+function isProblemDetails(value) {
+  return typeof value === "object" && value !== null && typeof value.title === "string" && typeof value.status === "number" && typeof value.type === "string";
+}
+
+exports.HttpClientErrorCode = HttpClientErrorCode;
+exports.HttpError = HttpError;
+exports.HttpErrorCode = HttpErrorCode;
+exports.HttpErrorDefinitions = HttpErrorDefinitions;
+exports.HttpInfoCode = HttpInfoCode;
+exports.HttpInfoDefinitions = HttpInfoDefinitions;
+exports.HttpRedirectCode = HttpRedirectCode;
+exports.HttpRedirectDefinitions = HttpRedirectDefinitions;
+exports.HttpServerErrorCode = HttpServerErrorCode;
+exports.HttpSuccessCode = HttpSuccessCode;
+exports.HttpSuccessDefinitions = HttpSuccessDefinitions;
+exports.PROBLEM_CONTENT_TYPE = PROBLEM_CONTENT_TYPE;
+exports.ResponseKit = ResponseKit;
+exports.SystemErrorStatusMap = SystemErrorStatusMap;
+exports.createErrorCatalog = createErrorCatalog;
+exports.createResponseKit = createResponseKit;
+exports.getErrorDefinition = getErrorDefinition;
+exports.getSuccessDefinition = getSuccessDefinition;
+exports.isErrorResponse = isErrorResponse;
+exports.isProblemDetails = isProblemDetails;
+exports.isSuccessResponse = isSuccessResponse;
+exports.mapSystemError = mapSystemError;
+exports.toProblem = toProblem;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map