@marianmeres/http-utils 1.23.0 → 2.0.2

package/dist/api.js

@@ -0,0 +1,298 @@
+import { createHttpError } from './error.js';
+// This is an opinionated HTTP client wrapper and may not be suitable for every use case.
+// It provides convenient defaults over plain fetch calls without adding unnecessary abstractions.
+/**
+ * Deep merges two objects. Later properties overwrite earlier properties.
+ */
+function deepMerge(target, source) {
+    const output = { ...target };
+    if (isObject(target) && isObject(source)) {
+        Object.keys(source).forEach(key => {
+            if (isObject(source[key])) {
+                if (!(key in target)) {
+                    Object.assign(output, { [key]: source[key] });
+                }
+                else {
+                    output[key] = deepMerge(target[key], source[key]);
+                }
+            }
+            else {
+                Object.assign(output, { [key]: source[key] });
+            }
+        });
+    }
+    return output;
+}
+function isObject(item) {
+    return item && typeof item === 'object' && !Array.isArray(item);
+}
+const _fetchRaw = async ({ method, path, data = null, token = null, headers = null, signal, credentials, }) => {
+    const normalizedHeaders = Object.entries(headers || {}).reduce((m, [k, v]) => ({ ...m, [k.toLowerCase()]: v }), {});
+    const opts = {
+        method,
+        credentials: credentials ?? undefined,
+        headers: normalizedHeaders,
+        signal
+    };
+    if (data) {
+        const isObj = typeof data === 'object';
+        // FormData: multipart/form-data -- no explicit Content-Type
+        if (data instanceof FormData) {
+            opts.body = data;
+        }
+        // Cover 99% of use cases (may not fit all scenarios)
+        else {
+            // If not explicitly stated, assume JSON
+            if (isObj || !normalizedHeaders['content-type']) {
+                normalizedHeaders['content-type'] = 'application/json';
+            }
+            opts.body = JSON.stringify(data);
+        }
+    }
+    // Opinionated convention: auto-add Bearer token
+    if (token) {
+        normalizedHeaders['authorization'] = `Bearer ${token}`;
+    }
+    opts.headers = normalizedHeaders;
+    return await fetch(path, opts);
+};
+const _fetch = async (params, respHeaders = null, errorMessageExtractor = null, _dumpParams = false) => {
+    if (_dumpParams)
+        return params;
+    const r = await _fetchRaw(params);
+    if (params.raw)
+        return r;
+    // Convert Headers to plain object
+    const headers = [...r.headers.entries()].reduce((m, [k, v]) => ({ ...m, [k]: v }), {});
+    // Mutate respHeaders to provide access to response headers and status
+    if (respHeaders) {
+        Object.assign(respHeaders, headers, 
+        // Add status/text under special keys
+        { __http_status_code__: r.status, __http_status_text__: r.statusText });
+    }
+    let body = await r.text();
+    // prettier-ignore
+    try {
+        body = JSON.parse(body);
+    }
+    catch (_e) { /* ignore parse errors */ }
+    params.assert ??= true; // default is true
+    if (!r.ok && params.assert) {
+        // now we need to extract error message from an unknown response... this is obviously
+        // impossible unless we know what to expect, but we'll do some educated tries...
+        const extractor = errorMessageExtractor ?? // provided arg
+            createHttpApi.defaultErrorMessageExtractor ?? // static default
+            // educated guess fallback
+            function (_body, _response) {
+                let msg = 
+                // try opinionated convention first
+                _body?.error?.message ||
+                    _body?.message ||
+                    _body?.error ||
+                    _response?.statusText ||
+                    'Unknown error';
+                if (msg.length > 255)
+                    msg = `[Shortened]: ${msg.slice(0, 255)}`;
+                return msg;
+            };
+        // adding `cause` describing more details
+        throw createHttpError(r.status, extractor(body, r), body, {
+            method: params.method,
+            path: params.path,
+            response: {
+                status: r.status,
+                statusText: r.statusText,
+                headers,
+            },
+        });
+    }
+    return body;
+};
+/**
+ * HTTP API client with convenient defaults and error handling.
+ */
+export class HttpApi {
+    #base;
+    #defaults;
+    #factoryErrorMessageExtractor;
+    constructor(base, defaults, factoryErrorMessageExtractor) {
+        this.#base = base;
+        this.#defaults = defaults;
+        this.#factoryErrorMessageExtractor = factoryErrorMessageExtractor;
+    }
+    #merge(a, b) {
+        return deepMerge(a, b);
+    }
+    async #getDefs() {
+        if (typeof this.#defaults === 'function') {
+            return { ...(await this.#defaults()) };
+        }
+        return { ...(this.#defaults || {}) };
+    }
+    #buildPath(path, base) {
+        base = `${base || ''}`;
+        path = `${path || ''}`;
+        return /^https?:/.test(path) ? path : base + path;
+    }
+    async get(path, paramsOrOptions, respHeaders, errorMessageExtractor, _dumpParams = false) {
+        // Detect which API is being used
+        let params;
+        let headers = null;
+        let extractor = null;
+        if (paramsOrOptions && ('respHeaders' in paramsOrOptions || 'errorExtractor' in paramsOrOptions)) {
+            // New options API
+            const opts = paramsOrOptions;
+            params = opts.params;
+            headers = opts.respHeaders ?? null;
+            extractor = opts.errorExtractor ?? null;
+        }
+        else {
+            // Legacy positional API
+            params = paramsOrOptions;
+            headers = respHeaders ?? null;
+            extractor = errorMessageExtractor ?? null;
+        }
+        path = this.#buildPath(path, this.#base);
+        return _fetch(this.#merge(await this.#getDefs(), { ...params, method: 'GET', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+    }
+    async post(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
+        // Detect which API is being used
+        let data = null;
+        let fetchParams;
+        let headers = null;
+        let extractor = null;
+        if (dataOrOptions && ('data' in dataOrOptions ||
+            'params' in dataOrOptions ||
+            'respHeaders' in dataOrOptions ||
+            'errorExtractor' in dataOrOptions)) {
+            // New options API
+            const opts = dataOrOptions;
+            data = opts.data ?? null;
+            fetchParams = opts.params;
+            headers = opts.respHeaders ?? null;
+            extractor = opts.errorExtractor ?? null;
+        }
+        else {
+            // Legacy positional API
+            data = dataOrOptions ?? null;
+            fetchParams = params;
+            headers = respHeaders ?? null;
+            extractor = errorMessageExtractor ?? null;
+        }
+        path = this.#buildPath(path, this.#base);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'POST', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+    }
+    async put(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
+        let data = null;
+        let fetchParams;
+        let headers = null;
+        let extractor = null;
+        if (dataOrOptions && ('data' in dataOrOptions ||
+            'params' in dataOrOptions ||
+            'respHeaders' in dataOrOptions ||
+            'errorExtractor' in dataOrOptions)) {
+            const opts = dataOrOptions;
+            data = opts.data ?? null;
+            fetchParams = opts.params;
+            headers = opts.respHeaders ?? null;
+            extractor = opts.errorExtractor ?? null;
+        }
+        else {
+            data = dataOrOptions ?? null;
+            fetchParams = params;
+            headers = respHeaders ?? null;
+            extractor = errorMessageExtractor ?? null;
+        }
+        path = this.#buildPath(path, this.#base);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'PUT', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+    }
+    async patch(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
+        let data = null;
+        let fetchParams;
+        let headers = null;
+        let extractor = null;
+        if (dataOrOptions && ('data' in dataOrOptions ||
+            'params' in dataOrOptions ||
+            'respHeaders' in dataOrOptions ||
+            'errorExtractor' in dataOrOptions)) {
+            const opts = dataOrOptions;
+            data = opts.data ?? null;
+            fetchParams = opts.params;
+            headers = opts.respHeaders ?? null;
+            extractor = opts.errorExtractor ?? null;
+        }
+        else {
+            data = dataOrOptions ?? null;
+            fetchParams = params;
+            headers = respHeaders ?? null;
+            extractor = errorMessageExtractor ?? null;
+        }
+        path = this.#buildPath(path, this.#base);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'PATCH', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+    }
+    async del(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
+        let data = null;
+        let fetchParams;
+        let headers = null;
+        let extractor = null;
+        if (dataOrOptions && ('data' in dataOrOptions ||
+            'params' in dataOrOptions ||
+            'respHeaders' in dataOrOptions ||
+            'errorExtractor' in dataOrOptions)) {
+            const opts = dataOrOptions;
+            data = opts.data ?? null;
+            fetchParams = opts.params;
+            headers = opts.respHeaders ?? null;
+            extractor = opts.errorExtractor ?? null;
+        }
+        else {
+            data = dataOrOptions ?? null;
+            fetchParams = params;
+            headers = respHeaders ?? null;
+            extractor = errorMessageExtractor ?? null;
+        }
+        path = this.#buildPath(path, this.#base);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'DELETE', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+    }
+    /**
+     * Helper method to build the full URL from a path.
+     *
+     * @param path - The path to resolve (absolute URLs are returned as-is).
+     * @returns The resolved URL (base + path, or just path if it's already absolute).
+     */
+    url(path) {
+        return this.#buildPath(path, this.#base);
+    }
+    /**
+     * Get or set the base URL for all requests.
+     */
+    get base() {
+        return this.#base;
+    }
+    set base(v) {
+        this.#base = v;
+    }
+}
+/**
+ * Creates an HTTP API client with convenient defaults and error handling.
+ *
+ * @param base - Optional base URL to prepend to all requests. Can be changed later via the `base` property.
+ * @param defaults - Optional default parameters to merge with each request. Can be an object or async function returning an object.
+ * @param factoryErrorMessageExtractor - Optional function to extract error messages from failed responses.
+ *
+ * @returns An HttpApi instance with methods: get, post, put, patch, del, url, base.
+ *
+ * @example
+ * ```ts
+ * const api = createHttpApi('https://api.example.com', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * const data = await api.get('/users');
+ * await api.post('/users', { name: 'John' });
+ * ```
+ */
+export function createHttpApi(base, defaults, factoryErrorMessageExtractor) {
+    return new HttpApi(base, defaults, factoryErrorMessageExtractor);
+}
+createHttpApi.defaultErrorMessageExtractor = null;

package/dist/error.d.ts

@@ -1,7 +1,13 @@
+/**
+ * Base HTTP error class. Extends Error with HTTP-specific properties.
+ */
 declare class HttpError extends Error {
     name: string;
+    /** HTTP status code (e.g., 404, 500) */
     status: number;
+    /** HTTP status text (e.g., "Not Found", "Internal Server Error") */
     statusText: string;
+    /** Response body (auto-parsed as JSON if possible) */
     body: any;
 }
 declare class BadRequest extends HttpError {
@@ -82,6 +88,7 @@ declare class ServiceUnavailable extends HttpError {
     status: number;
     statusText: string;
 }
+export { HttpError, BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, RequestTimeout, Conflict, Gone, LengthRequired, ImATeapot, UnprocessableContent, TooManyRequests, InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, };
 export declare const HTTP_ERROR: {
     HttpError: typeof HttpError;
     BadRequest: typeof BadRequest;
@@ -101,6 +108,42 @@ export declare const HTTP_ERROR: {
     BadGateway: typeof BadGateway;
     ServiceUnavailable: typeof ServiceUnavailable;
 };
-export declare const createHttpError: (code: number | string, message?: string | null, body?: string | null, cause?: any) => HttpError;
+/**
+ * Creates an HTTP error from a status code and optional details.
+ * Returns a specific error class for well-known status codes (e.g., 404 → NotFound),
+ * or generic HttpError for unknown codes. Invalid codes default to 500.
+ *
+ * @param code - HTTP status code (400-599).
+ * @param message - Optional error message (defaults to status text).
+ * @param body - Optional response body (will be auto-parsed as JSON if it's a string).
+ * @param cause - Optional error cause/details (will be auto-parsed as JSON if it's a string).
+ *
+ * @returns An HttpError instance (or subclass for well-known codes).
+ *
+ * @example
+ * ```ts
+ * const err = createHttpError(404, 'User not found', { id: 123 });
+ * console.log(err instanceof NotFound); // true
+ * console.log(err.status); // 404
+ * console.log(err.body); // { id: 123 }
+ * ```
+ */
+export declare const createHttpError: (code: number | string, message?: string | null, body?: any, cause?: any) => HttpError;
+/**
+ * Extracts a human-readable error message from various error formats.
+ * Tries multiple strategies to find the best message, with fallbacks.
+ *
+ * Priority order:
+ * 1. e.cause.message / e.cause.code / e.cause (if string)
+ * 2. e.body.error.message / e.body.message / e.body.error / e.body (if string)
+ * 3. e.message
+ * 4. e.name
+ * 5. e.toString()
+ * 6. "Unknown Error"
+ *
+ * @param e - The error to extract a message from (can be any type).
+ * @param stripErrorPrefix - Whether to remove "Error: " prefix from the message (default: true).
+ *
+ * @returns A human-readable error message string.
+ */
 export declare const getErrorMessage: (e: any, stripErrorPrefix?: boolean) => string;
-export {};

package/dist/error.js

@@ -0,0 +1,243 @@
+import { HTTP_STATUS } from './status.js';
+/**
+ * Base HTTP error class. Extends Error with HTTP-specific properties.
+ */
+class HttpError extends Error {
+    name = 'HttpError';
+    /** HTTP status code (e.g., 404, 500) */
+    status = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.CODE;
+    /** HTTP status text (e.g., "Not Found", "Internal Server Error") */
+    statusText = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.TEXT;
+    /** Response body (auto-parsed as JSON if possible) */
+    body = null;
+}
+// some more specific instances of the well known ones...
+// client
+class BadRequest extends HttpError {
+    name = 'HttpBadRequestError';
+    status = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.TEXT;
+}
+class Unauthorized extends HttpError {
+    name = 'HttpUnauthorizedError';
+    status = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.TEXT;
+}
+class Forbidden extends HttpError {
+    name = 'HttpForbiddenError';
+    status = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.TEXT;
+}
+class NotFound extends HttpError {
+    name = 'HttpNotFoundError';
+    status = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.TEXT;
+}
+class MethodNotAllowed extends HttpError {
+    name = 'HttpMethodNotAllowedError';
+    status = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.TEXT;
+}
+class RequestTimeout extends HttpError {
+    name = 'HttpRequestTimeoutError';
+    status = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.TEXT;
+}
+class Conflict extends HttpError {
+    name = 'HttpConflictError';
+    status = HTTP_STATUS.ERROR_CLIENT.CONFLICT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.CONFLICT.TEXT;
+}
+class Gone extends HttpError {
+    name = 'HttpGoneError';
+    status = HTTP_STATUS.ERROR_CLIENT.GONE.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.GONE.TEXT;
+}
+class LengthRequired extends HttpError {
+    name = 'HttpLengthRequiredError';
+    status = HTTP_STATUS.ERROR_CLIENT.LENGTH_REQUIRED.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.LENGTH_REQUIRED.TEXT;
+}
+class UnprocessableContent extends HttpError {
+    name = 'HttpUnprocessableContentError';
+    status = HTTP_STATUS.ERROR_CLIENT.UNPROCESSABLE_CONTENT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.UNPROCESSABLE_CONTENT.TEXT;
+}
+class TooManyRequests extends HttpError {
+    name = 'HttpTooManyRequestsError';
+    status = HTTP_STATUS.ERROR_CLIENT.TOO_MANY_REQUESTS.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.TOO_MANY_REQUESTS.TEXT;
+}
+class ImATeapot extends HttpError {
+    name = 'HttpImATeapotError';
+    status = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.TEXT;
+}
+// server
+class InternalServerError extends HttpError {
+    name = 'HttpInternalServerError';
+}
+class NotImplemented extends HttpError {
+    name = 'HttpServiceUnavailableError';
+    status = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.TEXT;
+}
+class BadGateway extends HttpError {
+    name = 'HttpBadGatewayError';
+    status = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.TEXT;
+}
+class ServiceUnavailable extends HttpError {
+    name = 'HttpServiceUnavailableError';
+    status = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.TEXT;
+}
+// Export individual error classes
+export { HttpError, 
+// Client errors
+BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, RequestTimeout, Conflict, Gone, LengthRequired, ImATeapot, UnprocessableContent, TooManyRequests, 
+// Server errors
+InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, };
+// Namespace export for convenience
+export const HTTP_ERROR = {
+    // base
+    HttpError,
+    // client
+    BadRequest,
+    Unauthorized,
+    Forbidden,
+    NotFound,
+    MethodNotAllowed,
+    RequestTimeout,
+    Conflict,
+    Gone,
+    LengthRequired,
+    ImATeapot,
+    UnprocessableContent,
+    TooManyRequests,
+    // server
+    InternalServerError,
+    NotImplemented,
+    BadGateway,
+    ServiceUnavailable,
+};
+const _wellKnownCtorMap = {
+    '400': BadRequest,
+    '401': Unauthorized,
+    '403': Forbidden,
+    '404': NotFound,
+    '405': MethodNotAllowed,
+    '408': RequestTimeout,
+    '409': Conflict,
+    '410': Gone,
+    '411': LengthRequired,
+    '418': ImATeapot,
+    '422': UnprocessableContent,
+    '429': TooManyRequests,
+    //
+    '500': InternalServerError,
+    '501': NotImplemented,
+    '502': BadGateway,
+    '503': ServiceUnavailable,
+};
+const _maybeJsonParse = (v) => {
+    if (typeof v === 'string') {
+        try {
+            v = JSON.parse(v);
+        }
+        catch (e) { }
+    }
+    return v;
+};
+/**
+ * Creates an HTTP error from a status code and optional details.
+ * Returns a specific error class for well-known status codes (e.g., 404 → NotFound),
+ * or generic HttpError for unknown codes. Invalid codes default to 500.
+ *
+ * @param code - HTTP status code (400-599).
+ * @param message - Optional error message (defaults to status text).
+ * @param body - Optional response body (will be auto-parsed as JSON if it's a string).
+ * @param cause - Optional error cause/details (will be auto-parsed as JSON if it's a string).
+ *
+ * @returns An HttpError instance (or subclass for well-known codes).
+ *
+ * @example
+ * ```ts
+ * const err = createHttpError(404, 'User not found', { id: 123 });
+ * console.log(err instanceof NotFound); // true
+ * console.log(err.status); // 404
+ * console.log(err.body); // { id: 123 }
+ * ```
+ */
+export const createHttpError = (code, message, body, cause) => {
+    const fallback = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR;
+    code = Number(code);
+    if (isNaN(code) || !(code >= 400 && code < 600))
+        code = fallback.CODE;
+    // opinionated conventions
+    body = _maybeJsonParse(body);
+    cause = _maybeJsonParse(cause);
+    // try to find the well known one, otherwise fallback to generic
+    const ctor = _wellKnownCtorMap[`${code}`] ?? HttpError;
+    //
+    const found = HTTP_STATUS.findByCode(code);
+    const statusText = found?.TEXT ?? fallback.TEXT;
+    //
+    let e = new ctor(message || statusText, { cause });
+    e.status = found?.CODE ?? fallback.CODE;
+    e.statusText = statusText;
+    e.body = body;
+    return e;
+};
+/**
+ * Extracts a human-readable error message from various error formats.
+ * Tries multiple strategies to find the best message, with fallbacks.
+ *
+ * Priority order:
+ * 1. e.cause.message / e.cause.code / e.cause (if string)
+ * 2. e.body.error.message / e.body.message / e.body.error / e.body (if string)
+ * 3. e.message
+ * 4. e.name
+ * 5. e.toString()
+ * 6. "Unknown Error"
+ *
+ * @param e - The error to extract a message from (can be any type).
+ * @param stripErrorPrefix - Whether to remove "Error: " prefix from the message (default: true).
+ *
+ * @returns A human-readable error message string.
+ */
+export const getErrorMessage = (e, stripErrorPrefix = true) => {
+    if (!e)
+        return '';
+    // Errors may bubble from various sources which are not always under control.
+    // We try our best to extract a meaningful message using common conventions.
+    const cause = _maybeJsonParse(e?.cause);
+    const body = _maybeJsonParse(e?.body);
+    let msg = 
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+    // e.cause is the standard prop for error details, so should be considered as
+    // the most authoritative (if available)
+    // "code" and "message" are my own conventions
+    cause?.message ||
+        cause?.code ||
+        (typeof cause === 'string' ? cause : null) ||
+        // non-standard "body" is this package's HttpError prop
+        body?.error?.message ||
+        body?.message ||
+        body?.error ||
+        (typeof body === 'string' ? body : null) ||
+        // the common message from Error ctor (e.g. "Foo" if new TypeError("Foo"))
+        e?.message ||
+        // the Error class name (e.g. TypeError)
+        e?.name ||
+        // this should handle (almost) everything else (mainly if e is not an Error instance)
+        e?.toString() ||
+        // very last fallback if `toString()` was not available (or returned empty)
+        'Unknown Error';
+    // ensure we're sending string
+    msg = `${msg}`;
+    if (stripErrorPrefix) {
+        msg = msg.replace(/^[^:]*Error: /i, '');
+    }
+    return msg;
+};

package/dist/mod.d.ts

@@ -0,0 +1,3 @@
+export { HttpApi, createHttpApi, type DataOptions, type GetOptions, } from "./api.js";
+export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
+export { HTTP_STATUS } from "./status.js";

package/dist/mod.js

@@ -0,0 +1,3 @@
+export { HttpApi, createHttpApi, } from "./api.js";
+export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
+export { HTTP_STATUS } from "./status.js";

package/dist/status.d.ts

@@ -1,3 +1,7 @@
+/**
+ * HTTP status codes organized by category with convenience shortcuts.
+ * Provides comprehensive coverage of standard HTTP status codes.
+ */
 export declare class HTTP_STATUS {
     static readonly INFO: {
         CONTINUE: {
@@ -60,7 +64,7 @@ export declare class HTTP_STATUS {
         };
     };
     static readonly REDIRECT: {
-        MUTLIPLE_CHOICES: {
+        MULTIPLE_CHOICES: {
             CODE: number;
             TEXT: string;
         };
@@ -257,7 +261,7 @@ export declare class HTTP_STATUS {
     static readonly CREATED: number;
     static readonly ACCEPTED: number;
     static readonly NO_CONTENT: number;
-    static readonly MUTLIPLE_CHOICES: number;
+    static readonly MULTIPLE_CHOICES: number;
     static readonly FOUND: number;
     static readonly NOT_MODIFIED: number;
     static readonly MOVED_PERMANENTLY: number;
@@ -275,6 +279,18 @@ export declare class HTTP_STATUS {
     static readonly INTERNAL_SERVER_ERROR: number;
     static readonly NOT_IMPLEMENTED: number;
     static readonly SERVICE_UNAVAILABLE: number;
+    /**
+     * Finds a status code definition by its numeric code.
+     *
+     * @param code - The HTTP status code to look up (e.g., 200, 404, 500).
+     * @returns An object with CODE, TEXT, _TYPE (category), and _KEY (name), or null if not found.
+     *
+     * @example
+     * ```ts
+     * const status = HTTP_STATUS.findByCode(404);
+     * // { CODE: 404, TEXT: "Not Found", _TYPE: "ERROR_CLIENT", _KEY: "NOT_FOUND" }
+     * ```
+     */
     static findByCode(code: number | string): {
         CODE: number;
         TEXT: string;