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

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on *Keep a Changelog*, and this project adheres to *Semantic Versioning*.
+
+## Unreleased
+
+### Contract (security)
+
+- Refresh single-flight: concurrent 401s trigger only one refresh request.
+- Refresh cooldown: honor `429` + `Retry-After` to prevent refresh storms.
+- Refresh path resolution: absolute refresh URLs are preserved; relative paths are resolved against `baseUrl`.
+- Bootstrap flow: `/auth/me` 401 → refresh → replay once (maxRetry=1).
+- No refresh on network errors (fetch/CORS/abort throws): no replay, no refresh.
+- Anti-loop: refresh+replay never triggers a second refresh for the same request attempt.
+
+
+### DX (presets, aliases, plugins)
+
+- Preset builder and alias factories are contract-tested (stable DX surface).
+- Cookie refresh remains opt-in; bearer auth never refreshes by default.
+- Plugins are applied synchronously in order and de-duplicated by name (first wins).

package/LICENSE

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

@@ -3,6 +3,10 @@
 Core HTTP client (Promises) built on `fetch`.
 
 ## Install
+
+**Runtime requirement:** Node **>= 22** (or any modern browser/edge runtime with `fetch`).
+
+If you run in an environment without a global `fetch`, pass one explicitly via `createHttpClient({ fetch })`.
 ```bash
 npm i @cedvict/http-guardian
 ```
@@ -42,3 +46,75 @@ else console.error(res.errors);
 
 ## Testing
 See `TESTING.md`.
+
+
+## Cookie session refresh guard (single-flight, cooldown, anti-loop)
+If you use cookie-based auth and your backend exposes a refresh endpoint, you can add the safe refresh guard:
+
+```ts
+import { createHttpClient, cookieAuth, cookieSafeRefreshGuard, createApiParserRestClassic } from "@cedvict/http-guardian";
+
+const api = createHttpClient({
+  baseUrl: "https://api.example.com",
+  auth: cookieAuth({ credentials: "include" }),
+  parser: createApiParserRestClassic(),
+  guards: [
+    cookieSafeRefreshGuard({
+      refreshPath: "/auth/refresh", // or absolute: "https://auth.example.com/refresh"
+      maxRetry: 1,                  // anti-loop (default)
+      honorRetryAfter: true         // cooldown on 429 (default)
+    })
+  ],
+});
+```
+
+You can disable any auth/refresh behavior per-request with `noAuth: true`:
+
+```ts
+await api.get("/public/health", { noAuth: true });
+```
+
+## Notifier redaction (optional)
+If you provide a custom notifier and it logs/sends events to telemetry, you can add a `redact` function
+to strip secrets from the event payload (e.g. query params in `url`):
+
+```ts
+import type { Notifier, NotifyEvent } from "@cedvict/http-guardian";
+
+const notifier: Notifier = {
+  redact: (e: NotifyEvent) => ({ ...e, url: e.url.replace(/\?.*$/, "") }),
+  notify: (e) => console.error(e),
+};
+```
+
+## Preset builder & aliases (stable DX)
+
+If you want a 1-liner setup without losing access to `createHttpClient`, use the preset builder:
+
+```ts
+import { createPresetBuilder } from "@cedvict/http-guardian";
+
+const api = createPresetBuilder({ baseUrl: "https://api.example.com" })
+  .cookie({ credentials: "include" })
+  // opt-in only:
+  // .cookieRefresh({ refreshPath: "/auth/refresh", mePath: "/auth/me" })
+  .create();
+```
+
+Aliases (thin wrappers around the preset builder):
+
+- `createCookieClient({ baseUrl, refresh?: CookieSafeRefreshGuardOptions | null, ... })`
+- `createBearerClient({ baseUrl, getToken, ... })`
+
+### Stable auth refresh policy
+
+- **Cookie auth**: refresh is **opt-in** (add `cookieRefresh(...)` or pass `refresh` to `createCookieClient`).
+- **Bearer auth**: refresh is **disabled by default**.
+
+## Plugins (config-time)
+
+`plugins` are applied synchronously during `createHttpClient(...)` to mutate a draft options object.
+
+Contract:
+- Applied **in order**
+- De-duplicated by `name` (first wins)

