@molecule/app-http 1.0.0

package/dist/provider.js

@@ -0,0 +1,298 @@
+/**
+ * HTTP client provider implementations.
+ *
+ * Contains concrete implementations of the HttpClient interface.
+ *
+ * @module
+ */
+import { t } from '@molecule/app-i18n';
+import { getLogger } from '@molecule/app-logger';
+import { HttpError } from './types.js';
+/**
+ * Creates a fetch-based HTTP client using the native Fetch API.
+ *
+ * Supports request/response/error interceptors, automatic JSON
+ * serialization, auth token injection, timeout via AbortController,
+ * and 401 error handler hooks.
+ *
+ * @param config - Client configuration including baseURL, default headers, timeout, and credentials.
+ * @returns A fully configured `HttpClient` instance.
+ */
+export const createFetchClient = (config = {}) => {
+    const logger = getLogger('http');
+    let authToken = null;
+    const requestInterceptors = [];
+    const responseInterceptors = [];
+    const errorInterceptors = [];
+    const authErrorHandlers = new Set();
+    // Track whether the document is currently navigating / unloading.
+    // Browser tears down in-flight fetch()es on navigation as
+    // `TypeError: Failed to fetch`, which is indistinguishable from a
+    // real outage at the catch site. The pagehide / beforeunload listeners
+    // give us a hint we can use to demote the log severity in that case
+    // without hiding genuine network failures.
+    let navigationInProgress = false;
+    if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+        const markNav = () => {
+            navigationInProgress = true;
+            // Auto-clear shortly after; if the navigation is real, the page
+            // will unload and we won't see anything else from this client
+            // anyway. If it's a same-page event, this lets us recover.
+            setTimeout(() => {
+                navigationInProgress = false;
+            }, 1000);
+        };
+        window.addEventListener('beforeunload', markNav);
+        window.addEventListener('pagehide', markNav);
+    }
+    const client = {
+        baseURL: config.baseURL || '',
+        defaultHeaders: config.defaultHeaders || {},
+        async request(requestConfig) {
+            // Apply request interceptors
+            let finalConfig = { ...requestConfig };
+            for (const interceptor of requestInterceptors) {
+                finalConfig = await interceptor(finalConfig);
+            }
+            // Build URL
+            let url = finalConfig.url;
+            if (client.baseURL && !url.startsWith('http://') && !url.startsWith('https://')) {
+                // Guard against double-prefixing: callers (e.g. @molecule/app-billing-react
+                // hooks) pass absolute `/api/...` paths whether or not a baseURL is bonded.
+                // If the URL already starts with the bonded baseURL, leave it alone.
+                const prefix = client.baseURL.endsWith('/') ? client.baseURL : client.baseURL + '/';
+                if (!url.startsWith(prefix) && url !== client.baseURL) {
+                    url = client.baseURL + url;
+                }
+            }
+            // Add query params
+            if (finalConfig.params) {
+                const params = new URLSearchParams();
+                for (const [key, value] of Object.entries(finalConfig.params)) {
+                    if (value !== undefined) {
+                        params.append(key, String(value));
+                    }
+                }
+                const queryString = params.toString();
+                if (queryString) {
+                    url += (url.includes('?') ? '&' : '?') + queryString;
+                }
+            }
+            // Build headers
+            const headers = {
+                ...client.defaultHeaders,
+                ...finalConfig.headers,
+            };
+            // Add auth token
+            if (authToken) {
+                headers['Authorization'] = `Bearer ${authToken}`;
+            }
+            // Add content-type for JSON
+            if (finalConfig.data && !headers['Content-Type']) {
+                headers['Content-Type'] = 'application/json';
+            }
+            // Build fetch options
+            const fetchOptions = {
+                method: finalConfig.method,
+                headers,
+                credentials: (finalConfig.withCredentials ?? config.withCredentials) ? 'include' : 'same-origin',
+                signal: finalConfig.signal,
+            };
+            // Add body
+            if (finalConfig.data) {
+                if (finalConfig.data instanceof FormData || finalConfig.data instanceof Blob) {
+                    fetchOptions.body = finalConfig.data;
+                    // Remove Content-Type for FormData (browser sets it with boundary)
+                    if (finalConfig.data instanceof FormData) {
+                        delete headers['Content-Type'];
+                    }
+                }
+                else {
+                    fetchOptions.body = JSON.stringify(finalConfig.data);
+                }
+            }
+            // Create abort controller for timeout
+            let timeoutId;
+            const timeout = finalConfig.timeout ?? config.timeout;
+            if (timeout && !finalConfig.signal) {
+                const controller = new AbortController();
+                fetchOptions.signal = controller.signal;
+                timeoutId = setTimeout(() => controller.abort(), timeout);
+            }
+            try {
+                const fetchResponse = await fetch(url, fetchOptions);
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                // Parse response headers
+                const responseHeaders = {};
+                fetchResponse.headers.forEach((value, key) => {
+                    responseHeaders[key] = value;
+                });
+                // Parse response body
+                let data;
+                const responseType = finalConfig.responseType || 'json';
+                switch (responseType) {
+                    case 'text':
+                        data = (await fetchResponse.text());
+                        break;
+                    case 'blob':
+                        data = (await fetchResponse.blob());
+                        break;
+                    case 'arraybuffer':
+                        data = (await fetchResponse.arrayBuffer());
+                        break;
+                    case 'json':
+                    default: {
+                        const text = await fetchResponse.text();
+                        try {
+                            data = text ? JSON.parse(text) : null;
+                        }
+                        catch (_error) {
+                            // Safe to ignore: the raw text is already captured above and used
+                            // as the fallback value. Non-JSON responses (plain text, HTML errors)
+                            // are a known valid case for some APIs.
+                            logger.debug('Response is not JSON, using raw text', url);
+                            data = text;
+                        }
+                        break;
+                    }
+                }
+                let response = {
+                    data,
+                    status: fetchResponse.status,
+                    statusText: fetchResponse.statusText,
+                    headers: responseHeaders,
+                    config: finalConfig,
+                };
+                // Handle error status codes
+                if (!fetchResponse.ok) {
+                    logger.warn('HTTP error', finalConfig.method, url, fetchResponse.status);
+                    const error = new HttpError(t('http.error.requestFailed', { status: fetchResponse.status }, { defaultValue: `Request failed with status ${fetchResponse.status}` }), fetchResponse.status, response, finalConfig, 'http.error.requestFailed');
+                    // Handle auth errors
+                    if (fetchResponse.status === 401) {
+                        authErrorHandlers.forEach((handler) => handler());
+                    }
+                    // Apply error interceptors
+                    let finalError = error;
+                    for (const interceptor of errorInterceptors) {
+                        finalError = await interceptor(finalError);
+                    }
+                    throw finalError;
+                }
+                // Apply response interceptors
+                for (const interceptor of responseInterceptors) {
+                    response = (await interceptor(response));
+                }
+                return response;
+            }
+            catch (err) {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                if (err instanceof HttpError) {
+                    throw err;
+                }
+                // Distinguish an explicit abort (AbortController, page unload
+                // wired up via signal) and SPA navigation-induced cancellation
+                // from a real network outage.
+                //
+                //  - AbortError → user-initiated cancel: silent
+                //  - "TypeError: Failed to fetch" while the browser tab is
+                //    hidden / unloading → SPA tore down a fetch as it left the
+                //    page. Demote to warn so it stays visible in the console
+                //    for debugging but doesn't fail strict console-error gates.
+                //  - Anything else (including "Failed to fetch" while the tab
+                //    is visible) → real outage: logger.error.
+                //
+                // Components that want zero navigation noise should still pass
+                // an AbortSignal from their useEffect cleanup.
+                const errMsg = err instanceof Error ? err.message : '';
+                const errName = err instanceof Error ? err.name : '';
+                const isAbort = errName === 'AbortError' ||
+                    (typeof DOMException !== 'undefined' &&
+                        err instanceof DOMException &&
+                        err.name === 'AbortError') ||
+                    /the user aborted a request/i.test(errMsg);
+                const tabHidden = typeof document !== 'undefined' &&
+                    (document.visibilityState === 'hidden' || document.hidden === true);
+                const isNavCancel = !isAbort &&
+                    errName === 'TypeError' &&
+                    /failed to fetch|network ?error|load failed/i.test(errMsg) &&
+                    (tabHidden || navigationInProgress);
+                if (isAbort) {
+                    // silent — not interesting
+                }
+                else if (isNavCancel) {
+                    logger.warn('Network request cancelled by navigation', finalConfig.method, url);
+                }
+                else {
+                    logger.error('Network error', finalConfig.method, url, err);
+                }
+                const error = new HttpError(err instanceof Error
+                    ? err.message
+                    : t('http.error.networkError', undefined, { defaultValue: 'Network error' }), 0, undefined, finalConfig, 'http.error.networkError');
+                // Apply error interceptors
+                let finalError = error;
+                for (const interceptor of errorInterceptors) {
+                    finalError = await interceptor(finalError);
+                }
+                throw finalError;
+            }
+        },
+        get(url, requestConfig) {
+            return client.request({ ...requestConfig, method: 'GET', url });
+        },
+        post(url, data, requestConfig) {
+            return client.request({ ...requestConfig, method: 'POST', url, data });
+        },
+        put(url, data, requestConfig) {
+            return client.request({ ...requestConfig, method: 'PUT', url, data });
+        },
+        patch(url, data, requestConfig) {
+            return client.request({ ...requestConfig, method: 'PATCH', url, data });
+        },
+        delete(url, requestConfig) {
+            return client.request({ ...requestConfig, method: 'DELETE', url });
+        },
+        addRequestInterceptor(interceptor) {
+            requestInterceptors.push(interceptor);
+            return () => {
+                const index = requestInterceptors.indexOf(interceptor);
+                if (index !== -1) {
+                    requestInterceptors.splice(index, 1);
+                }
+            };
+        },
+        addResponseInterceptor(interceptor) {
+            responseInterceptors.push(interceptor);
+            return () => {
+                const index = responseInterceptors.indexOf(interceptor);
+                if (index !== -1) {
+                    responseInterceptors.splice(index, 1);
+                }
+            };
+        },
+        addErrorInterceptor(interceptor) {
+            errorInterceptors.push(interceptor);
+            return () => {
+                const index = errorInterceptors.indexOf(interceptor);
+                if (index !== -1) {
+                    errorInterceptors.splice(index, 1);
+                }
+            };
+        },
+        setAuthToken(token) {
+            authToken = token;
+        },
+        getAuthToken() {
+            return authToken;
+        },
+        onAuthError(handler) {
+            authErrorHandlers.add(handler);
+            return () => authErrorHandlers.delete(handler);
+        },
+    };
+    return client;
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Core type definitions for the HTTP client.
+ *
+ * @module
+ */
+/**
+ * HTTP request method.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * HTTP request options (headers, query params, timeout, credentials, response type, abort signal).
+ */
+export interface RequestConfig {
+    /**
+     * Request headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Query parameters.
+     */
+    params?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Request timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Whether to include credentials (cookies).
+     */
+    withCredentials?: boolean;
+    /**
+     * Response type.
+     */
+    responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
+    /**
+     * Abort signal for cancellation.
+     */
+    signal?: AbortSignal;
+    /**
+     * Request body data.
+     */
+    data?: unknown;
+    /**
+     * Custom request options (implementation-specific).
+     */
+    options?: Record<string, unknown>;
+}
+/**
+ * Full request configuration including method and URL.
+ */
+export interface FullRequestConfig extends RequestConfig {
+    /**
+     * HTTP method.
+     */
+    method: HttpMethod;
+    /**
+     * Request URL (can be relative or absolute).
+     */
+    url: string;
+    /**
+     * Request body data.
+     */
+    data?: unknown;
+}
+/**
+ * Parsed HTTP response with status code, headers, and typed body data.
+ */
+export interface HttpResponse<T = unknown> {
+    /**
+     * Response data.
+     */
+    data: T;
+    /**
+     * HTTP status code.
+     */
+    status: number;
+    /**
+     * HTTP status text.
+     */
+    statusText: string;
+    /**
+     * Response headers.
+     */
+    headers: Record<string, string>;
+    /**
+     * Original request config.
+     */
+    config: FullRequestConfig;
+}
+/**
+ * HTTP error with response details.
+ */
+export declare class HttpError extends Error {
+    status: number;
+    response?: HttpResponse | undefined;
+    config?: FullRequestConfig | undefined;
+    errorKey?: string | undefined;
+    constructor(message: string, status: number, response?: HttpResponse | undefined, config?: FullRequestConfig | undefined, errorKey?: string | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAA;AAEzF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAE9D;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAA;IAEvD;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAElB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC;;OAEG;IACH,IAAI,EAAE,CAAC,CAAA;IAEP;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE/B;;OAEG;IACH,MAAM,EAAE,iBAAiB,CAAA;CAC1B;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAGzB,MAAM,EAAE,MAAM;IACd,QAAQ,CAAC,EAAE,YAAY;IACvB,MAAM,CAAC,EAAE,iBAAiB;IAC1B,QAAQ,CAAC,EAAE,MAAM;gBAJxB,OAAO,EAAE,MAAM,EACR,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,YAAY,YAAA,EACvB,MAAM,CAAC,EAAE,iBAAiB,YAAA,EAC1B,QAAQ,CAAC,EAAE,MAAM,YAAA;CAK3B"}

package/dist/types.js

@@ -0,0 +1,23 @@
+/**
+ * Core type definitions for the HTTP client.
+ *
+ * @module
+ */
+/**
+ * HTTP error with response details.
+ */
+export class HttpError extends Error {
+    status;
+    response;
+    config;
+    errorKey;
+    constructor(message, status, response, config, errorKey) {
+        super(message);
+        this.status = status;
+        this.response = response;
+        this.config = config;
+        this.errorKey = errorKey;
+        this.name = 'HttpError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsGH;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGzB;IACA;IACA;IACA;IALT,YACE,OAAe,EACR,MAAc,EACd,QAAuB,EACvB,MAA0B,EAC1B,QAAiB;QAExB,KAAK,CAAC,OAAO,CAAC,CAAA;QALP,WAAM,GAAN,MAAM,CAAQ;QACd,aAAQ,GAAR,QAAQ,CAAe;QACvB,WAAM,GAAN,MAAM,CAAoB;QAC1B,aAAQ,GAAR,QAAQ,CAAS;QAGxB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;IACzB,CAAC;CACF"}

package/dist/unwrap.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Response-envelope unwrappers.
+ *
+ * Apps and mock servers commonly return either a bare value (`T` or
+ * `T[]`) or an envelope `{ data: T }` / `{ data: T[] }`. These helpers
+ * normalize either shape into a predictable `T[]` or `T | null` for
+ * downstream code, eliminating the per-call `'data' in res ? ...` dance.
+ *
+ * Lifted out of the 59 apps that previously carried a local
+ * `lib/unwrap.ts` copy. The two functions cover the response shapes used
+ * by the molecule mock server and the typical resource routes — a bare
+ * value, a `{ data }` envelope, and (for lists) the RICH pagination
+ * envelope `{ data, total, limit, offset }` returned by the pre-built
+ * `@molecule/api-resource-*` list endpoints (comment, review,
+ * activity-feed, bookmark, …). Other bespoke envelopes are out of scope
+ * — handle those in the caller.
+ *
+ * @module
+ */
+/**
+ * Normalize an unknown response body into a typed array.
+ *
+ * Accepts:
+ *   - a bare array → returned as-is (cast)
+ *   - `{ data: T[] }` envelope → the inner array
+ *   - `HttpResponse<T[]>` (i.e. `{ data: T[], status, ... }`) → the inner array
+ *   - `HttpResponse<{ data: T[] }>` (the response of an envelope-returning
+ *     endpoint as it arrives from `@molecule/app-http`'s `HttpClient`) → the
+ *     doubly-nested inner array
+ *   - `HttpResponse<{ data: T[], total, limit, offset }>` (a RICH pagination
+ *     envelope from a pre-built `@molecule/api-resource-*` list endpoint) → the
+ *     inner `data` array (the numeric `total`/`limit`/`offset` make the shape
+ *     unambiguous, so callers can pass the whole HttpResponse and still get the rows)
+ *   - anything else → `[]`
+ *
+ * Callers commonly pass either the raw JSON body (e.g. from `fetch().then(r =>
+ * r.json())`) or the `HttpResponse` returned by `useHttpClient().get(...)`.
+ * Both shapes are handled here so pages don't have to remember to call
+ * `unwrapList(res.data)` vs `unwrapList(res)`.
+ *
+ * @param res - Raw response body OR an `HttpResponse` envelope from `@molecule/app-http`.
+ * @returns A typed array `T[]`; never `null`/`undefined`.
+ */
+export declare function unwrapList<T>(res: unknown): T[];
+/**
+ * Normalize an unknown response body into a single typed resource.
+ *
+ * Accepts:
+ *   - a non-empty plain object → returned as-is (cast)
+ *   - `{ data: T }` envelope → the inner value
+ *   - `{ data: null }`, `{ data: undefined }`, `{ data: [] }`, or
+ *     `{ data: {} }` (mock-server's no-match shape) → `null`
+ *   - an empty object `{}` → `null`
+ *   - arrays, primitives, `null`, `undefined` → `null`
+ *
+ * The "envelope contains an array → null" branch handles the case
+ * where the mock server returns `[]` for unmatched endpoints but the
+ * caller expects a single resource.
+ *
+ * @param res - Raw response body (e.g. `HttpResponse.data` from `@molecule/app-http`).
+ * @returns The typed resource `T`, or `null` when the response shape
+ *   indicates "no resource" (including the various empty envelopes
+ *   above).
+ */
+export declare function unwrapSingle<T>(res: unknown): T | null;
+//# sourceMappingURL=unwrap.d.ts.map

package/dist/unwrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unwrap.d.ts","sourceRoot":"","sources":["../src/unwrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,EAAE,CAmC/C;AAyED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,CAmDtD"}