@boy-offi9-inc/reqkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boy Offi9
+
+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,150 @@
+<p align="center">
+  <a href="https://www.npmjs.com/package/@boy-offi9-inc/reqkit" aria-label="npm">
+    <img src="./assets/logo-wordmark.svg" alt="reqkit on npm" width="480" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" alt="Node >=18">
+  <img src="https://img.shields.io/badge/npm-%40boy--offi9--inc%2Freqkit-CB3837?logo=npm&logoColor=white" alt="npm package">
+  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero dependencies">
+  <img src="https://img.shields.io/badge/module-CJS%20%2B%20ESM-blue" alt="CJS + ESM">
+  <img src="https://img.shields.io/badge/types-included-3178C6?logo=typescript&logoColor=white" alt="TypeScript types included">
+</p>
+
+# reqkit
+
+Small, composable HTTP helper functions. Not a client, not an axios replacement — works alongside `fetch`, `axios`, or anything else you're already using. Pull in the one function you need; igno[...]
+
+```js
+const { withRetry, normalizeError } = require("@boy-offi9-inc/reqkit");
+
+const data = await withRetry(() => fetch(url).then(r => r.json()));
+```
+
+---
+
+## Why this exists
+
+Most HTTP retry/timeout wrappers bundle everything into a client you have to fully adopt. This is the opposite: standalone functions that compose with whatever you're already using, and a couple o[...]
+
+**Honest note:** `withRetry`, `withTimeout`, and `normalizeError` solve a well-covered problem — there are other solid packages doing similar things (`fetchy`, `fetchpilot`, `p-retry`, to name a[...]
+
+- **`retryAfterAware`** — actually reads `Retry-After`/`X-RateLimit-Reset` headers instead of blind backoff on 429s. Most retry libraries treat rate-limit responses like any other failure and ig[...]
+- **`withProgress`** — progress callback for any streamed response body (downloads, large payloads, anything), not tied to a specific HTTP client.
+
+Zero dependencies. CJS + ESM. TypeScript types included.
+
+---
+
+## Install
+
+```bash
+npm install @boy-offi9-inc/reqkit
+```
+
+---
+
+## API
+
+### `withRetry(fn, opts?)`
+
+Retries an async function with exponential backoff + jitter.
+
+```js
+const data = await withRetry(
+  () => fetch(url).then(r => r.json()),
+  { retries: 3, baseDelayMs: 300, onRetry: (err, attempt, delayMs) => console.log(`retry ${attempt} in ${delayMs}ms`) }
+);
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `retries` | `3` | max retry attempts after the first try |
+| `baseDelayMs` | `300` | initial delay |
+| `maxDelayMs` | `10000` | delay ceiling |
+| `shouldRetry` | retries anything but AbortError | `(err, attempt) => boolean` |
+| `onRetry` | — | `(err, attempt, delayMs) => void` |
+
+### `withTimeout(fn, ms)`
+
+Races an async function against a timeout, passing it an `AbortSignal` so the underlying request can actually be cancelled.
+
+```js
+const data = await withTimeout(
+  signal => fetch(url, { signal }).then(r => r.json()),
+  5000
+);
+// throws TimeoutError on timeout, regardless of whether fn cooperates with the signal
+```
+
+### `normalizeError(err)`
+
+One consistent error shape regardless of source (fetch, axios, node http, generic):
+
+```js
+const { message, status, code, isNetworkError, isTimeout } = normalizeError(err);
+```
+
+Every field is always present (`null`/`false` when not applicable) — no existence checks needed.
+
+### `parseJsonSafe(input)`
+
+Never throws on malformed JSON. Accepts a `Response` or a raw string.
+
+```js
+const { data, error } = await parseJsonSafe(response);
+if (error) { /* handle malformed JSON without a try/catch */ }
+```
+
+### `buildQuery(params)`
+
+Minimal query string builder — skips `null`/`undefined`, repeats the key for arrays, encodes everything.
+
+```js
+buildQuery({ q: "hello world", tag: ["a", "b"] });
+// "q=hello%20world&tag=a&tag=b"
+```
+
+For full parsing/nested-object support, use [`query-string`](https://www.npmjs.com/package/query-string) instead — this only covers the common flat-object case with zero dependencies.
+
+### `retryAfterAware(fn, opts?)`
+
+Retries a fetch-like call, honoring `Retry-After`/`X-RateLimit-Reset` headers on 429/503 instead of blind backoff.
+
+```js
+const response = await retryAfterAware(
+  () => fetch(url),
+  { retries: 3, retryStatusCodes: [429, 503] }
+);
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `retries` | `3` | |
+| `retryStatusCodes` | `[429, 503]` | |
+| `fallbackDelayMs` | `1000` | used when no usable header is present |
+| `maxDelayMs` | `60000` | |
+| `onRetry` | — | `(status, waitMs, attempt) => void` |
+
+### `withProgress(response, onProgress?)`
+
+Reads a streamed `Response` body while reporting progress, returns the collected bytes as a `Uint8Array`.
+
+```js
+const bytes = await withProgress(response, ({ loaded, total, percent }) => {
+  console.log(`${percent ?? "?"}% (${loaded}/${total ?? "?"} bytes)`);
+});
+```
+
+Works without `Content-Length` too — `total`/`percent` are just `null` in that case, `loaded` is still accurate. Falls back to a single-shot read (still calling `onProgress` once) if the respon[...]
+
+---
+
+## Design notes
+
+- **Zero dependencies.** Nothing to audit, nothing to break underneath you.
+- **CJS + ESM.** `require()` and `import` both work.
+- **Composable, not a client.** Every function takes and returns plain values (`Response`, plain objects, `Uint8Array`) — nothing proprietary to learn.
+- **TypeScript types included**, hand-written (no build step to go wrong).

package/assets/logo-wordmark.svg

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="640" height="160" viewBox="0 0 640 160" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="wm-bg" x1="0" y1="0" x2="640" y2="160" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#101825"/>
+      <stop offset="1" stop-color="#080c14"/>
+    </linearGradient>
+    <linearGradient id="wm-icon-bg" x1="0" y1="0" x2="240" y2="240" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#16202e"/>
+      <stop offset="1" stop-color="#0c121c"/>
+    </linearGradient>
+    <linearGradient id="wm-arc" x1="175" y1="88" x2="98" y2="60" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#3d8bff"/>
+      <stop offset="1" stop-color="#ffb43d"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="640" height="160" rx="20" fill="url(#wm-bg)"/>
+
+  <!-- icon, scaled down from the 240x240 mark -->
+  <g transform="translate(24,20) scale(0.5)">
+    <rect x="6" y="6" width="228" height="228" rx="46" fill="url(#wm-icon-bg)"/>
+
+    <path d="M 175.4 88 A 64 64 0 1 1 98.1 59.9"
+          fill="none" stroke="url(#wm-arc)" stroke-width="13" stroke-linecap="round"/>
+
+    <polygon points="113.1,54.4 103.1,67.7 96.9,50.8" fill="#ffb43d"/>
+
+    <circle cx="169" cy="161.1" r="7" fill="#3d8bff"/>
+    <circle cx="78.9" cy="169" r="6" fill="#6f9fff"/>
+    <circle cx="59.9" cy="98.1" r="5" fill="#a3c2ff"/>
+  </g>
+
+  <!-- wordmark -->
+  <text x="164" y="82" font-family="'JetBrains Mono', 'Courier New', monospace" font-size="42" font-weight="700" fill="#eef2f7">req<tspan fill="#ffb43d">kit</tspan></text>
+  <text x="165" y="112" font-family="'JetBrains Mono', 'Courier New', monospace" font-size="16" fill="#6b7688">HTTP helpers — retry, timeout, rate-limit aware</text>
+</svg>

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@boy-offi9-inc/reqkit",
+  "version": "0.1.0",
+  "description": "Small, composable HTTP helper functions — retry with backoff, timeouts, normalized errors, safe JSON parsing, rate-limit-aware retry, and download progress. Not a client, works alongside fetch/axios/anything.",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./src/index.js",
+      "import": "./src/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "http",
+    "fetch",
+    "retry",
+    "backoff",
+    "timeout",
+    "rate-limit",
+    "retry-after",
+    "download-progress",
+    "error-normalization",
+    "utility"
+  ],
+  "author": "Boy Offi9",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE",
+    "assets"
+  ]
+}

