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

package/dist/internal/context.d.ts

@@ -2,6 +2,27 @@ import type { HttpMethod } from "../client/types.js";
 import type { AuthConfig } from "../auth/authConfig.js";
 import type { Notifier } from "../notify/types.js";
 import type { HeadersPolyfill } from "./headersPolyfill.js";
+/**
+ * Meta side-channel attached to a RequestContext. Populated by guards (e.g.
+ * correlationIdGuard, idempotencyGuard) and parsers (envelope) so downstream
+ * plugins (logger, sentry, otel) can pick the values up without having to
+ * re-read headers.
+ *
+ * All fields are optional — a context without a `meta` object is valid and
+ * keeps backwards compatibility.
+ */
+export type RequestContextMeta = {
+    /** ID corrélation propagé en header (cf. correlationIdGuard). */
+    correlationId?: string;
+    /** Clé d'idempotence (cf. idempotencyGuard / RequestOptions.idempotencyKey). */
+    idempotencyKey?: string;
+    /** Trace ID lu depuis l'enveloppe de réponse (parser-dependent). */
+    traceId?: string;
+    /** Span ID lu depuis l'enveloppe de réponse (parser-dependent). */
+    spanId?: string;
+    /** Enveloppe brute exposée par le parser (cf. createApiParserStructured). */
+    envelope?: unknown;
+};
 export type RequestContext = {
     /**
      * Base URL configured on the client (always set by createHttpClient).
@@ -26,6 +47,11 @@ export type RequestContext = {
     noAuth?: boolean;
     notifier?: Notifier;
     idempotencyKey?: string;
+    /**
+     * Meta side-channel for guards/parsers/plugins. Always undefined unless a
+     * guard or parser populates it; consumers must check `ctx.meta != null`.
+     */
+    meta?: RequestContextMeta;
     _fetch: typeof fetch;
 };
 //# sourceMappingURL=context.d.ts.map

package/dist/internal/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/internal/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC;IACnC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,OAAO,KAAK,CAAC;CACtB,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/internal/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC;IACnC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,OAAO,KAAK,CAAC;CACtB,CAAC"}

package/dist/parsing/apiParserStructured.d.ts

@@ -0,0 +1,94 @@
+import type { ShapeParser } from "./shapeParser.js";
+/**
+ * Parser pour une enveloppe HTTP "structurée" : succès / erreurs typées avec
+ * `issues[]`, `i18n`, et `meta { traceId, spanId, timestamp }`.
+ *
+ * Cette forme est typique des backends qui exposent un protocole d'erreur
+ * uniforme (FastAPI, NestJS custom, etc.) avec :
+ * - une distinction `success: boolean`
+ * - une liste d'issues structurées (code, message, category, severity,
+ *   retryable, i18n)
+ * - un bloc meta de tracing (traceId, spanId)
+ *
+ * @example
+ * // Succès
+ * { "success": true, "data": { ... }, "meta": { "traceId": "...", "timestamp": "..." } }
+ *
+ * @example
+ * // Erreur
+ * {
+ *   "success": false,
+ *   "code": "AUTH_OTP_INVALID",
+ *   "message": "Auth otp invalid",
+ *   "issues": [
+ *     {
+ *       "code": "AUTH_OTP_INVALID",
+ *       "message": "...",
+ *       "category": "auth",
+ *       "severity": "error",
+ *       "retryable": false,
+ *       "i18n": { "key": "auth.otp_invalid", "params": {}, "locale": null }
+ *     }
+ *   ],
+ *   "i18n": { "key": "...", "params": {}, "locale": null },
+ *   "meta": { "traceId": "...", "spanId": "...", "timestamp": "..." }
+ * }
+ */
+export type StructuredI18n = {
+    key?: string;
+    params?: Record<string, unknown>;
+    locale?: string | null;
+};
+export type StructuredIssue = {
+    code?: string;
+    message?: string;
+    category?: string;
+    severity?: string;
+    retryable?: boolean;
+    i18n?: StructuredI18n;
+    field?: string;
+};
+export type StructuredEnvelopeMeta = {
+    traceId?: string;
+    spanId?: string;
+    timestamp?: string;
+    [k: string]: unknown;
+};
+export type StructuredSuccessEnvelope<T = unknown> = {
+    success: true;
+    data: T;
+    meta?: StructuredEnvelopeMeta;
+};
+export type StructuredErrorEnvelope = {
+    success: false;
+    code?: string;
+    message?: string;
+    issues?: StructuredIssue[];
+    i18n?: StructuredI18n;
+    meta?: StructuredEnvelopeMeta;
+};
+export type StructuredEnvelope<T = unknown> = StructuredSuccessEnvelope<T> | StructuredErrorEnvelope;
+export type ApiParserStructuredOptions = {
+    /** Garde l'enveloppe `meta` accessible via `AppError.details.envelope`. */
+    exposeMeta?: boolean;
+    /**
+     * Pour les erreurs avec `retryable: false`, marquer la requête comme
+     * non-retryable (via `details.retryable`). Le retry plugin peut consulter
+     * ce flag via un `isRetryableRequest` custom — voir docs.
+     */
+    honorRetryableHint?: boolean;
+};
+/**
+ * Parser pour une enveloppe structurée à `issues[]` + `i18n` + `meta` de tracing.
+ *
+ * - Succès : `data = envelope.data`
+ * - Erreur : chaque `issue` est mappée en `AppError`, avec en `details` les
+ *   informations riches (code, category, severity, retryable, i18n, traceId,
+ *   spanId, timestamp, enveloppe brute si `exposeMeta=true`).
+ *
+ * Le `traceId` / `spanId` de l'enveloppe se retrouvent dans :
+ * - `errors[0].details.traceId` / `.spanId` (côté erreur)
+ * - `errors[0].details.envelope.meta` (enveloppe brute, si `exposeMeta`)
+ */
+export declare function createApiParserStructured(opts?: ApiParserStructuredOptions): ShapeParser;
+//# sourceMappingURL=apiParserStructured.d.ts.map

package/dist/parsing/apiParserStructured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiParserStructured.d.ts","sourceRoot":"","sources":["../../src/parsing/apiParserStructured.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,CAAC,GAAG,OAAO,IAAI;IACnD,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,CAAC,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,IAAI,CAAC,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IACtC,yBAAyB,CAAC,CAAC,CAAC,GAC5B,uBAAuB,CAAC;AAE5B,MAAM,MAAM,0BAA0B,GAAG;IACvC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAWF;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,0BAA+B,GAAG,WAAW,CAqE5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedvict/http-guardian",
-  "version": "0.0.1-next.8",
+  "version": "0.0.1-next.9",
   "description": "Configurable HTTP client for TypeScript: auth (bearer/cookie), guards, cache+dedupe, dynamic envelope parsing presets, notifications, redirect handling.",
   "type": "module",
   "exports": {