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

package/README.md

@@ -35,12 +35,78 @@ 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.
+
 ## Redirects
 - `redirects: { mode: "follow" | "manual" | "error", maxHops, onRedirect }`
 

package/dist/guards/bearerRefreshGuard.d.ts

@@ -0,0 +1,45 @@
+import type { Guard } from "./types.js";
+import type { RequestContext } from "../internal/context.js";
+export type BearerRefreshTokens = {
+    accessToken: string;
+    refreshToken?: string;
+};
+export type BearerRefreshGuardOptions = {
+    /** Appelé sur 401 pour obtenir un nouveau token. */
+    refreshFn: () => Promise<BearerRefreshTokens>;
+    /** Appelé si le refresh échoue (logout, redirect login, etc.). */
+    onAuthFailed?: (error: unknown) => void | Promise<void>;
+    /**
+     * Hook optionnel : appelé avec le résultat de refreshFn() **avant** que les
+     * requêtes en queue ne soient rejouées. Permet à l'application de persister
+     * le nouveau token (localStorage, signal, etc.) de façon atomique.
+     *
+     * Si non fourni, le guard se contente de laisser `auth.getToken` retourner
+     * la nouvelle valeur (l'application doit donc l'avoir mise à jour ailleurs,
+     * typiquement dans `refreshFn` lui-même).
+     */
+    onTokenRefreshed?: (tokens: BearerRefreshTokens) => void | Promise<void>;
+    /**
+     * Ne pas tenter de refresh si la requête originale matche ce predicate.
+     * Ex: ne pas refresh sur `/auth/login`, `/auth/refresh`.
+     */
+    skipRefreshFor?: (ctx: RequestContext) => boolean;
+    /** Statuts qui déclenchent un refresh (défaut: [401]). */
+    triggerStatuses?: number[];
+    /** Délai max d'attente d'une requête en queue (défaut: 30_000 ms). */
+    queueTimeoutMs?: number;
+};
+/**
+ * Guard de refresh JWT Bearer avec queue / 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 :
+ * - si refresh OK → toutes sont rejouées avec le nouveau token (header
+ *   `Authorization` ré-injecté via `auth.getToken()`).
+ * - si refresh KO → toutes sont rejetées et `onAuthFailed(error)` est appelé
+ *   une seule fois.
+ *
+ * Anti-boucle : un retry n'engendre jamais un nouveau refresh.
+ */
+export declare function bearerRefreshGuard(opts: BearerRefreshGuardOptions): Guard;
+//# sourceMappingURL=bearerRefreshGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bearerRefreshGuard.d.ts","sourceRoot":"","sources":["../../src/guards/bearerRefreshGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,oDAAoD;IACpD,SAAS,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAE9C,kEAAkE;IAClE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC;IAElD,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAgBF;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,KAAK,CAgEzE"}

package/dist/guards/correlationIdGuard.d.ts

@@ -0,0 +1,18 @@
+import type { Guard } from "./types.js";
+export type CorrelationIdGuardOptions = {
+    /** Header pour l'ID corrélation (défaut: 'X-Correlation-Id'). */
+    headerName?: string;
+    /** Générateur d'ID (défaut: crypto.randomUUID si dispo, sinon fallback). */
+    generator?: () => string;
+    /** Si présent en réponse, copier dans `ctx.meta.correlationId`. */
+    readResponseHeader?: boolean;
+};
+/**
+ * Guard qui injecte un header `X-Correlation-Id` (UUID par défaut) sur chaque
+ * requête, et lit le header de réponse pour le copier dans `ctx.meta.correlationId`.
+ *
+ * L'ID est **stable entre retries** : un ID est généré une seule fois par
+ * requête originale (mémorisé sur le ctx), pour préserver la traçabilité.
+ */
+export declare function correlationIdGuard(opts?: CorrelationIdGuardOptions): Guard;
+//# sourceMappingURL=correlationIdGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"correlationIdGuard.d.ts","sourceRoot":"","sources":["../../src/guards/correlationIdGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,yBAAyB,GAAG;IACtC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IAEzB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAqBF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,yBAA8B,GAAG,KAAK,CAwC9E"}

package/dist/guards/csrfGuard.d.ts