package/src/buildQuery.js

@@ -0,0 +1,31 @@
+/**
+ * Builds a query string from a params object. Skips null/undefined values,
+ * repeats the key for arrays (`?tag=a&tag=b`), and encodes everything.
+ *
+ * Deliberately minimal — for full query-string parsing/nested-object support,
+ * reach for `query-string` (sindresorhus) instead. This just covers the
+ * common "build a query string from a flat params object" case with zero deps.
+ *
+ * @param {Record<string, unknown>} params
+ */
+function buildQuery(params) {
+  if (!params) return "";
+
+  const pairs = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null || value === undefined) continue;
+
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        if (v === null || v === undefined) continue;
+        pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+      }
+    } else {
+      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+
+  return pairs.join("&");
+}
+
+module.exports = { buildQuery };

package/src/index.js

@@ -0,0 +1,20 @@
+const { withRetry } = require("./withRetry");
+const { withTimeout, TimeoutError } = require("./withTimeout");
+const { normalizeError } = require("./normalizeError");
+const { parseJsonSafe } = require("./parseJsonSafe");
+const { buildQuery } = require("./buildQuery");
+const { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders } = require("./retryAfterAware");
+const { withProgress } = require("./withProgress");
+
+module.exports = {
+  withRetry,
+  withTimeout,
+  TimeoutError,
+  normalizeError,
+  parseJsonSafe,
+  buildQuery,
+  retryAfterAware,
+  parseRetryAfter,
+  getWaitMsFromHeaders,
+  withProgress,
+};