package/dist/aliases.d.ts

@@ -0,0 +1,35 @@
+import type { HttpClientOptions } from "./client/types.js";
+import type { ShapeParser } from "./parsing/shapeParser.js";
+import type { AuthConfig } from "./auth/authConfig.js";
+import type { Notifier } from "./notify/types.js";
+/**
+ * Alias A: minimal, safe defaults.
+ *
+ * Goal: `createHttpClient` stays максимально configurable,
+ * while `createClient` offers a “works out of the box” path.
+ */
+export type CreateClientOptions = {
+    baseUrl: string;
+    /** Default: createApiParserRestClassic() */
+    parser?: ShapeParser;
+    /** Default: noAuth() */
+    auth?: AuthConfig;
+    fetch?: HttpClientOptions["fetch"];
+    notifier?: Notifier;
+    defaults?: HttpClientOptions["defaults"];
+    cache?: HttpClientOptions["cache"];
+    redirects?: HttpClientOptions["redirects"];
+    guards?: HttpClientOptions["guards"];
+};
+export declare function createClient(opts: CreateClientOptions): {
+    get: <T>(path: string, ro?: import("./publicTypes.js").RequestOptions<T>) => Promise<import("./publicTypes.js").ClientResult<T>>;
+    post: <T>(path: string, ro?: import("./publicTypes.js").RequestOptions<T>) => Promise<import("./publicTypes.js").ClientResult<T>>;
+    put: <T>(path: string, ro?: import("./publicTypes.js").RequestOptions<T>) => Promise<import("./publicTypes.js").ClientResult<T>>;
+    patch: <T>(path: string, ro?: import("./publicTypes.js").RequestOptions<T>) => Promise<import("./publicTypes.js").ClientResult<T>>;
+    delete: <T>(path: string, ro?: import("./publicTypes.js").RequestOptions<T>) => Promise<import("./publicTypes.js").ClientResult<T>>;
+    cache: {
+        invalidateByTag: (tag: string) => number;
+        clear: () => void | undefined;
+    };
+};
+//# sourceMappingURL=aliases.d.ts.map

package/dist/aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wBAAwB;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;CACtC,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB;;;;;;;;;;EAmBrD"}

package/dist/auth/authConfig.d.ts