@@ -0,0 +1,25 @@
+import type { Guard } from "./types.js";
+export type CsrfGuardOptions = {
+    /** Lit `document.cookie` (browser only). Ex: 'csrf_token'. */
+    tokenFromCookie?: string;
+    /** Source custom (storage, signal, observable, etc.). */
+    tokenFromStorage?: () => string | null | Promise<string | null>;
+    /**
+     * Lit le token depuis un header de réponse précédent (mémorisé en interne).
+     * Ex: header 'X-CSRF-Token' renvoyé par /auth/login.
+     */
+    tokenFromHeader?: string;
+    /** Header HTTP à injecter (défaut: 'X-CSRF-Token'). */
+    headerName?: string;
+    /** Méthodes mutantes (défaut: ['POST', 'PUT', 'PATCH', 'DELETE']). */
+    applyTo?: string[];
+};
+/**
+ * Guard d'injection de header CSRF sur méthodes mutantes.
+ *
+ * SSR-safety : si `tokenFromCookie` est utilisé hors browser, le guard skippe
+ * silencieusement (pas de header injecté). Combiner avec `tokenFromStorage`
+ * pour fournir un fallback côté serveur.
+ */
+export declare function csrfGuard(opts?: CsrfGuardOptions): Guard;
+//# sourceMappingURL=csrfGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csrfGuard.d.ts","sourceRoot":"","sources":["../../src/guards/csrfGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAChE;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAwBF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,gBAAqB,GAAG,KAAK,CAqD5D"}

package/dist/guards/idempotencyGuard.d.ts

@@ -0,0 +1,25 @@
+import type { Guard } from "./types.js";
+export type IdempotencyGuardOptions = {
+    /** Header (défaut: 'X-Idempotency-Key'). */
+    headerName?: string;
+    /** Méthodes ciblées (défaut: ['POST', 'PUT', 'PATCH']). */
+    applyTo?: string[];
+    /** Générateur (défaut: crypto.randomUUID si dispo, sinon fallback). */
+    generator?: () => string;
+    /**
+     * Si l'utilisateur fournit déjà une key (via `RequestOptions.idempotencyKey`,
+     * via `ctx.idempotencyKey`, via `ctx.meta.idempotencyKey` ou directement
+     * via header), la respecter (défaut: true).
+     */
+    respectExisting?: boolean;
+};
+/**
+ * Guard qui injecte un header `X-Idempotency-Key` (UUID par défaut) sur les
+ * méthodes mutantes (POST/PUT/PATCH).
+ *
+ * **Stable entre retries** : la clé est générée une seule fois par requête
+ * originale (mémorisée sur le ctx) ; rejouer la même requête utilise donc la
+ * même clé — sinon l'idempotence côté serveur est cassée.
+ */
+export declare function idempotencyGuard(opts?: IdempotencyGuardOptions): Guard;
+//# sourceMappingURL=idempotencyGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idempotencyGuard.d.ts","sourceRoot":"","sources":["../../src/guards/idempotencyGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,uBAAuB,GAAG;IACpC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IAEzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAoBF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG,KAAK,CAqC1E"}

package/dist/index.cjs

@@ -857,6 +857,250 @@ function cookieSafeRefreshGuard(opts) {
   }
 }
 
