@cedvict/http-guardian 0.0.1-next.0 → 0.0.1-next.10

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
 ```
@@ -31,14 +35,233 @@ else console.error(res.errors);
 - `createApiParserLaravel()`
 - `createApiParserNest()`
 - `createApiParserGraphQL({ allowPartialData? })`
+- `createApiParserStructured({ exposeMeta?, honorRetryableHint? })` — parser
+  pour une enveloppe structurée typée :
+  `{ success, code, message, issues[], i18n, meta { traceId, spanId } }`.
+  En cas d'erreur, chaque `AppError` porte `code`/`message` et expose dans
+  `details` les champs structurés (`category`, `severity`, `retryable`, `i18n`,
+  `traceId`, `spanId`, `envelope`).
 
 ## Auth modes
 - `bearerAuth(() => token)`
 - `cookieAuth({ credentials: "include", csrf: { headerName, getToken } })`
 - `noAuth()`
 
+## Guards
+
+Les guards composent un middleware autour de chaque requête.
+
+### `bearerRefreshGuard({ refreshFn, onAuthFailed?, ... })`
+
+Refresh JWT Bearer **single-flight** : sur 401, un seul `refreshFn()` est invoqué ;
+toutes les autres requêtes 401 reçues pendant ce refresh attendent dans une queue
+partagée puis sont rejouées avec le nouveau token. Si le refresh échoue,
+`onAuthFailed(error)` est appelé une seule fois et toutes les requêtes en queue
+voient le 401 d'origine.
+
+```ts
+import { createHttpClient, bearerAuth, bearerRefreshGuard } from "@cedvict/http-guardian";
+
+createHttpClient({
+  auth: bearerAuth(() => tokenStore.access()),
+  guards: [
+    bearerRefreshGuard({
+      refreshFn: async () => {
+        const { accessToken, refreshToken } = await api.refresh();
+        tokenStore.set(accessToken, refreshToken);
+        return { accessToken, refreshToken };
+      },
+      onAuthFailed: () => router.navigate("/login"),
+      skipRefreshFor: (ctx) => ctx.url.includes("/auth/"),
+    }),
+  ],
+});
+```
+
+### `csrfGuard({ tokenFromCookie?, tokenFromStorage?, tokenFromHeader?, headerName?, applyTo? })`
+
+Injecte un header `X-CSRF-Token` (défaut) sur les méthodes mutantes
+(`POST`/`PUT`/`PATCH`/`DELETE`). **SSR-safe** : si `tokenFromCookie` est utilisé
+hors browser (`typeof document === 'undefined'`), le guard skippe silencieusement.
+
+```ts
+csrfGuard(
+  isPlatformBrowser(platformId)
+    ? { tokenFromCookie: "csrf_token" }
+    : { tokenFromStorage: () => null },
+);
+```
+
+### `correlationIdGuard({ headerName?, generator?, readResponseHeader? })`
+
+Injecte un header `X-Correlation-Id` (UUID v4 par défaut, fallback
+`Math.random()`+timestamp si `crypto.randomUUID` absent). L'ID est **stable
+entre retries** (mémorisé sur le ctx). Si la réponse contient le même header,
+il est copié dans `ctx.meta.correlationId` pour les plugins downstream
+(logger, sentry, otel).
+
+### `idempotencyGuard({ headerName?, applyTo?, respectExisting? })`
+
+Injecte un header `X-Idempotency-Key` (UUID par défaut) sur `POST`/`PUT`/`PATCH`.
+La clé est **stable entre retries** — sinon l'idempotence côté serveur est cassée.
+Respecte une clé fournie via `RequestOptions.idempotencyKey`,
+`ctx.idempotencyKey`, ou directement via header.
+
+## Recipe : mapper le `traceId` backend ↔ Sentry / OTel frontend
+
+Quand le backend renvoie une enveloppe avec un `meta.traceId` (et `spanId`)
+— typiquement via `createApiParserStructured` — il est utile de stitcher cette
+trace avec le span/event front-end pour qu'un incident Sentry pointe directement
+vers la trace backend correspondante (et inversement).
+
+Le pattern repose sur deux briques :
+1. **`correlationIdGuard`** génère un `X-Correlation-Id` propagé sur la requête,
+   et lit le header de réponse pour exposer l'ID dans `ctx.meta.correlationId`.
+2. **`createApiParserStructured`** stocke `traceId` / `spanId` dans
+   `errors[].details` (en cas d'erreur). Pour les chemins succès, on lit le
+   header de réponse via un petit guard dédié.
+
+```ts
+import {
+  createHttpClient,
+  bearerAuth,
+  correlationIdGuard,
+  createApiParserStructured,
+  type Guard,
+} from "@cedvict/http-guardian";
+import { sentryPlugin } from "@cedvict/http-guardian-plugin-sentry";
+import { otelPlugin } from "@cedvict/http-guardian-plugin-otel";
+import * as Sentry from "@sentry/browser";
+
+// Lit X-Trace-Id / X-Span-Id de la réponse et les pose sur ctx.meta pour
+// les plugins downstream (sentry, otel, logger).
+const traceMetaGuard: Guard = async (ctx, next) => {
+  const res = await next(ctx);
+  const traceId = res.headers.get("x-trace-id");
+  const spanId = res.headers.get("x-span-id");
+  if (traceId || spanId) {
+    ctx.meta ??= {};
+    if (traceId) ctx.meta.traceId = traceId;
+    if (spanId) ctx.meta.spanId = spanId;
+  }
+  return res;
+};
+
+const api = createHttpClient({
+  baseUrl: "https://api.example.com",
+  auth: bearerAuth(() => token),
+  parser: createApiParserStructured(),
+  guards: [correlationIdGuard(), traceMetaGuard],
+  plugins: [
+    sentryPlugin({
+      // shouldCapture reçoit le ctx → on lit ctx.meta pour tagger l'event Sentry.
+      shouldCapture: ({ status, ctx }) => {
+        if (status && status >= 500) {
+          Sentry.getCurrentScope().setTags({
+            "backend.trace_id": ctx.meta?.traceId ?? "",
+            correlation_id: ctx.meta?.correlationId ?? "",
+          });
+          return true;
+        }
+        return false;
+      },
+    }),
+    otelPlugin({
+      setAttributes: (span, ctx) => {
+        if (ctx.meta?.traceId) span.setAttribute("backend.trace_id", ctx.meta.traceId);
+        if (ctx.meta?.spanId) span.setAttribute("backend.span_id", ctx.meta.spanId);
+        if (ctx.meta?.correlationId) span.setAttribute("correlation_id", ctx.meta.correlationId);
+      },
+    }),
+  ],
+});
+```
+
+Côté erreur, l'enveloppe parsée par `createApiParserStructured` expose déjà
+`traceId` / `spanId` dans `result.errors[0].details` :
+
+```ts
+const r = await api.post("/orders", { json: payload });
+if (!r.ok) {
+  const d = r.errors[0]?.details as { traceId?: string; spanId?: string } | undefined;
+  console.error("backend trace:", d?.traceId, d?.spanId);
+}
+```
+
 ## Redirects
 - `redirects: { mode: "follow" | "manual" | "error", maxHops, onRedirect }`
 
 ## 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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"}