@mfeflow/http 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @mfeflow/http
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small fetch client over [`@mfeflow/url-factory`](../url-factory) endpoints. Base URLs come from the runtime config, so one build runs in every environment. It adds an async bearer token, a timeout, retries with backoff for idempotent methods, typed JSON and an error that carries the status and body but no URL.
+
+## Install
+
+```sh
+pnpm add @mfeflow/http @mfeflow/url-factory
+```
+
+In a project made with mfeflow, `mfeflow add http` writes `src/api/client.ts` in every app.
+
+## Usage
+
+```ts
+import { createUrlFactory, defineEndpoints } from '@mfeflow/url-factory';
+import { createHttpClient, isHttpError } from '@mfeflow/http';
+
+const endpoints = defineEndpoints({
+  listProducts: { service: 'api', path: '/products' },
+  getProduct: { service: 'api', path: '/products/:sku' },
+  addOrder: { service: 'api', path: '/orders' },
+});
+const apiUrl = createUrlFactory(endpoints, (service) => config.services[service]);
+
+const api = createHttpClient<typeof endpoints, { listProducts: Product[]; getProduct: Product }>({
+  url: apiUrl,
+  getToken: () => session.accessToken(), // may be async; return undefined when signed out
+});
+
+const mugs = await api.get('listProducts', { query: { q: 'mug' } }); // Product[]
+await api.post('addOrder', { json: { sku: 'A1' } });
+
+try {
+  await api.get('getProduct', { params: { sku: 'nope' } });
+} catch (error) {
+  if (isHttpError(error) && error.status === 404) showNotFound(error.body);
+}
+```
+
+A second type argument says what each endpoint answers with; `parse` on a call checks the body and sets the type instead.
+
+## What it does
+
+- **Retries** GET, HEAD, OPTIONS, PUT and DELETE (never POST or PATCH) on a network error, a timeout and 408, 425, 429, 502, 503 and 504: twice by default, with exponential backoff and jitter. A `Retry-After` longer than the longest wait is not waited for. `retry: false` turns it off.
+- **Times out** each attempt after 10 seconds of waiting for the headers (`timeoutMs`); a slow body is not cut off. Your own `AbortSignal` is passed through; aborting it throws your reason and is not retried.
+- **Errors** are `HttpError` with `kind` (`status`, `network`, `timeout`, `parse`, `auth`), `status`, `body` (parsed JSON, or text cut to 4096 characters), `headers` and `attempts`. The message holds the method, the endpoint key and what happened: no URL and no body, so ids and emails stay out of logs by default.
+- **Does not add `traceparent`.** `@mfeflow/telemetry` instruments `fetch` for that, and this client calls the global `fetch` at request time, so the instrumentation applies however late it was installed.
+
+## Module Federation sharing
+
+Bucket: **stateless**. Nothing here holds state shared between micro-frontends, so each remote can bundle its own copy and different versions can run side by side. No sharing config is needed.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/error.d.ts

