name: openfetch description: Use when the user works with @hamdymohamedak/openfetch, openFetch, or a fetch-only HTTP client with interceptors, middleware, plugins (retry, timeout, hooks, debug), memory cache (TTL, stale-while-revalidate), fluent chaining (sugar), raw native Response, idempotency keys, or SSR/RSC-safe fetch in Node, browsers, Bun, Deno, or Workers. Use instead of guessing axios or XHR APIs.

openFetch agent skill

Library version this skill targets: v0.2.9 (@hamdymohamedak/openfetch). Prefer facts here and in quick reference over guessing other clients’ APIs.

Do not assume axios

• Transport is fetch only (no XHR). No upload progress bar via XHR.
• Package is ESM-only (import from "@hamdymohamedak/openfetch").
• Runtime: Node 18+ or any environment with fetch + AbortController.

Install & links

• npm: @hamdymohamedak/openfetch
• Source: https://github.com/openfetch-js/OpenFetch
• Human docs: https://openfetch-js.github.io/openfetch-docs/

Imports

Main entry (many symbols are also re-exported here; bundlers can still tree-shake with "sideEffects": false):

import openFetch, {
  create,
  createClient,
  createRetryMiddleware,
  createCacheMiddleware,
  MemoryCacheStore,
  appendCacheKeyVaryHeaders,
  OpenFetchError,
  isOpenFetchError,
  assertSafeHttpUrl,
  generateIdempotencyKey,
  hasIdempotencyKeyHeader,
  ensureIdempotencyKeyHeader,
  maskHeaderValues,
  cloneResponse,
  redactSensitiveUrlQuery,
  // Same as @hamdymohamedak/openfetch/plugins:
  retry,
  timeout,
  hooks,
  debug,
  strictFetch,
  // Same as @hamdymohamedak/openfetch/sugar:
  createFluentClient,
} from "@hamdymohamedak/openfetch";

Subpaths (explicit splits for tooling that respects package.json exports):

import { retry, timeout, hooks, debug, strictFetch } from "@hamdymohamedak/openfetch/plugins";
import { createFluentClient } from "@hamdymohamedak/openfetch/sugar";

• Default export openFetch = createClient() with no initial defaults.
• create is an alias of createClient.

Client & responses

const api = createClient({
  baseURL: "https://api.example.com",
  headers: { Authorization: "Bearer …" },
  timeout: 10_000,
  unwrapResponse: true,
  assertSafeUrl: true, // runs assertSafeHttpUrl on the resolved URL before fetch
  middlewares: [createRetryMiddleware()],
});

• unwrapResponse: false (default): helpers return OpenFetchResponse<T> → { data, status, statusText, headers, config }.
• unwrapResponse: true: helpers return T (body only).
• rawResponse: true: data is the native Response with an unread body; adapter skips parse + transformResponse. Request interceptors already ran; response interceptors still run (data is that Response). Middleware that assumes parsed JSON in ctx.response.data will not see transforms until you read the body. Use cloneResponse from the package if two independent reads are needed.

Merged config must resolve a url (absolute, or baseURL + relative path). Otherwise the client throws an Error whose message includes openfetch: `url` is required.

HTTP helpers

Plugins (retry, timeout, hooks, debug, strictFetch)

Shorthand factories that return middleware; register with client.use(fn) (same as createRetryMiddleware, with small DX differences).

const client = createClient({ baseURL: "https://api.example.com" })
  .use(retry({ attempts: 3, baseDelayMs: 400 })) // register retry before timeout
  .use(timeout(12_000))
  .use(debug({ includeRequestHeaders: true, maskStrategy: "partial" }));

• retry(options) — attempts aliases maxAttempts; supports timeoutTotalMs, enforceTotalTimeout, timeoutPerAttemptMs, retryNonIdempotentMethods, etc. (see retry section).
• timeout(ms) — request timeout middleware.
• hooks({ onRequest, onResponse, onError }) — lifecycle logging/tracing; for transforms prefer interceptors.
• debug({ … }) — structured logs; masked headers via maskStrategy (full | partial | hash); optional masked request headers; URL query redaction aligned with redactSensitiveUrlQuery.
• strictFetch() — if redirect is unset, sets redirect: 'error' so redirects are not followed silently.