package/src/index.mjs

@@ -0,0 +1,16 @@
+import reqkit from "./index.js";
+
+export const {
+  withRetry,
+  withTimeout,
+  TimeoutError,
+  normalizeError,
+  parseJsonSafe,
+  buildQuery,
+  retryAfterAware,
+  parseRetryAfter,
+  getWaitMsFromHeaders,
+  withProgress,
+} = reqkit;
+
+export default reqkit;

package/src/normalizeError.js

@@ -0,0 +1,79 @@
+/**
+ * Normalizes errors from fetch, axios, node's http/https, and generic
+ * Error objects into one consistent shape:
+ *   { message, status, code, isNetworkError, isTimeout, cause }
+ *
+ * Every field is always present (null/false when not applicable) so callers
+ * can destructure without existence checks.
+ */
+function normalizeError(err) {
+  const base = {
+    message: "Unknown error",
+    status: null,
+    code: null,
+    isNetworkError: false,
+    isTimeout: false,
+    cause: err,
+  };
+
+  if (!err) return base;
+
+  // axios error shape: err.response.{status,data}, err.request, err.code
+  if (err.isAxiosError || (err.response && typeof err.response.status === "number" && err.config)) {
+    return {
+      message: err.response?.data?.message || err.message || "Request failed",
+      status: err.response?.status ?? null,
+      code: err.code ?? null,
+      isNetworkError: !err.response && Boolean(err.request),
+      isTimeout: err.code === "ECONNABORTED" || /timeout/i.test(err.message || ""),
+      cause: err,
+    };
+  }
+
+  // fetch Response passed in directly (not thrown, but common enough to handle)
+  if (typeof err.status === "number" && typeof err.ok === "boolean") {
+    return {
+      message: err.statusText || `Request failed with status ${err.status}`,
+      status: err.status,
+      code: null,
+      isNetworkError: false,
+      isTimeout: false,
+      cause: err,
+    };
+  }
+
+  // our own TimeoutError, or DOMException from AbortController
+  if (err.name === "AbortError" || err.name === "TimeoutError" || err.code === "ETIMEDOUT") {
+    return {
+      message: err.message || "Request timed out",
+      status: null,
+      code: "ETIMEDOUT",
+      isNetworkError: false,
+      isTimeout: true,
+      cause: err,
+    };
+  }
+
+  // node http/https / undici network-level failures
+  if (err.code && /^E[A-Z]+$/.test(err.code)) {
+    return {
+      message: err.message || `Network error (${err.code})`,
+      status: null,
+      code: err.code,
+      isNetworkError: true,
+      isTimeout: false,
+      cause: err,
+    };
+  }
+
+  return {
+    message: err.message || String(err),
+    status: err.status ?? err.statusCode ?? null,
+    code: err.code ?? null,
+    isNetworkError: false,
+    isTimeout: false,
+    cause: err,
+  };
+}
+
+module.exports = { normalizeError };

package/src/parseJsonSafe.js

@@ -0,0 +1,26 @@
+/**
+ * Parses a fetch Response (or raw string) as JSON without throwing.
+ * Returns { data, error } — exactly one is non-null.
+ *
+ * @param {Response | string} input
+ */
+async function parseJsonSafe(input) {
+  let text;
+  try {
+    text = typeof input === "string" ? input : await input.text();
+  } catch (err) {
+    return { data: null, error: err };
+  }
+
+  if (!text) {
+    return { data: null, error: null };
+  }
+
+  try {
+    return { data: JSON.parse(text), error: null };
+  } catch (err) {
+    return { data: null, error: err };
+  }
+}
+
+module.exports = { parseJsonSafe };

package/src/retryAfterAware.js