+// src/guards/bearerRefreshGuard.ts
+var REFRESH_FLAG2 = "__hg_bearer_refresh_in_flight__";
+var RETRY_FLAG2 = "__hg_bearer_refresh_retry__";
+function isReplayableBody2(body) {
+  if (body == null) return true;
+  if (typeof body === "string") return true;
+  if (typeof Blob !== "undefined" && body instanceof Blob) return true;
+  if (typeof FormData !== "undefined" && body instanceof FormData) return true;
+  if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) return true;
+  if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) return true;
+  if (typeof Uint8Array !== "undefined" && body instanceof Uint8Array) return true;
+  return false;
+}
+function bearerRefreshGuard(opts) {
+  const trigger = new Set(opts.triggerStatuses ?? [401]);
+  const queueTimeoutMs = opts.queueTimeoutMs ?? 3e4;
+  let refreshPromise = null;
+  return async (ctx, next) => {
+    const anyCtx = ctx;
+    if (ctx.noAuth) return next(ctx);
+    if (ctx.auth.mode !== "bearer") return next(ctx);
+    if (opts.skipRefreshFor?.(ctx)) return next(ctx);
+    if (anyCtx[RETRY_FLAG2]) return next(ctx);
+    if (anyCtx[REFRESH_FLAG2]) return next(ctx);
+    const res = await next(ctx);
+    if (!trigger.has(res.status)) return res;
+    if (!isReplayableBody2(ctx.body)) return res;
+    try {
+      await withTimeout(
+        refreshPromise ??= runRefresh(opts).finally(() => {
+          refreshPromise = null;
+        }),
+        queueTimeoutMs
+      );
+    } catch {
+      return res;
+    }
+    const retryCtx = cloneCtxForReplay(ctx);
+    retryCtx[RETRY_FLAG2] = true;
+    await applyBearerAuth(retryCtx, ctx.auth);
+    return next(retryCtx);
+  };
+  async function runRefresh(o) {
+    try {
+      const tokens = await o.refreshFn();
+      if (o.onTokenRefreshed) await o.onTokenRefreshed(tokens);
+      return tokens;
+    } catch (e) {
+      if (o.onAuthFailed) {
+        try {
+          await o.onAuthFailed(e);
+        } catch {
+        }
+      }
+      throw e;
+    }
+  }
+}
+function cloneCtxForReplay(ctx) {
+  return Object.assign({}, ctx, { attempt: ctx.attempt + 1 });
+}
+async function applyBearerAuth(ctx, auth) {
+  const headerName = auth.headerName ?? "Authorization";
+  const prefix = auth.prefix ?? "Bearer";
+  const token = await auth.getToken();
+  if (token == null || token === "") {
+    ctx.headers.delete(headerName);
+    return;
+  }
+  ctx.headers.set(headerName, prefix ? `${prefix} ${token}` : String(token));
+}
+function withTimeout(p, ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return p;
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(`bearerRefreshGuard: queue timeout after ${ms}ms`)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(t);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(t);
+        reject(e);
+      }
+    );
+  });
+}
+
+// src/guards/csrfGuard.ts
+var DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
+function readCookie(name) {
+  if (typeof document === "undefined") return null;
+  const cookieStr = document.cookie;
+  if (typeof cookieStr !== "string" || cookieStr.length === 0) return null;
+  const target = encodeURIComponent(name);
+  const parts = cookieStr.split(";");
+  for (const part of parts) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const k = part.slice(0, eq).trim();
+    if (k === name || k === target) {
+      return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+  }
+  return null;
+}
+function csrfGuard(opts = {}) {
+  const headerName = opts.headerName ?? "X-CSRF-Token";
+  const methods = new Set((opts.applyTo ?? DEFAULT_METHODS).map((m) => m.toUpperCase()));
+  let cachedHeaderToken = null;
+  return async (ctx, next) => {
+    if (!methods.has(ctx.method)) return next(ctx);
+    if (ctx.headers.has(headerName)) {
+      const res2 = await next(ctx);
+      maybeReadResponseHeader(res2);
+      return res2;
+    }
+    const token = await resolveToken();
+    if (token != null && token !== "") {
+      ctx.headers.set(headerName, token);
+    }
+    const res = await next(ctx);
+    maybeReadResponseHeader(res);
+    return res;
+  };
+  async function resolveToken(_ctx) {
+    if (opts.tokenFromCookie) {
+      const t = readCookie(opts.tokenFromCookie);
+      if (t != null && t !== "") return t;
+    }
+    if (opts.tokenFromHeader && cachedHeaderToken != null) {
+      return cachedHeaderToken;
+    }
+    if (opts.tokenFromStorage) {
+      try {
+        const t = await opts.tokenFromStorage();
+        if (t != null && t !== "") return t;
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+  function maybeReadResponseHeader(res) {
+    if (!opts.tokenFromHeader) return;
+    try {
+      const v = res.headers?.get?.(opts.tokenFromHeader);
+      if (v != null && v !== "") cachedHeaderToken = v;
+    } catch {
+    }
+  }
+}
+
+// src/guards/correlationIdGuard.ts
+var CORRELATION_FLAG = "__hg_correlation_id__";
+function defaultGenerator() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    try {
+      return c.randomUUID();
+    } catch {
+    }
+  }
+  const ts = Date.now().toString(36);
+  const r1 = Math.floor(Math.random() * 4294967295).toString(36);
+  const r2 = Math.floor(Math.random() * 4294967295).toString(36);
+  return `${ts}-${r1}${r2}`;
+}
+function correlationIdGuard(opts = {}) {
+  const headerName = opts.headerName ?? "X-Correlation-Id";
+  const generator = opts.generator ?? defaultGenerator;
+  const readResponseHeader = opts.readResponseHeader ?? true;
+  return async (ctx, next) => {
+    const anyCtx = ctx;
+    let id = anyCtx[CORRELATION_FLAG] ?? void 0;
+    if (id == null) {
+      const existing = ctx.headers.get(headerName);
+      id = existing != null && existing !== "" ? existing : generator();
+      anyCtx[CORRELATION_FLAG] = id;
+    }
+    if (!ctx.headers.has(headerName)) {
+      ctx.headers.set(headerName, id);
+    }
+    if (!ctx.meta) ctx.meta = {};
+    if (!ctx.meta.correlationId) ctx.meta.correlationId = id;
+    const res = await next(ctx);
+    if (readResponseHeader) {
+      try {
+        const v = res.headers?.get?.(headerName);
+        if (v != null && v !== "") {
+          if (!ctx.meta) ctx.meta = {};
+          ctx.meta.correlationId = v;
+        }
+      } catch {
+      }
+    }
+    return res;
+  };
+}
+
+// src/guards/idempotencyGuard.ts
+var DEFAULT_METHODS2 = ["POST", "PUT", "PATCH"];
+var IDEMPOTENCY_FLAG = "__hg_idempotency_key__";
+function defaultGenerator2() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    try {
+      return c.randomUUID();
+    } catch {
+    }
+  }
+  const ts = Date.now().toString(36);
+  const r1 = Math.floor(Math.random() * 4294967295).toString(36);
+  const r2 = Math.floor(Math.random() * 4294967295).toString(36);
+  return `${ts}-${r1}${r2}`;
+}
+function idempotencyGuard(opts = {}) {
+  const headerName = opts.headerName ?? "X-Idempotency-Key";
+  const methods = new Set((opts.applyTo ?? DEFAULT_METHODS2).map((m) => m.toUpperCase()));
+  const generator = opts.generator ?? defaultGenerator2;
+  const respectExisting = opts.respectExisting ?? true;
+  return async (ctx, next) => {
+    if (!methods.has(ctx.method)) return next(ctx);
+    const anyCtx = ctx;
+    let key = anyCtx[IDEMPOTENCY_FLAG] ?? void 0;
+    if (key == null && respectExisting) {
+      const fromHeader = ctx.headers.get(headerName);
+      if (fromHeader != null && fromHeader !== "") {
+        key = fromHeader;
+      } else if (ctx.idempotencyKey != null && ctx.idempotencyKey !== "") {
+        key = ctx.idempotencyKey;
+      } else if (ctx.meta?.idempotencyKey != null && ctx.meta.idempotencyKey !== "") {
+        key = ctx.meta.idempotencyKey;
+      }
+    }
+    if (key == null) key = generator();
+    anyCtx[IDEMPOTENCY_FLAG] = key;
+    if (!ctx.headers.has(headerName)) ctx.headers.set(headerName, key);
+    if (!ctx.meta) ctx.meta = {};
+    if (!ctx.meta.idempotencyKey) ctx.meta.idempotencyKey = key;
+    return next(ctx);
+  };
+}
+
 // src/guards/unauthorizedGuard.ts
 function normalizePath2(url) {
   try {
@@ -904,8 +1148,8 @@ function unauthorizedGuard(opts) {
 }
 
 // src/guards/instrumentGuard.ts
-var REFRESH_FLAG2 = "__hg_is_refresh__";
-var RETRY_FLAG2 = "__hg_refresh_retry__";
+var REFRESH_FLAG3 = "__hg_is_refresh__";
+var RETRY_FLAG3 = "__hg_refresh_retry__";
 function safeUrl(u) {
   try {
     const url = new URL(u);
@@ -949,8 +1193,8 @@ function instrumentGuard(opts, guard) {
     }
     const anyCtx = ctx;
     const attempt = ctx.attempt ?? 0;
-    const isRefresh = Boolean(anyCtx[REFRESH_FLAG2]);
-    const retryCount = Number(anyCtx[RETRY_FLAG2] ?? 0);
+    const isRefresh = Boolean(anyCtx[REFRESH_FLAG3]);
+    const retryCount = Number(anyCtx[RETRY_FLAG3] ?? 0);
     const noAuth2 = Boolean(ctx.noAuth);
     const baseLine = `[HG][#${id}][${opts.name}]`;
     log(`${baseLine} \u25B6 start`, {
@@ -1186,6 +1430,78 @@ function createApiParserGraphQL(opts) {
   });
 }
 
+// src/parsing/apiParserStructured.ts
+function isRecord(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function pickString(o, key) {
+  const v = o[key];
+  return typeof v === "string" ? v : void 0;
+}
+function createApiParserStructured(opts = {}) {
+  const exposeMeta = opts.exposeMeta ?? true;
+  const honorRetryableHint = opts.honorRetryableHint ?? true;
+  return createShapeParser({
+    isSuccess: (raw, status) => {
+      if (isRecord(raw) && "success" in raw) return raw["success"] === true;
+      return status >= 200 && status < 400;
+    },
+    getData: (raw) => {
+      if (isRecord(raw) && raw["success"] === true && "data" in raw) {
+        return raw["data"];
+      }
+      return raw;
+    },
+    getErrors: (raw, status) => {
+      if (!isRecord(raw)) {
+        return [{ message: status ? `HTTP ${status}` : "Request failed" }];
+      }
+      const env = raw;
+      const meta = isRecord(env["meta"]) ? env["meta"] : void 0;
+      const traceId = meta?.traceId;
+      const spanId = meta?.spanId;
+      const issues = Array.isArray(env["issues"]) ? env["issues"] : [];
+      const topMessage = pickString(env, "message");
+      const topCode = pickString(env, "code");
+      const topI18n = isRecord(env["i18n"]) ? env["i18n"] : void 0;
+      const baseDetails = (extra = {}) => ({
+        ...traceId !== void 0 ? { traceId } : {},
+        ...spanId !== void 0 ? { spanId } : {},
+        ...exposeMeta ? { envelope: env } : {},
+        ...extra
+      });
+      if (issues.length > 0) {
+        return issues.map((iss) => {
+          const message = iss.message ?? topMessage ?? (status ? `HTTP ${status}` : "Request failed");
+          const code = iss.code ?? topCode;
+          const issueDetails = baseDetails({
+            ...iss.category !== void 0 ? { category: iss.category } : {},
+            ...iss.severity !== void 0 ? { severity: iss.severity } : {},
+            ...honorRetryableHint && iss.retryable !== void 0 ? { retryable: iss.retryable } : {},
+            ...iss.i18n !== void 0 ? { i18n: iss.i18n } : topI18n !== void 0 ? { i18n: topI18n } : {}
+          });
+          return {
+            message,
+            ...code !== void 0 ? { code } : {},
+            ...iss.field !== void 0 ? { field: iss.field } : {},
+            details: issueDetails
+          };
+        });
+      }
+      const details = baseDetails({
+        ...topI18n !== void 0 ? { i18n: topI18n } : {}
+      });
+      return [
+        {
+          message: topMessage ?? (status ? `HTTP ${status}` : "Request failed"),
+          ...topCode !== void 0 ? { code: topCode } : {},
+          details
+        }
+      ];
+    }
+  });
+}
+
 // src/presets/presetBuilder.ts
 function createPresetBuilder(init) {
   const state = {
@@ -1385,14 +1701,17 @@ exports.alertNotifier = alertNotifier;
 exports.apiKeyAuth = apiKeyAuth;
 exports.basicAuth = basicAuth;
 exports.bearerAuth = bearerAuth;
+exports.bearerRefreshGuard = bearerRefreshGuard;
 exports.consoleNotifier = consoleNotifier;
 exports.cookieAuth = cookieAuth;
 exports.cookieSafeRefreshGuard = cookieSafeRefreshGuard;
+exports.correlationIdGuard = correlationIdGuard;
 exports.createApiKeyClient = createApiKeyClient;
 exports.createApiParserGraphQL = createApiParserGraphQL;
 exports.createApiParserLaravel = createApiParserLaravel;
 exports.createApiParserNest = createApiParserNest;
 exports.createApiParserRestClassic = createApiParserRestClassic;
+exports.createApiParserStructured = createApiParserStructured;
 exports.createBasicClient = createBasicClient;
 exports.createBearerClient = createBearerClient;
 exports.createClient = createClient;
@@ -1401,7 +1720,9 @@ exports.createHttpClient = createHttpClient;
 exports.createPresetBuilder = createPresetBuilder;
 exports.createShapeParser = createShapeParser;
 exports.createSimpleClient = createSimpleClient;
+exports.csrfGuard = csrfGuard;
 exports.fromZod = fromZod;
+exports.idempotencyGuard = idempotencyGuard;
 exports.instrumentGuard = instrumentGuard;
 exports.memoryCache = memoryCache;
 exports.noAuth = noAuth;