@@ -0,0 +1,31 @@
+export type HttpErrorKind = 'status' | 'network' | 'timeout' | 'parse' | 'auth';
+export interface HttpErrorInit {
+    kind: HttpErrorKind;
+    method: string;
+    /** The endpoint key, for example `getOrder`. */
+    endpoint: string;
+    status?: number | undefined;
+    body?: unknown;
+    headers?: Headers | undefined;
+    attempts: number;
+    cause?: unknown;
+}
+/**
+ * A request that failed. The message names the method, the endpoint key and what happened, and
+ * nothing else: no URL (it can hold ids or emails) and no body. Read `status` and `body` to
+ * handle a failure, and decide yourself what to log.
+ */
+export declare class HttpError extends Error {
+    readonly kind: HttpErrorKind;
+    readonly method: string;
+    readonly endpoint: string;
+    /** The HTTP status; undefined when no response arrived. */
+    readonly status: number | undefined;
+    /** The response body: parsed when it was JSON, otherwise text cut to 4096 characters. */
+    readonly body: unknown;
+    readonly headers: Headers | undefined;
+    /** How many times the request was sent. */
+    readonly attempts: number;
+    constructor(init: HttpErrorInit, statusText?: string);
+}
+export declare function isHttpError(value: unknown): value is HttpError;

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import type { Endpoints, PathParams, Query, UrlFactory } from '@mfeflow/url-factory';
+import { type RetryOptions } from './retry.js';
+export { HttpError, isHttpError, type HttpErrorKind } from './error.js';
+export type { RetryOptions } from './retry.js';
+type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+export interface HttpClientOptions<E extends Endpoints> {
+    /** The URL factory from `src/api/endpoints.ts`: it knows each service's base URL from the runtime config. */
+    url: UrlFactory<E>;
+    /**
+     * The bearer token, asked for before every attempt so a refreshed token is picked up. Return
+     * undefined for a signed-out visitor and no header is sent.
+     */
+    getToken?: () => string | undefined | Promise<string | undefined>;
+    /** Sent with every request; a request's own headers win. */
+    headers?: Record<string, string>;
+    /** Per attempt, in ms. Default 10 000. */
+    timeoutMs?: number;
+    /** Set false to never retry. */
+    retry?: RetryOptions | false;
+    credentials?: RequestCredentials;
+    /**
+     * Defaults to the global `fetch`, looked up on every request, so instrumentation that wraps it
+     * after this client was created (OpenTelemetry's trace headers) still applies.
+     */
+    fetch?: Fetch;
+}
+interface Extras<T> {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    retry?: RetryOptions | false;
+    credentials?: RequestCredentials;
+    /** Checks or reshapes the parsed body; its return type becomes the result type. */
+    parse?: (raw: unknown) => T;
+}
+type ReadArgs<P extends string, T> = [PathParams<P>] extends [never] ? [options?: {
+    query?: Query;
+} & Extras<T>] : [
+    options: {
+        params: Readonly<Record<PathParams<P>, string | number>>;
+        query?: Query;
+    } & Extras<T>
+];
+type WriteArgs<P extends string, T> = [PathParams<P>] extends [never] ? [options?: {
+    query?: Query;
+    json?: unknown;
+} & Extras<T>] : [
+    options: {
+        params: Readonly<Record<PathParams<P>, string | number>>;
+        query?: Query;
+        json?: unknown;
+    } & Extras<T>
+];
+/** What each endpoint answers with, by endpoint key. Unlisted endpoints answer `unknown`. */
+export type ResponseMap<E extends Endpoints> = Partial<Record<keyof E & string, unknown>>;
+type ResponseOf<R, K> = K extends keyof R ? R[K] : unknown;
+export interface HttpClient<E extends Endpoints, R extends ResponseMap<E> = ResponseMap<E>> {
+    get: <K extends keyof E & string, T = ResponseOf<R, K>>(key: K, ...args: ReadArgs<E[K]['path'], T>) => Promise<T>;
+    post: <K extends keyof E & string, T = ResponseOf<R, K>>(key: K, ...args: WriteArgs<E[K]['path'], T>) => Promise<T>;
+    put: <K extends keyof E & string, T = ResponseOf<R, K>>(key: K, ...args: WriteArgs<E[K]['path'], T>) => Promise<T>;
+    patch: <K extends keyof E & string, T = ResponseOf<R, K>>(key: K, ...args: WriteArgs<E[K]['path'], T>) => Promise<T>;
+    delete: <K extends keyof E & string, T = ResponseOf<R, K>>(key: K, ...args: ReadArgs<E[K]['path'], T>) => Promise<T>;
+    /** The raw `Response` of a successful request, for streams and files. Errors still throw `HttpError`. */
+    response: <K extends keyof E & string>(method: string, key: K, ...args: WriteArgs<E[K]['path'], unknown>) => Promise<Response>;
+}
+/**
+ * A fetch client over your endpoints. Retries only idempotent methods (GET, HEAD, OPTIONS, PUT,
+ * DELETE) on network errors, timeouts and 408, 425, 429, 502, 503, 504, with backoff. Trace headers
+ * are not added here; `@mfeflow/telemetry` instruments `fetch` for that.
+ *
+ * ```ts
+ * const api = createHttpClient<typeof endpoints, { listProducts: Product[] }>({ url: apiUrl });
+ * const products = await api.get('listProducts', { query: { page: 1 } });
+ * ```
+ */
+export declare function createHttpClient<E extends Endpoints, R extends ResponseMap<E> = ResponseMap<E>>(options: HttpClientOptions<E>): HttpClient<E, R>;

package/dist/index.js