@@ -0,0 +1,90 @@
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Parses a Retry-After header value into milliseconds. Per HTTP spec it's
+ * either an integer number of seconds, or an HTTP-date.
+ */
+function parseRetryAfter(headerValue) {
+  if (!headerValue) return null;
+
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds)) {
+    return Math.max(0, seconds * 1000);
+  }
+
+  const dateMs = Date.parse(headerValue);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+
+  return null;
+}
+
+/**
+ * Reads a wait time from common rate-limit headers, trying Retry-After first,
+ * then falling back to X-RateLimit-Reset (epoch seconds or ms) if present.
+ */
+function getWaitMsFromHeaders(headers) {
+  if (!headers || typeof headers.get !== "function") return null;
+
+  const retryAfter = parseRetryAfter(headers.get("retry-after"));
+  if (retryAfter !== null) return retryAfter;
+
+  const resetHeader = headers.get("x-ratelimit-reset") || headers.get("x-rate-limit-reset");
+  if (resetHeader) {
+    const resetValue = Number(resetHeader);
+    if (!Number.isNaN(resetValue)) {
+      // Could be epoch seconds or epoch ms — treat values below a
+      // year-2100-in-seconds threshold as seconds.
+      const resetMs = resetValue > 4102444800 ? resetValue : resetValue * 1000;
+      return Math.max(0, resetMs - Date.now());
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Retries a fetch-like call, honoring Retry-After / X-RateLimit-Reset
+ * headers on 429/503 responses instead of blind exponential backoff — most
+ * generic retry libraries treat rate-limit responses like any other failure
+ * and ignore the header the server is explicitly giving you.
+ *
+ * `fn` should return a fetch Response (or anything with `.status` and
+ * `.headers.get()`).
+ *
+ * @param {() => Promise<Response>} fn
+ * @param {object} [opts]
+ * @param {number} [opts.retries=3]
+ * @param {number[]} [opts.retryStatusCodes=[429, 503]]
+ * @param {number} [opts.fallbackDelayMs=1000] - used when no usable header is present
+ * @param {number} [opts.maxDelayMs=60000]
+ * @param {(status: number, waitMs: number, attempt: number) => void} [opts.onRetry]
+ */
+async function retryAfterAware(fn, opts = {}) {
+  const {
+    retries = 3,
+    retryStatusCodes = [429, 503],
+    fallbackDelayMs = 1000,
+    maxDelayMs = 60000,
+    onRetry,
+  } = opts;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const response = await fn(attempt);
+
+    if (!retryStatusCodes.includes(response.status) || attempt === retries) {
+      return response;
+    }
+
+    const headerWaitMs = getWaitMsFromHeaders(response.headers);
+    const waitMs = Math.min(headerWaitMs ?? fallbackDelayMs * 2 ** attempt, maxDelayMs);
+
+    if (onRetry) onRetry(response.status, waitMs, attempt);
+    await delay(waitMs);
+  }
+}
+
+module.exports = { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders };

package/src/withProgress.js

@@ -0,0 +1,57 @@
+/**
+ * Reads a fetch Response body while reporting progress, and returns the
+ * fully collected bytes as a Uint8Array. Works for any streamed response,
+ * not just file downloads — same shape whether it's a media file, a large
+ * JSON payload, or anything else worth showing progress for.
+ *
+ * If the server doesn't send Content-Length, `total` will be null in the
+ * progress callback — the loaded count is still accurate.
+ *
+ * @param {Response} response
+ * @param {(progress: { loaded: number, total: number | null, percent: number | null }) => void} onProgress
+ * @returns {Promise<Uint8Array>}
+ */
+async function withProgress(response, onProgress) {
+  if (!response.body || typeof response.body.getReader !== "function") {
+    // No streaming support available — fall back to a single-shot read,
+    // still reporting one final progress event so callers don't need a branch.
+    const buf = new Uint8Array(await response.arrayBuffer());
+    if (onProgress) {
+      onProgress({ loaded: buf.byteLength, total: buf.byteLength, percent: 100 });
+    }
+    return buf;
+  }
+
+  const contentLength = response.headers?.get?.("content-length");
+  const total = contentLength ? Number(contentLength) : null;
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let loaded = 0;
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    chunks.push(value);
+    loaded += value.byteLength;
+
+    if (onProgress) {
+      onProgress({
+        loaded,
+        total,
+        percent: total ? Math.round((loaded / total) * 100) : null,
+      });
+    }
+  }
+
+  const result = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+module.exports = { withProgress };

package/src/withRetry.js

@@ -0,0 +1,52 @@
+function defaultShouldRetry(err) {
+  // Retry network-level failures by default. HTTP status handling is the
+  // caller's job (they know what "failure" means for their response shape) —
+  // see retryAfterAware.js for a version that understands status codes.
+  return Boolean(err) && err.name !== "AbortError";
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retries an async function with exponential backoff + jitter.
+ *
+ * @param {() => Promise<any>} fn
+ * @param {object} [opts]
+ * @param {number} [opts.retries=3] - max retry attempts after the first try
+ * @param {number} [opts.baseDelayMs=300] - initial delay
+ * @param {number} [opts.maxDelayMs=10000] - delay ceiling
+ * @param {(err: any, attempt: number) => boolean} [opts.shouldRetry]
+ * @param {(err: any, attempt: number, delayMs: number) => void} [opts.onRetry]
+ */
+async function withRetry(fn, opts = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 300,
+    maxDelayMs = 10000,
+    shouldRetry = defaultShouldRetry,
+    onRetry,
+  } = opts;
+
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastErr = err;
+      const isLastAttempt = attempt === retries;
+      if (isLastAttempt || !shouldRetry(err, attempt)) {
+        throw err;
+      }
+      const exponential = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+      const jitter = Math.random() * exponential * 0.2;
+      const waitMs = Math.round(exponential + jitter);
+      if (onRetry) onRetry(err, attempt, waitMs);
+      await delay(waitMs);
+    }
+  }
+  throw lastErr;
+}
+
+module.exports = { withRetry };