Order: register retry before timeout so the timeout middleware wraps attempts the way the docs describe.

Fluent client (createFluentClient)

Callable URL + method chaining (Wretch-style): fluent("/path").get().json(), fluent("/x").post(body).send().

• Terminals (.json(), .text(), .blob(), .arrayBuffer(), .stream(), .send(), .raw()) each start one HTTP request unless .memo() is used on that chain.
• .memo() — one round-trip; body buffered once as ArrayBuffer; multiple terminals reuse it (this is not HTTP cache).
• .raw() — same semantics as rawResponse: true.

Interceptors vs middleware

• Interceptors: client.interceptors.request.use / response.use — transform config or response; request stack is LIFO, response FIFO.
• Middleware: client.use(fn) — async (ctx, next) => … around the real fetch; use for retry, cache, logging. Order matters (e.g. cache vs retry).

Retry (createRetryMiddleware / retry())

Exponential backoff, jitter, configurable HTTP statuses and network/parse retries.

• By default, retries for network / parse / retryable HTTP errors apply only to GET, HEAD, OPTIONS, TRACE — not POST/PUT/PATCH/DELETE (avoid duplicate side effects).
• Opt in for mutating methods: retry: { retryNonIdempotentMethods: true } on the client or per request.
• When retryNonIdempotentMethods is true, maxAttempts > 1, method is POST, and no idempotency header exists, middleware adds a stable Idempotency-Key (unless autoIdempotencyKey: false). Use generateIdempotencyKey, hasIdempotencyKeyHeader, ensureIdempotencyKeyHeader for custom flows.
• timeoutTotalMs — monotonic budget for the whole retry sequence (including backoff); on expiry: OpenFetchError code ERR_RETRY_TIMEOUT (not retried). enforceTotalTimeout (default true) merges a deadline into signal per attempt.
• timeoutPerAttemptMs — overrides per-attempt request.timeout inside the retry middleware.
• ERR_CANCELED (user/per-attempt timeout abort) is not retried.

Memory cache

• new MemoryCacheStore({ maxEntries }) + createCacheMiddleware(store, { ttlMs, staleWhileRevalidateMs, methods, key, varyHeaderNames, … }).
• Default cache key includes method + full URL; authorization and cookie are always folded into the key unless varyHeaderNames is explicitly [] (dangerous for shared auth — see package warning / use suppressAuthCacheKeyWarning only when intentional). Prefer omitting varyHeaderNames or listing extra headers; use appendCacheKeyVaryHeaders for custom keys.
• staleWhileRevalidateMs: can serve stale after TTL and refresh in background; that background path calls dispatch directly — not every client.use() middleware runs for it (see human docs architecture note).

Errors & logging

• Guard with isOpenFetchError(err).
• error.toShape() / toJSON() — by default omits response data and headers; pass includeResponseData: true / includeResponseHeaders: true only for trusted diagnostics. redactSensitiveUrlQuery defaults on for the serialized URL in the shape.
• The live error may still hold full config (including secrets) — never forward raw instances to clients.

Security

• assertSafeHttpUrl(url) — optional guard for untrusted URLs (http/https only; blocks many literal private/loopback IPs). Does not stop DNS rebinding; pair with hostname allowlists / egress controls when relevant.
• assertSafeUrl: true on the client — runs assertSafeHttpUrl on the fully resolved URL before fetch.

Framework usage (minimal)

• React: useEffect + await openFetch.get(url); use res.data unless unwrapResponse is true on the client.
• RSC / server: await api.get(…) in an async component is fine; keep secrets server-side.
• Vue: onMounted + assign res.data to a ref.

When to refuse or redirect

• Need XHR upload progress → say fetch does not expose it; suggest multipart + server progress, or a different tool.
• User asks for openFetch docs verbatim → point to the docs URL above or read quick reference in this folder.

Repo layout (for code navigation)

• src/runtime/client.ts — client, verb helpers
• src/transport/dispatch.ts — fetch, parse, validateStatus, rawResponse
• src/runtime/middleware.ts, interceptors.ts, retry.ts, cache.ts
• src/domain/error.ts — OpenFetchError, toShape
• src/plugins/ — retry, timeout, hooks, debug, strictFetch
• src/sugar/fluent.ts — createFluentClient, .memo(), .raw()