@@ -0,0 +1,91 @@
+export type BearerAuthConfig = {
+    mode: "bearer";
+    getToken: () => string | null | Promise<string | null>;
+    headerName?: string;
+    prefix?: string;
+    /**
+     * Security hardening: only attach auth headers if request origin is allowed.
+     * If omitted: only same-origin as the client's baseUrl is allowed.
+     */
+    allowedOrigins?: string[] | ((url: string) => boolean);
+};
+export type CookieAuthConfig = {
+    mode: "cookie";
+    /**
+     * Sets RequestInit.credentials for every request.
+     * Use "include" for cross-site cookies.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Optional CSRF support for cookie-based sessions.
+     * If provided, a header will be injected on non-GET requests.
+     */
+    csrf?: {
+        headerName: string;
+        getToken: () => string | null | Promise<string | null>;
+    };
+};
+export type BasicAuthConfig = {
+    mode: "basic";
+    /**
+     * Return either { username, password } or a pre-encoded "user:pass" string.
+     * Return null to skip auth.
+     */
+    getCredentials: () => {
+        username: string;
+        password: string;
+    } | string | null | Promise<{
+        username: string;
+        password: string;
+    } | string | null>;
+    headerName?: string;
+    prefix?: string;
+    /**
+     * Security hardening: only attach auth headers if request origin is allowed.
+     * If omitted: only same-origin as the client's baseUrl is allowed.
+     */
+    allowedOrigins?: string[] | ((url: string) => boolean);
+};
+export type ApiKeyAuthConfig = {
+    mode: "apiKey";
+    getKey: () => string | null | Promise<string | null>;
+    /**
+     * Header to use for API key auth (default: "X-API-Key").
+     * You can also set to "Authorization" and use prefix.
+     */
+    headerName?: string;
+    prefix?: string;
+    /**
+     * Security hardening: only attach API key header if request origin is allowed.
+     * If omitted: only same-origin as the client's baseUrl is allowed.
+     */
+    allowedOrigins?: string[] | ((url: string) => boolean);
+};
+export type NoneAuthConfig = {
+    mode: "none";
+};
+export type AuthConfig = BearerAuthConfig | CookieAuthConfig | BasicAuthConfig | ApiKeyAuthConfig | NoneAuthConfig;
+export declare function bearerAuth(getToken: () => string | null | Promise<string | null>, opts?: {
+    headerName?: string;
+    prefix?: string;
+    allowedOrigins?: BearerAuthConfig["allowedOrigins"];
+}): BearerAuthConfig;
+export declare function cookieAuth(opts?: {
+    credentials?: RequestCredentials;
+    csrf?: {
+        headerName: string;
+        getToken: () => string | null | Promise<string | null>;
+    };
+}): CookieAuthConfig;
+export declare function basicAuth(getCredentials: BasicAuthConfig["getCredentials"], opts?: {
+    headerName?: string;
+    prefix?: string;
+    allowedOrigins?: BasicAuthConfig["allowedOrigins"];
+}): BasicAuthConfig;
+export declare function apiKeyAuth(getKey: () => string | null | Promise<string | null>, opts?: {
+    headerName?: string;
+    prefix?: string;
+    allowedOrigins?: ApiKeyAuthConfig["allowedOrigins"];
+}): ApiKeyAuthConfig;
+export declare function noAuth(): NoneAuthConfig;
+//# sourceMappingURL=authConfig.d.ts.map

package/dist/auth/authConfig.d.ts.map

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

package/dist/cache/inFlight.d.ts

@@ -0,0 +1,10 @@
+/**
+ * In-flight request de-duplication.
+ */
+export declare class InFlight {
+    private readonly map;
+    get(key: string): Promise<unknown> | undefined;
+    set(key: string, p: Promise<unknown>): void;
+    clear(): void;
+}
+//# sourceMappingURL=inFlight.d.ts.map

package/dist/cache/inFlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inFlight.d.ts","sourceRoot":"","sources":["../../src/cache/inFlight.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuC;IAE3D,GAAG,CAAC,GAAG,EAAE,MAAM;IAIf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAOpC,KAAK;CAGN"}

package/dist/cache/key.d.ts

@@ -0,0 +1,10 @@
+import type { HeadersPolyfill } from "../internal/headersPolyfill.js";
+export declare function makeCacheKey(parts: {
+    method: string;
+    url: string;
+    headers?: Headers | HeadersPolyfill;
+    body?: unknown;
+    idempotencyKey?: string;
+    keyOverride?: string;
+}): string;
+//# sourceMappingURL=key.d.ts.map

package/dist/cache/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/cache/key.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEtE,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IAGZ,OAAO,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAkBT"}

package/dist/cache/memoryCache.d.ts

@@ -0,0 +1,16 @@
+import type { CacheStore } from "./types.js";
+/**
+ * Options for {@link memoryCache}.
+ */
+export type MemoryCacheOptions = {
+    /**
+     * Maximum number of entries kept in memory (LRU-ish).
+     * Default: 1000
+     */
+    maxEntries?: number;
+};
+/**
+ * Simple in-memory LRU-ish cache with tag invalidation.
+ */
+export declare function memoryCache(opts?: MemoryCacheOptions): CacheStore;
+//# sourceMappingURL=memoryCache.d.ts.map

package/dist/cache/memoryCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryCache.d.ts","sourceRoot":"","sources":["../../src/cache/memoryCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,UAAU,CAsFjE"}