package/src/withTimeout.js

@@ -0,0 +1,41 @@
+class TimeoutError extends Error {
+  constructor(ms) {
+    super(`Timed out after ${ms}ms`);
+    this.name = "TimeoutError";
+    this.code = "ETIMEDOUT";
+  }
+}
+
+/**
+ * Races an async function against a timeout. If `fn` accepts an AbortSignal
+ * as its argument, it's passed one so the underlying request can actually be
+ * cancelled (not just abandoned) — e.g. `withTimeout(signal => fetch(url, { signal }), 5000)`.
+ *
+ * @param {(signal: AbortSignal) => Promise<any>} fn
+ * @param {number} ms
+ */
+async function withTimeout(fn, ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+
+  const timeoutPromise = new Promise((_, reject) => {
+    controller.signal.addEventListener("abort", () => reject(new TimeoutError(ms)));
+  });
+
+  try {
+    return await Promise.race([fn(controller.signal), timeoutPromise]);
+  } catch (err) {
+    // If our timeout is what triggered the abort, always surface TimeoutError —
+    // regardless of whether fn's own rejection or our timeout promise "won"
+    // the race (that's a listener-registration-order detail callers shouldn't
+    // have to think about).
+    if (controller.signal.aborted) {
+      throw new TimeoutError(ms);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = { withTimeout, TimeoutError };

package/types/index.d.ts

@@ -0,0 +1,63 @@
+export interface RetryOptions {
+  retries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+  onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+}
+
+export function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryOptions): Promise<T>;
+
+export class TimeoutError extends Error {
+  code: "ETIMEDOUT";
+  constructor(ms: number);
+}
+
+export function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, ms: number): Promise<T>;
+
+export interface NormalizedError {
+  message: string;
+  status: number | null;
+  code: string | null;
+  isNetworkError: boolean;
+  isTimeout: boolean;
+  cause: unknown;
+}
+
+export function normalizeError(err: unknown): NormalizedError;
+
+export interface JsonSafeResult<T = unknown> {
+  data: T | null;
+  error: Error | null;
+}
+
+export function parseJsonSafe<T = unknown>(input: Response | string): Promise<JsonSafeResult<T>>;
+
+export function buildQuery(params: Record<string, unknown> | null | undefined): string;
+
+export interface RetryAfterAwareOptions {
+  retries?: number;
+  retryStatusCodes?: number[];
+  fallbackDelayMs?: number;
+  maxDelayMs?: number;
+  onRetry?: (status: number, waitMs: number, attempt: number) => void;
+}
+
+export function retryAfterAware(
+  fn: (attempt: number) => Promise<Response>,
+  opts?: RetryAfterAwareOptions
+): Promise<Response>;
+
+export function parseRetryAfter(headerValue: string | null): number | null;
+export function getWaitMsFromHeaders(headers: Headers | null | undefined): number | null;
+
+export interface DownloadProgress {
+  loaded: number;
+  total: number | null;
+  percent: number | null;
+}
+
+export function withProgress(
+  response: Response,
+  onProgress?: (progress: DownloadProgress) => void
+): Promise<Uint8Array>;