@cedvict/http-guardian 0.0.1-next.6 → 0.0.1-next.7

package/dist/index.js

@@ -1,16 +1,14 @@
 // src/internal/compose.ts
 function composeGuards(guards, terminal) {
-  return (ctx) => {
-    let idx = -1;
-    const dispatch = (i, c) => {
-      if (i <= idx) return Promise.reject(new Error("composeGuards: next() called multiple times"));
-      idx = i;
-      const guard = guards[i];
-      if (!guard) return terminal(c);
-      return guard(c, (nextCtx) => dispatch(i + 1, nextCtx));
-    };
-    return dispatch(0, ctx);
-  };
+  if (!guards.length) return terminal;
+  return (ctx) => dispatch(0, ctx);
+  function dispatch(i, c) {
+    const guard = guards[i];
+    if (!guard) return terminal(c);
+    return Promise.resolve(
+      guard(c, (nextCtx) => dispatch(i + 1, nextCtx ?? c))
+    );
+  }
 }
 
 // src/internal/url.ts
@@ -36,6 +34,34 @@ function sanitizeHeaderValue(v) {
   if (/[\r\n]/.test(v)) return null;
   return v;
 }
+function base64Encode(input) {
+  if (typeof globalThis.btoa === "function") return globalThis.btoa(input);
+  const B = globalThis.Buffer;
+  if (typeof B?.from === "function") return B.from(input, "utf8").toString("base64");
+  throw new Error("No base64 encoder available in this runtime");
+}
+function isUnsafeMethod(m) {
+  const u = m.toUpperCase();
+  return u !== "GET" && u !== "HEAD" && u !== "OPTIONS";
+}
+function sameOrigin(url, baseOrigin) {
+  if (!baseOrigin) return true;
+  try {
+    return new URL(url).origin === baseOrigin;
+  } catch {
+    return true;
+  }
+}
+function isAllowedOrigin(url, baseOrigin, allowed) {
+  if (!allowed) return sameOrigin(url, baseOrigin);
+  if (typeof allowed === "function") return !!allowed(url);
+  try {
+    const origin = new URL(url).origin;
+    return allowed.includes(origin);
+  } catch {
+    return true;
+  }
+}
 function authGuard(auth) {
   return async (ctx, next) => {
     if (ctx.noAuth) return next(ctx);
@@ -43,6 +69,9 @@ function authGuard(auth) {
     if (auth.mode === "bearer") {
       const token = await auth.getToken();
       if (token) {
+        if (!isAllowedOrigin(ctx.url, ctx.baseOrigin, auth.allowedOrigins)) {
+          return next(ctx);
+        }
         const headerName = auth.headerName ?? "Authorization";
         const prefix = auth.prefix ?? "Bearer";
         const safe = sanitizeHeaderValue(`${prefix} ${token}`);
@@ -50,8 +79,36 @@ function authGuard(auth) {
       }
       return next(ctx);
     }
+    if (auth.mode === "basic") {
+      const cred = await auth.getCredentials();
+      if (cred) {
+        if (!isAllowedOrigin(ctx.url, ctx.baseOrigin, auth.allowedOrigins)) {
+          return next(ctx);
+        }
+        const headerName = auth.headerName ?? "Authorization";
+        const prefix = auth.prefix ?? "Basic";
+        const raw = typeof cred === "string" ? cred : `${cred.username}:${cred.password}`;
+        const safe = sanitizeHeaderValue(`${prefix} ${base64Encode(raw)}`);
+        if (safe) ctx.headers.set(headerName, safe);
+      }
+      return next(ctx);
+    }
+    if (auth.mode === "apiKey") {
+      const key = await auth.getKey();
+      if (key) {
+        if (!isAllowedOrigin(ctx.url, ctx.baseOrigin, auth.allowedOrigins)) {
+          return next(ctx);
+        }
+        const headerName = auth.headerName ?? "X-API-Key";
+        const prefix = auth.prefix ?? "";
+        const value = prefix ? `${prefix} ${key}` : key;
+        const safe = sanitizeHeaderValue(value);
+        if (safe) ctx.headers.set(headerName, safe);
+      }
+      return next(ctx);
+    }
     ctx.credentials = auth.credentials ?? "include";
-    if (auth.csrf) {
+    if (auth.csrf && isUnsafeMethod(ctx.method)) {
       const csrf = await auth.csrf.getToken();
       if (csrf) ctx.headers.set(auth.csrf.headerName, csrf);
     }
@@ -59,6 +116,84 @@ function authGuard(auth) {
   };
 }
 
+// src/internal/headersPolyfill.ts
+function norm(name) {
+  return String(name).toLowerCase();
+}
+var HeadersPolyfill = class {
+  map = /* @__PURE__ */ new Map();
+  constructor(init) {
+    if (!init) return;
+    if (typeof init.forEach === "function" && typeof init.get === "function") {
+      init.forEach((v, k) => this.set(k, v));
+      return;
+    }
+    if (Symbol.iterator in Object(init)) {
+      for (const [k, v] of init) this.append(k, v);
+      return;
+    }
+    for (const [k, v] of Object.entries(init)) {
+      this.set(k, String(v));
+    }
+  }
+  get(name) {
+    const hit = this.map.get(norm(name));
+    return hit ? hit.value : null;
+  }
+  has(name) {
+    return this.map.has(norm(name));
+  }
+  set(name, value) {
+    this.map.set(norm(name), { name, value: String(value) });
+  }
+  append(name, value) {
+    const key = norm(name);
+    const prev = this.map.get(key);
+    if (!prev) {
+      this.map.set(key, { name, value: String(value) });
+      return;
+    }
+    this.map.set(key, { name: prev.name, value: `${prev.value}, ${String(value)}` });
+  }
+  delete(name) {
+    this.map.delete(norm(name));
+  }
+  forEach(cb) {
+    for (const { name, value } of this.map.values()) cb(value, name);
+  }
+  entries() {
+    const it = this.map.values();
+    return {
+      [Symbol.iterator]() {
+        return this;
+      },
+      next() {
+        const n = it.next();
+        if (n.done) return { done: true, value: void 0 };
+        return { done: false, value: [n.value.name, n.value.value] };
+      }
+    };
+  }
+  /** Convert to HeadersInit that any fetch can consume. */
+  toObject() {
+    const out = {};
+    for (const { name, value } of this.map.values()) out[name] = value;
+    return out;
+  }
+};
+function createHeaders(init) {
+  if (typeof globalThis.Headers === "function") {
+    return new globalThis.Headers(init);
+  }
+  return new HeadersPolyfill(init);
+}
+function toFetchHeaders(headers) {
+  if (typeof globalThis.Headers === "function" && headers instanceof globalThis.Headers) {
+    return headers;
+  }
+  return headers.toObject();
+}
+
 // src/internal/stableStringify.ts
 function stableStringify(value) {
   return JSON.stringify(sortValue(value));
@@ -175,21 +310,49 @@ function normalizeFetch(f) {
   const bound = f.bind ? f.bind(globalThis) : f;
   return ((input, init) => bound(input, init));
 }
+function getDefaultFetch() {
+  if (typeof globalThis.fetch === "function") return globalThis.fetch;
+  throw new Error(
+    "No global fetch detected. Provide a fetch implementation via createHttpClient({ fetch }) or run in an environment that supports fetch (Node >= 18 / modern browsers)."
+  );
+}
 var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
-function createHttpClient(opts) {
-  const resolvedFetch = opts.fetch ? normalizeFetch(opts.fetch) : ((input, init) => globalThis.fetch(input, init));
-  const cache = opts.cache;
+function createHttpClient(options) {
+  const draft = { ...options };
+  if (draft.plugins?.length) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const p of draft.plugins) {
+      if (!p || !p.name || typeof p.apply !== "function") continue;
+      if (seen.has(p.name)) continue;
+      seen.add(p.name);
+      p.apply(draft);
+    }
+  }
+  const resolvedFetch = (() => {
+    if (draft.fetch) return normalizeFetch(draft.fetch);
+    let lastRef = null;
+    let lastBound = null;
+    return ((input, init) => {
+      const cur = getDefaultFetch();
+      if (cur !== lastRef || !lastBound) {
+        lastRef = cur;
+        lastBound = normalizeFetch(cur);
+      }
+      return lastBound(input, init);
+    });
+  })();
+  const cache = draft.cache;
   const inFlight = new InFlight();
-  const defaultNotifier = opts.notifier ?? consoleNotifier;
-  const shouldNotify = opts.defaults?.shouldNotify ?? ((r) => !r.ok);
-  const baseGuards = [authGuard(opts.auth), ...opts.guards ?? []];
+  const defaultNotifier = draft.notifier ?? consoleNotifier;
+  const shouldNotify = draft.defaults?.shouldNotify ?? ((r) => !r.ok);
+  const baseGuards = [authGuard(draft.auth), ...draft.guards ?? []];
   async function terminal(ctx) {
     const controller = ctx.timeoutMs ? new AbortController() : void 0;
     const timeout = ctx.timeoutMs ? setTimeout(() => controller?.abort(new TimeoutError()), ctx.timeoutMs) : void 0;
     try {
       const init = {
         method: ctx.method,
-        headers: ctx.headers,
+        headers: toFetchHeaders(ctx.headers),
         ...ctx.body !== void 0 ? { body: ctx.body } : {},
         ...ctx.signal ? { signal: controller ? anySignal([ctx.signal, controller.signal]) : ctx.signal } : controller ? { signal: controller.signal } : {},
         ...ctx.credentials !== void 0 ? { credentials: ctx.credentials } : {},
@@ -209,9 +372,9 @@ function createHttpClient(opts) {
   }
   const pipeline = composeGuards(baseGuards, terminal);
   async function request(method, path, ro) {
-    const requestUrl = withQuery(joinUrl(opts.baseUrl, path), ro?.query);
-    const headers = new Headers();
-    if (opts.defaults?.headers) for (const [k, v] of Object.entries(opts.defaults.headers)) headers.set(k, v);
+    const requestUrl = withQuery(joinUrl(draft.baseUrl, path), ro?.query);
+    const headers = createHeaders();
+    if (draft.defaults?.headers) for (const [k, v] of Object.entries(draft.defaults.headers)) headers.set(k, v);
     if (ro?.headers) {
       for (const [k, v] of Object.entries(ro.headers)) if (v !== void 0) headers.set(k, v);
     }
@@ -229,19 +392,31 @@ function createHttpClient(opts) {
     } else {
       if (!headers.has("accept")) headers.set("accept", "application/json");
     }
-    const timeoutMs = ro?.timeoutMs ?? opts.defaults?.timeoutMs;
+    const timeoutMs = ro?.timeoutMs ?? draft.defaults?.timeoutMs;
     const notifier = ro?.notifier ?? defaultNotifier;
+    const emit = (event) => {
+      const redact = notifier.redact;
+      const n = notifier.notify?.bind(notifier) ?? defaultNotifier.notify.bind(defaultNotifier);
+      return n(redact ? redact(event) : event);
+    };
     const cacheOpts = ro?.cache;
     const wantsCache = method === "GET" && !!cache && !!cacheOpts;
     const dedupe = cacheOpts?.dedupe ?? true;
     const canDedupeWrite = method !== "GET" && !!ro?.idempotencyKey;
-    const inflightKey = (wantsCache || canDedupeWrite) && dedupe ? makeCacheKey({ method, url: requestUrl, headers, ...method === "GET" ? {} : { body: bodyForKey }, ...ro?.idempotencyKey !== void 0 ? { idempotencyKey: ro.idempotencyKey } : {}, ...cacheOpts?.key !== void 0 ? { keyOverride: cacheOpts.key } : {} }) : void 0;
+    const inflightKey = (wantsCache || canDedupeWrite) && dedupe ? makeCacheKey({
+      method,
+      url: requestUrl,
+      headers,
+      ...method === "GET" ? {} : { body: bodyForKey },
+      ...ro?.idempotencyKey !== void 0 ? { idempotencyKey: ro.idempotencyKey } : {},
+      ...cacheOpts?.key !== void 0 ? { keyOverride: cacheOpts.key } : {}
+    }) : void 0;
     if (inflightKey) {
       const existing = inFlight.get(inflightKey);
       if (existing) {
         try {
           const stored = await existing;
-          return asClientResult(stored, requestUrl, opts, ro, notifier, shouldNotify);
+          return asClientResult(stored, requestUrl, draft, ro, notifier, shouldNotify, emit);
         } catch {
         }
       }
@@ -263,7 +438,7 @@ function createHttpClient(opts) {
         }
       }
       const res = await fetchWithRedirects({
-        opts,
+        opts: draft,
         resolvedFetch,
         pipeline,
         method,
@@ -278,13 +453,17 @@ function createHttpClient(opts) {
       const envelope = { kind: "network", url: res.url || requestUrl, status: res.status, headers: res.headers, raw };
       if (wantsCache && cacheOpts && res.ok) {
         const key = inflightKey;
-        cache.set(key, { expiresAt: Date.now() + cacheOpts.ttlMs, value: raw, ...cacheOpts.tags ? { tags: cacheOpts.tags } : {} });
+        cache.set(key, {
+          expiresAt: Date.now() + cacheOpts.ttlMs,
+          value: raw,
+          ...cacheOpts.tags ? { tags: cacheOpts.tags } : {}
+        });
       }
       return envelope;
       async function refreshInBackground(key) {
         try {
           const res2 = await fetchWithRedirects({
-            opts,
+            opts: draft,
             resolvedFetch,
             pipeline,
             method,
@@ -297,7 +476,11 @@ function createHttpClient(opts) {
           });
           if (!res2.ok) return;
           const raw2 = await decodeResponse(res2);
-          cache.set(key, { expiresAt: Date.now() + cacheOpts.ttlMs, value: raw2, ...cacheOpts.tags ? { tags: cacheOpts.tags } : {} });
+          cache.set(key, {
+            expiresAt: Date.now() + cacheOpts.ttlMs,
+            value: raw2,
+            ...cacheOpts.tags ? { tags: cacheOpts.tags } : {}
+          });
         } catch {
         }
       }
@@ -305,13 +488,13 @@ function createHttpClient(opts) {
     if (inflightKey) inFlight.set(inflightKey, promise);
     try {
       const stored = await promise;
-      return asClientResult(stored, requestUrl, opts, ro, notifier, shouldNotify);
+      return asClientResult(stored, requestUrl, draft, ro, notifier, shouldNotify, emit);
     } catch (e) {
       const err = e instanceof TimeoutError ? e : new NetworkError(
         isIllegalInvocation(e) ? `Network request failed. ${ILLEGAL_INVOCATION_HINT}` : "Network request failed",
         e
       );
-      if (shouldNotify({ ok: false, status: 0 })) notifier.notify({ type: "network-error", level: "error", title: "Network error", message: err.message, url: requestUrl });
+      if (shouldNotify({ ok: false, status: 0 })) emit({ type: "network-error", level: "error", title: "Network error", message: err.message, url: requestUrl });
       return { ok: false, status: 0, headers: new Headers(), errors: [{ message: err.message, details: e }], raw: null, url: requestUrl };
     }
   }
@@ -343,7 +526,19 @@ async function fetchWithRedirects(args) {
     );
     if (!REDIRECT_STATUSES.has(res.status)) return res;
     const loc = res.headers.get("location");
-    if (!loc) throw new RedirectError("Redirect without Location header", currentUrl);
+    if (!loc) {
+      return args.pipeline(
+        makeCtx(
+          {
+            ...args,
+            url: currentUrl,
+            method,
+            ...body !== void 0 ? { body } : {}
+          },
+          "follow"
+        )
+      );
+    }
     const nextUrl = new URL(loc, currentUrl).toString();
     const decision = policy.onRedirect?.({ fromUrl: currentUrl, toUrl: nextUrl, status: res.status, hop, method });
     if (decision?.action === "deny") throw new RedirectError(decision.reason ?? "Redirect denied by policy", currentUrl, nextUrl);
@@ -363,18 +558,38 @@ async function fetchWithRedirects(args) {
 }
 function stripAuthOnCrossOriginRedirect(opts, initialUrl, toUrl, headers) {
   try {
-    if (opts.auth.mode !== "bearer") return;
     const initialOrigin = new URL(initialUrl).origin;
     const toOrigin = new URL(toUrl).origin;
-    if (initialOrigin !== toOrigin) {
+    if (initialOrigin === toOrigin) return;
+    if (opts.auth.mode === "bearer") {
       const headerName = opts.auth.headerName ?? "Authorization";
       headers.delete(headerName);
+      return;
+    }
+    if (opts.auth.mode === "basic") {
+      const headerName = opts.auth.headerName ?? "Authorization";
+      headers.delete(headerName);
+      return;
+    }
+    if (opts.auth.mode === "apiKey") {
+      const headerName = opts.auth.headerName ?? "X-API-Key";
+      headers.delete(headerName);
+      return;
     }
   } catch {
   }
 }
 function makeCtx(args, redirect) {
+  const baseOrigin = (() => {
+    try {
+      return new URL(args.opts.baseUrl).origin;
+    } catch {
+      return "";
+    }
+  })();
   return {
+    baseUrl: args.opts.baseUrl,
+    baseOrigin,
     method: args.method,
     url: args.url,
     headers: args.headers,
@@ -404,10 +619,10 @@ async function decodeResponse(res) {
     throw new ParseError("Failed to read response body", void 0, e);
   }
 }
-function asClientResult(envelope, requestUrl, opts, ro, notifier, shouldNotify) {
+function asClientResult(envelope, requestUrl, opts, ro, notifier, shouldNotify, emit) {
   if (envelope?.kind === "cache-miss") {
     const errors2 = [{ message: "Cache miss" }];
-    if (shouldNotify({ ok: false, status: 0 })) notifier.notify({ type: "http-error", level: "warning", title: "Cache", message: "Cache miss", status: 0, errors: errors2, url: requestUrl });
+    if (shouldNotify({ ok: false, status: 0 })) emit({ type: "http-error", level: "warning", title: "Cache", message: "Cache miss", status: 0, errors: errors2, url: requestUrl });
     return { ok: false, status: 0, headers: new Headers(), errors: errors2, raw: envelope.raw, url: requestUrl };
   }
   const status = envelope.status ?? 0;
@@ -422,17 +637,24 @@ function asClientResult(envelope, requestUrl, opts, ro, notifier, shouldNotify)
       return { ok: true, status, headers: resHeaders, data, raw, url: finalUrl };
     } catch (e) {
       const msg2 = e instanceof Error ? e.message : "Schema parse failed";
-      if (shouldNotify({ ok: false, status })) notifier.notify({ type: "parse-error", level: "error", title: "Parse error", message: msg2, url: finalUrl });
+      if (shouldNotify({ ok: false, status })) emit({ type: "parse-error", level: "error", title: "Parse error", message: msg2, url: finalUrl });
       return { ok: false, status, headers: resHeaders, errors: [{ message: msg2, details: e }], raw, url: finalUrl };
     }
   }
   const errors = opts.parser.getErrors(raw, status);
   const msg = errors[0]?.message ?? (status ? `HTTP ${status}` : "Request failed");
-  if (shouldNotify({ ok: false, status })) notifier.notify({ type: "http-error", level: status >= 500 ? "error" : "warning", title: "Request failed", message: msg, status, errors, url: finalUrl });
+  if (shouldNotify({ ok: false, status })) emit({ type: "http-error", level: status >= 500 ? "error" : "warning", title: "Request failed", message: msg, status, errors, url: finalUrl });
   return { ok: false, status, headers: resHeaders, errors, raw, url: finalUrl };
 }
 function anySignal(signals) {
   const valid = signals.filter(Boolean);
+  const any = AbortSignal.any;
+  if (any) {
+    try {
+      return any(valid);
+    } catch {
+    }
+  }
   const controller = new AbortController();
   const onAbort = () => controller.abort();
   for (const s of valid) {
@@ -448,7 +670,8 @@ function bearerAuth(getToken, opts) {
     mode: "bearer",
     getToken,
     ...opts?.headerName !== void 0 ? { headerName: opts.headerName } : {},
-    ...opts?.prefix !== void 0 ? { prefix: opts.prefix } : {}
+    ...opts?.prefix !== void 0 ? { prefix: opts.prefix } : {},
+    ...opts?.allowedOrigins !== void 0 ? { allowedOrigins: opts.allowedOrigins } : {}
   };
 }
 function cookieAuth(opts) {
@@ -458,6 +681,24 @@ function cookieAuth(opts) {
     ...opts?.csrf !== void 0 ? { csrf: opts.csrf } : {}
   };
 }
+function basicAuth(getCredentials, opts) {
+  return {
+    mode: "basic",
+    getCredentials,
+    ...opts?.headerName !== void 0 ? { headerName: opts.headerName } : {},
+    ...opts?.prefix !== void 0 ? { prefix: opts.prefix } : {},
+    ...opts?.allowedOrigins !== void 0 ? { allowedOrigins: opts.allowedOrigins } : {}
+  };
+}
+function apiKeyAuth(getKey, opts) {
+  return {
+    mode: "apiKey",
+    getKey,
+    ...opts?.headerName !== void 0 ? { headerName: opts.headerName } : {},
+    ...opts?.prefix !== void 0 ? { prefix: opts.prefix } : {},
+    ...opts?.allowedOrigins !== void 0 ? { allowedOrigins: opts.allowedOrigins } : {}
+  };
+}
 function noAuth() {
   return { mode: "none" };
 }
@@ -497,8 +738,7 @@ function isReplayableBody(body) {
 }
 function normalizePath(url) {
   try {
-    const u = new URL(url);
-    return u.pathname;
+    return new URL(url).pathname;
   } catch {
     const q = url.indexOf("?");
     const h = url.indexOf("#");
@@ -515,6 +755,14 @@ function parseRetryAfterMs(headers) {
   if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
   return null;
 }
+function isAbsoluteUrl(u) {
+  try {
+    void new URL(u);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function cookieSafeRefreshGuard(opts) {
   const trigger = new Set(opts.triggerStatuses ?? [401, 419]);
   const maxRetry = opts.maxRetry ?? 1;
@@ -527,38 +775,39 @@ function cookieSafeRefreshGuard(opts) {
     const path = normalizePath(ctx.url);
     if (opts.excludePaths?.includes(path)) return next(ctx);
     if (ctx.noAuth) return next(ctx);
-    const refreshPathNorm = normalizePath(opts.refreshPath);
+    const refreshPathNorm = normalizePath(resolveRefreshUrl(ctx, opts.refreshPath));
     if (path === refreshPathNorm) return next(ctx);
     if (honorRetryAfter && refreshCooldownUntil > Date.now()) {
       return next(ctx);
     }
     const res = await next(ctx);
     if (!trigger.has(res.status)) return res;
-    if (opts.shouldRefresh && !opts.shouldRefresh(ctx, res.status)) {
-      return res;
-    }
+    if (opts.shouldRefresh && !opts.shouldRefresh(ctx, res.status)) return res;
     const alreadyRetried = Number(anyCtx[RETRY_FLAG] ?? 0);
     if (alreadyRetried >= maxRetry) return res;
-    if (!isReplayableBody(ctx.body)) {
-      return res;
-    }
+    if (!isReplayableBody(ctx.body)) return res;
     const decision = await (refreshPromise ??= doRefresh(ctx, next).finally(() => {
       refreshPromise = null;
     }));
     if (!decision.ok) {
-      opts.onRefreshFailed?.({ url: ctx.url, reason: decision.reason ?? "" });
+      opts.onRefreshFailed?.({
+        url: ctx.url,
+        ...decision.reason !== void 0 ? { reason: decision.reason } : {},
+        ...decision.status !== void 0 ? { status: decision.status } : {}
+      });
       return res;
     }
     opts.onRefreshSuccess?.({ url: ctx.url });
     const retryCtx = Object.assign({}, ctx, { attempt: ctx.attempt + 1 });
     retryCtx[RETRY_FLAG] = alreadyRetried + 1;
+    await applyCookieAuth(retryCtx);
     return next(retryCtx);
   };
   async function doRefresh(originalCtx, next) {
     if (honorRetryAfter && refreshCooldownUntil > Date.now()) {
       return { ok: false, reason: "Refresh cooldown active" };
     }
-    const refreshUrl = resolveRefreshUrl(originalCtx.url, opts.refreshPath);
+    const refreshUrl = resolveRefreshUrl(originalCtx, opts.refreshPath);
     const refreshCtx = {
       ...originalCtx,
       url: refreshUrl,
@@ -568,36 +817,177 @@ function cookieSafeRefreshGuard(opts) {
       attempt: 0
     };
     refreshCtx[REFRESH_FLAG] = true;
+    refreshCtx[RETRY_FLAG] = 0;
+    await applyCookieAuth(refreshCtx);
     try {
       const res = await next(refreshCtx);
       if (res.status === 429 && honorRetryAfter) {
         const ms = parseRetryAfterMs(res.headers);
         refreshCooldownUntil = Date.now() + (ms ?? 3e4);
-        return { ok: false, reason: "Refresh rate-limited (429)" };
+        return { ok: false, reason: "Refresh rate-limited (429)", status: 429 };
       }
       if (!res.ok) {
-        return { ok: false, reason: `Refresh failed (HTTP ${res.status})` };
+        return { ok: false, reason: `Refresh failed (HTTP ${res.status})`, status: res.status };
       }
       return { ok: true };
     } catch (e) {
       return { ok: false, reason: e instanceof Error ? e.message : "Refresh exception" };
     }
   }
-  function resolveRefreshUrl(baseRequestUrl, refreshPath) {
-    try {
-      const u = new URL(refreshPath);
-      return u.toString();
-    } catch {
-      try {
-        const base = new URL(baseRequestUrl);
-        return new URL(refreshPath, base.origin).toString();
-      } catch {
-        return refreshPath;
+  function resolveRefreshUrl(ctx, refreshPath) {
+    if (isAbsoluteUrl(refreshPath)) return refreshPath;
+    return joinUrl(ctx.baseUrl, refreshPath);
+  }
+  async function applyCookieAuth(ctx) {
+    if (ctx.noAuth) return;
+    const auth = ctx.auth;
+    if (!auth || auth.mode !== "cookie") return;
+    if (ctx.credentials === void 0) {
+      ctx.credentials = auth.credentials ?? "include";
+    }
+    if (auth.csrf) {
+      const hn = auth.csrf.headerName;
+      if (!ctx.headers.has(hn)) {
+        const t = await auth.csrf.getToken();
+        if (t != null && String(t) !== "") ctx.headers.set(hn, String(t));
       }
     }
   }
 }
 
+// src/guards/unauthorizedGuard.ts
+function normalizePath2(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    const q = url.indexOf("?");
+    const h = url.indexOf("#");
+    const cut = Math.min(q === -1 ? url.length : q, h === -1 ? url.length : h);
+    return url.slice(0, cut);
+  }
+}
+function unauthorizedGuard(opts) {
+  const statuses = opts.statuses ?? [401, 419];
+  const ignoreNoAuth = opts.ignoreNoAuth ?? true;
+  const once = opts.once ?? true;
+  const cooldownMs = opts.cooldownMs ?? 250;
+  let locked = false;
+  let cooldownUntil = 0;
+  return async (ctx, next) => {
+    let res;
+    try {
+      res = await next(ctx);
+    } catch (e) {
+      throw e;
+    }
+    if (ignoreNoAuth && ctx.noAuth) return res;
+    const path = normalizePath2(ctx.url);
+    if (opts.excludePaths?.includes(path)) return res;
+    if (!statuses.includes(res.status)) return res;
+    if (opts.shouldHandle && !opts.shouldHandle(ctx, res.status)) return res;
+    const now = Date.now();
+    if (now < cooldownUntil) return res;
+    if (once) {
+      if (locked) return res;
+      locked = true;
+    }
+    try {
+      opts.onUnauthorized({ url: ctx.url, status: res.status });
+    } finally {
+      cooldownUntil = Date.now() + cooldownMs;
+      if (once) setTimeout(() => locked = false, cooldownMs);
+    }
+    return res;
+  };
+}
+
+// src/guards/instrumentGuard.ts
+var REFRESH_FLAG2 = "__hg_is_refresh__";
+var RETRY_FLAG2 = "__hg_refresh_retry__";
+function safeUrl(u) {
+  try {
+    const url = new URL(u);
+    return url.toString();
+  } catch {
+    return u;
+  }
+}
+function nowMs() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function headersToObject(h) {
+  if (!h) return {};
+  const out = {};
+  try {
+    h.forEach((v, k) => {
+      const key = String(k).toLowerCase();
+      if (key === "authorization" || key === "cookie" || key === "set-cookie" || key === "x-api-key" || key === "proxy-authorization") {
+        out[k] = "[REDACTED]";
+      } else {
+        out[k] = v;
+      }
+    });
+  } catch {
+  }
+  return out;
+}
+var __hg_req_seq = 0;
+function instrumentGuard(opts, guard) {
+  const log = opts.log ?? ((line, data) => data !== void 0 ? console.log(line, data) : console.log(line));
+  return async (ctx, next) => {
+    const id = ++__hg_req_seq;
+    const t0 = nowMs();
+    const url = safeUrl(ctx.url);
+    const method = ctx.method ?? "GET";
+    if (opts.include && !opts.include.test(url)) {
+      return guard(ctx, next);
+    }
+    if (opts.exclude && opts.exclude.test(url)) {
+      return guard(ctx, next);
+    }
+    const anyCtx = ctx;
+    const attempt = ctx.attempt ?? 0;
+    const isRefresh = Boolean(anyCtx[REFRESH_FLAG2]);
+    const retryCount = Number(anyCtx[RETRY_FLAG2] ?? 0);
+    const noAuth2 = Boolean(ctx.noAuth);
+    const baseLine = `[HG][#${id}][${opts.name}]`;
+    log(`${baseLine} \u25B6 start`, {
+      method,
+      url,
+      attempt,
+      retryCount,
+      isRefresh,
+      noAuth: noAuth2,
+      baseUrl: ctx.baseUrl,
+      ...opts.logInit ? {
+        credentials: ctx.credentials,
+        redirect: ctx.redirect,
+        headers: headersToObject(ctx.headers)
+      } : {},
+      ...opts.stack ? { stack: new Error().stack } : {}
+    });
+    try {
+      const res = await guard(ctx, next);
+      const dt = Math.round(nowMs() - t0);
+      log(`${baseLine} \u25C0 end (${dt}ms)`, {
+        status: res.status,
+        ok: res.ok,
+        url: res.url || url,
+        redirected: res.redirected,
+        location: res.headers?.get?.("location") ?? null,
+        retryAfter: res.headers?.get?.("retry-after") ?? null
+      });
+      return res;
+    } catch (e) {
+      const dt = Math.round(nowMs() - t0);
+      log(`${baseLine} \u2716 throw (${dt}ms)`, {
+        error: e instanceof Error ? { name: e.name, message: e.message, stack: e.stack } : e
+      });
+      throw e;
+    }
+  };
+}
+
 // src/cache/memoryCache.ts
 function memoryCache(opts) {
   const max = opts?.maxEntries ?? 1e3;
@@ -794,6 +1184,196 @@ function createApiParserGraphQL(opts) {
   });
 }
 
-export { ILLEGAL_INVOCATION_HINT, NetworkError, ParseError, RedirectError, TimeoutError, alertNotifier, bearerAuth, consoleNotifier, cookieAuth, cookieSafeRefreshGuard, createApiParserGraphQL, createApiParserLaravel, createApiParserNest, createApiParserRestClassic, createHttpClient, createShapeParser, fromZod, memoryCache, noAuth, retryGuard, schema, tailwindAlertRenderer };
+// src/presets/presetBuilder.ts
+function createPresetBuilder(init) {
+  const state = {
+    baseUrl: init?.baseUrl ?? "",
+    parser: init?.parser ?? createApiParserRestClassic(),
+    auth: init?.auth ?? noAuth(),
+    ...init?.fetch ? { fetch: init.fetch } : {},
+    ...init?.notifier ? { notifier: init.notifier } : { notifier: consoleNotifier },
+    guards: []
+  };
+  function ensureBaseUrl() {
+    if (!state.baseUrl) throw new Error("presetBuilder: baseUrl is required");
+  }
+  const api = {
+    /** Set / override baseUrl */
+    baseUrl(baseUrl) {
+      state.baseUrl = baseUrl;
+      return api;
+    },
+    /** Set / override parser */
+    parser(parser) {
+      state.parser = parser;
+      return api;
+    },
+    /** Set / override fetch */
+    fetch(fetchImpl) {
+      state.fetch = fetchImpl;
+      return api;
+    },
+    /** Set / override notifier */
+    notifier(notifier) {
+      state.notifier = notifier;
+      return api;
+    },
+    /** Add guard(s) (preserves order) */
+    guards(...guards) {
+      state.guards = [...state.guards ?? [], ...guards];
+      return api;
+    },
+    /** Enable in-memory cache */
+    memoryCache(opts) {
+      state.cache = memoryCache(opts);
+      return api;
+    },
+    /** Low-level cache assignment */
+    cache(cache) {
+      if (cache === void 0) {
+        delete state.cache;
+      } else {
+        state.cache = cache;
+      }
+      return api;
+    },
+    /** Default headers / timeouts / notify policy */
+    defaults(defaults) {
+      state.defaults = { ...state.defaults ?? {}, ...defaults ?? {} };
+      return api;
+    },
+    /** Redirect policy */
+    redirects(redirects) {
+      if (redirects === void 0) {
+        delete state.redirects;
+      } else {
+        state.redirects = redirects;
+      }
+      return api;
+    },
+    /** Auth presets */
+    auth(auth) {
+      state.auth = auth;
+      return api;
+    },
+    bearer(getToken, opts) {
+      state.auth = bearerAuth(getToken, opts);
+      return api;
+    },
+    cookie(opts) {
+      state.auth = cookieAuth(opts);
+      return api;
+    },
+    basic(getCred, opts) {
+      state.auth = basicAuth(getCred, opts);
+      return api;
+    },
+    apiKey(getKey, opts) {
+      state.auth = apiKeyAuth(getKey, opts);
+      return api;
+    },
+    none() {
+      state.auth = noAuth();
+      return api;
+    },
+    /**
+     * Cookie refresh guard preset (only meaningful for cookie auth).
+     * You can still add it manually via `.guards(...)`.
+     */
+    cookieRefresh(opts) {
+      state.guards = [...state.guards ?? [], cookieSafeRefreshGuard(opts)];
+      return api;
+    },
+    /** Unauthorized handler preset (redirect/logout). */
+    unauthorized(opts) {
+      state.guards = [...state.guards ?? [], unauthorizedGuard(opts)];
+      return api;
+    },
+    /** Returns the final HttpClientOptions */
+    options() {
+      ensureBaseUrl();
+      return { ...state, guards: [...state.guards ?? []] };
+    },
+    /** Creates the http client */
+    create() {
+      ensureBaseUrl();
+      return createHttpClient(api.options());
+    }
+  };
+  return api;
+}
+function createSimpleClient(opts) {
+  return createPresetBuilder(opts).create();
+}
+function createBearerClient(opts) {
+  const bearerOpts = {
+    ...opts.headerName !== void 0 ? { headerName: opts.headerName } : {},
+    ...opts.prefix !== void 0 ? { prefix: opts.prefix } : {}
+  };
+  return createPresetBuilder({
+    baseUrl: opts.baseUrl,
+    ...opts.parser ? { parser: opts.parser } : {},
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    ...opts.notifier ? { notifier: opts.notifier } : {}
+  }).bearer(opts.getToken, Object.keys(bearerOpts).length ? bearerOpts : void 0).create();
+}
+function createCookieClient(opts) {
+  const b = createPresetBuilder({
+    baseUrl: opts.baseUrl,
+    ...opts.parser ? { parser: opts.parser } : {},
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    ...opts.notifier ? { notifier: opts.notifier } : {}
+  }).cookie({
+    ...opts.credentials !== void 0 ? { credentials: opts.credentials } : {},
+    ...opts.csrf !== void 0 ? { csrf: opts.csrf } : {}
+  });
+  if (opts.refresh) b.cookieRefresh(opts.refresh);
+  return b.create();
+}
+function createBasicClient(opts) {
+  const basicOpts = {
+    ...opts.headerName !== void 0 ? { headerName: opts.headerName } : {},
+    ...opts.prefix !== void 0 ? { prefix: opts.prefix } : {}
+  };
+  return createPresetBuilder({
+    baseUrl: opts.baseUrl,
+    ...opts.parser ? { parser: opts.parser } : {},
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    ...opts.notifier ? { notifier: opts.notifier } : {}
+  }).basic(opts.getCredentials, Object.keys(basicOpts).length ? basicOpts : void 0).create();
+}
+function createApiKeyClient(opts) {
+  const apiKeyOpts = {
+    ...opts.headerName !== void 0 ? { headerName: opts.headerName } : {},
+    ...opts.prefix !== void 0 ? { prefix: opts.prefix } : {}
+  };
+  return createPresetBuilder({
+    baseUrl: opts.baseUrl,
+    ...opts.parser ? { parser: opts.parser } : {},
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    ...opts.notifier ? { notifier: opts.notifier } : {}
+  }).apiKey(opts.getKey, Object.keys(apiKeyOpts).length ? apiKeyOpts : void 0).create();
+}
+
+// src/aliases.ts
+function createClient(opts) {
+  const parser = opts.parser ?? createApiParserRestClassic();
+  const auth = opts.auth ?? noAuth();
+  const notifier = opts.notifier ?? consoleNotifier;
+  const cfg = {
+    baseUrl: opts.baseUrl,
+    parser,
+    auth,
+    notifier,
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    ...opts.defaults ? { defaults: opts.defaults } : {},
+    ...opts.cache ? { cache: opts.cache } : {},
+    ...opts.redirects ? { redirects: opts.redirects } : {},
+    ...opts.guards ? { guards: opts.guards } : {}
+  };
+  return createHttpClient(cfg);
+}
+
+export { ILLEGAL_INVOCATION_HINT, NetworkError, ParseError, RedirectError, TimeoutError, alertNotifier, apiKeyAuth, basicAuth, bearerAuth, consoleNotifier, cookieAuth, cookieSafeRefreshGuard, createApiKeyClient, createApiParserGraphQL, createApiParserLaravel, createApiParserNest, createApiParserRestClassic, createBasicClient, createBearerClient, createClient, createCookieClient, createHttpClient, createPresetBuilder, createShapeParser, createSimpleClient, fromZod, instrumentGuard, memoryCache, noAuth, retryGuard, schema, tailwindAlertRenderer, unauthorizedGuard };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map