@@ -0,0 +1,250 @@
+const WHAT = {
+    status: (init, text)=>`answered ${String(init.status ?? 0)}${'' === text ? '' : ` ${text}`}`,
+    network: ()=>'could not reach the server',
+    timeout: ()=>'timed out',
+    auth: ()=>'could not get a token',
+    parse: (init)=>`answered ${String(init.status ?? 0)} with a body that is not valid JSON`
+};
+class HttpError extends Error {
+    kind;
+    method;
+    endpoint;
+    status;
+    body;
+    headers;
+    attempts;
+    constructor(init, statusText = ''){
+        super(`${init.method} ${init.endpoint} ${WHAT[init.kind](init, statusText)}`, void 0 === init.cause ? void 0 : {
+            cause: init.cause
+        });
+        this.name = 'HttpError';
+        this.kind = init.kind;
+        this.method = init.method;
+        this.endpoint = init.endpoint;
+        this.status = init.status;
+        this.body = init.body;
+        this.headers = init.headers;
+        this.attempts = init.attempts;
+    }
+}
+function isHttpError(value) {
+    return value instanceof HttpError;
+}
+const DEFAULT_RETRY = {
+    retries: 2,
+    baseDelayMs: 200,
+    maxDelayMs: 2000
+};
+const IDEMPOTENT = new Set([
+    'GET',
+    'HEAD',
+    'OPTIONS',
+    'PUT',
+    'DELETE'
+]);
+const RETRY_STATUS = new Set([
+    408,
+    425,
+    429,
+    502,
+    503,
+    504
+]);
+const canRetryMethod = (method)=>IDEMPOTENT.has(method);
+const canRetryStatus = (status)=>RETRY_STATUS.has(status);
+function retryAfterMs(headers, now = Date.now()) {
+    const value = headers.get('retry-after')?.trim();
+    if (!value) return;
+    if (/^\d+$/.test(value)) return 1000 * Number(value);
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? void 0 : Math.max(0, at - now);
+}
+function backoffMs(attempt, options, random = Math.random) {
+    return Math.round(random() * Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** attempt));
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject)=>{
+        if (signal?.aborted) return void reject(signal.reason);
+        const onAbort = ()=>{
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(()=>{
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, {
+            once: true
+        });
+    });
+}
+const BODY_LIMIT = 4096;
+const DEFAULT_TIMEOUT_MS = 10000;
+async function readBody(response) {
+    const text = await response.text().catch(()=>'');
+    if ('' === text) return;
+    if (response.headers.get('content-type')?.includes('json')) try {
+        return JSON.parse(text);
+    } catch  {}
+    return text.slice(0, BODY_LIMIT);
+}
+function createHttpClient(options) {
+    const urlFor = options.url;
+    const doFetch = options.fetch ?? ((input, init)=>globalThis.fetch(input, init));
+    function headersFor(extra, hasBody) {
+        const headers = new Headers({
+            accept: 'application/json'
+        });
+        for (const source of [
+            options.headers,
+            extra
+        ])for (const [name, value] of Object.entries(source ?? {}))headers.set(name, value);
+        if (hasBody && !headers.has('content-type')) headers.set('content-type', 'application/json');
+        if (headers.has('authorization') || !options.getToken) return headers;
+        const withToken = (token)=>{
+            if (token) headers.set('authorization', `Bearer ${token}`);
+            return headers;
+        };
+        const token = options.getToken();
+        return 'object' == typeof token ? token.then(withToken) : withToken(token);
+    }
+    async function attempt(method, key, url, request, count) {
+        const hasBody = void 0 !== request.json;
+        const fail = (kind, cause)=>new HttpError({
+                kind,
+                method,
+                endpoint: key,
+                attempts: count,
+                cause
+            });
+        let headers;
+        try {
+            const ready = headersFor(request.headers, hasBody);
+            headers = ready instanceof Headers ? ready : await ready;
+        } catch (cause) {
+            throw fail('auth', cause);
+        }
+        const timer = new AbortController();
+        const wait = setTimeout(()=>{
+            timer.abort();
+        }, request.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const signal = request.signal ? AbortSignal.any([
+            request.signal,
+            timer.signal
+        ]) : timer.signal;
+        try {
+            const credentials = request.credentials ?? options.credentials;
+            return await doFetch(url, {
+                method,
+                headers,
+                signal,
+                ...hasBody ? {
+                    body: JSON.stringify(request.json)
+                } : {},
+                ...credentials ? {
+                    credentials
+                } : {}
+            });
+        } catch (error) {
+            if (request.signal?.aborted) throw request.signal.reason;
+            throw fail(timer.signal.aborted ? 'timeout' : 'network', error);
+        } finally{
+            clearTimeout(wait);
+        }
+    }
+    async function once(method, key, url, request, count) {
+        let response;
+        try {
+            response = await attempt(method, key, url, request, count);
+        } catch (error) {
+            if (error instanceof HttpError) return {
+                failure: error,
+                retryable: 'auth' !== error.kind,
+                asked: void 0
+            };
+            throw error;
+        }
+        if (response.ok) return {
+            ok: response
+        };
+        const failure = new HttpError({
+            kind: 'status',
+            method,
+            endpoint: key,
+            status: response.status,
+            body: await readBody(response),
+            headers: response.headers,
+            attempts: count
+        }, response.statusText);
+        return {
+            failure,
+            retryable: canRetryStatus(response.status),
+            asked: retryAfterMs(response.headers)
+        };
+    }
+    async function send(method, key, request) {
+        const url = urlFor(key, {
+            params: request.params,
+            query: request.query
+        });
+        const setting = request.retry ?? options.retry;
+        const policy = false !== setting && canRetryMethod(method) ? {
+            ...DEFAULT_RETRY,
+            ...setting
+        } : void 0;
+        for(let count = 1;; count++){
+            const outcome = await once(method, key, url, request, count);
+            if ('ok' in outcome) return {
+                response: outcome.ok,
+                attempts: count
+            };
+            if (!policy || count > policy.retries || !outcome.retryable) throw outcome.failure;
+            if (void 0 !== outcome.asked && outcome.asked > policy.maxDelayMs) throw outcome.failure;
+            await sleep(outcome.asked ?? backoffMs(count - 1, policy), request.signal);
+        }
+    }
+    async function json(method, key, request) {
+        const { response, attempts } = await send(method, key, request);
+        let text = '';
+        if (204 !== response.status && 205 !== response.status) try {
+            text = await response.text();
+        } catch (cause) {
+            if (request.signal?.aborted) throw request.signal.reason;
+            throw new HttpError({
+                kind: 'network',
+                method,
+                endpoint: key,
+                status: response.status,
+                headers: response.headers,
+                attempts,
+                cause
+            });
+        }
+        if ('' === text) return request.parse ? request.parse(void 0) : void 0;
+        let raw;
+        try {
+            raw = JSON.parse(text);
+        } catch (cause) {
+            throw new HttpError({
+                kind: 'parse',
+                method,
+                endpoint: key,
+                status: response.status,
+                headers: response.headers,
+                attempts,
+                cause
+            });
+        }
+        return request.parse ? request.parse(raw) : raw;
+    }
+    const verb = (method)=>(key, request = {})=>json(method, key, request);
+    return {
+        get: verb('GET'),
+        post: verb('POST'),
+        put: verb('PUT'),
+        patch: verb('PATCH'),
+        delete: verb('DELETE'),
+        response: async (method, key, request = {})=>(await send(method.toUpperCase(), key, request)).response
+    };
+}
+export { HttpError, createHttpClient, isHttpError };

package/dist/retry.d.ts

@@ -0,0 +1,21 @@
+export interface RetryOptions {
+    /** Extra tries after the first. Default 2. */
+    retries?: number;
+    /** First wait before a retry, in ms; each one doubles, with jitter. Default 200. */
+    baseDelayMs?: number;
+    /** Longest wait in ms. A server that asks for longer (Retry-After) is not waited for. Default 2000. */
+    maxDelayMs?: number;
+}
+export declare const DEFAULT_RETRY: {
+    retries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
+export declare const canRetryMethod: (method: string) => boolean;
+export declare const canRetryStatus: (status: number) => boolean;
+/** The wait asked for by a `Retry-After` header (seconds or a date), in ms; undefined without one. */
+export declare function retryAfterMs(headers: Headers, now?: number): number | undefined;
+/** Exponential backoff with full jitter: somewhere between 0 and base * 2^attempt, capped. */
+export declare function backoffMs(attempt: number, options: Required<RetryOptions>, random?: () => number): number;
+/** Resolves after `ms`; rejects with the signal's reason if it aborts first. */
+export declare function sleep(ms: number, signal: AbortSignal | undefined): Promise<void>;

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@mfeflow/http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "A small fetch client over @mfeflow/url-factory endpoints: async bearer tokens, timeouts, retries with backoff for idempotent methods only, typed JSON, and errors that carry the status and body but no URL.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "fetch",
+    "http-client",
+    "retry",
+    "typescript"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/http"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mfeflow/url-factory": "0.3.0"
+  },
+  "devDependencies": {
+    "@rslib/core": "1.0.5",
+    "@types/node": "26.6.6",
+    "msw": "3.0.3",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "stateless"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }