@geekmidas/errors 10.0.0-alpha.12 → 10.0.0-alpha.121

package/dist/index.d.mts

@@ -12,7 +12,7 @@
  * });
  * ```
  */
-declare class HttpError extends Error {
+export declare class HttpError extends Error {
   /** The HTTP status code (e.g., 400, 404, 500) */
   readonly statusCode: number;
   /** The standard HTTP status message (e.g., 'Bad Request', 'Not Found') */
@@ -23,6 +23,13 @@ declare class HttpError extends Error {
   readonly details?: any;
   /** Application-specific error code for client-side handling */
   readonly code?: string;
+  /**
+   * Headers the response that reports this error carries — a 429's
+   * `Retry-After`, a 401's `WWW-Authenticate`. Every endpoint adaptor sets
+   * them on the error response, so the error says everything the client is
+   * told.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
   /**
    * Creates a new HttpError instance.
    *
@@ -32,12 +39,14 @@ declare class HttpError extends Error {
    * @param options.statusMessage - Override the default status message
    * @param options.details - Additional error details or context
    * @param options.code - Application-specific error code
+   * @param options.headers - Headers the error response carries
    * @param options.cause - The underlying error that caused this error (ES2022)
    */
   constructor(statusCode: number, message?: string, options?: {
     statusMessage?: string;
     details?: any;
     code?: string;
+    headers?: Readonly<Record<string, string>>;
     cause?: Error;
   });
   /**
@@ -82,7 +91,7 @@ declare class HttpError extends Error {
  * throw new BadRequestError('Invalid JSON', { line: 5, column: 12 });
  * ```
  */
