@rtorcato/api-http 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Torcato
+
+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

@@ -0,0 +1,58 @@
+# @rtorcato/api-http
+
+Typed HTTP client over native `fetch` — base URL, default headers, timeout, optional retry, and errors normalized to [`@rtorcato/api-errors`](https://github.com/rtorcato/api-common/tree/main/packages/api-errors).
+
+No `axios`, no wrapper dependency — built on Node's global `fetch` and `AbortSignal.timeout` (Node 22+).
+
+## Install
+
+```sh
+pnpm add @rtorcato/api-http @rtorcato/api-errors
+```
+
+## Usage
+
+```ts
+import { createHttpClient } from '@rtorcato/api-http'
+
+const api = createHttpClient({
+  baseURL: 'https://api.example.com',
+  headers: { authorization: `Bearer ${token}` },
+  timeoutMs: 10_000,
+})
+
+const user = await api.get<{ id: string; name: string }>('/users/me')
+await api.post('/users', { name: 'Ada' })
+await api.get('/items', { query: { page: 2, q: 'hi' } })
+```
+
+- `get` / `delete` — `(path, options?)`
+- `post` / `put` / `patch` — `(path, body?, options?)` — `body` is JSON-encoded with a `content-type: application/json` header.
+
+## Errors
+
+Non-2xx responses throw an `HttpError` (from `@rtorcato/api-errors`) carrying the status and a message pulled from the response body (`{ message }` / `{ error }` / raw text), so it slots straight into the `api-errors-express` / `api-errors-hono` error handlers. Network failures throw `HttpError` with status `0` and code `network_error`.
+
+```ts
+import { HttpError } from '@rtorcato/api-errors'
+
+try {
+  await api.get('/missing')
+} catch (err) {
+  if (err instanceof HttpError && err.status === 404) { /* … */ }
+}
+```
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `baseURL` | — | prepended to every request path |
+| `headers` | — | sent on every request (per-request headers merge on top) |
+| `timeoutMs` | `30_000` | per-request timeout (override per call) |
+| `retries` | `0` | retry attempts on network error or 5xx |
+| `retryDelayMs` | `200` | fixed delay between retries |
+
+Per-request options: `{ headers, query, timeoutMs, signal }`. A caller `signal` is combined with the timeout signal.
+
+Source: https://github.com/rtorcato/api-common/tree/main/packages/api-http

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export interface HttpClientOptions {
+    /** Prepended to every request path. */
+    baseURL?: string;
+    /** Sent on every request (per-request headers merge on top). */
+    headers?: Record<string, string>;
+    /** Per-request timeout in ms. Default: 30_000. */
+    timeoutMs?: number;
+    /** Retry attempts on network error or 5xx. Default: 0 (no retry). */
+    retries?: number;
+    /** Fixed delay between retries in ms. Default: 200. */
+    retryDelayMs?: number;
+}
+export interface RequestOptions {
+    /** Merged on top of the client's default headers. */
+    headers?: Record<string, string>;
+    /** Appended as a query string; `undefined` values are skipped. */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Overrides the client timeout for this request. */
+    timeoutMs?: number;
+    /** Caller abort signal — combined with the timeout signal. */
+    signal?: AbortSignal;
+}
+export interface HttpClient {
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+}
+/**
+ * Create a typed HTTP client bound to a base URL and default headers.
+ *
+ * @example
+ * ```ts
+ * const api = createHttpClient({ baseURL: 'https://api.example.com', headers: { authorization: `Bearer ${token}` } })
+ * const user = await api.get<{ id: string }>('/users/me')
+ * await api.post('/users', { name: 'Ada' })
+ * ```
+ *
+ * Non-2xx responses throw an `HttpError` (from `@rtorcato/api-errors`) carrying the
+ * status and a message pulled from the response body, so it slots straight into the
+ * error-handler middleware. Network failures throw `HttpError` with status `0` and
+ * code `network_error`.
+ */
+export declare function createHttpClient(clientOptions?: HttpClientOptions): HttpClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,iBAAiB;IACjC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACpE,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACvE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACrF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACpF,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACtF;AA+FD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,GAAE,iBAAsB,GAAG,UAAU,CAQlF"}

package/dist/index.js

@@ -0,0 +1,105 @@
+import { HttpError } from '@rtorcato/api-errors';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function buildUrl(baseURL, path, query) {
+    const url = baseURL
+        ? new URL(path, baseURL.endsWith('/') ? baseURL : `${baseURL}/`)
+        : new URL(path);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+/** Pull a human-readable message out of an error response body (JSON `{message|error}` or raw text). */
+function messageFromBody(text, statusText) {
+    if (!text)
+        return statusText || 'Request failed';
+    try {
+        const json = JSON.parse(text);
+        if (json && typeof json === 'object') {
+            const m = json['message'] ?? json['error'];
+            if (typeof m === 'string')
+                return m;
+        }
+    }
+    catch {
+        // not JSON — fall through to the raw text
+    }
+    return text;
+}
+async function parseBody(res) {
+    if (res.status === 204 || res.headers.get('content-length') === '0')
+        return undefined;
+    const text = await res.text();
+    if (!text)
+        return undefined;
+    const contentType = res.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json'))
+        return JSON.parse(text);
+    return text;
+}
+async function request(client, method, path, body, options = {}) {
+    const url = buildUrl(client.baseURL, path, options.query);
+    const headers = { ...client.headers, ...options.headers };
+    let payload;
+    if (body !== undefined) {
+        payload = JSON.stringify(body);
+        headers['content-type'] ??= 'application/json';
+    }
+    const timeoutMs = options.timeoutMs ?? client.timeoutMs ?? 30_000;
+    const retries = client.retries ?? 0;
+    const retryDelayMs = client.retryDelayMs ?? 200;
+    for (let attempt = 0;; attempt++) {
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+        let res;
+        try {
+            res = await fetch(url, { method, headers, body: payload, signal });
+        }
+        catch (err) {
+            // Network failure or timeout. Retry if attempts remain, else normalize.
+            if (attempt < retries) {
+                await sleep(retryDelayMs);
+                continue;
+            }
+            const message = err instanceof Error ? err.message : 'Network request failed';
+            throw new HttpError(0, message, 'network_error');
+        }
+        if (!res.ok) {
+            if (res.status >= 500 && attempt < retries) {
+                await sleep(retryDelayMs);
+                continue;
+            }
+            const text = await res.text();
+            throw new HttpError(res.status, messageFromBody(text, res.statusText), 'http_error');
+        }
+        return parseBody(res);
+    }
+}
+/**
+ * Create a typed HTTP client bound to a base URL and default headers.
+ *
+ * @example
+ * ```ts
+ * const api = createHttpClient({ baseURL: 'https://api.example.com', headers: { authorization: `Bearer ${token}` } })
+ * const user = await api.get<{ id: string }>('/users/me')
+ * await api.post('/users', { name: 'Ada' })
+ * ```
+ *
+ * Non-2xx responses throw an `HttpError` (from `@rtorcato/api-errors`) carrying the
+ * status and a message pulled from the response body, so it slots straight into the
+ * error-handler middleware. Network failures throw `HttpError` with status `0` and
+ * code `network_error`.
+ */
+export function createHttpClient(clientOptions = {}) {
+    return {
+        get: (path, options) => request(clientOptions, 'GET', path, undefined, options),
+        delete: (path, options) => request(clientOptions, 'DELETE', path, undefined, options),
+        post: (path, body, options) => request(clientOptions, 'POST', path, body, options),
+        put: (path, body, options) => request(clientOptions, 'PUT', path, body, options),
+        patch: (path, body, options) => request(clientOptions, 'PATCH', path, body, options),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@rtorcato/api-http",
+  "version": "0.2.0",
+  "description": "Typed HTTP client over native fetch — base URL, default headers, timeout, and errors normalized to @rtorcato/api-errors.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Richard Torcato",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@rtorcato/api-errors": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api",
+    "nodejs",
+    "typescript",
+    "http",
+    "fetch",
+    "client"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rtorcato/api-common.git",
+    "directory": "packages/api-http"
+  },
+  "homepage": "https://github.com/rtorcato/api-common/tree/main/packages/api-http#readme",
+  "bugs": {
+    "url": "https://github.com/rtorcato/api-common/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}