@boy-offi9-inc/reqkit 0.6.0 → 0.7.1

package/src/createFetch.js

@@ -9,11 +9,13 @@ const { createRateLimiter } = require("./createRateLimiter");
 const { createCircuitBreaker } = require("./createCircuitBreaker");
 const { createMemoryCache } = require("./createMemoryCache");
 const { cacheKey, snapshotResponse, entryToResponse } = require("./_cache");
-const { discardBody } = require("./_http");
+const { discardBody, getOrigin } = require("./_http");
 
 const DEFAULT_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504];
 // Safe to repeat without side effects. POST/PATCH are deliberately absent.
 const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"];
+// Default headers that carry credentials. They're only sent to trusted origins.
+const SENSITIVE_HEADERS = ["authorization", "proxy-authorization", "cookie", "x-api-key", "x-auth-token"];
 
 function isAbsoluteUrl(url) {
   return /^[a-z][a-z0-9+.-]*:/i.test(url);
@@ -47,11 +49,19 @@ function isStreamBody(body) {
 }
 
 function originOf(url) {
-  try {
-    return new URL(url).origin;
-  } catch {
-    return url;
+  return getOrigin(url) || url;
+}
+
+// One in-flight token refresh per `auth` config object, so concurrent 401s —
+// even across extend() children — trigger exactly one refresh.
+const refreshStates = new WeakMap();
+function refreshStateFor(auth) {
+  let state = refreshStates.get(auth);
+  if (!state) {
+    state = { inflight: null };
+    refreshStates.set(auth, state);
   }
+  return state;
 }
 
 function mergeDefaults(base, extra) {
@@ -87,6 +97,11 @@ function mergeDefaults(base, extra) {
  *  - `cache`: in-memory GET cache with TTL, stale-while-revalidate and
  *    ETag / Last-Modified revalidation (304s)
  *  - concurrent GET de-duplication (withDedupe)
+ *  - `auth`: attach a token, and on a 401 refresh it ONCE (shared by all
+ *    concurrent requests) and replay the request
+ *  - credential safety: default credentials (`auth`, and default headers like
+ *    Authorization/Cookie/X-API-Key) are only sent to `baseUrl`'s origin and
+ *    `trustedOrigins` — pass an absolute URL to another host and they stay home
  *  - `HTTPError` on non-2xx (turn off with `throwHttpErrors: false`)
  *  - `onRequest` / `onResponse` hooks
  *
@@ -104,6 +119,14 @@ function mergeDefaults(base, extra) {
  *   a per-origin breaker, a createCircuitBreaker() instance, or `(url) => breaker`
  * @param {boolean | object} [defaults.cache] - `{ ttl, staleWhileRevalidate,
  *   maxEntries, maxBodyBytes, store, onEvent }`; `true` = 60s TTL
+ * @param {object} [defaults.auth] - `{ getToken, refresh, header?, scheme?, shouldRefresh? }`.
+ *   `getToken()` supplies the current token (sync or async); on a 401 (or
+ *   whatever `shouldRefresh(response)` says) `refresh({ token, response })` is
+ *   called once for all concurrent callers and the request is replayed with the
+ *   new token. `header` defaults to "authorization", `scheme` to "Bearer" ("" for none).
+ * @param {string[]} [defaults.trustedOrigins] - extra origins ("https://cdn.example.com") that may
+ *   receive the default credentials, besides `baseUrl`'s. With neither `baseUrl` nor
+ *   `trustedOrigins` set there is nothing to compare against and credentials go everywhere.
  * @param {boolean} [defaults.dedupe=false] - merge identical concurrent GET/HEAD calls
  * @param {boolean} [defaults.throwHttpErrors=true]
  * @param {typeof fetch} [defaults.fetch=globalThis.fetch]
@@ -120,6 +143,8 @@ function createFetch(defaults = {}) {
     rateLimit,
     circuitBreaker,
     cache,
+    auth,
+    trustedOrigins,
     dedupe = false,
     throwHttpErrors: defaultThrow = true,
     fetch: customFetch,
@@ -129,6 +154,18 @@ function createFetch(defaults = {}) {
 
   const doFetch = (...args) => (customFetch || globalThis.fetch)(...args);
 
+  // Origins allowed to receive default credentials. Empty = no baseUrl to compare against = unrestricted.
+  const trusted = new Set();
+  for (const o of [baseUrl, ...(trustedOrigins || [])]) {
+    const origin = o && getOrigin(o);
+    if (origin) trusted.add(origin);
+  }
+  const isTrustedTarget = (url) => {
+    if (trusted.size === 0 || !isAbsoluteUrl(url)) return true; // relative URLs resolve against our own base
+    const origin = getOrigin(url);
+    return origin !== null && trusted.has(origin);
+  };
+
   // --- stateful pieces, built once so `extend()` children share them -------
   const limiter = !rateLimit
     ? null
@@ -190,6 +227,27 @@ function createFetch(defaults = {}) {
     pendingStores.set(key, p);
   }
 
+  // Returns a token newer than `usedToken`, refreshing at most once no matter
+  // how many requests were rejected at the same time. If someone else already
+  // refreshed (the current token isn't the one we used), just use that.
+  async function obtainFreshToken(authCfg, tokenUsed, response) {
+    const current = await authCfg.getToken();
+    if (current && current !== tokenUsed) return current;
+
+    const state = refreshStateFor(authCfg);
+    if (!state.inflight) {
+      state.inflight = (async () => {
+        try {
+          const out = await authCfg.refresh({ token: tokenUsed, response });
+          return typeof out === "string" && out ? out : await authCfg.getToken();
+        } finally {
+          state.inflight = null;
+        }
+      })();
+    }
+    return state.inflight;
+  }
+
   async function request(input, init = {}) {
     const {
       query,
@@ -204,7 +262,18 @@ function createFetch(defaults = {}) {
     } = init;
 
     const method = String(fetchInit.method || "GET").toUpperCase();
-    const headers = mergeHeaders(await resolveHeaders(defaultHeaders), new Headers(initHeaders || undefined));
+    const url = joinUrl(baseUrl, input, query);
+    const credentialsAllowed = isTrustedTarget(url);
+
+    const defaultHeaderSet = await resolveHeaders(defaultHeaders);
+    if (!credentialsAllowed) {
+      // An absolute URL to some other host: don't hand it our default credentials.
+      for (const name of [...SENSITIVE_HEADERS, ...(auth && auth.header ? [String(auth.header).toLowerCase()] : [])]) {
+        defaultHeaderSet.delete(name);
+      }
+    }
+    // Headers the caller passes for *this* call are deliberate, so they always go through.
+    const headers = mergeHeaders(defaultHeaderSet, new Headers(initHeaders || undefined));
 
     let body = fetchInit.body;
     if (json !== undefined) {
@@ -212,11 +281,20 @@ function createFetch(defaults = {}) {
       if (!headers.has("content-type")) headers.set("content-type", "application/json");
     }
 
-    const ctx = { url: joinUrl(baseUrl, input, query), init: { ...fetchInit, method, headers, body } };
+    const ctx = { url, init: { ...fetchInit, method, headers, body } };
     if (onRequest) await onRequest(ctx);
     const finalHeaders = ctx.init.headers instanceof Headers ? ctx.init.headers : new Headers(ctx.init.headers);
     const finalMethod = String(ctx.init.method || method).toUpperCase();
 
+    // --- auth: attach the current token (unless the caller set the header) ----
+    const authHeader = auth ? String(auth.header || "authorization").toLowerCase() : null;
+    const formatToken = (token) => (auth.scheme === "" ? String(token) : `${auth.scheme === undefined ? "Bearer" : auth.scheme} ${token}`);
+    let usedToken = null;
+    if (auth && credentialsAllowed && !finalHeaders.has(authHeader)) {
+      usedToken = (await auth.getToken()) || null;
+      if (usedToken) finalHeaders.set(authHeader, formatToken(usedToken));
+    }
+
     // --- retry policy ------------------------------------------------------
     const retryCfg = retryOpt === false || defaultRetry === false ? false : { ...defaultRetry, ...retryOpt };
     const methods = (retryCfg && retryCfg.methods) || DEFAULT_RETRY_METHODS;
@@ -292,7 +370,7 @@ function createFetch(defaults = {}) {
       !ctx.init.body &&
       cacheMode !== false &&
       cacheMode !== "no-store";
-    const key = useCache ? cacheKey(finalMethod, ctx.url, finalHeaders) : null;
+    let key = useCache ? cacheKey(finalMethod, ctx.url, finalHeaders) : null;
     let entry = null;
 
     const finish = async (response) => {
@@ -353,6 +431,24 @@ function createFetch(defaults = {}) {
       throw err;
     }
 
+    // --- auth: a rejected token is refreshed once, then the request replays ----
+    const needsRefresh = auth && (auth.shouldRefresh ? auth.shouldRefresh(response) : response.status === 401);
+    if (usedToken && needsRefresh && !isStreamBody(ctx.init.body)) {
+      const fresh = await obtainFreshToken(auth, usedToken, response);
+      if (fresh) {
+        await discardBody(response);
+        finalHeaders.set(authHeader, formatToken(fresh));
+        entry = null; // belongs to the old token's cache key
+        if (useCache) key = cacheKey(finalMethod, ctx.url, finalHeaders);
+        try {
+          response = await network(finalHeaders, signal);
+        } catch (err) {
+          if (err instanceof RetryAbortedError && signal && signal.aborted) throw signal.reason ?? err;
+          throw err;
+        }
+      }
+    }
+
     if (useCache) {
       if (response.status === 304 && entry) {
         entry.storedAt = Date.now();
@@ -369,6 +465,9 @@ function createFetch(defaults = {}) {
     return finish(response);
   }
 
+  /** The `baseUrl` this instance was created with (paginateLinks uses it to stay on-origin). */
+  request.baseUrl = baseUrl;
+
   /** Like `request`, but resolves to the parsed JSON body (null for an empty body). */
   request.json = async (input, init) => {
     const response = await request(input, init);

package/src/index.js

@@ -15,6 +15,7 @@ const { createMockFetch } = require("./createMockFetch");
 const { downloadResumable } = require("./downloadResumable");
 const { readLines, readNDJSON, readSSE } = require("./streams");
 const { streamSSE } = require("./streamSSE");
+const { paginate, paginatePages, paginateLinks, parseLinkHeader } = require("./paginate");
 
 module.exports = {
   withRetry,
@@ -44,4 +45,8 @@ module.exports = {
   readNDJSON,
   readSSE,
   streamSSE,
+  paginate,
+  paginatePages,
+  paginateLinks,
+  parseLinkHeader,
 };

package/src/index.mjs

@@ -28,6 +28,10 @@ export const {
   readNDJSON,
   readSSE,
   streamSSE,
+  paginate,
+  paginatePages,
+  paginateLinks,
+  parseLinkHeader,
 } = reqkit;
 
 export default reqkit;

package/src/paginate.js

@@ -0,0 +1,195 @@
+const { HTTPError } = require("./HTTPError");
+const { getOrigin } = require("./_http");
+
+const MAX_LINK_HEADER_LENGTH = 64 * 1024;
+
+/**
+ * Parses an RFC 8288 `Link` header (GitHub, GitLab, WordPress... use it for
+ * pagination) into `{ rel: url }`. Pass `base` to resolve relative URLs.
+ *
+ * ```js
+ * parseLinkHeader('<https://api.x/items?page=2>; rel="next", <https://api.x/items?page=9>; rel="last"');
+ * // { next: "https://api.x/items?page=2", last: "https://api.x/items?page=9" }
+ * ```
+ *
+ * A link with several rels (`rel="next last"`) is listed under each; the first
+ * link wins when a rel appears twice. Commas inside `<...>` are handled. Input
+ * is treated as untrusted: headers over 64 KB are ignored and parsing is linear-time.
+ *
+ * @param {string | null | undefined} header
+ * @param {string} [base]
+ * @returns {Record<string, string>}
+ */
+function parseLinkHeader(header, base) {
+  const links = {};
+  // Link headers are server-controlled; real ones are a few hundred bytes (HTTP stacks cap headers at ~16 KB).
+  if (!header || header.length > MAX_LINK_HEADER_LENGTH) return links;
+
+  // <url> followed by any number of `; name` / `; name=token` / `; name="quoted, value"` params
+  const linkRe = /<([^<>]*)>((?:\s*;\s*[^=;,<\s]+(?:\s*=\s*(?:"[^"]*"|[^;,<\s]*))?)*)/g;
+  let match;
+  while ((match = linkRe.exec(header)) !== null) {
+    const rel = /;\s*rel\s*=\s*(?:"([^"]*)"|([^\s;,]+))/i.exec(match[2]);
+    if (!rel) continue;
+
+    let url = match[1].trim();
+    if (base) {
+      try {
+        url = new URL(url, base).href;
+      } catch {
+        // leave it as written
+      }
+    }
+    for (const name of (rel[1] ?? rel[2]).toLowerCase().split(/\s+/).filter(Boolean)) {
+      if (!(name in links)) links[name] = url;
+    }
+  }
+  return links;
+}
+
+function stuckError(message) {
+  return Object.assign(new Error(message), { code: "PAGINATE_STUCK" });
+}
+
+/**
+ * Walks a paginated API page by page. You write `fetchPage(cursor, ctx)` —
+ * it returns `{ items, next }`, where `next` is whatever identifies the next
+ * page (a cursor token, an offset, a URL...) or `undefined`/`null` on the
+ * last page — and you get an async iterator of pages.
+ *
+ * ```js
+ * for await (const { items, index } of paginatePages(async (cursor) => {
+ *   const r = await api.json("/users", { query: { cursor, limit: 100 } });
+ *   return { items: r.data, next: r.next_cursor };
+ * })) { ... }
+ * ```
+ *
+ * A `next` that equals the cursor just used throws `code: "PAGINATE_STUCK"`
+ * instead of looping forever.
+ *
+ * @template T
+ * @param {(cursor: any, ctx: { index: number, signal?: AbortSignal }) => Promise<{ items: T[], next?: any }>} fetchPage
+ * @param {object} [opts]
+ * @param {any} [opts.start] - the cursor for the first page (default undefined)
+ * @param {number} [opts.maxPages=Infinity]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {AsyncGenerator<{ items: T[], index: number, cursor: any }>}
+ */
+async function* paginatePages(fetchPage, opts = {}) {
+  const { start, maxPages = Infinity, signal } = opts;
+  let cursor = start;
+  let index = 0;
+
+  for (;;) {
+    if (index >= maxPages) return;
+    signal?.throwIfAborted?.();
+
+    const result = await fetchPage(cursor, { index, signal });
+    if (!result || !Array.isArray(result.items)) {
+      throw new TypeError("paginate: fetchPage must return { items: array, next?: cursor }");
+    }
+    yield { items: result.items, index, cursor };
+
+    const next = result.next;
+    if (next === undefined || next === null) return;
+    if (next === cursor) {
+      throw stuckError("paginate: `next` equals the cursor just used, so the page didn't advance — stopping to avoid an infinite loop");
+    }
+    cursor = next;
+    index++;
+  }
+}
+
+/**
+ * Like `paginatePages`, but yields the items one by one. `maxItems` stops
+ * early (mid-page) — and since nothing is fetched until you ask for it,
+ * `break`-ing out of the loop never fetches a page you didn't need.
+ *
+ * ```js
+ * for await (const user of paginate(fetchUsersPage, { maxItems: 250 })) { ... }
+ * ```
+ *
+ * @template T
+ * @param {(cursor: any, ctx: { index: number, signal?: AbortSignal }) => Promise<{ items: T[], next?: any }>} fetchPage
+ * @param {object} [opts] - same as paginatePages, plus `maxItems`
+ * @param {number} [opts.maxItems=Infinity]
+ * @returns {AsyncGenerator<T>}
+ */
+async function* paginate(fetchPage, opts = {}) {
+  const { maxItems = Infinity } = opts;
+  if (maxItems <= 0) return;
+
+  let count = 0;
+  for await (const page of paginatePages(fetchPage, opts)) {
+    for (const item of page.items) {
+      yield item;
+      if (++count >= maxItems) return;
+    }
+  }
+}
+
+function defaultGetItems(data) {
+  if (Array.isArray(data)) return data;
+  for (const key of ["items", "data", "results", "records"]) {
+    if (data && Array.isArray(data[key])) return data[key];
+  }
+  throw new TypeError("paginateLinks: couldn't find the items array in the response — pass `getItems(data)`");
+}
+
+/**
+ * Follows `Link: <...>; rel="next"` headers (GitHub-style) and yields the
+ * items of every page. `request` is anything fetch-like — a `createFetch`
+ * instance or plain `fetch` (a non-2xx response throws `HTTPError`).
+ *
+ * ```js
+ * for await (const repo of paginateLinks(api, "/orgs/acme/repos?per_page=100")) { ... }
+ * ```
+ *
+ * @param {(url: string, init?: object) => Promise<Response>} request
+ * @param {string} url - the first page
+ * @param {object} [opts]
+ * @param {(data: any, response: Response) => any[]} [opts.getItems] - default: the body if it's an array, else its `items` / `data` / `results` / `records`
+ * @param {number} [opts.maxPages=Infinity]
+ * @param {number} [opts.maxItems=Infinity]
+ * @param {AbortSignal} [opts.signal]
+ * @param {object} [opts.init] - extra options passed to every `request`
+ * @param {string[]} [opts.origins] - origins a `Link` may point to. Default: the origin of `url`
+ *   (or of the `createFetch` instance's `baseUrl`). A `Link` to anywhere else throws
+ *   `code: "PAGINATE_CROSS_ORIGIN"` — a server could otherwise steer your requests (and any
+ *   credentials in `init`) to a third party. The check is skipped only when no origin can be determined.
+ */
+async function* paginateLinks(request, url, opts = {}) {
+  const { getItems = defaultGetItems, init = {}, signal } = opts;
+
+  const allowed = new Set();
+  if (opts.origins) {
+    for (const o of opts.origins) {
+      const origin = getOrigin(o);
+      if (origin) allowed.add(origin);
+    }
+  } else {
+    const origin = getOrigin(url) || getOrigin(request && request.baseUrl) || getOrigin(globalThis.location && globalThis.location.href);
+    if (origin) allowed.add(origin);
+  }
+
+  async function fetchPage(pageUrl) {
+    const res = await request(pageUrl, { ...init, signal });
+    if (!res.ok) throw new HTTPError(res, { method: init.method || "GET", url: pageUrl });
+    const items = getItems(await res.json(), res);
+    const next = parseLinkHeader(res.headers.get("link"), pageUrl).next;
+    if (next && allowed.size > 0) {
+      const nextOrigin = getOrigin(next);
+      if (nextOrigin !== null && !allowed.has(nextOrigin)) {
+        throw Object.assign(
+          new Error(`paginateLinks: refusing to follow a Link to another origin (${nextOrigin}). Pass { origins: [...] } if that's intended.`),
+          { code: "PAGINATE_CROSS_ORIGIN" }
+        );
+      }
+    }
+    return { items, next };
+  }
+
+  yield* paginate(fetchPage, { ...opts, start: url });
+}
+
+module.exports = { paginate, paginatePages, paginateLinks, parseLinkHeader };

package/src/streams.js

@@ -34,46 +34,83 @@ async function* chunks(source, signal) {
   }
 }
 
+const DEFAULT_MAX_LINE_LENGTH = 16 * 1024 * 1024;
+
+function lineTooLong(limit) {
+  return Object.assign(
+    new Error(`reqkit streams: a line exceeded ${limit} characters without a line break (raise \`maxLineLength\` if that's expected)`),
+    { code: "LINE_TOO_LONG" }
+  );
+}
+
 /**
  * Async-iterates the text lines of a streamed body. Handles \n, \r\n and \r,
  * multi-byte characters split across chunks, and a leading BOM.
  *
+ * Runs in linear time and bounded memory: only newly arrived text is scanned,
+ * and a "line" longer than `maxLineLength` characters (default 16 Mi — a
+ * server that never sends a newline) throws `code: "LINE_TOO_LONG"` instead
+ * of buffering forever.
+ *
  * ```js
  * for await (const line of readLines(response)) console.log(line);
  * ```
  *
  * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
- * @param {{ signal?: AbortSignal }} [opts]
+ * @param {{ signal?: AbortSignal, maxLineLength?: number }} [opts]
  * @returns {AsyncGenerator<string>}
  */
 async function* readLines(source, opts = {}) {
+  const { maxLineLength = DEFAULT_MAX_LINE_LENGTH } = opts;
   const decoder = new TextDecoder("utf-8");
-  let buffer = "";
+  const terminator = /[\r\n]/g;
+
+  let parts = []; // pieces of the line being assembled (no terminators in them)
+  let partsLength = 0;
+  let skipLF = false; // the previous line ended with "\r", so a leading "\n" belongs to it
   let first = true;
 
   for await (const chunk of chunks(source, opts.signal)) {
-    buffer += decoder.decode(chunk, { stream: true });
-    if (first && buffer.length > 0) {
-      buffer = buffer.replace(/^\uFEFF/, "");
+    let text = decoder.decode(chunk, { stream: true });
+    if (first && text.length > 0) {
+      text = text.replace(/^\uFEFF/, "");
       first = false;
     }
 
-    let pos = 0;
-    for (;;) {
-      const rest = buffer.slice(pos);
-      const i = rest.search(/\r\n|\n|\r/);
-      if (i === -1) break;
-      // A trailing "\r" might be the first half of "\r\n" — wait for more data.
-      if (rest[i] === "\r" && i === rest.length - 1) break;
-      yield rest.slice(0, i);
-      pos += i + (rest.startsWith("\r\n", i) ? 2 : 1);
+    let start = 0;
+    terminator.lastIndex = 0;
+    let match;
+    while ((match = terminator.exec(text)) !== null) {
+      const ch = match[0];
+      if (ch === "\n" && skipLF && match.index === start) {
+        skipLF = false; // the "\n" of a "\r\n" pair — swallow it
+        start = match.index + 1;
+        continue;
+      }
+      skipLF = false;
+
+      const piece = text.slice(start, match.index);
+      if (partsLength + piece.length > maxLineLength) throw lineTooLong(maxLineLength);
+      const line = parts.length > 0 ? parts.join("") + piece : piece;
+      parts = [];
+      partsLength = 0;
+      yield line;
+
+      start = match.index + 1;
+      skipLF = ch === "\r";
+    }
+
+    if (start < text.length) {
+      const rest = text.slice(start);
+      partsLength += rest.length;
+      if (partsLength > maxLineLength) throw lineTooLong(maxLineLength);
+      parts.push(rest);
+      skipLF = false;
     }
-    buffer = buffer.slice(pos);
   }
 
-  buffer += decoder.decode();
-  if (buffer.endsWith("\r")) buffer = buffer.slice(0, -1);
-  if (buffer.length > 0) yield buffer;
+  const tail = parts.join("") + decoder.decode();
+  if (tail.length > 0) yield tail;
 }
 
 /**
@@ -113,11 +150,13 @@ async function* readNDJSON(source, opts = {}) {
  * ```
  *
  * @param {Response | ReadableStream | AsyncIterable<Uint8Array>} source
- * @param {{ signal?: AbortSignal }} [opts]
+ * @param {{ signal?: AbortSignal, maxLineLength?: number }} [opts] - `maxLineLength` also caps the data of a single event
  */
 async function* readSSE(source, opts = {}) {
+  const maxEventLength = opts.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
   let event = "";
   let data = [];
+  let dataLength = 0;
   let retry;
   let lastId = "";
 
@@ -126,6 +165,7 @@ async function* readSSE(source, opts = {}) {
       if (data.length > 0) yield { event: event || "message", data: data.join("\n"), id: lastId, retry };
       event = "";
       data = [];
+      dataLength = 0;
       retry = undefined;
       continue;
     }
@@ -137,7 +177,11 @@ async function* readSSE(source, opts = {}) {
     if (value.startsWith(" ")) value = value.slice(1);
 
     if (field === "event") event = value;
-    else if (field === "data") data.push(value);
+    else if (field === "data") {
+      dataLength += value.length + 1;
+      if (dataLength > maxEventLength) throw lineTooLong(maxEventLength);
+      data.push(value);
+    }
     else if (field === "id") {
       if (!value.includes("\0")) lastId = value;
     } else if (field === "retry") {

package/types/index.d.ts

@@ -210,6 +210,15 @@ export interface CreateFetchDefaults {
   rateLimit?: boolean | RateLimiterOptions | RateLimiter;
   /** Options for a per-origin breaker, a shared breaker instance, or `(url) => breaker`. */
   circuitBreaker?: boolean | CircuitBreakerOptions | CircuitBreaker | ((url: string) => CircuitBreaker);
+  /**
+   * Extra origins ("https://cdn.example.com") that may receive the default credentials
+   * (`auth` and default Authorization/Cookie/X-API-Key headers), besides `baseUrl`'s.
+   * Absolute URLs to any other origin don't get them. With neither `baseUrl` nor
+   * `trustedOrigins` there's nothing to compare against and credentials go everywhere.
+   */
+  trustedOrigins?: string[];
+  /** Attach a token and, on a 401, refresh it once (shared by all concurrent requests) and replay. */
+  auth?: AuthOptions;
   /** In-memory GET cache with TTL, stale-while-revalidate and ETag/Last-Modified revalidation. `true` = 60s TTL. */
   cache?: boolean | CacheOptions;
   /** Merge identical concurrent GET/HEAD calls. Default false. */
@@ -235,6 +244,8 @@ export interface ReqkitRequestInit extends Omit<RequestInit, "headers" | "cache"
 
 export interface ReqkitFetch {
   (input: string, init?: ReqkitRequestInit): Promise<Response>;
+  /** The `baseUrl` this instance was created with. */
+  readonly baseUrl: string | undefined;
   /** Resolves to the parsed JSON body (null for an empty body). */
   json<T = unknown>(input: string, init?: ReqkitRequestInit): Promise<T>;
   /** New instance with these defaults merged over the current ones. */
@@ -390,6 +401,12 @@ export type StreamSource = Response | ReadableStream<Uint8Array> | AsyncIterable
 
 export interface StreamOptions {
   signal?: AbortSignal;
+  /**
+   * Longest line (or, for readSSE, one event's data) in characters before throwing
+   * `code: "LINE_TOO_LONG"` — protects against a server that never sends a newline.
+   * Default 16 Mi (16 * 1024 * 1024); pass Infinity to disable.
+   */
+  maxLineLength?: number;
 }
 
 export interface SSEEvent {
@@ -441,3 +458,81 @@ export interface StreamSSEOptions {
 
 /** Auto-reconnecting SSE: resumes with Last-Event-ID, honors `retry:` and Retry-After. */
 export function streamSSE(url: string, opts?: StreamSSEOptions): AsyncGenerator<SSEEvent, void, undefined>;
+
+export interface AuthOptions {
+  /** The current token (sync or async). Falsy = send no auth header. */
+  getToken(): string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Called ONCE when requests are rejected (401 by default), no matter how many
+   * are waiting. Return the new token, or update your store and return nothing
+   * (reqkit then calls getToken() again). Throwing rejects every waiting request.
+   */
+  refresh(ctx: { token: string; response: Response }): string | void | undefined | Promise<string | void | undefined>;
+  /** Default "authorization". */
+  header?: string;
+  /** Default "Bearer". Use "" to send the bare token (e.g. for an X-API-Key header). */
+  scheme?: string;
+  /** Default: `res.status === 401`. */
+  shouldRefresh?: (response: Response) => boolean;
+}
+
+export interface PageContext {
+  index: number;
+  signal?: AbortSignal;
+}
+
+export interface PageResult<T, C = any> {
+  items: T[];
+  /** Whatever identifies the next page (token, offset, URL...). undefined/null = last page. */
+  next?: C | null;
+}
+
+export interface Page<T, C = any> {
+  items: T[];
+  index: number;
+  /** The cursor this page was fetched with (undefined for the first, unless `start` was given). */
+  cursor: C | undefined;
+}
+
+export interface PaginateOptions<C = any> {
+  /** The cursor for the first page. */
+  start?: C;
+  maxPages?: number;
+  maxItems?: number;
+  signal?: AbortSignal;
+}
+
+export type FetchPage<T, C = any> = (cursor: C | undefined, ctx: PageContext) => Promise<PageResult<T, C>>;
+
+/** Yields every item, fetching pages lazily. */
+export function paginate<T, C = any>(fetchPage: FetchPage<T, C>, opts?: PaginateOptions<C>): AsyncGenerator<T, void, undefined>;
+/** Yields whole pages. */
+export function paginatePages<T, C = any>(
+  fetchPage: FetchPage<T, C>,
+  opts?: Omit<PaginateOptions<C>, "maxItems">
+): AsyncGenerator<Page<T, C>, void, undefined>;
+
+export interface PaginateLinksOptions<T = any> {
+  /** Default: the body if it's an array, else its `items` / `data` / `results` / `records`. */
+  getItems?: (data: any, response: Response) => T[];
+  maxPages?: number;
+  maxItems?: number;
+  signal?: AbortSignal;
+  /** Extra options passed to every request. */
+  init?: Record<string, any>;
+  /**
+   * Origins a `Link` may point to. Default: the origin of `url` (or of the createFetch
+   * instance's `baseUrl`). Any other origin throws `code: "PAGINATE_CROSS_ORIGIN"`.
+   */
+  origins?: string[];
+}
+
+/** Follows `Link: <...>; rel="next"` headers and yields the items of every page. */
+export function paginateLinks<T = any>(
+  request: (url: string, init?: any) => Promise<Response>,
+  url: string,
+  opts?: PaginateLinksOptions<T>
+): AsyncGenerator<T, void, undefined>;
+
+/** Parses an RFC 8288 Link header into `{ rel: url }`. Pass `base` to resolve relative URLs. */
+export function parseLinkHeader(header: string | null | undefined, base?: string): Record<string, string>;