-declare class BadRequestError extends HttpError {
+export declare class BadRequestError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -96,7 +105,7 @@ declare class BadRequestError extends HttpError {
  * throw new UnauthorizedError('Invalid token');
  * ```
  */
-declare class UnauthorizedError extends HttpError {
+export declare class UnauthorizedError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -110,7 +119,7 @@ declare class UnauthorizedError extends HttpError {
  * throw new ForbiddenError('Insufficient permissions', { required: 'admin' });
  * ```
  */
-declare class ForbiddenError extends HttpError {
+export declare class ForbiddenError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -124,7 +133,7 @@ declare class ForbiddenError extends HttpError {
  * throw new NotFoundError('User not found', { userId: '123' });
  * ```
  */
-declare class NotFoundError extends HttpError {
+export declare class NotFoundError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -138,7 +147,7 @@ declare class NotFoundError extends HttpError {
  * throw new MethodNotAllowedError('DELETE not supported', ['GET', 'POST', 'PUT']);
  * ```
  */
-declare class MethodNotAllowedError extends HttpError {
+export declare class MethodNotAllowedError extends HttpError {
   /**
    * @param message - Optional error message
    * @param allowedMethods - Array of allowed HTTP methods for this resource
@@ -156,7 +165,7 @@ declare class MethodNotAllowedError extends HttpError {
  * throw new ConflictError('Email already exists', { email: 'user@example.com' });
  * ```
  */
-declare class ConflictError extends HttpError {
+export declare class ConflictError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -173,7 +182,7 @@ declare class ConflictError extends HttpError {
  * });
  * ```
  */
-declare class UnprocessableEntityError extends HttpError {
+export declare class UnprocessableEntityError extends HttpError {
   /**
    * @param message - Optional error message
    * @param validationErrors - Object containing field-specific validation errors
@@ -191,12 +200,19 @@ declare class UnprocessableEntityError extends HttpError {
  * throw new TooManyRequestsError('Rate limit exceeded', 60); // retry after 60 seconds
  * ```
  */
-declare class TooManyRequestsError extends HttpError {
+export declare class TooManyRequestsError extends HttpError {
+  /** Seconds the client should wait before retrying, where known. */
+  readonly retryAfter?: number;
   /**
    * @param message - Optional error message
-   * @param retryAfter - Number of seconds the client should wait before retrying
+   * @param retryAfter - Number of seconds the client should wait before
+   * retrying, sent as the `Retry-After` header
+   * @param options.headers - Further headers the response carries, such as
+   * a rate limiter's `X-RateLimit-*`
    */
-  constructor(message?: string, retryAfter?: number);
+  constructor(message?: string, retryAfter?: number, options?: {
+    headers?: Readonly<Record<string, string>>;
+  });
 }
 /**
  * Represents a 500 Internal Server Error.
@@ -209,7 +225,7 @@ declare class TooManyRequestsError extends HttpError {
  * throw new InternalServerError('Database connection failed');
  * ```
  */
-declare class InternalServerError extends HttpError {
+export declare class InternalServerError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -223,7 +239,7 @@ declare class InternalServerError extends HttpError {
  * throw new NotImplementedError('WebSocket support not implemented');
  * ```
  */
-declare class NotImplementedError extends HttpError {
+export declare class NotImplementedError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -237,7 +253,7 @@ declare class NotImplementedError extends HttpError {
  * throw new BadGatewayError('Upstream server error');
  * ```
  */
-declare class BadGatewayError extends HttpError {
+export declare class BadGatewayError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /**
@@ -251,7 +267,7 @@ declare class BadGatewayError extends HttpError {
  * throw new ServiceUnavailableError('Maintenance in progress', 300); // retry after 5 minutes
  * ```
  */
-declare class ServiceUnavailableError extends HttpError {
+export declare class ServiceUnavailableError extends HttpError {
   /**
    * @param message - Optional error message
    * @param retryAfter - Number of seconds the client should wait before retrying
@@ -269,61 +285,61 @@ declare class ServiceUnavailableError extends HttpError {
  * throw new GatewayTimeoutError('Upstream server timeout');
  * ```
  */
-declare class GatewayTimeoutError extends HttpError {
+export declare class GatewayTimeoutError extends HttpError {
   constructor(message?: string, details?: any);
 }
 /** Type-safe error registry mapping status codes to their factory functions */
 declare const errorRegistry: {
   readonly 400: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => BadRequestError;
   };
   readonly 401: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => UnauthorizedError;
   };
   readonly 403: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => ForbiddenError;
   };
   readonly 404: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => NotFoundError;
   };
   readonly 405: {
-    readonly type: "methodNotAllowed";
+    readonly type: 'methodNotAllowed';
     readonly factory: (m: string, am: string[]) => MethodNotAllowedError;
   };
   readonly 409: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => ConflictError;
   };
   readonly 422: {
-    readonly type: "validation";
+    readonly type: 'validation';
     readonly factory: (m: string, ve: any) => UnprocessableEntityError;
   };
   readonly 429: {
-    readonly type: "retryAfter";
+    readonly type: 'retryAfter';
     readonly factory: (m: string, ra: number) => TooManyRequestsError;
   };
   readonly 500: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => InternalServerError;
   };
   readonly 501: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => NotImplementedError;
   };
   readonly 502: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => BadGatewayError;
   };
   readonly 503: {
-    readonly type: "retryAfter";
+    readonly type: 'retryAfter';
     readonly factory: (m: string, ra: number) => ServiceUnavailableError;
   };
   readonly 504: {
-    readonly type: "standard";
+    readonly type: 'standard';
     readonly factory: (m: string, d: any) => GatewayTimeoutError;
   };
 };
@@ -366,8 +382,8 @@ type ErrorOptions<T extends number> = T extends 405 ? {
  * createHttpError(429, 'Rate limited', { retryAfter: 60 });
  * ```
  */
-declare function createHttpError<T extends ValidStatusCode>(statusCode: T, message?: string, options?: ErrorOptions<T>): HttpError;
-declare function createHttpError(statusCode: number, message?: string, options?: HttpErrorOptions): HttpError;
+export declare function createHttpError<T extends ValidStatusCode>(statusCode: T, message?: string, options?: ErrorOptions<T>): HttpError;
+export declare function createHttpError(statusCode: number, message?: string, options?: HttpErrorOptions): HttpError;
 /**
  * Type-safe error creation utilities with descriptive method names.
  * Provides a fluent API for creating specific HTTP errors.
@@ -379,7 +395,7 @@ declare function createHttpError(statusCode: number, message?: string, options?:
  * createError.methodNotAllowed('DELETE not supported', ['GET', 'POST']);
  * ```
  */
-declare const createError: {
+export declare const createError: {
   readonly badRequest: (message?: string, details?: any) => BadRequestError;
   readonly unauthorized: (message?: string, details?: any) => UnauthorizedError;
   readonly forbidden: (message?: string, details?: any) => ForbiddenError;
@@ -412,7 +428,7 @@ declare const createError: {
  * }
  * ```
  */
-declare function isHttpError(error: unknown): error is HttpError;
+export declare function isHttpError(error: unknown): error is HttpError;
 /**
  * Type guard to check if an error is a client error (4xx status code).
  *
@@ -426,7 +442,7 @@ declare function isHttpError(error: unknown): error is HttpError;
  * }
  * ```
  */
-declare function isClientError(error: unknown): error is HttpError;
+export declare function isClientError(error: unknown): error is HttpError;
 /**
  * Type guard to check if an error is a server error (5xx status code).
  *
@@ -440,10 +456,16 @@ declare function isClientError(error: unknown): error is HttpError;
  * }
  * ```
  */
-declare function isServerError(error: unknown): error is HttpError;
+export declare function isServerError(error: unknown): error is HttpError;
 /**
  * Wraps an unknown error into an HttpError.
- * If the error is already an HttpError, returns it unchanged.
+ *
+ * One rule: an error that is an HttpError ({@link isHttpError}) passes
+ * through unchanged, its status and headers with it; anything else — however
+ * it is shaped, a `statusCode` field included — becomes `statusCode` (500 by
+ * default). An error that should answer with its own status extends
+ * HttpError, so the decision is made where the error is defined rather than
+ * guessed from its fields here.
  *
  * @param error - The error to wrap
  * @param statusCode - The HTTP status code to use (defaults to 500)
@@ -459,26 +481,27 @@ declare function isServerError(error: unknown): error is HttpError;
  * }
  * ```
  */
-declare function wrapError(error: unknown, statusCode?: number, message?: string): HttpError;
+export declare function wrapError(error: unknown, statusCode?: number, message?: string): HttpError;
 /**
  * Options for creating an HttpError.
  */
-interface HttpErrorOptions {
+export interface HttpErrorOptions {
   statusMessage?: string;
   details?: any;
   code?: string;
+  headers?: Readonly<Record<string, string>>;
   cause?: Error;
 }
 /**
  * Constructor type for HttpError classes.
  * Useful for factory patterns and dependency injection.
  */
-type HttpErrorConstructor = new (message?: string, options?: HttpErrorOptions) => HttpError;
+export type HttpErrorConstructor = new (message?: string, options?: HttpErrorOptions) => HttpError;
 /**
  * HTTP status code enum for type-safe status code usage.
  * Includes common 2xx, 3xx, 4xx, and 5xx status codes.
  */
-declare enum HttpStatusCode {
+export declare enum HttpStatusCode {
   OK = 200,
   CREATED = 201,
   ACCEPTED = 202,
@@ -501,7 +524,7 @@ declare enum HttpStatusCode {
   NOT_IMPLEMENTED = 501,
   BAD_GATEWAY = 502,
   SERVICE_UNAVAILABLE = 503,
-  GATEWAY_TIMEOUT = 504,
+  GATEWAY_TIMEOUT = 504
 }
 /**
  * Namespace containing all HTTP error classes.
@@ -513,7 +536,7 @@ declare enum HttpStatusCode {
  * throw new HttpErrors.NotFoundError('Resource not found');
  * ```
  */
-declare const HttpErrors: {
+export declare const HttpErrors: {
   HttpError: typeof HttpError;
   BadRequestError: typeof BadRequestError;
   UnauthorizedError: typeof UnauthorizedError;
@@ -530,5 +553,4 @@ declare const HttpErrors: {
   GatewayTimeoutError: typeof GatewayTimeoutError;
 };
 //#endregion
-export { BadGatewayError, BadRequestError, ConflictError, ForbiddenError, GatewayTimeoutError, HttpError, HttpErrorConstructor, HttpErrorOptions, HttpErrors, HttpStatusCode, InternalServerError, MethodNotAllowedError, NotFoundError, NotImplementedError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, createError, createHttpError, isClientError, isHttpError, isServerError, wrapError };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -24,6 +24,13 @@ var HttpError = class extends Error {
 	/** Application-specific error code for client-side handling */
 	code;
 	/**
+	* Headers the response that reports this error carries — a 429's
+	* `Retry-After`, a 401's `WWW-Authenticate`. Every endpoint adaptor sets
+	* them on the error response, so the error says everything the client is
+	* told.
+	*/
+	headers;
+	/**
 	* Creates a new HttpError instance.
 	*
 	* @param statusCode - The HTTP status code
@@ -32,6 +39,7 @@ var HttpError = class extends Error {
 	* @param options.statusMessage - Override the default status message
 	* @param options.details - Additional error details or context
 	* @param options.code - Application-specific error code
+	* @param options.headers - Headers the error response carries
 	* @param options.cause - The underlying error that caused this error (ES2022)
 	*/
 	constructor(statusCode, message, options) {
@@ -41,6 +49,7 @@ var HttpError = class extends Error {
 		this.statusMessage = options?.statusMessage || this.getDefaultStatusMessage(statusCode);
 		this.details = options?.details;
 		this.code = options?.code;
+		if (options?.headers) this.headers = options.headers;
 		if (options?.cause) this.cause = options.cause;
 		Error.captureStackTrace(this, this.constructor);
 	}
@@ -65,7 +74,7 @@ var HttpError = class extends Error {
 	* @private
 	*/
 	getDefaultStatusMessage(statusCode) {
-		const statusMessages = {
+		return {
 			400: "Bad Request",
 			401: "Unauthorized",
 			403: "Forbidden",
@@ -82,8 +91,7 @@ var HttpError = class extends Error {
 			502: "Bad Gateway",
 			503: "Service Unavailable",
 			504: "Gateway Timeout"
-		};
-		return statusMessages[statusCode] || "Unknown Error";
+		}[statusCode] || "Unknown Error";
 	}
 	/**
 	* Serializes the error to a JSON-compatible object.
@@ -238,12 +246,25 @@ var UnprocessableEntityError = class extends HttpError {
 * ```
 */
 var TooManyRequestsError = class extends HttpError {
+	/** Seconds the client should wait before retrying, where known. */
+	retryAfter;
 	/**
 	* @param message - Optional error message
-	* @param retryAfter - Number of seconds the client should wait before retrying
+	* @param retryAfter - Number of seconds the client should wait before
+	* retrying, sent as the `Retry-After` header
+	* @param options.headers - Further headers the response carries, such as
+	* a rate limiter's `X-RateLimit-*`
 	*/
-	constructor(message, retryAfter) {
-		super(429, message, { details: retryAfter ? { retryAfter } : void 0 });
+	constructor(message, retryAfter, options) {
+		const headers = {
+			...options?.headers,
+			...retryAfter !== void 0 ? { "Retry-After": String(retryAfter) } : {}
+		};
+		super(429, message, {
+			details: retryAfter !== void 0 ? { retryAfter } : void 0,
+			...Object.keys(headers).length > 0 ? { headers } : {}
+		});
+		if (retryAfter !== void 0) this.retryAfter = retryAfter;
 	}
 };
 /**
@@ -481,7 +502,13 @@ function isServerError(error) {
 }
 /**
 * Wraps an unknown error into an HttpError.
-* If the error is already an HttpError, returns it unchanged.
+*
+* One rule: an error that is an HttpError ({@link isHttpError}) passes
+* through unchanged, its status and headers with it; anything else — however
+* it is shaped, a `statusCode` field included — becomes `statusCode` (500 by
+* default). An error that should answer with its own status extends
+* HttpError, so the decision is made where the error is defined rather than
+* guessed from its fields here.
 *
 * @param error - The error to wrap
 * @param statusCode - The HTTP status code to use (defaults to 500)
@@ -499,38 +526,37 @@ function isServerError(error) {
 */
 function wrapError(error, statusCode = 500, message) {
 	if (isHttpError(error)) return error;
-	if (error instanceof HttpError) return error;
 	return new HttpError(statusCode, message || "An unknown error occurred", { details: { originalError: error } });
 }
 /**
 * HTTP status code enum for type-safe status code usage.
 * Includes common 2xx, 3xx, 4xx, and 5xx status codes.
 */
-let HttpStatusCode = /* @__PURE__ */ function(HttpStatusCode$1) {
-	HttpStatusCode$1[HttpStatusCode$1["OK"] = 200] = "OK";
-	HttpStatusCode$1[HttpStatusCode$1["CREATED"] = 201] = "CREATED";
-	HttpStatusCode$1[HttpStatusCode$1["ACCEPTED"] = 202] = "ACCEPTED";
-	HttpStatusCode$1[HttpStatusCode$1["NO_CONTENT"] = 204] = "NO_CONTENT";
-	HttpStatusCode$1[HttpStatusCode$1["MOVED_PERMANENTLY"] = 301] = "MOVED_PERMANENTLY";
-	HttpStatusCode$1[HttpStatusCode$1["FOUND"] = 302] = "FOUND";
-	HttpStatusCode$1[HttpStatusCode$1["NOT_MODIFIED"] = 304] = "NOT_MODIFIED";
-	HttpStatusCode$1[HttpStatusCode$1["BAD_REQUEST"] = 400] = "BAD_REQUEST";
-	HttpStatusCode$1[HttpStatusCode$1["UNAUTHORIZED"] = 401] = "UNAUTHORIZED";
-	HttpStatusCode$1[HttpStatusCode$1["FORBIDDEN"] = 403] = "FORBIDDEN";
-	HttpStatusCode$1[HttpStatusCode$1["NOT_FOUND"] = 404] = "NOT_FOUND";
-	HttpStatusCode$1[HttpStatusCode$1["METHOD_NOT_ALLOWED"] = 405] = "METHOD_NOT_ALLOWED";
-	HttpStatusCode$1[HttpStatusCode$1["NOT_ACCEPTABLE"] = 406] = "NOT_ACCEPTABLE";
-	HttpStatusCode$1[HttpStatusCode$1["REQUEST_TIMEOUT"] = 408] = "REQUEST_TIMEOUT";
-	HttpStatusCode$1[HttpStatusCode$1["CONFLICT"] = 409] = "CONFLICT";
-	HttpStatusCode$1[HttpStatusCode$1["GONE"] = 410] = "GONE";
-	HttpStatusCode$1[HttpStatusCode$1["UNPROCESSABLE_ENTITY"] = 422] = "UNPROCESSABLE_ENTITY";
-	HttpStatusCode$1[HttpStatusCode$1["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
-	HttpStatusCode$1[HttpStatusCode$1["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
-	HttpStatusCode$1[HttpStatusCode$1["NOT_IMPLEMENTED"] = 501] = "NOT_IMPLEMENTED";
-	HttpStatusCode$1[HttpStatusCode$1["BAD_GATEWAY"] = 502] = "BAD_GATEWAY";
-	HttpStatusCode$1[HttpStatusCode$1["SERVICE_UNAVAILABLE"] = 503] = "SERVICE_UNAVAILABLE";
-	HttpStatusCode$1[HttpStatusCode$1["GATEWAY_TIMEOUT"] = 504] = "GATEWAY_TIMEOUT";
-	return HttpStatusCode$1;
+let HttpStatusCode = /* @__PURE__ */ function(HttpStatusCode) {
+	HttpStatusCode[HttpStatusCode["OK"] = 200] = "OK";
+	HttpStatusCode[HttpStatusCode["CREATED"] = 201] = "CREATED";
+	HttpStatusCode[HttpStatusCode["ACCEPTED"] = 202] = "ACCEPTED";
+	HttpStatusCode[HttpStatusCode["NO_CONTENT"] = 204] = "NO_CONTENT";
+	HttpStatusCode[HttpStatusCode["MOVED_PERMANENTLY"] = 301] = "MOVED_PERMANENTLY";
+	HttpStatusCode[HttpStatusCode["FOUND"] = 302] = "FOUND";
+	HttpStatusCode[HttpStatusCode["NOT_MODIFIED"] = 304] = "NOT_MODIFIED";
+	HttpStatusCode[HttpStatusCode["BAD_REQUEST"] = 400] = "BAD_REQUEST";
+	HttpStatusCode[HttpStatusCode["UNAUTHORIZED"] = 401] = "UNAUTHORIZED";
+	HttpStatusCode[HttpStatusCode["FORBIDDEN"] = 403] = "FORBIDDEN";
+	HttpStatusCode[HttpStatusCode["NOT_FOUND"] = 404] = "NOT_FOUND";
+	HttpStatusCode[HttpStatusCode["METHOD_NOT_ALLOWED"] = 405] = "METHOD_NOT_ALLOWED";
+	HttpStatusCode[HttpStatusCode["NOT_ACCEPTABLE"] = 406] = "NOT_ACCEPTABLE";
+	HttpStatusCode[HttpStatusCode["REQUEST_TIMEOUT"] = 408] = "REQUEST_TIMEOUT";
+	HttpStatusCode[HttpStatusCode["CONFLICT"] = 409] = "CONFLICT";
+	HttpStatusCode[HttpStatusCode["GONE"] = 410] = "GONE";
+	HttpStatusCode[HttpStatusCode["UNPROCESSABLE_ENTITY"] = 422] = "UNPROCESSABLE_ENTITY";
+	HttpStatusCode[HttpStatusCode["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
+	HttpStatusCode[HttpStatusCode["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
+	HttpStatusCode[HttpStatusCode["NOT_IMPLEMENTED"] = 501] = "NOT_IMPLEMENTED";
+	HttpStatusCode[HttpStatusCode["BAD_GATEWAY"] = 502] = "BAD_GATEWAY";
+	HttpStatusCode[HttpStatusCode["SERVICE_UNAVAILABLE"] = 503] = "SERVICE_UNAVAILABLE";
+	HttpStatusCode[HttpStatusCode["GATEWAY_TIMEOUT"] = 504] = "GATEWAY_TIMEOUT";
+	return HttpStatusCode;
 }({});
 /**
 * Namespace containing all HTTP error classes.
@@ -558,7 +584,7 @@ const HttpErrors = {
 	ServiceUnavailableError,
 	GatewayTimeoutError
 };
-
 //#endregion
 export { BadGatewayError, BadRequestError, ConflictError, ForbiddenError, GatewayTimeoutError, HttpError, HttpErrors, HttpStatusCode, InternalServerError, MethodNotAllowedError, NotFoundError, NotImplementedError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, createError, createHttpError, isClientError, isHttpError, isServerError, wrapError };
+
 //# sourceMappingURL=index.mjs.map