package/dist/cache/types.d.ts

@@ -0,0 +1,13 @@
+export type CacheEntry = {
+    expiresAt: number;
+    value: unknown;
+    tags?: string[];
+};
+export type CacheStore = {
+    get: (key: string) => CacheEntry | undefined;
+    set: (key: string, entry: CacheEntry) => void;
+    delete: (key: string) => void;
+    invalidateByTag: (tag: string) => number;
+    clear: () => void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEhF,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IAC7C,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC"}

package/dist/client/errors.d.ts

@@ -0,0 +1,29 @@
+export type AppError = {
+    message: string;
+    code?: string;
+    field?: string;
+    details?: unknown;
+};
+export declare class NetworkError extends Error {
+    readonly cause?: unknown | undefined;
+    name: string;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class TimeoutError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+export declare class RedirectError extends Error {
+    readonly fromUrl: string;
+    readonly toUrl?: string | undefined;
+    name: string;
+    constructor(message: string, fromUrl: string, toUrl?: string | undefined);
+}
+export declare class ParseError extends Error {
+    readonly raw?: unknown | undefined;
+    readonly cause?: unknown | undefined;
+    name: string;
+    constructor(message: string, raw?: unknown | undefined, cause?: unknown | undefined);
+}
+export declare const ILLEGAL_INVOCATION_HINT = "Detected a browser fetch invocation error (\"Illegal invocation\"). This usually happens when passing a detached reference to window.fetch. Fix by configuring the client with fetch: (input, init) => window.fetch(input, init) or fetch: window.fetch.bind(window).";
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,qBAAa,YAAa,SAAQ,KAAK;aAEQ,KAAK,CAAC,EAAE,OAAO;IAD5D,IAAI,SAAkB;gBACV,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAG7D;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,SAAkB;gBACV,OAAO,SAAsB;CAG1C;AAED,qBAAa,aAAc,SAAQ,KAAK;aAEO,OAAO,EAAE,MAAM;aAAkB,KAAK,CAAC,EAAE,MAAM;IAD5F,IAAI,SAAmB;gBACX,OAAO,EAAE,MAAM,EAAkB,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,MAAM,YAAA;CAG7F;AAED,qBAAa,UAAW,SAAQ,KAAK;aAEU,GAAG,CAAC,EAAE,OAAO;aAAkB,KAAK,CAAC,EAAE,OAAO;IAD3F,IAAI,SAAgB;gBACR,OAAO,EAAE,MAAM,EAAkB,GAAG,CAAC,EAAE,OAAO,YAAA,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAG5F;AAGD,eAAO,MAAM,uBAAuB,0QAAwQ,CAAC"}

package/dist/client/httpClient.d.ts

@@ -0,0 +1,13 @@
+import type { HttpClientOptions, RequestOptions, ClientResult } from "./types.js";
+export declare function createHttpClient(options: HttpClientOptions): {
+    get: <T>(path: string, ro?: RequestOptions<T>) => Promise<ClientResult<T>>;
+    post: <T>(path: string, ro?: RequestOptions<T>) => Promise<ClientResult<T>>;
+    put: <T>(path: string, ro?: RequestOptions<T>) => Promise<ClientResult<T>>;
+    patch: <T>(path: string, ro?: RequestOptions<T>) => Promise<ClientResult<T>>;
+    delete: <T>(path: string, ro?: RequestOptions<T>) => Promise<ClientResult<T>>;
+    cache: {
+        invalidateByTag: (tag: string) => number;
+        clear: () => void | undefined;
+    };
+};
+//# sourceMappingURL=httpClient.d.ts.map

package/dist/client/httpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpClient.d.ts","sourceRoot":"","sources":["../../src/client/httpClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AA2C9F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB;UAoOjD,CAAC,QAAQ,MAAM,OAAO,cAAc,CAAC,CAAC,CAAC;WACtC,CAAC,QAAQ,MAAM,OAAO,cAAc,CAAC,CAAC,CAAC;UACxC,CAAC,QAAQ,MAAM,OAAO,cAAc,CAAC,CAAC,CAAC;YACrC,CAAC,QAAQ,MAAM,OAAO,cAAc,CAAC,CAAC,CAAC;aACtC,CAAC,QAAQ,MAAM,OAAO,cAAc,CAAC,CAAC,CAAC;;+BAChB,MAAM;;;EAEzC"}

package/dist/client/types.d.ts

@@ -0,0 +1,84 @@
+import type { AuthConfig } from "../auth/authConfig.js";
+import type { Guard } from "../guards/types.js";
+import type { CacheStore } from "../cache/types.js";
+import type { ShapeParser } from "../parsing/shapeParser.js";
+import type { Schema } from "../parsing/schemaAdapter.js";
+import type { Notifier } from "../notify/types.js";
+import type { AppError } from "./errors.js";
+import type { HttpPlugin } from "../plugins/types.js";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type RedirectMode = "follow" | "manual" | "error";
+export type RedirectPolicy = {
+    mode: RedirectMode;
+    maxHops?: number;
+    onRedirect?: (info: {
+        fromUrl: string;
+        toUrl: string;
+        status: number;
+        hop: number;
+        method: HttpMethod;
+    }) => {
+        action: "follow";
+    } | {
+        action: "deny";
+        reason?: string;
+    } | {
+        action: "modify";
+        url: string;
+    };
+};
+export type CacheOptions = {
+    ttlMs: number;
+    key?: string;
+    tags?: string[];
+    policy?: "networkFirst" | "cacheFirst" | "cacheOnly" | "networkOnly" | "staleWhileRevalidate";
+    dedupe?: boolean;
+};
+export type RequestOptions<T> = {
+    query?: Record<string, string | number | boolean | null | undefined>;
+    headers?: Record<string, string | undefined>;
+    json?: unknown;
+    body?: BodyInit;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    cache?: CacheOptions;
+    dataSchema?: Schema<T>;
+    notifier?: Notifier;
+    noAuth?: boolean;
+    idempotencyKey?: string;
+};
+export type ClientResult<T> = {
+    ok: true;
+    status: number;
+    headers: Headers;
+    data: T;
+    raw: unknown;
+    url: string;
+} | {
+    ok: false;
+    status: number;
+    headers: Headers;
+    errors: AppError[];
+    raw: unknown;
+    url: string;
+};
+export type HttpClientOptions = {
+    baseUrl: string;
+    fetch?: typeof fetch;
+    auth: AuthConfig;
+    parser: ShapeParser;
+    cache?: CacheStore;
+    notifier?: Notifier;
+    redirects?: RedirectPolicy;
+    plugins?: HttpPlugin[];
+    defaults?: {
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+        shouldNotify?: (result: {
+            ok: boolean;
+            status: number;
+        }) => boolean;
+    };
+    guards?: Guard[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

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

package/dist/guards/cookieSafeRefreshGuard.d.ts

@@ -0,0 +1,40 @@
+import type { Guard } from "./types.js";
+import type { RequestContext } from "../internal/context.js";
+export type CookieSafeRefreshGuardOptions = {
+    /**
+     * Endpoint refresh (absolu ou relatif)
+     * ex: "/auth/refresh" ou "https://api.example.com/auth/refresh"
+     */
+    refreshPath: string;
+    /** Méthode refresh (souvent POST) */
+    refreshMethod?: "POST" | "GET";
+    /** Statuts qui déclenchent refresh. Default: [401, 419] */
+    triggerStatuses?: number[];
+    /** Nombre max de replays de la requête originale. Default: 1 */
+    maxRetry?: number;
+    /**
+     * Exclure certains paths (pathname) de la logique refresh.
+     * Ex: ["/auth/refresh", "/health"]
+     */
+    excludePaths?: string[];
+    /**
+     * Si refresh renvoie 429 Too Many Requests,
+     * on stoppe les refresh jusqu’à une date (cooldown).
+     * Default: true
+     */
+    honorRetryAfter?: boolean;
+    /** Décider si on refresh selon ctx + status */
+    shouldRefresh?: (ctx: RequestContext, status: number) => boolean;
+    /** Hook: appelé quand refresh échoue (utile pour redirect login) */
+    onRefreshFailed?: (info: {
+        status?: number;
+        url: string;
+        reason?: string;
+    }) => void;
+    /** Hook: appelé quand refresh réussit */
+    onRefreshSuccess?: (info: {
+        url: string;
+    }) => void;
+};
+export declare function cookieSafeRefreshGuard(opts: CookieSafeRefreshGuardOptions): Guard;
+//# sourceMappingURL=cookieSafeRefreshGuard.d.ts.map

package/dist/guards/cookieSafeRefreshGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookieSafeRefreshGuard.d.ts","sourceRoot":"","sources":["../../src/guards/cookieSafeRefreshGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAO7D,MAAM,MAAM,6BAA6B,GAAG;IAC1C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAE/B,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,+CAA+C;IAC/C,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAEjE,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAEpF,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACpD,CAAC;AAoDF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,KAAK,CAyIjF"}

package/dist/guards/instrumentGuard.d.ts

@@ -0,0 +1,12 @@
+import type { Guard } from "./types.js";
+type InstrumentOptions = {
+    name: string;
+    log?: (line: string, data?: any) => void;
+    include?: RegExp;
+    exclude?: RegExp;
+    logInit?: boolean;
+    stack?: boolean;
+};
+export declare function instrumentGuard(opts: InstrumentOptions, guard: Guard): Guard;
+export {};
+//# sourceMappingURL=instrumentGuard.d.ts.map

package/dist/guards/instrumentGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentGuard.d.ts","sourceRoot":"","sources":["../../src/guards/instrumentGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AASxC,KAAK,iBAAiB,GAAG;IAEvB,IAAI,EAAE,MAAM,CAAC;IAGb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAGzC,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAIlB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AA0CF,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAiE5E"}

package/dist/guards/retryGuard.d.ts

@@ -0,0 +1,12 @@
+import type { Guard } from "./types.js";
+/**
+ * Simple retry guard for transient HTTP statuses.
+ * Note: this doesn't retry network errors thrown by fetch itself (those are handled by the client wrapper).
+ */
+export declare function retryGuard(opts?: {
+    retries?: number;
+    retryOn?: number[];
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}): Guard;
+//# sourceMappingURL=retryGuard.d.ts.map

package/dist/guards/retryGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryGuard.d.ts","sourceRoot":"","sources":["../../src/guards/retryGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAkB5H"}

package/dist/guards/types.d.ts

@@ -0,0 +1,3 @@
+import type { RequestContext } from "../internal/context.js";
+export type Guard = (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
+//# sourceMappingURL=types.d.ts.map

package/dist/guards/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guards/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC"}

package/dist/guards/unauthorizedGuard.d.ts

@@ -0,0 +1,19 @@
+import type { Guard } from "./types.js";
+import type { RequestContext } from "../internal/context.js";
+export type UnauthorizedGuardOptions = {
+    onUnauthorized: (ctx: {
+        url: string;
+        status: number;
+    }) => void;
+    statuses?: number[];
+    ignoreNoAuth?: boolean;
+    once?: boolean;
+    cooldownMs?: number;
+    shouldHandle?: (ctx: RequestContext, status: number) => boolean;
+    excludePaths?: string[];
+};
+/**
+ * Centralizes “unauthorized” handling (redirect/logout) with anti-spam.
+ */
+export declare function unauthorizedGuard(opts: UnauthorizedGuardOptions): Guard;
+//# sourceMappingURL=unauthorizedGuard.d.ts.map

package/dist/guards/unauthorizedGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorizedGuard.d.ts","sourceRoot":"","sources":["../../src/guards/unauthorizedGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAa7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,cAAc,EAAE,CAAC,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,KAAK,CA6CvE"}