tempest-react-sdk 0.78.0 → 0.79.0

package/dist/http/build-url.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"build-url.cjs","names":[],"sources":["../../src/http/build-url.ts"],"sourcesContent":["/**\n * Matches a path that already carries its own scheme (`https:`, `blob:`), which\n * makes it an absolute URL rather than something to resolve against the base.\n */\nconst ABSOLUTE_URL = /^[a-z][a-z\\d+\\-.]*:/i;\n\n/** Split a path into its non-empty segments, dropping surrounding slashes. */\nfunction segments(path: string): string[] {\n    return path.split(\"/\").filter(Boolean);\n}\n\n/**\n * Whether `path` already starts with every segment of `prefix`.\n *\n * Compared segment by segment, so a `/api` prefix is not considered present in\n * `/api-keys` — a plain `startsWith` would swallow the resource.\n *\n * @param path - Segments of the request path.\n * @param prefix - Segments of the base path.\n * @returns Whether the prefix is already applied.\n */\nfunction startsWithSegments(path: string[], prefix: string[]): boolean {\n    if (prefix.length === 0 || prefix.length > path.length) return false;\n    return prefix.every((segment, index) => path[index] === segment);\n}\n\n/**\n * Resolve the origin a relative `baseURL` hangs off.\n *\n * A base such as `\"/api\"` is the shape you get behind a dev-server proxy or a\n * reverse proxy that serves app and API from one host. It only means something\n * in a browsing context, so this throws with the config to fix rather than\n * letting `new URL` report `Invalid base URL` from three frames deeper.\n *\n * @param baseURL - The base as the caller wrote it.\n * @returns The origin to resolve against.\n * @throws When there is no `location` to borrow an origin from.\n */\nfunction currentOrigin(baseURL: string): string {\n    const origin = globalThis.location?.origin;\n    if (!origin) {\n        throw new TypeError(\n            `createApiClient: baseURL \"${baseURL}\" is relative and there is no location to resolve it against. Pass an absolute URL (https://api.example.com) outside the browser.`,\n        );\n    }\n    return origin;\n}\n\n/** Options accepted by {@link buildApiUrl}. */\nexport interface BuildApiUrlOptions {\n    /**\n     * Path segment every request is nested under, such as `\"/api\"`. Joined\n     * after the path the `baseURL` already carries.\n     */\n    prefix?: string;\n    /** Query params to append. `undefined` and `null` values are skipped. */\n    params?: Record<string, string | number | boolean | undefined | null>;\n}\n\n/**\n * Join a base URL, an optional prefix and a request path into an absolute URL.\n *\n * `new URL(path, base)` on its own is wrong for an API client. It follows the\n * URL spec, where a path starting with `/` is absolute against the *origin* and\n * therefore discards whatever path the base carried: a client on\n * `https://api.example.com/api` asked for `/auth/login` reaches\n * `https://api.example.com/auth/login`, and every request 404s with nothing in\n * the config that looks wrong. This function resolves the path against the base\n * *path* instead, so the leading slash is a matter of taste rather than a\n * silent 404, and `baseURL` + `prefix` are interchangeable ways to say the same\n * thing.\n *\n * The prefix is applied at most once: a path that already opens with it — say\n * `\"/api/auth/login\"` under a `\"/api\"` prefix — is left alone, so a codebase\n * migrating to `prefix` can move its call sites one at a time. The check is per\n * segment, so `/api-keys` is not mistaken for an already-prefixed path.\n *\n * A path that is itself an absolute URL wins over all of this, which is how a\n * client reaches a second host (a signed upload endpoint, a CDN) without a\n * second client.\n *\n * @example\n * buildApiUrl(\"https://api.example.com\", \"/auth/login\", { prefix: \"/api\" });\n * // \"https://api.example.com/api/auth/login\"\n *\n * buildApiUrl(\"https://api.example.com/api\", \"auth/login\");\n * // \"https://api.example.com/api/auth/login\"\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path, or an absolute URL to use as-is.\n * @param options - Optional prefix and query params.\n * @returns The absolute URL to fetch.\n * @throws When `baseURL` is relative and there is no `location` to resolve it.\n */\nexport function buildApiUrl(\n    baseURL: string,\n    path: string,\n    options: BuildApiUrlOptions = {},\n): string {\n    const { prefix, params } = options;\n    const url = ABSOLUTE_URL.test(path) ? new URL(path) : new URL(resolve(baseURL, path, prefix));\n\n    if (params) {\n        for (const [key, value] of Object.entries(params)) {\n            if (value !== undefined && value !== null) {\n                url.searchParams.set(key, String(value));\n            }\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Build the absolute URL string for a path that is not already absolute.\n *\n * Kept separate from {@link buildApiUrl} so the query-param loop is not nested\n * inside the joining rules.\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path.\n * @param prefix - Optional segment every request is nested under.\n * @returns The joined absolute URL.\n */\nfunction resolve(baseURL: string, path: string, prefix?: string): string {\n    const base = ABSOLUTE_URL.test(baseURL)\n        ? new URL(baseURL)\n        : new URL(baseURL, currentOrigin(baseURL));\n\n    const queryStart = path.indexOf(\"?\");\n    const rawPath = queryStart === -1 ? path : path.slice(0, queryStart);\n    const query = queryStart === -1 ? \"\" : path.slice(queryStart);\n\n    const basePath = [...segments(base.pathname), ...segments(prefix ?? \"\")];\n    const requested = segments(rawPath);\n    const joined = startsWithSegments(requested, basePath)\n        ? requested\n        : [...basePath, ...requested];\n\n    const trailing = rawPath.endsWith(\"/\") ? \"/\" : \"\";\n    const pathname = joined.length > 0 ? `/${joined.join(\"/\")}${trailing}` : \"/\";\n    return `${base.origin}${pathname}${query}`;\n}\n"],"mappings":"AAIA,IAAM,EAAe,uBAGrB,SAAS,EAAS,EAAwB,CACtC,OAAO,EAAK,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,CACzC,CAYA,SAAS,EAAmB,EAAgB,EAA2B,CAEnE,OADI,EAAO,SAAW,GAAK,EAAO,OAAS,EAAK,OAAe,GACxD,EAAO,OAAO,EAAS,IAAU,EAAK,KAAW,CAAO,CACnE,CAcA,SAAS,EAAc,EAAyB,CAC5C,IAAM,EAAS,WAAW,UAAU,OACpC,GAAI,CAAC,EACD,MAAU,UACN,6BAA6B,EAAQ,kIACzC,EAEJ,OAAO,CACX,CAgDA,SAAgB,EACZ,EACA,EACA,EAA8B,CAAC,EACzB,CACN,GAAM,CAAE,SAAQ,UAAW,EACrB,EAAM,EAAa,KAAK,CAAI,EAAI,IAAI,IAAI,CAAI,EAAI,IAAI,IAAI,EAAQ,EAAS,EAAM,CAAM,CAAC,EAE5F,GAAI,EACK,IAAA,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAAM,EACxC,GAAiC,MACjC,EAAI,aAAa,IAAI,EAAK,OAAO,CAAK,CAAC,EAInD,OAAO,EAAI,SAAS,CACxB,CAaA,SAAS,EAAQ,EAAiB,EAAc,EAAyB,CACrE,IAAM,EAAO,EAAa,KAAK,CAAO,EAChC,IAAI,IAAI,CAAO,EACf,IAAI,IAAI,EAAS,EAAc,CAAO,CAAC,EAEvC,EAAa,EAAK,QAAQ,GAAG,EAC7B,EAAU,IAAe,GAAK,EAAO,EAAK,MAAM,EAAG,CAAU,EAC7D,EAAQ,IAAe,GAAK,GAAK,EAAK,MAAM,CAAU,EAEtD,EAAW,CAAC,GAAG,EAAS,EAAK,QAAQ,EAAG,GAAG,EAAS,GAAU,EAAE,CAAC,EACjE,EAAY,EAAS,CAAO,EAC5B,EAAS,EAAmB,EAAW,CAAQ,EAC/C,EACA,CAAC,GAAG,EAAU,GAAG,CAAS,EAE1B,EAAW,EAAQ,SAAS,GAAG,EAAI,IAAM,GACzC,EAAW,EAAO,OAAS,EAAI,IAAI,EAAO,KAAK,GAAG,IAAI,IAAa,IACzE,MAAO,GAAG,EAAK,SAAS,IAAW,GACvC"}
+{"version":3,"file":"build-url.cjs","names":["ABSOLUTE_URL","segments","path","startsWithSegments","prefix","index","segment","currentOrigin","origin","baseURL","buildApiUrl","options","url","resolve","params","key","value","base","queryStart","rawPath","query","basePath","requested","joined","trailing","pathname"],"sources":["../../src/http/build-url.ts"],"sourcesContent":["/**\n * Matches a path that already carries its own scheme (`https:`, `blob:`), which\n * makes it an absolute URL rather than something to resolve against the base.\n */\nconst ABSOLUTE_URL = /^[a-z][a-z\\d+\\-.]*:/i;\n\n/** Split a path into its non-empty segments, dropping surrounding slashes. */\nfunction segments(path: string): string[] {\n    return path.split(\"/\").filter(Boolean);\n}\n\n/**\n * Whether `path` already starts with every segment of `prefix`.\n *\n * Compared segment by segment, so a `/api` prefix is not considered present in\n * `/api-keys` — a plain `startsWith` would swallow the resource.\n *\n * @param path - Segments of the request path.\n * @param prefix - Segments of the base path.\n * @returns Whether the prefix is already applied.\n */\nfunction startsWithSegments(path: string[], prefix: string[]): boolean {\n    if (prefix.length === 0 || prefix.length > path.length) return false;\n    return prefix.every((segment, index) => path[index] === segment);\n}\n\n/**\n * Resolve the origin a relative `baseURL` hangs off.\n *\n * A base such as `\"/api\"` is the shape you get behind a dev-server proxy or a\n * reverse proxy that serves app and API from one host. It only means something\n * in a browsing context, so this throws with the config to fix rather than\n * letting `new URL` report `Invalid base URL` from three frames deeper.\n *\n * @param baseURL - The base as the caller wrote it.\n * @returns The origin to resolve against.\n * @throws When there is no `location` to borrow an origin from.\n */\nfunction currentOrigin(baseURL: string): string {\n    const origin = globalThis.location?.origin;\n    if (!origin) {\n        throw new TypeError(\n            `createApiClient: baseURL \"${baseURL}\" is relative and there is no location to resolve it against. Pass an absolute URL (https://api.example.com) outside the browser.`,\n        );\n    }\n    return origin;\n}\n\n/** Options accepted by {@link buildApiUrl}. */\nexport interface BuildApiUrlOptions {\n    /**\n     * Path segment every request is nested under, such as `\"/api\"`. Joined\n     * after the path the `baseURL` already carries.\n     */\n    prefix?: string;\n    /** Query params to append. `undefined` and `null` values are skipped. */\n    params?: Record<string, string | number | boolean | undefined | null>;\n}\n\n/**\n * Join a base URL, an optional prefix and a request path into an absolute URL.\n *\n * `new URL(path, base)` on its own is wrong for an API client. It follows the\n * URL spec, where a path starting with `/` is absolute against the *origin* and\n * therefore discards whatever path the base carried: a client on\n * `https://api.example.com/api` asked for `/auth/login` reaches\n * `https://api.example.com/auth/login`, and every request 404s with nothing in\n * the config that looks wrong. This function resolves the path against the base\n * *path* instead, so the leading slash is a matter of taste rather than a\n * silent 404, and `baseURL` + `prefix` are interchangeable ways to say the same\n * thing.\n *\n * The prefix is applied at most once: a path that already opens with it — say\n * `\"/api/auth/login\"` under a `\"/api\"` prefix — is left alone, so a codebase\n * migrating to `prefix` can move its call sites one at a time. The check is per\n * segment, so `/api-keys` is not mistaken for an already-prefixed path.\n *\n * A path that is itself an absolute URL wins over all of this, which is how a\n * client reaches a second host (a signed upload endpoint, a CDN) without a\n * second client.\n *\n * @example\n * buildApiUrl(\"https://api.example.com\", \"/auth/login\", { prefix: \"/api\" });\n * // \"https://api.example.com/api/auth/login\"\n *\n * buildApiUrl(\"https://api.example.com/api\", \"auth/login\");\n * // \"https://api.example.com/api/auth/login\"\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path, or an absolute URL to use as-is.\n * @param options - Optional prefix and query params.\n * @returns The absolute URL to fetch.\n * @throws When `baseURL` is relative and there is no `location` to resolve it.\n */\nexport function buildApiUrl(\n    baseURL: string,\n    path: string,\n    options: BuildApiUrlOptions = {},\n): string {\n    const { prefix, params } = options;\n    const url = ABSOLUTE_URL.test(path) ? new URL(path) : new URL(resolve(baseURL, path, prefix));\n\n    if (params) {\n        for (const [key, value] of Object.entries(params)) {\n            if (value !== undefined && value !== null) {\n                url.searchParams.set(key, String(value));\n            }\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Build the absolute URL string for a path that is not already absolute.\n *\n * Kept separate from {@link buildApiUrl} so the query-param loop is not nested\n * inside the joining rules.\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path.\n * @param prefix - Optional segment every request is nested under.\n * @returns The joined absolute URL.\n */\nfunction resolve(baseURL: string, path: string, prefix?: string): string {\n    const base = ABSOLUTE_URL.test(baseURL)\n        ? new URL(baseURL)\n        : new URL(baseURL, currentOrigin(baseURL));\n\n    const queryStart = path.indexOf(\"?\");\n    const rawPath = queryStart === -1 ? path : path.slice(0, queryStart);\n    const query = queryStart === -1 ? \"\" : path.slice(queryStart);\n\n    const basePath = [...segments(base.pathname), ...segments(prefix ?? \"\")];\n    const requested = segments(rawPath);\n    const joined = startsWithSegments(requested, basePath)\n        ? requested\n        : [...basePath, ...requested];\n\n    const trailing = rawPath.endsWith(\"/\") ? \"/\" : \"\";\n    const pathname = joined.length > 0 ? `/${joined.join(\"/\")}${trailing}` : \"/\";\n    return `${base.origin}${pathname}${query}`;\n}\n"],"mappings":"AAIA,IAAMA,EAAe,uBAGrB,SAASC,EAAS,EAAwB,CACtC,OAAOC,EAAK,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,CACzC,CAYA,SAASC,EAAmB,EAAgB,EAA2B,CAEnE,OADIC,EAAO,SAAW,GAAKA,EAAO,OAASF,EAAK,OAAe,GACxDE,EAAO,OAAO,EAAS,IAAUF,EAAKG,KAAWC,CAAO,CACnE,CAcA,SAASC,EAAc,EAAyB,CAC5C,IAAMC,EAAS,WAAW,UAAU,OACpC,GAAI,CAACA,EACD,MAAU,UACN,6BAA6BC,EAAQ,kIACzC,EAEJ,OAAOD,CACX,CAgDA,SAAgBE,EACZ,EACA,EACA,EAA8B,CAAC,EACzB,CACN,GAAM,CAAE,SAAQ,UAAWC,EACrBC,EAAMZ,EAAa,KAAKE,CAAI,EAAI,IAAI,IAAIA,CAAI,EAAI,IAAI,IAAIW,EAAQJ,EAASP,EAAME,CAAM,CAAC,EAE5F,GAAIU,EACK,IAAA,GAAM,CAACC,EAAKC,KAAU,OAAO,QAAQF,CAAM,EACxCE,GAAiC,MACjCJ,EAAI,aAAa,IAAIG,EAAK,OAAOC,CAAK,CAAC,EAInD,OAAOJ,EAAI,SAAS,CACxB,CAaA,SAASC,EAAQ,EAAiB,EAAc,EAAyB,CACrE,IAAMI,EAAOjB,EAAa,KAAKS,CAAO,EAChC,IAAI,IAAIA,CAAO,EACf,IAAI,IAAIA,EAASF,EAAcE,CAAO,CAAC,EAEvCS,EAAahB,EAAK,QAAQ,GAAG,EAC7BiB,EAAUD,IAAe,GAAKhB,EAAOA,EAAK,MAAM,EAAGgB,CAAU,EAC7DE,EAAQF,IAAe,GAAK,GAAKhB,EAAK,MAAMgB,CAAU,EAEtDG,EAAW,CAAC,GAAGpB,EAASgB,EAAK,QAAQ,EAAG,GAAGhB,EAASG,GAAU,EAAE,CAAC,EACjEkB,EAAYrB,EAASkB,CAAO,EAC5BI,EAASpB,EAAmBmB,EAAWD,CAAQ,EAC/CC,EACA,CAAC,GAAGD,EAAU,GAAGC,CAAS,EAE1BE,EAAWL,EAAQ,SAAS,GAAG,EAAI,IAAM,GACzCM,EAAWF,EAAO,OAAS,EAAI,IAAIA,EAAO,KAAK,GAAG,IAAIC,IAAa,IACzE,MAAO,GAAGP,EAAK,SAASQ,IAAWL,GACvC,C"}

package/dist/http/build-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-url.js","names":[],"sources":["../../src/http/build-url.ts"],"sourcesContent":["/**\n * Matches a path that already carries its own scheme (`https:`, `blob:`), which\n * makes it an absolute URL rather than something to resolve against the base.\n */\nconst ABSOLUTE_URL = /^[a-z][a-z\\d+\\-.]*:/i;\n\n/** Split a path into its non-empty segments, dropping surrounding slashes. */\nfunction segments(path: string): string[] {\n    return path.split(\"/\").filter(Boolean);\n}\n\n/**\n * Whether `path` already starts with every segment of `prefix`.\n *\n * Compared segment by segment, so a `/api` prefix is not considered present in\n * `/api-keys` — a plain `startsWith` would swallow the resource.\n *\n * @param path - Segments of the request path.\n * @param prefix - Segments of the base path.\n * @returns Whether the prefix is already applied.\n */\nfunction startsWithSegments(path: string[], prefix: string[]): boolean {\n    if (prefix.length === 0 || prefix.length > path.length) return false;\n    return prefix.every((segment, index) => path[index] === segment);\n}\n\n/**\n * Resolve the origin a relative `baseURL` hangs off.\n *\n * A base such as `\"/api\"` is the shape you get behind a dev-server proxy or a\n * reverse proxy that serves app and API from one host. It only means something\n * in a browsing context, so this throws with the config to fix rather than\n * letting `new URL` report `Invalid base URL` from three frames deeper.\n *\n * @param baseURL - The base as the caller wrote it.\n * @returns The origin to resolve against.\n * @throws When there is no `location` to borrow an origin from.\n */\nfunction currentOrigin(baseURL: string): string {\n    const origin = globalThis.location?.origin;\n    if (!origin) {\n        throw new TypeError(\n            `createApiClient: baseURL \"${baseURL}\" is relative and there is no location to resolve it against. Pass an absolute URL (https://api.example.com) outside the browser.`,\n        );\n    }\n    return origin;\n}\n\n/** Options accepted by {@link buildApiUrl}. */\nexport interface BuildApiUrlOptions {\n    /**\n     * Path segment every request is nested under, such as `\"/api\"`. Joined\n     * after the path the `baseURL` already carries.\n     */\n    prefix?: string;\n    /** Query params to append. `undefined` and `null` values are skipped. */\n    params?: Record<string, string | number | boolean | undefined | null>;\n}\n\n/**\n * Join a base URL, an optional prefix and a request path into an absolute URL.\n *\n * `new URL(path, base)` on its own is wrong for an API client. It follows the\n * URL spec, where a path starting with `/` is absolute against the *origin* and\n * therefore discards whatever path the base carried: a client on\n * `https://api.example.com/api` asked for `/auth/login` reaches\n * `https://api.example.com/auth/login`, and every request 404s with nothing in\n * the config that looks wrong. This function resolves the path against the base\n * *path* instead, so the leading slash is a matter of taste rather than a\n * silent 404, and `baseURL` + `prefix` are interchangeable ways to say the same\n * thing.\n *\n * The prefix is applied at most once: a path that already opens with it — say\n * `\"/api/auth/login\"` under a `\"/api\"` prefix — is left alone, so a codebase\n * migrating to `prefix` can move its call sites one at a time. The check is per\n * segment, so `/api-keys` is not mistaken for an already-prefixed path.\n *\n * A path that is itself an absolute URL wins over all of this, which is how a\n * client reaches a second host (a signed upload endpoint, a CDN) without a\n * second client.\n *\n * @example\n * buildApiUrl(\"https://api.example.com\", \"/auth/login\", { prefix: \"/api\" });\n * // \"https://api.example.com/api/auth/login\"\n *\n * buildApiUrl(\"https://api.example.com/api\", \"auth/login\");\n * // \"https://api.example.com/api/auth/login\"\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path, or an absolute URL to use as-is.\n * @param options - Optional prefix and query params.\n * @returns The absolute URL to fetch.\n * @throws When `baseURL` is relative and there is no `location` to resolve it.\n */\nexport function buildApiUrl(\n    baseURL: string,\n    path: string,\n    options: BuildApiUrlOptions = {},\n): string {\n    const { prefix, params } = options;\n    const url = ABSOLUTE_URL.test(path) ? new URL(path) : new URL(resolve(baseURL, path, prefix));\n\n    if (params) {\n        for (const [key, value] of Object.entries(params)) {\n            if (value !== undefined && value !== null) {\n                url.searchParams.set(key, String(value));\n            }\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Build the absolute URL string for a path that is not already absolute.\n *\n * Kept separate from {@link buildApiUrl} so the query-param loop is not nested\n * inside the joining rules.\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path.\n * @param prefix - Optional segment every request is nested under.\n * @returns The joined absolute URL.\n */\nfunction resolve(baseURL: string, path: string, prefix?: string): string {\n    const base = ABSOLUTE_URL.test(baseURL)\n        ? new URL(baseURL)\n        : new URL(baseURL, currentOrigin(baseURL));\n\n    const queryStart = path.indexOf(\"?\");\n    const rawPath = queryStart === -1 ? path : path.slice(0, queryStart);\n    const query = queryStart === -1 ? \"\" : path.slice(queryStart);\n\n    const basePath = [...segments(base.pathname), ...segments(prefix ?? \"\")];\n    const requested = segments(rawPath);\n    const joined = startsWithSegments(requested, basePath)\n        ? requested\n        : [...basePath, ...requested];\n\n    const trailing = rawPath.endsWith(\"/\") ? \"/\" : \"\";\n    const pathname = joined.length > 0 ? `/${joined.join(\"/\")}${trailing}` : \"/\";\n    return `${base.origin}${pathname}${query}`;\n}\n"],"mappings":";AAIA,IAAM,IAAe;AAGrB,SAAS,EAAS,GAAwB;CACtC,OAAO,EAAK,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO;AACzC;AAYA,SAAS,EAAmB,GAAgB,GAA2B;CAEnE,OADI,EAAO,WAAW,KAAK,EAAO,SAAS,EAAK,SAAe,KACxD,EAAO,OAAO,GAAS,MAAU,EAAK,OAAW,CAAO;AACnE;AAcA,SAAS,EAAc,GAAyB;CAC5C,IAAM,IAAS,WAAW,UAAU;CACpC,IAAI,CAAC,GACD,MAAU,UACN,6BAA6B,EAAQ,kIACzC;CAEJ,OAAO;AACX;AAgDA,SAAgB,EACZ,GACA,GACA,IAA8B,CAAC,GACzB;CACN,IAAM,EAAE,WAAQ,cAAW,GACrB,IAAM,EAAa,KAAK,CAAI,IAAI,IAAI,IAAI,CAAI,IAAI,IAAI,IAAI,EAAQ,GAAS,GAAM,CAAM,CAAC;CAE5F,IAAI,GACK,KAAA,IAAM,CAAC,GAAK,MAAU,OAAO,QAAQ,CAAM,GAC5C,AAAI,KAAiC,QACjC,EAAI,aAAa,IAAI,GAAK,OAAO,CAAK,CAAC;CAInD,OAAO,EAAI,SAAS;AACxB;AAaA,SAAS,EAAQ,GAAiB,GAAc,GAAyB;CACrE,IAAM,IAAO,EAAa,KAAK,CAAO,IAChC,IAAI,IAAI,CAAO,IACf,IAAI,IAAI,GAAS,EAAc,CAAO,CAAC,GAEvC,IAAa,EAAK,QAAQ,GAAG,GAC7B,IAAU,MAAe,KAAK,IAAO,EAAK,MAAM,GAAG,CAAU,GAC7D,IAAQ,MAAe,KAAK,KAAK,EAAK,MAAM,CAAU,GAEtD,IAAW,CAAC,GAAG,EAAS,EAAK,QAAQ,GAAG,GAAG,EAAS,KAAU,EAAE,CAAC,GACjE,IAAY,EAAS,CAAO,GAC5B,IAAS,EAAmB,GAAW,CAAQ,IAC/C,IACA,CAAC,GAAG,GAAU,GAAG,CAAS,GAE1B,IAAW,EAAQ,SAAS,GAAG,IAAI,MAAM,IACzC,IAAW,EAAO,SAAS,IAAI,IAAI,EAAO,KAAK,GAAG,IAAI,MAAa;CACzE,OAAO,GAAG,EAAK,SAAS,IAAW;AACvC"}
+{"version":3,"file":"build-url.js","names":["ABSOLUTE_URL","segments","path","startsWithSegments","prefix","index","segment","currentOrigin","origin","baseURL","buildApiUrl","options","url","resolve","params","key","value","base","queryStart","rawPath","query","basePath","requested","joined","trailing","pathname"],"sources":["../../src/http/build-url.ts"],"sourcesContent":["/**\n * Matches a path that already carries its own scheme (`https:`, `blob:`), which\n * makes it an absolute URL rather than something to resolve against the base.\n */\nconst ABSOLUTE_URL = /^[a-z][a-z\\d+\\-.]*:/i;\n\n/** Split a path into its non-empty segments, dropping surrounding slashes. */\nfunction segments(path: string): string[] {\n    return path.split(\"/\").filter(Boolean);\n}\n\n/**\n * Whether `path` already starts with every segment of `prefix`.\n *\n * Compared segment by segment, so a `/api` prefix is not considered present in\n * `/api-keys` — a plain `startsWith` would swallow the resource.\n *\n * @param path - Segments of the request path.\n * @param prefix - Segments of the base path.\n * @returns Whether the prefix is already applied.\n */\nfunction startsWithSegments(path: string[], prefix: string[]): boolean {\n    if (prefix.length === 0 || prefix.length > path.length) return false;\n    return prefix.every((segment, index) => path[index] === segment);\n}\n\n/**\n * Resolve the origin a relative `baseURL` hangs off.\n *\n * A base such as `\"/api\"` is the shape you get behind a dev-server proxy or a\n * reverse proxy that serves app and API from one host. It only means something\n * in a browsing context, so this throws with the config to fix rather than\n * letting `new URL` report `Invalid base URL` from three frames deeper.\n *\n * @param baseURL - The base as the caller wrote it.\n * @returns The origin to resolve against.\n * @throws When there is no `location` to borrow an origin from.\n */\nfunction currentOrigin(baseURL: string): string {\n    const origin = globalThis.location?.origin;\n    if (!origin) {\n        throw new TypeError(\n            `createApiClient: baseURL \"${baseURL}\" is relative and there is no location to resolve it against. Pass an absolute URL (https://api.example.com) outside the browser.`,\n        );\n    }\n    return origin;\n}\n\n/** Options accepted by {@link buildApiUrl}. */\nexport interface BuildApiUrlOptions {\n    /**\n     * Path segment every request is nested under, such as `\"/api\"`. Joined\n     * after the path the `baseURL` already carries.\n     */\n    prefix?: string;\n    /** Query params to append. `undefined` and `null` values are skipped. */\n    params?: Record<string, string | number | boolean | undefined | null>;\n}\n\n/**\n * Join a base URL, an optional prefix and a request path into an absolute URL.\n *\n * `new URL(path, base)` on its own is wrong for an API client. It follows the\n * URL spec, where a path starting with `/` is absolute against the *origin* and\n * therefore discards whatever path the base carried: a client on\n * `https://api.example.com/api` asked for `/auth/login` reaches\n * `https://api.example.com/auth/login`, and every request 404s with nothing in\n * the config that looks wrong. This function resolves the path against the base\n * *path* instead, so the leading slash is a matter of taste rather than a\n * silent 404, and `baseURL` + `prefix` are interchangeable ways to say the same\n * thing.\n *\n * The prefix is applied at most once: a path that already opens with it — say\n * `\"/api/auth/login\"` under a `\"/api\"` prefix — is left alone, so a codebase\n * migrating to `prefix` can move its call sites one at a time. The check is per\n * segment, so `/api-keys` is not mistaken for an already-prefixed path.\n *\n * A path that is itself an absolute URL wins over all of this, which is how a\n * client reaches a second host (a signed upload endpoint, a CDN) without a\n * second client.\n *\n * @example\n * buildApiUrl(\"https://api.example.com\", \"/auth/login\", { prefix: \"/api\" });\n * // \"https://api.example.com/api/auth/login\"\n *\n * buildApiUrl(\"https://api.example.com/api\", \"auth/login\");\n * // \"https://api.example.com/api/auth/login\"\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path, or an absolute URL to use as-is.\n * @param options - Optional prefix and query params.\n * @returns The absolute URL to fetch.\n * @throws When `baseURL` is relative and there is no `location` to resolve it.\n */\nexport function buildApiUrl(\n    baseURL: string,\n    path: string,\n    options: BuildApiUrlOptions = {},\n): string {\n    const { prefix, params } = options;\n    const url = ABSOLUTE_URL.test(path) ? new URL(path) : new URL(resolve(baseURL, path, prefix));\n\n    if (params) {\n        for (const [key, value] of Object.entries(params)) {\n            if (value !== undefined && value !== null) {\n                url.searchParams.set(key, String(value));\n            }\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Build the absolute URL string for a path that is not already absolute.\n *\n * Kept separate from {@link buildApiUrl} so the query-param loop is not nested\n * inside the joining rules.\n *\n * @param baseURL - Absolute base URL, or a path relative to the current origin.\n * @param path - The request path.\n * @param prefix - Optional segment every request is nested under.\n * @returns The joined absolute URL.\n */\nfunction resolve(baseURL: string, path: string, prefix?: string): string {\n    const base = ABSOLUTE_URL.test(baseURL)\n        ? new URL(baseURL)\n        : new URL(baseURL, currentOrigin(baseURL));\n\n    const queryStart = path.indexOf(\"?\");\n    const rawPath = queryStart === -1 ? path : path.slice(0, queryStart);\n    const query = queryStart === -1 ? \"\" : path.slice(queryStart);\n\n    const basePath = [...segments(base.pathname), ...segments(prefix ?? \"\")];\n    const requested = segments(rawPath);\n    const joined = startsWithSegments(requested, basePath)\n        ? requested\n        : [...basePath, ...requested];\n\n    const trailing = rawPath.endsWith(\"/\") ? \"/\" : \"\";\n    const pathname = joined.length > 0 ? `/${joined.join(\"/\")}${trailing}` : \"/\";\n    return `${base.origin}${pathname}${query}`;\n}\n"],"mappings":";AAIA,IAAMA,IAAe;AAGrB,SAASC,EAAS,GAAwB;CACtC,OAAOC,EAAK,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO;AACzC;AAYA,SAASC,EAAmB,GAAgB,GAA2B;CAEnE,OADIC,EAAO,WAAW,KAAKA,EAAO,SAASF,EAAK,SAAe,KACxDE,EAAO,OAAO,GAAS,MAAUF,EAAKG,OAAWC,CAAO;AACnE;AAcA,SAASC,EAAc,GAAyB;CAC5C,IAAMC,IAAS,WAAW,UAAU;CACpC,IAAI,CAACA,GACD,MAAU,UACN,6BAA6BC,EAAQ,kIACzC;CAEJ,OAAOD;AACX;AAgDA,SAAgBE,EACZ,GACA,GACA,IAA8B,CAAC,GACzB;CACN,IAAM,EAAE,WAAQ,cAAWC,GACrBC,IAAMZ,EAAa,KAAKE,CAAI,IAAI,IAAI,IAAIA,CAAI,IAAI,IAAI,IAAIW,EAAQJ,GAASP,GAAME,CAAM,CAAC;CAE5F,IAAIU,GACK,KAAA,IAAM,CAACC,GAAKC,MAAU,OAAO,QAAQF,CAAM,GAC5C,AAAIE,KAAiC,QACjCJ,EAAI,aAAa,IAAIG,GAAK,OAAOC,CAAK,CAAC;CAInD,OAAOJ,EAAI,SAAS;AACxB;AAaA,SAASC,EAAQ,GAAiB,GAAc,GAAyB;CACrE,IAAMI,IAAOjB,EAAa,KAAKS,CAAO,IAChC,IAAI,IAAIA,CAAO,IACf,IAAI,IAAIA,GAASF,EAAcE,CAAO,CAAC,GAEvCS,IAAahB,EAAK,QAAQ,GAAG,GAC7BiB,IAAUD,MAAe,KAAKhB,IAAOA,EAAK,MAAM,GAAGgB,CAAU,GAC7DE,IAAQF,MAAe,KAAK,KAAKhB,EAAK,MAAMgB,CAAU,GAEtDG,IAAW,CAAC,GAAGpB,EAASgB,EAAK,QAAQ,GAAG,GAAGhB,EAASG,KAAU,EAAE,CAAC,GACjEkB,IAAYrB,EAASkB,CAAO,GAC5BI,IAASpB,EAAmBmB,GAAWD,CAAQ,IAC/CC,IACA,CAAC,GAAGD,GAAU,GAAGC,CAAS,GAE1BE,IAAWL,EAAQ,SAAS,GAAG,IAAI,MAAM,IACzCM,IAAWF,EAAO,SAAS,IAAI,IAAIA,EAAO,KAAK,GAAG,IAAIC,MAAa;CACzE,OAAO,GAAGP,EAAK,SAASQ,IAAWL;AACvC"}

package/dist/http/credential-scope.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"credential-scope.cjs","names":[],"sources":["../../src/http/credential-scope.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Origins already reported by {@link reportSuppressedCredential}, so a chunked\n * upload warns once instead of once per chunk.\n */\nconst reported = new Set<string>();\n\n/**\n * The origin a URL resolves to, or `null` when it has none to compare.\n *\n * Relative values resolve against the document, because that is what they mean\n * everywhere else in the SDK: an `endpoint` of `\"/api/uploads\"` and a `baseURL`\n * of `\"/api\"` are the shape you get behind a dev-server or a reverse proxy, and\n * both name the page's own origin. Comparing a resolved absolute target against\n * an unresolved relative reference is how the first draft of this function\n * withheld the credential from every client configured that way.\n *\n * `null` is reserved for the case with genuinely nothing to compare: a relative\n * URL outside a browsing context, where there is no document to resolve against.\n *\n * @param url - Absolute or relative URL.\n * @returns The origin, or `null` when it cannot be resolved.\n */\nfunction originOf(url: string): string | null {\n    try {\n        return new URL(url, globalThis.location?.href).origin;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Whether a request to `target` may carry the caller's credential.\n *\n * The SDK writes `Authorization: Bearer` in three places, and until 0.66.0 none\n * of them looked at where the request was going. That is only safe while every\n * target URL is written by the app: a resumable upload takes its URL from the\n * server's `Location` header, and `createApiClient` lets an absolute path\n * override `baseURL` entirely, so a URL arriving over the network could decide\n * which origin received the token — and the file bytes with it.\n *\n * Handing an upload off to object storage on another host is ordinary `tus`\n * deployment, not an attack, which is exactly why the credential must be scoped\n * rather than the request blocked: the upload still goes through, it just goes\n * without the API's bearer token.\n *\n * Both sides are resolved against the document first, so a relative `baseURL`\n * or `endpoint` — the shape behind a dev-server or reverse proxy — compares\n * equal to the absolute URL the request actually goes to. Outside a browsing\n * context a relative target resolves to nothing and is allowed: there is no\n * origin for it to cross.\n *\n * @param target - The URL the request is about to go to.\n * @param reference - The origin the credential belongs to, normally the\n *     client's `baseURL` or the upload `endpoint`.\n * @param trustedOrigins - Extra origins the app declared, for the legitimate\n *     second host: a CDN, a signed upload endpoint.\n * @returns Whether the credential may be attached.\n *\n * @example\n * isTrustedCredentialTarget(\"https://api.acme.com/me\", \"https://api.acme.com\");\n * // true\n * isTrustedCredentialTarget(\"https://cdn.other/u/1\", \"https://api.acme.com\");\n * // false\n */\nexport function isTrustedCredentialTarget(\n    target: string,\n    reference: string,\n    trustedOrigins: readonly string[] = [],\n): boolean {\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return true;\n    if (targetOrigin === originOf(reference)) return true;\n    return trustedOrigins.some((origin) => originOf(origin) === targetOrigin);\n}\n\n/**\n * Say once, in a development build, that a credential was withheld.\n *\n * Without it the symptom is a `401` (or, for the CSRF header, a `403`) from a\n * host the developer never typed, and nothing in the app's code mentions the\n * origin that produced it. Keyed by credential and target origin, so a\n * hundred-chunk upload reports one line per header it withheld.\n *\n * Silent in production for the same reason {@link parseResponse} is: the origin\n * an app talks to is not something to print into a user's console or ship to an\n * error tracker.\n *\n * @param target - The URL whose request went out unauthenticated.\n * @param reference - The origin the credential was scoped to.\n * @param header - The header that was withheld. Default `\"Authorization\"`.\n */\nexport function reportSuppressedCredential(\n    target: string,\n    reference: string,\n    header = \"Authorization\",\n): void {\n    if (!isDevBuild()) return;\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return;\n    const key = `${header} ${targetOrigin}`;\n    if (reported.has(key)) return;\n    reported.add(key);\n    console.warn(\n        `[tempest-react-sdk] ${header} was not sent to ${targetOrigin}: the credential is scoped to ${originOf(reference) ?? reference}. Add the origin to trustedOrigins if it should receive the token.`,\n    );\n}\n\n/**\n * Forget which origins were already reported.\n *\n * Exported for tests, which assert the once-per-origin behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetSuppressedCredentialReports(): void {\n    reported.clear();\n}\n"],"mappings":"yCAMA,IAAM,EAAW,IAAI,IAkBrB,SAAS,EAAS,EAA4B,CAC1C,GAAI,CACA,OAAO,IAAI,IAAI,EAAK,WAAW,UAAU,IAAI,CAAC,CAAC,MACnD,MAAQ,CACJ,OAAO,IACX,CACJ,CAoCA,SAAgB,EACZ,EACA,EACA,EAAoC,CAAC,EAC9B,CACP,IAAM,EAAe,EAAS,CAAM,EAGpC,OAFI,IAAiB,MACjB,IAAiB,EAAS,CAAS,GAChC,EAAe,KAAM,GAAW,EAAS,CAAM,IAAM,CAAY,CAC5E,CAkBA,SAAgB,EACZ,EACA,EACA,EAAS,gBACL,CACJ,GAAI,CAAC,EAAA,WAAW,EAAG,OACnB,IAAM,EAAe,EAAS,CAAM,EACpC,GAAI,IAAiB,KAAM,OAC3B,IAAM,EAAM,GAAG,EAAO,GAAG,IACrB,EAAS,IAAI,CAAG,IACpB,EAAS,IAAI,CAAG,EAChB,QAAQ,KACJ,uBAAuB,EAAO,mBAAmB,EAAa,gCAAgC,EAAS,CAAS,GAAK,EAAU,mEACnI,EACJ"}
+{"version":3,"file":"credential-scope.cjs","names":["isDevBuild","require_dev_mode","reported","originOf","url","isTrustedCredentialTarget","targetOrigin","target","reference","trustedOrigins","origin","reportSuppressedCredential","key","header"],"sources":["../../src/http/credential-scope.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Origins already reported by {@link reportSuppressedCredential}, so a chunked\n * upload warns once instead of once per chunk.\n */\nconst reported = new Set<string>();\n\n/**\n * The origin a URL resolves to, or `null` when it has none to compare.\n *\n * Relative values resolve against the document, because that is what they mean\n * everywhere else in the SDK: an `endpoint` of `\"/api/uploads\"` and a `baseURL`\n * of `\"/api\"` are the shape you get behind a dev-server or a reverse proxy, and\n * both name the page's own origin. Comparing a resolved absolute target against\n * an unresolved relative reference is how the first draft of this function\n * withheld the credential from every client configured that way.\n *\n * `null` is reserved for the case with genuinely nothing to compare: a relative\n * URL outside a browsing context, where there is no document to resolve against.\n *\n * @param url - Absolute or relative URL.\n * @returns The origin, or `null` when it cannot be resolved.\n */\nfunction originOf(url: string): string | null {\n    try {\n        return new URL(url, globalThis.location?.href).origin;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Whether a request to `target` may carry the caller's credential.\n *\n * The SDK writes `Authorization: Bearer` in three places, and until 0.66.0 none\n * of them looked at where the request was going. That is only safe while every\n * target URL is written by the app: a resumable upload takes its URL from the\n * server's `Location` header, and `createApiClient` lets an absolute path\n * override `baseURL` entirely, so a URL arriving over the network could decide\n * which origin received the token — and the file bytes with it.\n *\n * Handing an upload off to object storage on another host is ordinary `tus`\n * deployment, not an attack, which is exactly why the credential must be scoped\n * rather than the request blocked: the upload still goes through, it just goes\n * without the API's bearer token.\n *\n * Both sides are resolved against the document first, so a relative `baseURL`\n * or `endpoint` — the shape behind a dev-server or reverse proxy — compares\n * equal to the absolute URL the request actually goes to. Outside a browsing\n * context a relative target resolves to nothing and is allowed: there is no\n * origin for it to cross.\n *\n * @param target - The URL the request is about to go to.\n * @param reference - The origin the credential belongs to, normally the\n *     client's `baseURL` or the upload `endpoint`.\n * @param trustedOrigins - Extra origins the app declared, for the legitimate\n *     second host: a CDN, a signed upload endpoint.\n * @returns Whether the credential may be attached.\n *\n * @example\n * isTrustedCredentialTarget(\"https://api.acme.com/me\", \"https://api.acme.com\");\n * // true\n * isTrustedCredentialTarget(\"https://cdn.other/u/1\", \"https://api.acme.com\");\n * // false\n */\nexport function isTrustedCredentialTarget(\n    target: string,\n    reference: string,\n    trustedOrigins: readonly string[] = [],\n): boolean {\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return true;\n    if (targetOrigin === originOf(reference)) return true;\n    return trustedOrigins.some((origin) => originOf(origin) === targetOrigin);\n}\n\n/**\n * Say once, in a development build, that a credential was withheld.\n *\n * Without it the symptom is a `401` (or, for the CSRF header, a `403`) from a\n * host the developer never typed, and nothing in the app's code mentions the\n * origin that produced it. Keyed by credential and target origin, so a\n * hundred-chunk upload reports one line per header it withheld.\n *\n * Silent in production for the same reason {@link parseResponse} is: the origin\n * an app talks to is not something to print into a user's console or ship to an\n * error tracker.\n *\n * @param target - The URL whose request went out unauthenticated.\n * @param reference - The origin the credential was scoped to.\n * @param header - The header that was withheld. Default `\"Authorization\"`.\n */\nexport function reportSuppressedCredential(\n    target: string,\n    reference: string,\n    header = \"Authorization\",\n): void {\n    if (!isDevBuild()) return;\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return;\n    const key = `${header} ${targetOrigin}`;\n    if (reported.has(key)) return;\n    reported.add(key);\n    console.warn(\n        `[tempest-react-sdk] ${header} was not sent to ${targetOrigin}: the credential is scoped to ${originOf(reference) ?? reference}. Add the origin to trustedOrigins if it should receive the token.`,\n    );\n}\n\n/**\n * Forget which origins were already reported.\n *\n * Exported for tests, which assert the once-per-origin behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetSuppressedCredentialReports(): void {\n    reported.clear();\n}\n"],"mappings":"A,yCAMA,IAAME,EAAW,IAAI,IAkBrB,SAASC,EAAS,EAA4B,CAC1C,GAAI,CACA,OAAO,IAAI,IAAIC,EAAK,WAAW,UAAU,IAAI,CAAC,CAAC,MACnD,MAAQ,CACJ,OAAO,IACX,CACJ,CAoCA,SAAgBC,EACZ,EACA,EACA,EAAoC,CAAC,EAC9B,CACP,IAAMC,EAAeH,EAASI,CAAM,EAGpC,OAFID,IAAiB,MACjBA,IAAiBH,EAASK,CAAS,GAChCC,EAAe,KAAM,GAAWN,EAASO,CAAM,IAAMJ,CAAY,CAC5E,CAkBA,SAAgBK,EACZ,EACA,EACA,EAAS,gBACL,CACJ,GAAI,CAACX,EAAAA,WAAW,EAAG,OACnB,IAAMM,EAAeH,EAASI,CAAM,EACpC,GAAID,IAAiB,KAAM,OAC3B,IAAMM,EAAM,GAAGC,EAAO,GAAGP,IACrBJ,EAAS,IAAIU,CAAG,IACpBV,EAAS,IAAIU,CAAG,EAChB,QAAQ,KACJ,uBAAuBC,EAAO,mBAAmBP,EAAa,gCAAgCH,EAASK,CAAS,GAAKA,EAAU,mEACnI,EACJ,C"}

package/dist/http/credential-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"credential-scope.js","names":[],"sources":["../../src/http/credential-scope.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Origins already reported by {@link reportSuppressedCredential}, so a chunked\n * upload warns once instead of once per chunk.\n */\nconst reported = new Set<string>();\n\n/**\n * The origin a URL resolves to, or `null` when it has none to compare.\n *\n * Relative values resolve against the document, because that is what they mean\n * everywhere else in the SDK: an `endpoint` of `\"/api/uploads\"` and a `baseURL`\n * of `\"/api\"` are the shape you get behind a dev-server or a reverse proxy, and\n * both name the page's own origin. Comparing a resolved absolute target against\n * an unresolved relative reference is how the first draft of this function\n * withheld the credential from every client configured that way.\n *\n * `null` is reserved for the case with genuinely nothing to compare: a relative\n * URL outside a browsing context, where there is no document to resolve against.\n *\n * @param url - Absolute or relative URL.\n * @returns The origin, or `null` when it cannot be resolved.\n */\nfunction originOf(url: string): string | null {\n    try {\n        return new URL(url, globalThis.location?.href).origin;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Whether a request to `target` may carry the caller's credential.\n *\n * The SDK writes `Authorization: Bearer` in three places, and until 0.66.0 none\n * of them looked at where the request was going. That is only safe while every\n * target URL is written by the app: a resumable upload takes its URL from the\n * server's `Location` header, and `createApiClient` lets an absolute path\n * override `baseURL` entirely, so a URL arriving over the network could decide\n * which origin received the token — and the file bytes with it.\n *\n * Handing an upload off to object storage on another host is ordinary `tus`\n * deployment, not an attack, which is exactly why the credential must be scoped\n * rather than the request blocked: the upload still goes through, it just goes\n * without the API's bearer token.\n *\n * Both sides are resolved against the document first, so a relative `baseURL`\n * or `endpoint` — the shape behind a dev-server or reverse proxy — compares\n * equal to the absolute URL the request actually goes to. Outside a browsing\n * context a relative target resolves to nothing and is allowed: there is no\n * origin for it to cross.\n *\n * @param target - The URL the request is about to go to.\n * @param reference - The origin the credential belongs to, normally the\n *     client's `baseURL` or the upload `endpoint`.\n * @param trustedOrigins - Extra origins the app declared, for the legitimate\n *     second host: a CDN, a signed upload endpoint.\n * @returns Whether the credential may be attached.\n *\n * @example\n * isTrustedCredentialTarget(\"https://api.acme.com/me\", \"https://api.acme.com\");\n * // true\n * isTrustedCredentialTarget(\"https://cdn.other/u/1\", \"https://api.acme.com\");\n * // false\n */\nexport function isTrustedCredentialTarget(\n    target: string,\n    reference: string,\n    trustedOrigins: readonly string[] = [],\n): boolean {\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return true;\n    if (targetOrigin === originOf(reference)) return true;\n    return trustedOrigins.some((origin) => originOf(origin) === targetOrigin);\n}\n\n/**\n * Say once, in a development build, that a credential was withheld.\n *\n * Without it the symptom is a `401` (or, for the CSRF header, a `403`) from a\n * host the developer never typed, and nothing in the app's code mentions the\n * origin that produced it. Keyed by credential and target origin, so a\n * hundred-chunk upload reports one line per header it withheld.\n *\n * Silent in production for the same reason {@link parseResponse} is: the origin\n * an app talks to is not something to print into a user's console or ship to an\n * error tracker.\n *\n * @param target - The URL whose request went out unauthenticated.\n * @param reference - The origin the credential was scoped to.\n * @param header - The header that was withheld. Default `\"Authorization\"`.\n */\nexport function reportSuppressedCredential(\n    target: string,\n    reference: string,\n    header = \"Authorization\",\n): void {\n    if (!isDevBuild()) return;\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return;\n    const key = `${header} ${targetOrigin}`;\n    if (reported.has(key)) return;\n    reported.add(key);\n    console.warn(\n        `[tempest-react-sdk] ${header} was not sent to ${targetOrigin}: the credential is scoped to ${originOf(reference) ?? reference}. Add the origin to trustedOrigins if it should receive the token.`,\n    );\n}\n\n/**\n * Forget which origins were already reported.\n *\n * Exported for tests, which assert the once-per-origin behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetSuppressedCredentialReports(): void {\n    reported.clear();\n}\n"],"mappings":";;AAMA,IAAM,oBAAW,IAAI,IAAY;AAkBjC,SAAS,EAAS,GAA4B;CAC1C,IAAI;EACA,OAAO,IAAI,IAAI,GAAK,WAAW,UAAU,IAAI,CAAC,CAAC;CACnD,QAAQ;EACJ,OAAO;CACX;AACJ;AAoCA,SAAgB,EACZ,GACA,GACA,IAAoC,CAAC,GAC9B;CACP,IAAM,IAAe,EAAS,CAAM;CAGpC,OAFI,MAAiB,QACjB,MAAiB,EAAS,CAAS,KAChC,EAAe,MAAM,MAAW,EAAS,CAAM,MAAM,CAAY;AAC5E;AAkBA,SAAgB,EACZ,GACA,GACA,IAAS,iBACL;CACJ,IAAI,CAAC,EAAW,GAAG;CACnB,IAAM,IAAe,EAAS,CAAM;CACpC,IAAI,MAAiB,MAAM;CAC3B,IAAM,IAAM,GAAG,EAAO,GAAG;CACrB,EAAS,IAAI,CAAG,MACpB,EAAS,IAAI,CAAG,GAChB,QAAQ,KACJ,uBAAuB,EAAO,mBAAmB,EAAa,gCAAgC,EAAS,CAAS,KAAK,EAAU,mEACnI;AACJ"}
+{"version":3,"file":"credential-scope.js","names":["reported","originOf","url","isTrustedCredentialTarget","targetOrigin","target","reference","trustedOrigins","origin","reportSuppressedCredential","isDevBuild","key","header"],"sources":["../../src/http/credential-scope.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Origins already reported by {@link reportSuppressedCredential}, so a chunked\n * upload warns once instead of once per chunk.\n */\nconst reported = new Set<string>();\n\n/**\n * The origin a URL resolves to, or `null` when it has none to compare.\n *\n * Relative values resolve against the document, because that is what they mean\n * everywhere else in the SDK: an `endpoint` of `\"/api/uploads\"` and a `baseURL`\n * of `\"/api\"` are the shape you get behind a dev-server or a reverse proxy, and\n * both name the page's own origin. Comparing a resolved absolute target against\n * an unresolved relative reference is how the first draft of this function\n * withheld the credential from every client configured that way.\n *\n * `null` is reserved for the case with genuinely nothing to compare: a relative\n * URL outside a browsing context, where there is no document to resolve against.\n *\n * @param url - Absolute or relative URL.\n * @returns The origin, or `null` when it cannot be resolved.\n */\nfunction originOf(url: string): string | null {\n    try {\n        return new URL(url, globalThis.location?.href).origin;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Whether a request to `target` may carry the caller's credential.\n *\n * The SDK writes `Authorization: Bearer` in three places, and until 0.66.0 none\n * of them looked at where the request was going. That is only safe while every\n * target URL is written by the app: a resumable upload takes its URL from the\n * server's `Location` header, and `createApiClient` lets an absolute path\n * override `baseURL` entirely, so a URL arriving over the network could decide\n * which origin received the token — and the file bytes with it.\n *\n * Handing an upload off to object storage on another host is ordinary `tus`\n * deployment, not an attack, which is exactly why the credential must be scoped\n * rather than the request blocked: the upload still goes through, it just goes\n * without the API's bearer token.\n *\n * Both sides are resolved against the document first, so a relative `baseURL`\n * or `endpoint` — the shape behind a dev-server or reverse proxy — compares\n * equal to the absolute URL the request actually goes to. Outside a browsing\n * context a relative target resolves to nothing and is allowed: there is no\n * origin for it to cross.\n *\n * @param target - The URL the request is about to go to.\n * @param reference - The origin the credential belongs to, normally the\n *     client's `baseURL` or the upload `endpoint`.\n * @param trustedOrigins - Extra origins the app declared, for the legitimate\n *     second host: a CDN, a signed upload endpoint.\n * @returns Whether the credential may be attached.\n *\n * @example\n * isTrustedCredentialTarget(\"https://api.acme.com/me\", \"https://api.acme.com\");\n * // true\n * isTrustedCredentialTarget(\"https://cdn.other/u/1\", \"https://api.acme.com\");\n * // false\n */\nexport function isTrustedCredentialTarget(\n    target: string,\n    reference: string,\n    trustedOrigins: readonly string[] = [],\n): boolean {\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return true;\n    if (targetOrigin === originOf(reference)) return true;\n    return trustedOrigins.some((origin) => originOf(origin) === targetOrigin);\n}\n\n/**\n * Say once, in a development build, that a credential was withheld.\n *\n * Without it the symptom is a `401` (or, for the CSRF header, a `403`) from a\n * host the developer never typed, and nothing in the app's code mentions the\n * origin that produced it. Keyed by credential and target origin, so a\n * hundred-chunk upload reports one line per header it withheld.\n *\n * Silent in production for the same reason {@link parseResponse} is: the origin\n * an app talks to is not something to print into a user's console or ship to an\n * error tracker.\n *\n * @param target - The URL whose request went out unauthenticated.\n * @param reference - The origin the credential was scoped to.\n * @param header - The header that was withheld. Default `\"Authorization\"`.\n */\nexport function reportSuppressedCredential(\n    target: string,\n    reference: string,\n    header = \"Authorization\",\n): void {\n    if (!isDevBuild()) return;\n    const targetOrigin = originOf(target);\n    if (targetOrigin === null) return;\n    const key = `${header} ${targetOrigin}`;\n    if (reported.has(key)) return;\n    reported.add(key);\n    console.warn(\n        `[tempest-react-sdk] ${header} was not sent to ${targetOrigin}: the credential is scoped to ${originOf(reference) ?? reference}. Add the origin to trustedOrigins if it should receive the token.`,\n    );\n}\n\n/**\n * Forget which origins were already reported.\n *\n * Exported for tests, which assert the once-per-origin behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetSuppressedCredentialReports(): void {\n    reported.clear();\n}\n"],"mappings":";;AAMA,IAAMA,oBAAW,IAAI,IAAY;AAkBjC,SAASC,EAAS,GAA4B;CAC1C,IAAI;EACA,OAAO,IAAI,IAAIC,GAAK,WAAW,UAAU,IAAI,CAAC,CAAC;CACnD,QAAQ;EACJ,OAAO;CACX;AACJ;AAoCA,SAAgBC,EACZ,GACA,GACA,IAAoC,CAAC,GAC9B;CACP,IAAMC,IAAeH,EAASI,CAAM;CAGpC,OAFID,MAAiB,QACjBA,MAAiBH,EAASK,CAAS,KAChCC,EAAe,MAAM,MAAWN,EAASO,CAAM,MAAMJ,CAAY;AAC5E;AAkBA,SAAgBK,EACZ,GACA,GACA,IAAS,iBACL;CACJ,IAAI,CAACC,EAAW,GAAG;CACnB,IAAMN,IAAeH,EAASI,CAAM;CACpC,IAAID,MAAiB,MAAM;CAC3B,IAAMO,IAAM,GAAGC,EAAO,GAAGR;CACzB,AAAIJ,EAAS,IAAIW,CAAG,MACpBX,EAAS,IAAIW,CAAG,GAChB,QAAQ,KACJ,uBAAuBC,EAAO,mBAAmBR,EAAa,gCAAgCH,EAASK,CAAS,KAAKA,EAAU,mEACnI;AACJ"}

package/dist/http/csrf.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"csrf.cjs","names":[],"sources":["../../src/http/csrf.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\nimport { isTrustedCredentialTarget, reportSuppressedCredential } from \"./credential-scope\";\n\n/**\n * Default cookie the CSRF token is read from.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_COOKIE_NAME`\n * (`tempest_fastapi_sdk/api/middlewares/csrf.py`), which is the cookie its\n * `make_csrf_token_dependency()` sets and its `CSRFMiddleware` compares against.\n * Matching it is what lets `csrf: true` work against that backend with no\n * configuration on either side.\n */\nexport const DEFAULT_CSRF_COOKIE_NAME = \"csrf_token\";\n\n/**\n * Default header the CSRF token is echoed in.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_HEADER_NAME`, the header its\n * `CSRFMiddleware` reads on every unsafe request.\n */\nexport const DEFAULT_CSRF_HEADER_NAME = \"X-CSRF-Token\";\n\n/**\n * Where the CSRF token comes from and which header carries it.\n *\n * The default is the **double-submit cookie**: the server sets a cookie that is\n * deliberately not `HttpOnly`, the client reads it and echoes the value in a\n * header, and the server rejects a write whose header does not match the\n * cookie. A page on another site can make the browser *send* the cookie, but\n * cannot *read* it, so it cannot write the header.\n *\n * The token is read again on every request, so a server that rotates the\n * cookie is followed without any capture step: the browser's cookie jar is the\n * store. That is also why there is no \"read the token from a response header\"\n * mode — it would depend on `Access-Control-Expose-Headers`, and a missing\n * expose header fails silently, as a `403` on the second write.\n */\nexport interface CsrfOptions {\n    /** Cookie to read the token from. Default {@link DEFAULT_CSRF_COOKIE_NAME}. */\n    cookieName?: string;\n    /** Header to send the token in. Default {@link DEFAULT_CSRF_HEADER_NAME}. */\n    headerName?: string;\n    /**\n     * Supply the token yourself instead of reading `cookieName`.\n     *\n     * For the cases the cookie cannot serve: an API on another **site**, whose\n     * cookie `document.cookie` cannot see, or a backend that hands the token\n     * out in a response body. Called per request, like `getToken`.\n     */\n    getToken?: () => string | null | undefined;\n}\n\n/**\n * Methods that must not change state, and so never carry the token.\n *\n * A deny list rather than an allow list of the four write verbs: RFC 9110\n * names the safe methods, and a custom method (`PROPFIND`, a tus extension)\n * is a write until proven otherwise. Sending the token to its own origin on\n * an unexpected verb costs nothing; omitting it costs a `403`.\n */\nconst SAFE_METHODS: ReadonlySet<string> = new Set([\"GET\", \"HEAD\", \"OPTIONS\", \"TRACE\"]);\n\n/** Token sources already reported empty, so a burst of writes warns once. */\nconst reportedMissing = new Set<string>();\n\n/**\n * Read one cookie from `document.cookie`, or `null` when it is absent.\n *\n * Returns `null` outside a document (a worker, a test without jsdom), where\n * there is no cookie jar to read. The value is URI-decoded when it can be,\n * and returned raw when it is not valid percent-encoding.\n *\n * @param name - The cookie name.\n * @returns The value, or `null`.\n */\nfunction readCookie(name: string): string | null {\n    if (typeof document === \"undefined\") return null;\n    const prefix = `${name}=`;\n    for (const part of document.cookie.split(\";\")) {\n        const entry = part.trim();\n        if (!entry.startsWith(prefix)) continue;\n        const raw = entry.slice(prefix.length);\n        try {\n            return decodeURIComponent(raw);\n        } catch {\n            return raw;\n        }\n    }\n    return null;\n}\n\n/**\n * Say once, in a development build, that CSRF is on but there is no token.\n *\n * The request still goes out, because the SDK cannot know whether this path\n * is guarded — `CSRFMiddleware` is commonly mounted with `exclude_paths`. When\n * it is guarded, the symptom is a `403 CSRF_VALIDATION_FAILED` with nothing\n * in the app's code pointing at the cause, and the three usual causes are all\n * on the server: the cookie was never issued, was issued `HttpOnly`, or was\n * issued for a domain this page cannot read.\n *\n * @param source - What was read: the cookie name, or `\"getToken\"`.\n */\nfunction reportMissingToken(source: string): void {\n    if (!isDevBuild() || reportedMissing.has(source)) return;\n    reportedMissing.add(source);\n    const where =\n        source === \"getToken\"\n            ? \"csrf.getToken() returned nothing\"\n            : `no readable \"${source}\" cookie on this page`;\n    console.warn(\n        `[tempest-react-sdk] CSRF is enabled but ${where}, so the write went without the token. The cookie must be issued before the first write and must not be HttpOnly.`,\n    );\n}\n\n/**\n * Whether a header is already present, compared case-insensitively.\n *\n * Header names are case-insensitive, but object keys are not: a caller's\n * `\"x-csrf-token\"` next to the SDK's `\"X-CSRF-Token\"` would reach `fetch` as\n * two entries and be joined into `\"a, b\"`, which matches neither.\n *\n * @param headers - The headers the caller already set.\n * @param name - The header to look for.\n * @returns Whether it is set.\n */\nfunction hasHeader(headers: HeadersInit | undefined, name: string): boolean {\n    if (!headers) return false;\n    return new Headers(headers).has(name);\n}\n\n/** What {@link csrfHeaders} needs to decide. */\nexport interface CsrfHeadersInput {\n    /** The HTTP method of the request. Case-insensitive. */\n    method: string;\n    /** The URL the request is going to. */\n    url: string;\n    /**\n     * The origin the token belongs to, normally the API's `baseURL`. The token\n     * is only sent to this origin or to one listed in `trustedOrigins`.\n     */\n    reference: string;\n    /** The CSRF config. `undefined` or `false` turns the header off. */\n    csrf: boolean | CsrfOptions | undefined;\n    /** Extra origins allowed to receive the token. */\n    trustedOrigins?: readonly string[];\n    /** Headers the caller already set. A CSRF header among them is never replaced. */\n    headers?: HeadersInit;\n}\n\n/**\n * The CSRF header a request should carry, or an empty object.\n *\n * Every request path in the SDK — `createApiClient`, `uploadWithProgress`,\n * `createResumableUpload` — asks this function, so the rules are one rule:\n *\n * - **Off unless configured.** Without `csrf`, nothing changes.\n * - **Unsafe methods only.** `GET`, `HEAD`, `OPTIONS` and `TRACE` never carry\n *   it; they must not change state, and a token in a `GET` ends up in logs\n *   and caches for nothing.\n * - **Never across an origin.** The token follows the same scope as the bearer\n *   credential ({@link isTrustedCredentialTarget}), because a URL can come off\n *   the network — a tus `Location`, a pagination link — and a CSRF token sent\n *   to a third party is a token that third party can replay. Withheld tokens\n *   are reported once per origin in a development build.\n * - **Your header wins.** A CSRF header you set by hand, in any casing, is\n *   left alone.\n * - **Independent of auth.** It is sent on `skipAuth` requests too: login and\n *   refresh are exactly the writes a cookie session exposes to forgery.\n *\n * Exported for the request you build by hand, so it follows the same rules.\n *\n * @example\n * const headers = csrfHeaders({\n *     method: \"POST\",\n *     url: \"https://api.acme.com/orders\",\n *     reference: \"https://api.acme.com\",\n *     csrf: true,\n * });\n * // { \"X-CSRF-Token\": \"<value of the csrf_token cookie>\" }\n *\n * @param input - The request and the CSRF config.\n * @returns A header record to spread into the request's headers.\n */\nexport function csrfHeaders(input: CsrfHeadersInput): Record<string, string> {\n    const { method, url, reference, csrf, trustedOrigins, headers } = input;\n    if (!csrf) return {};\n    if (SAFE_METHODS.has(method.toUpperCase())) return {};\n    const options: CsrfOptions = csrf === true ? {} : csrf;\n    const headerName = options.headerName ?? DEFAULT_CSRF_HEADER_NAME;\n    if (hasHeader(headers, headerName)) return {};\n    if (!isTrustedCredentialTarget(url, reference, trustedOrigins)) {\n        reportSuppressedCredential(url, reference, headerName);\n        return {};\n    }\n    const cookieName = options.cookieName ?? DEFAULT_CSRF_COOKIE_NAME;\n    const token = options.getToken ? options.getToken() : readCookie(cookieName);\n    if (!token) {\n        reportMissingToken(options.getToken ? \"getToken\" : cookieName);\n        return {};\n    }\n    return { [headerName]: token };\n}\n\n/**\n * Forget which token sources were already reported empty.\n *\n * Exported for tests, which assert the once-per-source behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetCsrfReports(): void {\n    reportedMissing.clear();\n}\n"],"mappings":"6EAYA,IAAa,EAA2B,aAQ3B,EAA2B,eAwClC,EAAoC,IAAI,IAAI,CAAC,MAAO,OAAQ,UAAW,OAAO,CAAC,EAG/E,EAAkB,IAAI,IAY5B,SAAS,EAAW,EAA6B,CAC7C,GAAI,OAAO,SAAa,IAAa,OAAO,KAC5C,IAAM,EAAS,GAAG,EAAK,GACvB,IAAK,IAAM,KAAQ,SAAS,OAAO,MAAM,GAAG,EAAG,CAC3C,IAAM,EAAQ,EAAK,KAAK,EACxB,GAAI,CAAC,EAAM,WAAW,CAAM,EAAG,SAC/B,IAAM,EAAM,EAAM,MAAM,EAAO,MAAM,EACrC,GAAI,CACA,OAAO,mBAAmB,CAAG,CACjC,MAAQ,CACJ,OAAO,CACX,CACJ,CACA,OAAO,IACX,CAcA,SAAS,EAAmB,EAAsB,CAC9C,GAAI,CAAC,EAAA,WAAW,GAAK,EAAgB,IAAI,CAAM,EAAG,OAClD,EAAgB,IAAI,CAAM,EAC1B,IAAM,EACF,IAAW,WACL,mCACA,gBAAgB,EAAO,uBACjC,QAAQ,KACJ,2CAA2C,EAAM,kHACrD,CACJ,CAaA,SAAS,EAAU,EAAkC,EAAuB,CAExE,OADK,EACE,IAAI,QAAQ,CAAO,CAAC,CAAC,IAAI,CAAI,EADf,EAEzB,CAuDA,SAAgB,EAAY,EAAiD,CACzE,GAAM,CAAE,SAAQ,MAAK,YAAW,OAAM,iBAAgB,WAAY,EAElE,GADI,CAAC,GACD,EAAa,IAAI,EAAO,YAAY,CAAC,EAAG,MAAO,CAAC,EACpD,IAAM,EAAuB,IAAS,GAAO,CAAC,EAAI,EAC5C,EAAa,EAAQ,YAAA,eAC3B,GAAI,EAAU,EAAS,CAAU,EAAG,MAAO,CAAC,EAC5C,GAAI,CAAC,EAAA,0BAA0B,EAAK,EAAW,CAAc,EAEzD,OADA,EAAA,2BAA2B,EAAK,EAAW,CAAU,EAC9C,CAAC,EAEZ,IAAM,EAAa,EAAQ,YAAA,aACrB,EAAQ,EAAQ,SAAW,EAAQ,SAAS,EAAI,EAAW,CAAU,EAK3E,OAJK,EAIE,EAAG,GAAa,CAAM,GAHzB,EAAmB,EAAQ,SAAW,WAAa,CAAU,EACtD,CAAC,EAGhB"}
+{"version":3,"file":"csrf.cjs","names":["isDevBuild","isTrustedCredentialTarget","require_dev_mode","require_credential_scope","DEFAULT_CSRF_COOKIE_NAME","DEFAULT_CSRF_HEADER_NAME","SAFE_METHODS","reportedMissing","readCookie","prefix","name","part","entry","raw","reportMissingToken","source","where","hasHeader","headers","csrfHeaders","input","csrf","method","options","headerName","url","reference","trustedOrigins","cookieName","token"],"sources":["../../src/http/csrf.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\nimport { isTrustedCredentialTarget, reportSuppressedCredential } from \"./credential-scope\";\n\n/**\n * Default cookie the CSRF token is read from.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_COOKIE_NAME`\n * (`tempest_fastapi_sdk/api/middlewares/csrf.py`), which is the cookie its\n * `make_csrf_token_dependency()` sets and its `CSRFMiddleware` compares against.\n * Matching it is what lets `csrf: true` work against that backend with no\n * configuration on either side.\n */\nexport const DEFAULT_CSRF_COOKIE_NAME = \"csrf_token\";\n\n/**\n * Default header the CSRF token is echoed in.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_HEADER_NAME`, the header its\n * `CSRFMiddleware` reads on every unsafe request.\n */\nexport const DEFAULT_CSRF_HEADER_NAME = \"X-CSRF-Token\";\n\n/**\n * Where the CSRF token comes from and which header carries it.\n *\n * The default is the **double-submit cookie**: the server sets a cookie that is\n * deliberately not `HttpOnly`, the client reads it and echoes the value in a\n * header, and the server rejects a write whose header does not match the\n * cookie. A page on another site can make the browser *send* the cookie, but\n * cannot *read* it, so it cannot write the header.\n *\n * The token is read again on every request, so a server that rotates the\n * cookie is followed without any capture step: the browser's cookie jar is the\n * store. That is also why there is no \"read the token from a response header\"\n * mode — it would depend on `Access-Control-Expose-Headers`, and a missing\n * expose header fails silently, as a `403` on the second write.\n */\nexport interface CsrfOptions {\n    /** Cookie to read the token from. Default {@link DEFAULT_CSRF_COOKIE_NAME}. */\n    cookieName?: string;\n    /** Header to send the token in. Default {@link DEFAULT_CSRF_HEADER_NAME}. */\n    headerName?: string;\n    /**\n     * Supply the token yourself instead of reading `cookieName`.\n     *\n     * For the cases the cookie cannot serve: an API on another **site**, whose\n     * cookie `document.cookie` cannot see, or a backend that hands the token\n     * out in a response body. Called per request, like `getToken`.\n     */\n    getToken?: () => string | null | undefined;\n}\n\n/**\n * Methods that must not change state, and so never carry the token.\n *\n * A deny list rather than an allow list of the four write verbs: RFC 9110\n * names the safe methods, and a custom method (`PROPFIND`, a tus extension)\n * is a write until proven otherwise. Sending the token to its own origin on\n * an unexpected verb costs nothing; omitting it costs a `403`.\n */\nconst SAFE_METHODS: ReadonlySet<string> = new Set([\"GET\", \"HEAD\", \"OPTIONS\", \"TRACE\"]);\n\n/** Token sources already reported empty, so a burst of writes warns once. */\nconst reportedMissing = new Set<string>();\n\n/**\n * Read one cookie from `document.cookie`, or `null` when it is absent.\n *\n * Returns `null` outside a document (a worker, a test without jsdom), where\n * there is no cookie jar to read. The value is URI-decoded when it can be,\n * and returned raw when it is not valid percent-encoding.\n *\n * @param name - The cookie name.\n * @returns The value, or `null`.\n */\nfunction readCookie(name: string): string | null {\n    if (typeof document === \"undefined\") return null;\n    const prefix = `${name}=`;\n    for (const part of document.cookie.split(\";\")) {\n        const entry = part.trim();\n        if (!entry.startsWith(prefix)) continue;\n        const raw = entry.slice(prefix.length);\n        try {\n            return decodeURIComponent(raw);\n        } catch {\n            return raw;\n        }\n    }\n    return null;\n}\n\n/**\n * Say once, in a development build, that CSRF is on but there is no token.\n *\n * The request still goes out, because the SDK cannot know whether this path\n * is guarded — `CSRFMiddleware` is commonly mounted with `exclude_paths`. When\n * it is guarded, the symptom is a `403 CSRF_VALIDATION_FAILED` with nothing\n * in the app's code pointing at the cause, and the three usual causes are all\n * on the server: the cookie was never issued, was issued `HttpOnly`, or was\n * issued for a domain this page cannot read.\n *\n * @param source - What was read: the cookie name, or `\"getToken\"`.\n */\nfunction reportMissingToken(source: string): void {\n    if (!isDevBuild() || reportedMissing.has(source)) return;\n    reportedMissing.add(source);\n    const where =\n        source === \"getToken\"\n            ? \"csrf.getToken() returned nothing\"\n            : `no readable \"${source}\" cookie on this page`;\n    console.warn(\n        `[tempest-react-sdk] CSRF is enabled but ${where}, so the write went without the token. The cookie must be issued before the first write and must not be HttpOnly.`,\n    );\n}\n\n/**\n * Whether a header is already present, compared case-insensitively.\n *\n * Header names are case-insensitive, but object keys are not: a caller's\n * `\"x-csrf-token\"` next to the SDK's `\"X-CSRF-Token\"` would reach `fetch` as\n * two entries and be joined into `\"a, b\"`, which matches neither.\n *\n * @param headers - The headers the caller already set.\n * @param name - The header to look for.\n * @returns Whether it is set.\n */\nfunction hasHeader(headers: HeadersInit | undefined, name: string): boolean {\n    if (!headers) return false;\n    return new Headers(headers).has(name);\n}\n\n/** What {@link csrfHeaders} needs to decide. */\nexport interface CsrfHeadersInput {\n    /** The HTTP method of the request. Case-insensitive. */\n    method: string;\n    /** The URL the request is going to. */\n    url: string;\n    /**\n     * The origin the token belongs to, normally the API's `baseURL`. The token\n     * is only sent to this origin or to one listed in `trustedOrigins`.\n     */\n    reference: string;\n    /** The CSRF config. `undefined` or `false` turns the header off. */\n    csrf: boolean | CsrfOptions | undefined;\n    /** Extra origins allowed to receive the token. */\n    trustedOrigins?: readonly string[];\n    /** Headers the caller already set. A CSRF header among them is never replaced. */\n    headers?: HeadersInit;\n}\n\n/**\n * The CSRF header a request should carry, or an empty object.\n *\n * Every request path in the SDK — `createApiClient`, `uploadWithProgress`,\n * `createResumableUpload` — asks this function, so the rules are one rule:\n *\n * - **Off unless configured.** Without `csrf`, nothing changes.\n * - **Unsafe methods only.** `GET`, `HEAD`, `OPTIONS` and `TRACE` never carry\n *   it; they must not change state, and a token in a `GET` ends up in logs\n *   and caches for nothing.\n * - **Never across an origin.** The token follows the same scope as the bearer\n *   credential ({@link isTrustedCredentialTarget}), because a URL can come off\n *   the network — a tus `Location`, a pagination link — and a CSRF token sent\n *   to a third party is a token that third party can replay. Withheld tokens\n *   are reported once per origin in a development build.\n * - **Your header wins.** A CSRF header you set by hand, in any casing, is\n *   left alone.\n * - **Independent of auth.** It is sent on `skipAuth` requests too: login and\n *   refresh are exactly the writes a cookie session exposes to forgery.\n *\n * Exported for the request you build by hand, so it follows the same rules.\n *\n * @example\n * const headers = csrfHeaders({\n *     method: \"POST\",\n *     url: \"https://api.acme.com/orders\",\n *     reference: \"https://api.acme.com\",\n *     csrf: true,\n * });\n * // { \"X-CSRF-Token\": \"<value of the csrf_token cookie>\" }\n *\n * @param input - The request and the CSRF config.\n * @returns A header record to spread into the request's headers.\n */\nexport function csrfHeaders(input: CsrfHeadersInput): Record<string, string> {\n    const { method, url, reference, csrf, trustedOrigins, headers } = input;\n    if (!csrf) return {};\n    if (SAFE_METHODS.has(method.toUpperCase())) return {};\n    const options: CsrfOptions = csrf === true ? {} : csrf;\n    const headerName = options.headerName ?? DEFAULT_CSRF_HEADER_NAME;\n    if (hasHeader(headers, headerName)) return {};\n    if (!isTrustedCredentialTarget(url, reference, trustedOrigins)) {\n        reportSuppressedCredential(url, reference, headerName);\n        return {};\n    }\n    const cookieName = options.cookieName ?? DEFAULT_CSRF_COOKIE_NAME;\n    const token = options.getToken ? options.getToken() : readCookie(cookieName);\n    if (!token) {\n        reportMissingToken(options.getToken ? \"getToken\" : cookieName);\n        return {};\n    }\n    return { [headerName]: token };\n}\n\n/**\n * Forget which token sources were already reported empty.\n *\n * Exported for tests, which assert the once-per-source behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetCsrfReports(): void {\n    reportedMissing.clear();\n}\n"],"mappings":"A,6EAYA,IAAaI,EAA2B,aAQ3BC,EAA2B,eAwClCC,EAAoC,IAAI,IAAI,CAAC,MAAO,OAAQ,UAAW,OAAO,CAAC,EAG/EC,EAAkB,IAAI,IAY5B,SAASC,EAAW,EAA6B,CAC7C,GAAI,OAAO,SAAa,IAAa,OAAO,KAC5C,IAAMC,EAAS,GAAGC,EAAK,GACvB,IAAK,IAAMC,KAAQ,SAAS,OAAO,MAAM,GAAG,EAAG,CAC3C,IAAMC,EAAQD,EAAK,KAAK,EACxB,GAAI,CAACC,EAAM,WAAWH,CAAM,EAAG,SAC/B,IAAMI,EAAMD,EAAM,MAAMH,EAAO,MAAM,EACrC,GAAI,CACA,OAAO,mBAAmBI,CAAG,CACjC,MAAQ,CACJ,OAAOA,CACX,CACJ,CACA,OAAO,IACX,CAcA,SAASC,EAAmB,EAAsB,CAC9C,GAAI,CAACd,EAAAA,WAAW,GAAKO,EAAgB,IAAIQ,CAAM,EAAG,OAClDR,EAAgB,IAAIQ,CAAM,EAC1B,IAAMC,EACFD,IAAW,WACL,mCACA,gBAAgBA,EAAO,uBACjC,QAAQ,KACJ,2CAA2CC,EAAM,kHACrD,CACJ,CAaA,SAASC,EAAU,EAAkC,EAAuB,CAExE,OADKC,EACE,IAAI,QAAQA,CAAO,CAAC,CAAC,IAAIR,CAAI,EADf,EAEzB,CAuDA,SAAgBS,EAAY,EAAiD,CACzE,GAAM,CAAE,SAAQ,MAAK,YAAW,OAAM,iBAAgB,WAAYC,EAElE,GADI,CAACC,GACDf,EAAa,IAAIgB,EAAO,YAAY,CAAC,EAAG,MAAO,CAAC,EACpD,IAAMC,EAAuBF,IAAS,GAAO,CAAC,EAAIA,EAC5CG,EAAaD,EAAQ,YAAA,eAC3B,GAAIN,EAAUC,EAASM,CAAU,EAAG,MAAO,CAAC,EAC5C,GAAI,CAACvB,EAAAA,0BAA0BwB,EAAKC,EAAWC,CAAc,EAEzD,OADAxB,EAAA,2BAA2BsB,EAAKC,EAAWF,CAAU,EAC9C,CAAC,EAEZ,IAAMI,EAAaL,EAAQ,YAAA,aACrBM,EAAQN,EAAQ,SAAWA,EAAQ,SAAS,EAAIf,EAAWoB,CAAU,EAK3E,OAJKC,EAIE,EAAGL,GAAaK,CAAM,GAHzBf,EAAmBS,EAAQ,SAAW,WAAaK,CAAU,EACtD,CAAC,EAGhB,C"}

package/dist/http/csrf.js.map

@@ -1 +1 @@
-{"version":3,"file":"csrf.js","names":[],"sources":["../../src/http/csrf.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\nimport { isTrustedCredentialTarget, reportSuppressedCredential } from \"./credential-scope\";\n\n/**\n * Default cookie the CSRF token is read from.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_COOKIE_NAME`\n * (`tempest_fastapi_sdk/api/middlewares/csrf.py`), which is the cookie its\n * `make_csrf_token_dependency()` sets and its `CSRFMiddleware` compares against.\n * Matching it is what lets `csrf: true` work against that backend with no\n * configuration on either side.\n */\nexport const DEFAULT_CSRF_COOKIE_NAME = \"csrf_token\";\n\n/**\n * Default header the CSRF token is echoed in.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_HEADER_NAME`, the header its\n * `CSRFMiddleware` reads on every unsafe request.\n */\nexport const DEFAULT_CSRF_HEADER_NAME = \"X-CSRF-Token\";\n\n/**\n * Where the CSRF token comes from and which header carries it.\n *\n * The default is the **double-submit cookie**: the server sets a cookie that is\n * deliberately not `HttpOnly`, the client reads it and echoes the value in a\n * header, and the server rejects a write whose header does not match the\n * cookie. A page on another site can make the browser *send* the cookie, but\n * cannot *read* it, so it cannot write the header.\n *\n * The token is read again on every request, so a server that rotates the\n * cookie is followed without any capture step: the browser's cookie jar is the\n * store. That is also why there is no \"read the token from a response header\"\n * mode — it would depend on `Access-Control-Expose-Headers`, and a missing\n * expose header fails silently, as a `403` on the second write.\n */\nexport interface CsrfOptions {\n    /** Cookie to read the token from. Default {@link DEFAULT_CSRF_COOKIE_NAME}. */\n    cookieName?: string;\n    /** Header to send the token in. Default {@link DEFAULT_CSRF_HEADER_NAME}. */\n    headerName?: string;\n    /**\n     * Supply the token yourself instead of reading `cookieName`.\n     *\n     * For the cases the cookie cannot serve: an API on another **site**, whose\n     * cookie `document.cookie` cannot see, or a backend that hands the token\n     * out in a response body. Called per request, like `getToken`.\n     */\n    getToken?: () => string | null | undefined;\n}\n\n/**\n * Methods that must not change state, and so never carry the token.\n *\n * A deny list rather than an allow list of the four write verbs: RFC 9110\n * names the safe methods, and a custom method (`PROPFIND`, a tus extension)\n * is a write until proven otherwise. Sending the token to its own origin on\n * an unexpected verb costs nothing; omitting it costs a `403`.\n */\nconst SAFE_METHODS: ReadonlySet<string> = new Set([\"GET\", \"HEAD\", \"OPTIONS\", \"TRACE\"]);\n\n/** Token sources already reported empty, so a burst of writes warns once. */\nconst reportedMissing = new Set<string>();\n\n/**\n * Read one cookie from `document.cookie`, or `null` when it is absent.\n *\n * Returns `null` outside a document (a worker, a test without jsdom), where\n * there is no cookie jar to read. The value is URI-decoded when it can be,\n * and returned raw when it is not valid percent-encoding.\n *\n * @param name - The cookie name.\n * @returns The value, or `null`.\n */\nfunction readCookie(name: string): string | null {\n    if (typeof document === \"undefined\") return null;\n    const prefix = `${name}=`;\n    for (const part of document.cookie.split(\";\")) {\n        const entry = part.trim();\n        if (!entry.startsWith(prefix)) continue;\n        const raw = entry.slice(prefix.length);\n        try {\n            return decodeURIComponent(raw);\n        } catch {\n            return raw;\n        }\n    }\n    return null;\n}\n\n/**\n * Say once, in a development build, that CSRF is on but there is no token.\n *\n * The request still goes out, because the SDK cannot know whether this path\n * is guarded — `CSRFMiddleware` is commonly mounted with `exclude_paths`. When\n * it is guarded, the symptom is a `403 CSRF_VALIDATION_FAILED` with nothing\n * in the app's code pointing at the cause, and the three usual causes are all\n * on the server: the cookie was never issued, was issued `HttpOnly`, or was\n * issued for a domain this page cannot read.\n *\n * @param source - What was read: the cookie name, or `\"getToken\"`.\n */\nfunction reportMissingToken(source: string): void {\n    if (!isDevBuild() || reportedMissing.has(source)) return;\n    reportedMissing.add(source);\n    const where =\n        source === \"getToken\"\n            ? \"csrf.getToken() returned nothing\"\n            : `no readable \"${source}\" cookie on this page`;\n    console.warn(\n        `[tempest-react-sdk] CSRF is enabled but ${where}, so the write went without the token. The cookie must be issued before the first write and must not be HttpOnly.`,\n    );\n}\n\n/**\n * Whether a header is already present, compared case-insensitively.\n *\n * Header names are case-insensitive, but object keys are not: a caller's\n * `\"x-csrf-token\"` next to the SDK's `\"X-CSRF-Token\"` would reach `fetch` as\n * two entries and be joined into `\"a, b\"`, which matches neither.\n *\n * @param headers - The headers the caller already set.\n * @param name - The header to look for.\n * @returns Whether it is set.\n */\nfunction hasHeader(headers: HeadersInit | undefined, name: string): boolean {\n    if (!headers) return false;\n    return new Headers(headers).has(name);\n}\n\n/** What {@link csrfHeaders} needs to decide. */\nexport interface CsrfHeadersInput {\n    /** The HTTP method of the request. Case-insensitive. */\n    method: string;\n    /** The URL the request is going to. */\n    url: string;\n    /**\n     * The origin the token belongs to, normally the API's `baseURL`. The token\n     * is only sent to this origin or to one listed in `trustedOrigins`.\n     */\n    reference: string;\n    /** The CSRF config. `undefined` or `false` turns the header off. */\n    csrf: boolean | CsrfOptions | undefined;\n    /** Extra origins allowed to receive the token. */\n    trustedOrigins?: readonly string[];\n    /** Headers the caller already set. A CSRF header among them is never replaced. */\n    headers?: HeadersInit;\n}\n\n/**\n * The CSRF header a request should carry, or an empty object.\n *\n * Every request path in the SDK — `createApiClient`, `uploadWithProgress`,\n * `createResumableUpload` — asks this function, so the rules are one rule:\n *\n * - **Off unless configured.** Without `csrf`, nothing changes.\n * - **Unsafe methods only.** `GET`, `HEAD`, `OPTIONS` and `TRACE` never carry\n *   it; they must not change state, and a token in a `GET` ends up in logs\n *   and caches for nothing.\n * - **Never across an origin.** The token follows the same scope as the bearer\n *   credential ({@link isTrustedCredentialTarget}), because a URL can come off\n *   the network — a tus `Location`, a pagination link — and a CSRF token sent\n *   to a third party is a token that third party can replay. Withheld tokens\n *   are reported once per origin in a development build.\n * - **Your header wins.** A CSRF header you set by hand, in any casing, is\n *   left alone.\n * - **Independent of auth.** It is sent on `skipAuth` requests too: login and\n *   refresh are exactly the writes a cookie session exposes to forgery.\n *\n * Exported for the request you build by hand, so it follows the same rules.\n *\n * @example\n * const headers = csrfHeaders({\n *     method: \"POST\",\n *     url: \"https://api.acme.com/orders\",\n *     reference: \"https://api.acme.com\",\n *     csrf: true,\n * });\n * // { \"X-CSRF-Token\": \"<value of the csrf_token cookie>\" }\n *\n * @param input - The request and the CSRF config.\n * @returns A header record to spread into the request's headers.\n */\nexport function csrfHeaders(input: CsrfHeadersInput): Record<string, string> {\n    const { method, url, reference, csrf, trustedOrigins, headers } = input;\n    if (!csrf) return {};\n    if (SAFE_METHODS.has(method.toUpperCase())) return {};\n    const options: CsrfOptions = csrf === true ? {} : csrf;\n    const headerName = options.headerName ?? DEFAULT_CSRF_HEADER_NAME;\n    if (hasHeader(headers, headerName)) return {};\n    if (!isTrustedCredentialTarget(url, reference, trustedOrigins)) {\n        reportSuppressedCredential(url, reference, headerName);\n        return {};\n    }\n    const cookieName = options.cookieName ?? DEFAULT_CSRF_COOKIE_NAME;\n    const token = options.getToken ? options.getToken() : readCookie(cookieName);\n    if (!token) {\n        reportMissingToken(options.getToken ? \"getToken\" : cookieName);\n        return {};\n    }\n    return { [headerName]: token };\n}\n\n/**\n * Forget which token sources were already reported empty.\n *\n * Exported for tests, which assert the once-per-source behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetCsrfReports(): void {\n    reportedMissing.clear();\n}\n"],"mappings":";;;AAYA,IAAa,IAA2B,cAQ3B,IAA2B,gBAwClC,oBAAoC,IAAI,IAAI;CAAC;CAAO;CAAQ;CAAW;AAAO,CAAC,GAG/E,oBAAkB,IAAI,IAAY;AAYxC,SAAS,EAAW,GAA6B;CAC7C,IAAI,OAAO,WAAa,KAAa,OAAO;CAC5C,IAAM,IAAS,GAAG,EAAK;CACvB,KAAK,IAAM,KAAQ,SAAS,OAAO,MAAM,GAAG,GAAG;EAC3C,IAAM,IAAQ,EAAK,KAAK;EACxB,IAAI,CAAC,EAAM,WAAW,CAAM,GAAG;EAC/B,IAAM,IAAM,EAAM,MAAM,EAAO,MAAM;EACrC,IAAI;GACA,OAAO,mBAAmB,CAAG;EACjC,QAAQ;GACJ,OAAO;EACX;CACJ;CACA,OAAO;AACX;AAcA,SAAS,EAAmB,GAAsB;CAC9C,IAAI,CAAC,EAAW,KAAK,EAAgB,IAAI,CAAM,GAAG;CAClD,EAAgB,IAAI,CAAM;CAC1B,IAAM,IACF,MAAW,aACL,qCACA,gBAAgB,EAAO;CACjC,QAAQ,KACJ,2CAA2C,EAAM,kHACrD;AACJ;AAaA,SAAS,EAAU,GAAkC,GAAuB;CAExE,OADK,IACE,IAAI,QAAQ,CAAO,CAAC,CAAC,IAAI,CAAI,IADf;AAEzB;AAuDA,SAAgB,EAAY,GAAiD;CACzE,IAAM,EAAE,WAAQ,QAAK,cAAW,SAAM,mBAAgB,eAAY;CAElE,IADI,CAAC,KACD,EAAa,IAAI,EAAO,YAAY,CAAC,GAAG,OAAO,CAAC;CACpD,IAAM,IAAuB,MAAS,KAAO,CAAC,IAAI,GAC5C,IAAa,EAAQ,cAAA;CAC3B,IAAI,EAAU,GAAS,CAAU,GAAG,OAAO,CAAC;CAC5C,IAAI,CAAC,EAA0B,GAAK,GAAW,CAAc,GAEzD,OADA,EAA2B,GAAK,GAAW,CAAU,GAC9C,CAAC;CAEZ,IAAM,IAAa,EAAQ,cAAA,cACrB,IAAQ,EAAQ,WAAW,EAAQ,SAAS,IAAI,EAAW,CAAU;CAK3E,OAJK,IAIE,GAAG,IAAa,EAAM,KAHzB,EAAmB,EAAQ,WAAW,aAAa,CAAU,GACtD,CAAC;AAGhB"}
+{"version":3,"file":"csrf.js","names":["DEFAULT_CSRF_COOKIE_NAME","DEFAULT_CSRF_HEADER_NAME","SAFE_METHODS","reportedMissing","readCookie","prefix","name","part","entry","raw","reportMissingToken","isDevBuild","source","where","hasHeader","headers","csrfHeaders","input","csrf","method","options","headerName","isTrustedCredentialTarget","url","reference","trustedOrigins","reportSuppressedCredential","cookieName","token"],"sources":["../../src/http/csrf.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\nimport { isTrustedCredentialTarget, reportSuppressedCredential } from \"./credential-scope\";\n\n/**\n * Default cookie the CSRF token is read from.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_COOKIE_NAME`\n * (`tempest_fastapi_sdk/api/middlewares/csrf.py`), which is the cookie its\n * `make_csrf_token_dependency()` sets and its `CSRFMiddleware` compares against.\n * Matching it is what lets `csrf: true` work against that backend with no\n * configuration on either side.\n */\nexport const DEFAULT_CSRF_COOKIE_NAME = \"csrf_token\";\n\n/**\n * Default header the CSRF token is echoed in.\n *\n * Ported from `tempest-fastapi-sdk`'s `CSRF_HEADER_NAME`, the header its\n * `CSRFMiddleware` reads on every unsafe request.\n */\nexport const DEFAULT_CSRF_HEADER_NAME = \"X-CSRF-Token\";\n\n/**\n * Where the CSRF token comes from and which header carries it.\n *\n * The default is the **double-submit cookie**: the server sets a cookie that is\n * deliberately not `HttpOnly`, the client reads it and echoes the value in a\n * header, and the server rejects a write whose header does not match the\n * cookie. A page on another site can make the browser *send* the cookie, but\n * cannot *read* it, so it cannot write the header.\n *\n * The token is read again on every request, so a server that rotates the\n * cookie is followed without any capture step: the browser's cookie jar is the\n * store. That is also why there is no \"read the token from a response header\"\n * mode — it would depend on `Access-Control-Expose-Headers`, and a missing\n * expose header fails silently, as a `403` on the second write.\n */\nexport interface CsrfOptions {\n    /** Cookie to read the token from. Default {@link DEFAULT_CSRF_COOKIE_NAME}. */\n    cookieName?: string;\n    /** Header to send the token in. Default {@link DEFAULT_CSRF_HEADER_NAME}. */\n    headerName?: string;\n    /**\n     * Supply the token yourself instead of reading `cookieName`.\n     *\n     * For the cases the cookie cannot serve: an API on another **site**, whose\n     * cookie `document.cookie` cannot see, or a backend that hands the token\n     * out in a response body. Called per request, like `getToken`.\n     */\n    getToken?: () => string | null | undefined;\n}\n\n/**\n * Methods that must not change state, and so never carry the token.\n *\n * A deny list rather than an allow list of the four write verbs: RFC 9110\n * names the safe methods, and a custom method (`PROPFIND`, a tus extension)\n * is a write until proven otherwise. Sending the token to its own origin on\n * an unexpected verb costs nothing; omitting it costs a `403`.\n */\nconst SAFE_METHODS: ReadonlySet<string> = new Set([\"GET\", \"HEAD\", \"OPTIONS\", \"TRACE\"]);\n\n/** Token sources already reported empty, so a burst of writes warns once. */\nconst reportedMissing = new Set<string>();\n\n/**\n * Read one cookie from `document.cookie`, or `null` when it is absent.\n *\n * Returns `null` outside a document (a worker, a test without jsdom), where\n * there is no cookie jar to read. The value is URI-decoded when it can be,\n * and returned raw when it is not valid percent-encoding.\n *\n * @param name - The cookie name.\n * @returns The value, or `null`.\n */\nfunction readCookie(name: string): string | null {\n    if (typeof document === \"undefined\") return null;\n    const prefix = `${name}=`;\n    for (const part of document.cookie.split(\";\")) {\n        const entry = part.trim();\n        if (!entry.startsWith(prefix)) continue;\n        const raw = entry.slice(prefix.length);\n        try {\n            return decodeURIComponent(raw);\n        } catch {\n            return raw;\n        }\n    }\n    return null;\n}\n\n/**\n * Say once, in a development build, that CSRF is on but there is no token.\n *\n * The request still goes out, because the SDK cannot know whether this path\n * is guarded — `CSRFMiddleware` is commonly mounted with `exclude_paths`. When\n * it is guarded, the symptom is a `403 CSRF_VALIDATION_FAILED` with nothing\n * in the app's code pointing at the cause, and the three usual causes are all\n * on the server: the cookie was never issued, was issued `HttpOnly`, or was\n * issued for a domain this page cannot read.\n *\n * @param source - What was read: the cookie name, or `\"getToken\"`.\n */\nfunction reportMissingToken(source: string): void {\n    if (!isDevBuild() || reportedMissing.has(source)) return;\n    reportedMissing.add(source);\n    const where =\n        source === \"getToken\"\n            ? \"csrf.getToken() returned nothing\"\n            : `no readable \"${source}\" cookie on this page`;\n    console.warn(\n        `[tempest-react-sdk] CSRF is enabled but ${where}, so the write went without the token. The cookie must be issued before the first write and must not be HttpOnly.`,\n    );\n}\n\n/**\n * Whether a header is already present, compared case-insensitively.\n *\n * Header names are case-insensitive, but object keys are not: a caller's\n * `\"x-csrf-token\"` next to the SDK's `\"X-CSRF-Token\"` would reach `fetch` as\n * two entries and be joined into `\"a, b\"`, which matches neither.\n *\n * @param headers - The headers the caller already set.\n * @param name - The header to look for.\n * @returns Whether it is set.\n */\nfunction hasHeader(headers: HeadersInit | undefined, name: string): boolean {\n    if (!headers) return false;\n    return new Headers(headers).has(name);\n}\n\n/** What {@link csrfHeaders} needs to decide. */\nexport interface CsrfHeadersInput {\n    /** The HTTP method of the request. Case-insensitive. */\n    method: string;\n    /** The URL the request is going to. */\n    url: string;\n    /**\n     * The origin the token belongs to, normally the API's `baseURL`. The token\n     * is only sent to this origin or to one listed in `trustedOrigins`.\n     */\n    reference: string;\n    /** The CSRF config. `undefined` or `false` turns the header off. */\n    csrf: boolean | CsrfOptions | undefined;\n    /** Extra origins allowed to receive the token. */\n    trustedOrigins?: readonly string[];\n    /** Headers the caller already set. A CSRF header among them is never replaced. */\n    headers?: HeadersInit;\n}\n\n/**\n * The CSRF header a request should carry, or an empty object.\n *\n * Every request path in the SDK — `createApiClient`, `uploadWithProgress`,\n * `createResumableUpload` — asks this function, so the rules are one rule:\n *\n * - **Off unless configured.** Without `csrf`, nothing changes.\n * - **Unsafe methods only.** `GET`, `HEAD`, `OPTIONS` and `TRACE` never carry\n *   it; they must not change state, and a token in a `GET` ends up in logs\n *   and caches for nothing.\n * - **Never across an origin.** The token follows the same scope as the bearer\n *   credential ({@link isTrustedCredentialTarget}), because a URL can come off\n *   the network — a tus `Location`, a pagination link — and a CSRF token sent\n *   to a third party is a token that third party can replay. Withheld tokens\n *   are reported once per origin in a development build.\n * - **Your header wins.** A CSRF header you set by hand, in any casing, is\n *   left alone.\n * - **Independent of auth.** It is sent on `skipAuth` requests too: login and\n *   refresh are exactly the writes a cookie session exposes to forgery.\n *\n * Exported for the request you build by hand, so it follows the same rules.\n *\n * @example\n * const headers = csrfHeaders({\n *     method: \"POST\",\n *     url: \"https://api.acme.com/orders\",\n *     reference: \"https://api.acme.com\",\n *     csrf: true,\n * });\n * // { \"X-CSRF-Token\": \"<value of the csrf_token cookie>\" }\n *\n * @param input - The request and the CSRF config.\n * @returns A header record to spread into the request's headers.\n */\nexport function csrfHeaders(input: CsrfHeadersInput): Record<string, string> {\n    const { method, url, reference, csrf, trustedOrigins, headers } = input;\n    if (!csrf) return {};\n    if (SAFE_METHODS.has(method.toUpperCase())) return {};\n    const options: CsrfOptions = csrf === true ? {} : csrf;\n    const headerName = options.headerName ?? DEFAULT_CSRF_HEADER_NAME;\n    if (hasHeader(headers, headerName)) return {};\n    if (!isTrustedCredentialTarget(url, reference, trustedOrigins)) {\n        reportSuppressedCredential(url, reference, headerName);\n        return {};\n    }\n    const cookieName = options.cookieName ?? DEFAULT_CSRF_COOKIE_NAME;\n    const token = options.getToken ? options.getToken() : readCookie(cookieName);\n    if (!token) {\n        reportMissingToken(options.getToken ? \"getToken\" : cookieName);\n        return {};\n    }\n    return { [headerName]: token };\n}\n\n/**\n * Forget which token sources were already reported empty.\n *\n * Exported for tests, which assert the once-per-source behaviour and would\n * otherwise leak state between cases.\n */\nexport function resetCsrfReports(): void {\n    reportedMissing.clear();\n}\n"],"mappings":";;;AAYA,IAAaA,IAA2B,cAQ3BC,IAA2B,gBAwClCC,oBAAoC,IAAI,IAAI;CAAC;CAAO;CAAQ;CAAW;AAAO,CAAC,GAG/EC,oBAAkB,IAAI,IAAY;AAYxC,SAASC,EAAW,GAA6B;CAC7C,IAAI,OAAO,WAAa,KAAa,OAAO;CAC5C,IAAMC,IAAS,GAAGC,EAAK;CACvB,KAAK,IAAMC,KAAQ,SAAS,OAAO,MAAM,GAAG,GAAG;EAC3C,IAAMC,IAAQD,EAAK,KAAK;EACxB,IAAI,CAACC,EAAM,WAAWH,CAAM,GAAG;EAC/B,IAAMI,IAAMD,EAAM,MAAMH,EAAO,MAAM;EACrC,IAAI;GACA,OAAO,mBAAmBI,CAAG;EACjC,QAAQ;GACJ,OAAOA;EACX;CACJ;CACA,OAAO;AACX;AAcA,SAASC,EAAmB,GAAsB;CAC9C,IAAI,CAACC,EAAW,KAAKR,EAAgB,IAAIS,CAAM,GAAG;CAClD,EAAgB,IAAIA,CAAM;CAC1B,IAAMC,IACFD,MAAW,aACL,qCACA,gBAAgBA,EAAO;CACjC,QAAQ,KACJ,2CAA2CC,EAAM,kHACrD;AACJ;AAaA,SAASC,EAAU,GAAkC,GAAuB;CAExE,OADKC,IACE,IAAI,QAAQA,CAAO,CAAC,CAAC,IAAIT,CAAI,IADf;AAEzB;AAuDA,SAAgBU,EAAY,GAAiD;CACzE,IAAM,EAAE,WAAQ,QAAK,cAAW,SAAM,mBAAgB,eAAYC;CAElE,IADI,CAACC,KACDhB,EAAa,IAAIiB,EAAO,YAAY,CAAC,GAAG,OAAO,CAAC;CACpD,IAAMC,IAAuBF,MAAS,KAAO,CAAC,IAAIA,GAC5CG,IAAaD,EAAQ,cAAA;CAC3B,IAAIN,EAAUC,GAASM,CAAU,GAAG,OAAO,CAAC;CAC5C,IAAI,CAACC,EAA0BC,GAAKC,GAAWC,CAAc,GAEzD,OADAC,EAA2BH,GAAKC,GAAWH,CAAU,GAC9C,CAAC;CAEZ,IAAMM,IAAaP,EAAQ,cAAA,cACrBQ,IAAQR,EAAQ,WAAWA,EAAQ,SAAS,IAAIhB,EAAWuB,CAAU;CAK3E,OAJKC,IAIE,GAAGP,IAAaO,EAAM,KAHzBlB,EAAmBU,EAAQ,WAAW,aAAaO,CAAU,GACtD,CAAC;AAGhB"}

package/dist/http/decode-response.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"decode-response.cjs","names":[],"sources":["../../src/http/decode-response.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Media-type fragments that name something safe to read as text, for the types\n * that do not open with `text/` — `application/xml`, `application/javascript`,\n * `application/x-www-form-urlencoded`.\n */\nconst TEXTUAL_TOKENS: readonly string[] = [\"xml\", \"javascript\", \"ecmascript\", \"urlencoded\", \"csv\"];\n\n/** How a {@link createApiClient} response body becomes the value a caller awaited. */\nexport type ResponseDecoder<T> = (response: Response) => Promise<T>;\n\n/**\n * Whether a `Content-Type` names a JSON dialect.\n *\n * Matches the suffix forms as well as the plain one, so `application/json`,\n * `application/problem+json` (RFC 9457, what a FastAPI error handler sends) and\n * `application/vnd.tempest.v2+json` all decode as JSON instead of falling\n * through to text.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.json()`.\n */\nexport function isJsonContentType(contentType: string): boolean {\n    return contentType.toLowerCase().includes(\"json\");\n}\n\n/**\n * Whether a `Content-Type` names something that survives being read as text.\n *\n * An absent header counts as textual: a backend that answers without one is\n * almost always sending text, and treating it as binary would change what\n * existing callers get back for no measured gain.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.text()`.\n */\nexport function isTextualContentType(contentType: string): boolean {\n    const type = contentType.trim().toLowerCase();\n    if (type === \"\") return true;\n    if (type.startsWith(\"text/\")) return true;\n    return TEXTUAL_TOKENS.some((token) => type.includes(token));\n}\n\n/**\n * Warn, in a development build, that a binary body reached the JSON/text path.\n *\n * @param contentType - The `Content-Type` that was decoded as a `Blob`.\n */\nfunction warnBinaryBody(contentType: string): void {\n    if (!isDevBuild()) return;\n    console.warn(\n        `[tempest] <ApiClient> received a binary response (content-type: ${contentType}) and returned a Blob. ` +\n            \"Call `client.blob()` or `client.arrayBuffer()` so the type matches what arrives.\",\n    );\n}\n\n/**\n * Decode a response the way its `Content-Type` asks to be decoded.\n *\n * JSON is parsed, text is read as text, and **everything else comes back as a\n * `Blob`**. That last branch is the fix for a silent data defect: the client\n * used to fall back to `response.text()` for any non-JSON body, so an\n * `image/jpeg` was decoded as UTF-8 and the bytes were destroyed on the way in.\n * Measured on a bare JPEG header — `ff d8 ff e0 00 10 4a 46 49 46` — the\n * round-trip through text returns 18 bytes for the 10 that arrived, 4 of them\n * replaced by `U+FFFD`. No caller can undo that, which is why the download had\n * to leave the client entirely.\n *\n * A `204` has no body at all and resolves to `undefined`, whatever the headers\n * claim.\n *\n * @typeParam T - What the caller expects back.\n * @param response - A response already known to be successful.\n * @returns The decoded body.\n */\nexport async function decodeByContentType<T>(response: Response): Promise<T> {\n    if (response.status === 204) {\n        return undefined as T;\n    }\n\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n    if (isJsonContentType(contentType)) {\n        return (await response.json()) as T;\n    }\n    if (isTextualContentType(contentType)) {\n        return (await response.text()) as unknown as T;\n    }\n\n    warnBinaryBody(contentType);\n    return (await response.blob()) as unknown as T;\n}\n"],"mappings":"yCAOA,IAAM,EAAoC,CAAC,MAAO,aAAc,aAAc,aAAc,KAAK,EAgBjG,SAAgB,EAAkB,EAA8B,CAC5D,OAAO,EAAY,YAAY,CAAC,CAAC,SAAS,MAAM,CACpD,CAYA,SAAgB,EAAqB,EAA8B,CAC/D,IAAM,EAAO,EAAY,KAAK,CAAC,CAAC,YAAY,EAG5C,OAFI,IAAS,IACT,EAAK,WAAW,OAAO,EAAU,GAC9B,EAAe,KAAM,GAAU,EAAK,SAAS,CAAK,CAAC,CAC9D,CAOA,SAAS,EAAe,EAA2B,CAC1C,EAAA,WAAW,GAChB,QAAQ,KACJ,mEAAmE,EAAY,4GAEnF,CACJ,CAqBA,eAAsB,EAAuB,EAAgC,CACzE,GAAI,EAAS,SAAW,IACpB,OAGJ,IAAM,EAAc,EAAS,QAAQ,IAAI,cAAc,GAAK,GAS5D,OARI,EAAkB,CAAW,EACrB,MAAM,EAAS,KAAK,EAE5B,EAAqB,CAAW,EACxB,MAAM,EAAS,KAAK,GAGhC,EAAe,CAAW,EAClB,MAAM,EAAS,KAAK,EAChC"}
+{"version":3,"file":"decode-response.cjs","names":["isDevBuild","require_dev_mode","TEXTUAL_TOKENS","isJsonContentType","contentType","isTextualContentType","type","token","warnBinaryBody","decodeByContentType","response"],"sources":["../../src/http/decode-response.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Media-type fragments that name something safe to read as text, for the types\n * that do not open with `text/` — `application/xml`, `application/javascript`,\n * `application/x-www-form-urlencoded`.\n */\nconst TEXTUAL_TOKENS: readonly string[] = [\"xml\", \"javascript\", \"ecmascript\", \"urlencoded\", \"csv\"];\n\n/** How a {@link createApiClient} response body becomes the value a caller awaited. */\nexport type ResponseDecoder<T> = (response: Response) => Promise<T>;\n\n/**\n * Whether a `Content-Type` names a JSON dialect.\n *\n * Matches the suffix forms as well as the plain one, so `application/json`,\n * `application/problem+json` (RFC 9457, what a FastAPI error handler sends) and\n * `application/vnd.tempest.v2+json` all decode as JSON instead of falling\n * through to text.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.json()`.\n */\nexport function isJsonContentType(contentType: string): boolean {\n    return contentType.toLowerCase().includes(\"json\");\n}\n\n/**\n * Whether a `Content-Type` names something that survives being read as text.\n *\n * An absent header counts as textual: a backend that answers without one is\n * almost always sending text, and treating it as binary would change what\n * existing callers get back for no measured gain.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.text()`.\n */\nexport function isTextualContentType(contentType: string): boolean {\n    const type = contentType.trim().toLowerCase();\n    if (type === \"\") return true;\n    if (type.startsWith(\"text/\")) return true;\n    return TEXTUAL_TOKENS.some((token) => type.includes(token));\n}\n\n/**\n * Warn, in a development build, that a binary body reached the JSON/text path.\n *\n * @param contentType - The `Content-Type` that was decoded as a `Blob`.\n */\nfunction warnBinaryBody(contentType: string): void {\n    if (!isDevBuild()) return;\n    console.warn(\n        `[tempest] <ApiClient> received a binary response (content-type: ${contentType}) and returned a Blob. ` +\n            \"Call `client.blob()` or `client.arrayBuffer()` so the type matches what arrives.\",\n    );\n}\n\n/**\n * Decode a response the way its `Content-Type` asks to be decoded.\n *\n * JSON is parsed, text is read as text, and **everything else comes back as a\n * `Blob`**. That last branch is the fix for a silent data defect: the client\n * used to fall back to `response.text()` for any non-JSON body, so an\n * `image/jpeg` was decoded as UTF-8 and the bytes were destroyed on the way in.\n * Measured on a bare JPEG header — `ff d8 ff e0 00 10 4a 46 49 46` — the\n * round-trip through text returns 18 bytes for the 10 that arrived, 4 of them\n * replaced by `U+FFFD`. No caller can undo that, which is why the download had\n * to leave the client entirely.\n *\n * A `204` has no body at all and resolves to `undefined`, whatever the headers\n * claim.\n *\n * @typeParam T - What the caller expects back.\n * @param response - A response already known to be successful.\n * @returns The decoded body.\n */\nexport async function decodeByContentType<T>(response: Response): Promise<T> {\n    if (response.status === 204) {\n        return undefined as T;\n    }\n\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n    if (isJsonContentType(contentType)) {\n        return (await response.json()) as T;\n    }\n    if (isTextualContentType(contentType)) {\n        return (await response.text()) as unknown as T;\n    }\n\n    warnBinaryBody(contentType);\n    return (await response.blob()) as unknown as T;\n}\n"],"mappings":"A,yCAOA,IAAME,EAAoC,CAAC,MAAO,aAAc,aAAc,aAAc,KAAK,EAgBjG,SAAgBC,EAAkB,EAA8B,CAC5D,OAAOC,EAAY,YAAY,CAAC,CAAC,SAAS,MAAM,CACpD,CAYA,SAAgBC,EAAqB,EAA8B,CAC/D,IAAMC,EAAOF,EAAY,KAAK,CAAC,CAAC,YAAY,EAG5C,OAFIE,IAAS,IACTA,EAAK,WAAW,OAAO,EAAU,GAC9BJ,EAAe,KAAM,GAAUI,EAAK,SAASC,CAAK,CAAC,CAC9D,CAOA,SAASC,EAAe,EAA2B,CAC1CR,EAAAA,WAAW,GAChB,QAAQ,KACJ,mEAAmEI,EAAY,4GAEnF,CACJ,CAqBA,eAAsBK,EAAuB,EAAgC,CACzE,GAAIC,EAAS,SAAW,IACpB,OAGJ,IAAMN,EAAcM,EAAS,QAAQ,IAAI,cAAc,GAAK,GAS5D,OARIP,EAAkBC,CAAW,EACrB,MAAMM,EAAS,KAAK,EAE5BL,EAAqBD,CAAW,EACxB,MAAMM,EAAS,KAAK,GAGhCF,EAAeJ,CAAW,EAClB,MAAMM,EAAS,KAAK,EAChC,C"}

package/dist/http/decode-response.js.map

@@ -1 +1 @@
-{"version":3,"file":"decode-response.js","names":[],"sources":["../../src/http/decode-response.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Media-type fragments that name something safe to read as text, for the types\n * that do not open with `text/` — `application/xml`, `application/javascript`,\n * `application/x-www-form-urlencoded`.\n */\nconst TEXTUAL_TOKENS: readonly string[] = [\"xml\", \"javascript\", \"ecmascript\", \"urlencoded\", \"csv\"];\n\n/** How a {@link createApiClient} response body becomes the value a caller awaited. */\nexport type ResponseDecoder<T> = (response: Response) => Promise<T>;\n\n/**\n * Whether a `Content-Type` names a JSON dialect.\n *\n * Matches the suffix forms as well as the plain one, so `application/json`,\n * `application/problem+json` (RFC 9457, what a FastAPI error handler sends) and\n * `application/vnd.tempest.v2+json` all decode as JSON instead of falling\n * through to text.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.json()`.\n */\nexport function isJsonContentType(contentType: string): boolean {\n    return contentType.toLowerCase().includes(\"json\");\n}\n\n/**\n * Whether a `Content-Type` names something that survives being read as text.\n *\n * An absent header counts as textual: a backend that answers without one is\n * almost always sending text, and treating it as binary would change what\n * existing callers get back for no measured gain.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.text()`.\n */\nexport function isTextualContentType(contentType: string): boolean {\n    const type = contentType.trim().toLowerCase();\n    if (type === \"\") return true;\n    if (type.startsWith(\"text/\")) return true;\n    return TEXTUAL_TOKENS.some((token) => type.includes(token));\n}\n\n/**\n * Warn, in a development build, that a binary body reached the JSON/text path.\n *\n * @param contentType - The `Content-Type` that was decoded as a `Blob`.\n */\nfunction warnBinaryBody(contentType: string): void {\n    if (!isDevBuild()) return;\n    console.warn(\n        `[tempest] <ApiClient> received a binary response (content-type: ${contentType}) and returned a Blob. ` +\n            \"Call `client.blob()` or `client.arrayBuffer()` so the type matches what arrives.\",\n    );\n}\n\n/**\n * Decode a response the way its `Content-Type` asks to be decoded.\n *\n * JSON is parsed, text is read as text, and **everything else comes back as a\n * `Blob`**. That last branch is the fix for a silent data defect: the client\n * used to fall back to `response.text()` for any non-JSON body, so an\n * `image/jpeg` was decoded as UTF-8 and the bytes were destroyed on the way in.\n * Measured on a bare JPEG header — `ff d8 ff e0 00 10 4a 46 49 46` — the\n * round-trip through text returns 18 bytes for the 10 that arrived, 4 of them\n * replaced by `U+FFFD`. No caller can undo that, which is why the download had\n * to leave the client entirely.\n *\n * A `204` has no body at all and resolves to `undefined`, whatever the headers\n * claim.\n *\n * @typeParam T - What the caller expects back.\n * @param response - A response already known to be successful.\n * @returns The decoded body.\n */\nexport async function decodeByContentType<T>(response: Response): Promise<T> {\n    if (response.status === 204) {\n        return undefined as T;\n    }\n\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n    if (isJsonContentType(contentType)) {\n        return (await response.json()) as T;\n    }\n    if (isTextualContentType(contentType)) {\n        return (await response.text()) as unknown as T;\n    }\n\n    warnBinaryBody(contentType);\n    return (await response.blob()) as unknown as T;\n}\n"],"mappings":";;AAOA,IAAM,IAAoC;CAAC;CAAO;CAAc;CAAc;CAAc;AAAK;AAgBjG,SAAgB,EAAkB,GAA8B;CAC5D,OAAO,EAAY,YAAY,CAAC,CAAC,SAAS,MAAM;AACpD;AAYA,SAAgB,EAAqB,GAA8B;CAC/D,IAAM,IAAO,EAAY,KAAK,CAAC,CAAC,YAAY;CAG5C,OAFI,MAAS,MACT,EAAK,WAAW,OAAO,IAAU,KAC9B,EAAe,MAAM,MAAU,EAAK,SAAS,CAAK,CAAC;AAC9D;AAOA,SAAS,EAAe,GAA2B;CAC1C,EAAW,KAChB,QAAQ,KACJ,mEAAmE,EAAY,4GAEnF;AACJ;AAqBA,eAAsB,EAAuB,GAAgC;CACzE,IAAI,EAAS,WAAW,KACpB;CAGJ,IAAM,IAAc,EAAS,QAAQ,IAAI,cAAc,KAAK;CAS5D,OARI,EAAkB,CAAW,IACrB,MAAM,EAAS,KAAK,IAE5B,EAAqB,CAAW,IACxB,MAAM,EAAS,KAAK,KAGhC,EAAe,CAAW,GAClB,MAAM,EAAS,KAAK;AAChC"}
+{"version":3,"file":"decode-response.js","names":["TEXTUAL_TOKENS","isJsonContentType","contentType","isTextualContentType","type","token","warnBinaryBody","isDevBuild","decodeByContentType","response"],"sources":["../../src/http/decode-response.ts"],"sourcesContent":["import { isDevBuild } from \"../utils/dev-mode\";\n\n/**\n * Media-type fragments that name something safe to read as text, for the types\n * that do not open with `text/` — `application/xml`, `application/javascript`,\n * `application/x-www-form-urlencoded`.\n */\nconst TEXTUAL_TOKENS: readonly string[] = [\"xml\", \"javascript\", \"ecmascript\", \"urlencoded\", \"csv\"];\n\n/** How a {@link createApiClient} response body becomes the value a caller awaited. */\nexport type ResponseDecoder<T> = (response: Response) => Promise<T>;\n\n/**\n * Whether a `Content-Type` names a JSON dialect.\n *\n * Matches the suffix forms as well as the plain one, so `application/json`,\n * `application/problem+json` (RFC 9457, what a FastAPI error handler sends) and\n * `application/vnd.tempest.v2+json` all decode as JSON instead of falling\n * through to text.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.json()`.\n */\nexport function isJsonContentType(contentType: string): boolean {\n    return contentType.toLowerCase().includes(\"json\");\n}\n\n/**\n * Whether a `Content-Type` names something that survives being read as text.\n *\n * An absent header counts as textual: a backend that answers without one is\n * almost always sending text, and treating it as binary would change what\n * existing callers get back for no measured gain.\n *\n * @param contentType - The raw header value, possibly with parameters.\n * @returns Whether the body should be read with `response.text()`.\n */\nexport function isTextualContentType(contentType: string): boolean {\n    const type = contentType.trim().toLowerCase();\n    if (type === \"\") return true;\n    if (type.startsWith(\"text/\")) return true;\n    return TEXTUAL_TOKENS.some((token) => type.includes(token));\n}\n\n/**\n * Warn, in a development build, that a binary body reached the JSON/text path.\n *\n * @param contentType - The `Content-Type` that was decoded as a `Blob`.\n */\nfunction warnBinaryBody(contentType: string): void {\n    if (!isDevBuild()) return;\n    console.warn(\n        `[tempest] <ApiClient> received a binary response (content-type: ${contentType}) and returned a Blob. ` +\n            \"Call `client.blob()` or `client.arrayBuffer()` so the type matches what arrives.\",\n    );\n}\n\n/**\n * Decode a response the way its `Content-Type` asks to be decoded.\n *\n * JSON is parsed, text is read as text, and **everything else comes back as a\n * `Blob`**. That last branch is the fix for a silent data defect: the client\n * used to fall back to `response.text()` for any non-JSON body, so an\n * `image/jpeg` was decoded as UTF-8 and the bytes were destroyed on the way in.\n * Measured on a bare JPEG header — `ff d8 ff e0 00 10 4a 46 49 46` — the\n * round-trip through text returns 18 bytes for the 10 that arrived, 4 of them\n * replaced by `U+FFFD`. No caller can undo that, which is why the download had\n * to leave the client entirely.\n *\n * A `204` has no body at all and resolves to `undefined`, whatever the headers\n * claim.\n *\n * @typeParam T - What the caller expects back.\n * @param response - A response already known to be successful.\n * @returns The decoded body.\n */\nexport async function decodeByContentType<T>(response: Response): Promise<T> {\n    if (response.status === 204) {\n        return undefined as T;\n    }\n\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n    if (isJsonContentType(contentType)) {\n        return (await response.json()) as T;\n    }\n    if (isTextualContentType(contentType)) {\n        return (await response.text()) as unknown as T;\n    }\n\n    warnBinaryBody(contentType);\n    return (await response.blob()) as unknown as T;\n}\n"],"mappings":";;AAOA,IAAMA,IAAoC;CAAC;CAAO;CAAc;CAAc;CAAc;AAAK;AAgBjG,SAAgBC,EAAkB,GAA8B;CAC5D,OAAOC,EAAY,YAAY,CAAC,CAAC,SAAS,MAAM;AACpD;AAYA,SAAgBC,EAAqB,GAA8B;CAC/D,IAAMC,IAAOF,EAAY,KAAK,CAAC,CAAC,YAAY;CAG5C,OAFIE,MAAS,MACTA,EAAK,WAAW,OAAO,IAAU,KAC9BJ,EAAe,MAAM,MAAUI,EAAK,SAASC,CAAK,CAAC;AAC9D;AAOA,SAASC,EAAe,GAA2B;CAC/C,AAAKC,EAAW,KAChB,QAAQ,KACJ,mEAAmEL,EAAY,4GAEnF;AACJ;AAqBA,eAAsBM,EAAuB,GAAgC;CACzE,IAAIC,EAAS,WAAW,KACpB;CAGJ,IAAMP,IAAcO,EAAS,QAAQ,IAAI,cAAc,KAAK;CAS5D,OARIR,EAAkBC,CAAW,IACrB,MAAMO,EAAS,KAAK,IAE5BN,EAAqBD,CAAW,IACxB,MAAMO,EAAS,KAAK,KAGhCH,EAAeJ,CAAW,GAClB,MAAMO,EAAS,KAAK;AAChC"}

package/dist/http/describe-api-error.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"describe-api-error.cjs","names":[],"sources":["../../src/http/describe-api-error.ts"],"sourcesContent":["// The last mile of error handling: a typed error is what code reads, a sentence\n// is what a person reads, and every app was writing the funnel between the two.\n// The case everyone forgets is the request that never reached the server, which\n// without special handling renders as the nonsense \"erro 0\".\n\nimport { isApiError, syntheticDetail } from \"./errors\";\n\n/** The fixed sentences {@link describeApiError} may need. */\nexport interface ApiErrorStrings {\n    /** Shown when the request never reached the server. */\n    offline: string;\n    /**\n     * Shown when the backend rejected the payload field by field.\n     *\n     * The per-field messages are on `error.fields`, to be attached to the inputs\n     * themselves; this sentence is what the toast says.\n     *\n     * It does not apply to the one rejection that named a single field with a\n     * finished sentence — there the server's own `detail` is shown instead, since\n     * it is the same string `fields` carries. Pass `useDetail: false` to force\n     * this sentence in that case too.\n     */\n    validation: string;\n}\n\n/**\n * PT-BR defaults, used when no strings are supplied and no catalog answers.\n *\n * The SDK's copy is pt-BR everywhere else (`FilterBar`, `DataTable`, `Chat`), so\n * the default here matches rather than introducing an English string that only\n * shows up on a network failure.\n */\nexport const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings = {\n    offline: \"Sem conexão com o servidor. Verifique sua internet e tente de novo.\",\n    validation: \"Confira os campos destacados e tente de novo.\",\n};\n\n/**\n * Translation key the {@link useDescribeApiError} hook looks up.\n *\n * A catalog that does not define it falls back to\n * {@link DEFAULT_API_ERROR_STRINGS}, because `t` returns the key itself when the\n * lookup misses and printing `tempest.error.offline` at the user would be worse\n * than printing pt-BR at them.\n */\nexport const API_ERROR_OFFLINE_KEY = \"tempest.error.offline\";\n\n/**\n * Translation key for the validation sentence, looked up the same way as\n * {@link API_ERROR_OFFLINE_KEY}.\n */\nexport const API_ERROR_VALIDATION_KEY = \"tempest.error.validation\";\n\n/**\n * Everything {@link describeApiError} accepts beyond the error and the fallback.\n *\n * Extends the fixed sentences rather than sitting beside them, so a caller that\n * already passed `{ offline, validation }` keeps compiling untouched.\n */\nexport interface DescribeApiErrorOptions extends Partial<ApiErrorStrings> {\n    /**\n     * Maps the backend's programmatic `code` to a sentence in your language.\n     *\n     * The client already surfaces `code` on `ApiError`, but without this every\n     * app writes the same `switch` over it. A hit here wins over every other\n     * step: it is the only sentence written for that exact case, by someone who\n     * knew both the backend contract and the screen it lands on.\n     */\n    codes?: Readonly<Record<string, string>>;\n    /**\n     * Maps an HTTP status to a sentence, for the failures that arrive with no\n     * useful body.\n     *\n     * `codes` covers the cases the backend named; this covers the ones it did\n     * not. The reference case is the `403` of an admin-only route: the body\n     * carries a generic `detail` (or none), so the funnel fell through to the\n     * fallback and an administrator read \"Não foi possível carregar\" when the\n     * fact that answers their question is \"esta listagem é só para\n     * administradores\".\n     *\n     * Checked after `codes` and **before** the backend's `detail`: a generic\n     * sentence emitted by the framework is worse than the one the app wrote for\n     * that status. `useDetail: false` remains the way to suppress `detail`\n     * entirely.\n     *\n     * A `0` key is honoured like any other, ahead of the offline sentence —\n     * `statuses` is the caller's explicit map, and the fixed `offline` string is\n     * already the way to reword that case. Status `0` covers a request that\n     * never landed **and** one abandoned by the client timeout, so an app that\n     * maps it is taking both.\n     */\n    statuses?: Readonly<Record<number, string>>;\n    /**\n     * Whether the backend's `detail` may be shown when no `code` matched.\n     * Default `true`.\n     *\n     * Set it to `false` when `detail` is written for developers rather than\n     * users, or when it could echo internals — the result is then always either\n     * a sentence you wrote or the fallback.\n     */\n    useDetail?: boolean;\n}\n\n/**\n * Whether the browser currently reports itself as offline.\n *\n * `fetch` rejects a network failure with a plain `TypeError` whose message\n * differs per browser (\"Failed to fetch\", \"NetworkError when attempting to fetch\n * resource.\", \"Load failed\"), so sniffing the message is not portable. The online\n * flag is, and it is the signal that matters for the sentence being chosen.\n *\n * @returns `true` only when the environment positively says it is offline.\n */\nfunction browserIsOffline(): boolean {\n    return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/**\n * Whether `fields` is the flattened single-field envelope, carrying `detail`.\n *\n * The check is identity rather than shape-sniffing. `collectFields` has exactly\n * two sources: FastAPI's `detail` **list**, whose entries are the per-issue\n * messages, and the flattened envelope, whose one entry is built from the same\n * string that becomes `ApiError.detail`. So one entry equal to `detail` can only\n * have come from the second, and returning `detail` there shows the string the\n * form is already about to attach to that input.\n *\n * @param fields - The error's field messages.\n * @param detail - `error.detail`, already trimmed.\n * @param status - The HTTP status, to recognise the synthetic `Erro <status>`\n *     that stands in when the body carried no message at all.\n * @returns Whether `detail` is safe to show as the sentence.\n */\nfunction singleFieldSentence(\n    fields: Record<string, string>,\n    detail: string,\n    status: number,\n): boolean {\n    if (detail === \"\" || detail === syntheticDetail(status)) return false;\n    const messages = Object.values(fields);\n    return messages.length === 1 && messages[0].trim() === detail;\n}\n\n/**\n * Turn any caught value into a sentence worth showing.\n *\n * The funnel, in order:\n *\n * 0. `codes[error.code]` — the sentence you wrote for that exact backend case.\n *    Checked first because nothing the funnel derives can beat it, and because a\n *    request that never landed carries no `code` for it to shadow.\n * 0.5. `statuses[error.status]` — the sentence for a whole class of failure,\n *    for the errors that arrive with no useful body. It beats the backend's\n *    `detail`, because a generic line emitted by the framework is worse than the\n *    one the app wrote for that status, and it beats the offline sentence when\n *    the caller maps `0` explicitly.\n * 1. A request that never reached the server — `status === 0`, or a non-API\n *    error thrown while the browser reports itself offline — produces the\n *    offline sentence. This is the step apps skip, and skipping it renders\n *    \"erro 0\" or a raw `TypeError` at the user.\n * 2. A validation rejection — `error.fields` is set — produces the validation\n *    sentence, **not** `detail`. On a FastAPI `422` the `detail` line is assembled\n *    from the backend's field paths and the validator's own wording\n *    (`\"items.0.price: Input should be greater than 0\"`), which is right for a\n *    log and wrong for a person: it is half English in a pt-BR screen and it\n *    names internals. The per-field messages stay on `fields`, where a form can\n *    attach them to the inputs that failed.\n *\n *    **Unless the rejection named exactly one field and its message is\n *    `detail` itself**, in which case `detail` is returned. That is not a guess\n *    about the text: `collectFields` fills a single entry from `detail` only for\n *    the flattened envelope a `tempest-fastapi-sdk` backend sends, where the\n *    server wrote one finished sentence about one field (`\"CPF ou CNPJ\n *    inválido\"`). Returning it shows the same string that is already on\n *    `fields`, so nothing is invented and nothing is lost. The assembled FastAPI\n *    line never reaches this branch, because it comes from the `detail` **list**\n *    and its entries are the per-issue messages, not `detail`.\n *\n *    This is a fix, not a preference. Before `namedField` shipped in 0.54.0,\n *    `fields` was empty against that backend and the sentence reached the user\n *    through step 3; filling `fields` silently replaced it with \"Confira os\n *    campos destacados\", which presumes a screen that highlights fields — and\n *    no app highlighted anything on the day of the bump.\n *\n *    `useDetail: false` still suppresses it, and is the way to force the fixed\n *    sentence for a backend whose text is written for developers. `validation`\n *    does **not** override it, and that is on purpose: its own contract is the\n *    sentence for a payload rejected *field by field*, which one field carrying\n *    one finished sentence is not — and `useDescribeApiError` always passes\n *    `validation`, so treating it as an override would mean the branch never ran\n *    for any component, which is every caller that matters here.\n * 3. The backend's own `detail`, which is the most specific thing available and\n *    is already written for a person — unless `useDetail: false` says that text\n *    is for developers.\n * 4. `fallback`, with `(HTTP <status>)` appended when a status is known, so the\n *    screenshot in the support ticket carries the one fact a developer needs.\n *\n * Pure on purpose: it works in an interceptor, in a logger and anywhere outside\n * the React tree. {@link useDescribeApiError} is the same funnel with the\n * sentences resolved through `I18nProvider`.\n *\n * @example\n * catch (error) {\n *     toast(describeApiError(error, \"Não foi possível salvar o pedido\"));\n * }\n *\n * @example\n * catch (error) {\n *     toast(\n *         describeApiError(error, \"Não foi possível se candidatar\", {\n *             codes: {\n *                 SERVICE_FULL: \"Este serviço atingiu o limite de vagas.\",\n *                 CANDIDATE_ALREADY_EXISTS: \"Você já se candidatou a este serviço.\",\n *             },\n *             useDetail: false,\n *         }),\n *     );\n * }\n *\n * @param error - The caught value, of any shape.\n * @param fallback - What to say when the error carries nothing better.\n * @param options - A `codes` catalog, `useDetail`, and overrides for the fixed\n *     sentences.\n * @returns A sentence to show the user.\n */\nexport function describeApiError(\n    error: unknown,\n    fallback: string,\n    options?: DescribeApiErrorOptions,\n): string {\n    const offline = options?.offline ?? DEFAULT_API_ERROR_STRINGS.offline;\n\n    if (isApiError(error)) {\n        const mapped = error.code === undefined ? undefined : options?.codes?.[error.code];\n        if (mapped !== undefined) return mapped;\n        const byStatus = options?.statuses?.[error.status];\n        if (byStatus !== undefined) return byStatus;\n        if (error.status === 0) return offline;\n        const detail = error.detail.trim();\n        if (error.fields && Object.keys(error.fields).length > 0) {\n            if (\n                options?.useDetail !== false &&\n                singleFieldSentence(error.fields, detail, error.status)\n            ) {\n                return detail;\n            }\n            return options?.validation ?? DEFAULT_API_ERROR_STRINGS.validation;\n        }\n        if (\n            options?.useDetail !== false &&\n            detail !== \"\" &&\n            detail !== syntheticDetail(error.status)\n        ) {\n            return detail;\n        }\n        return `${fallback} (HTTP ${error.status})`;\n    }\n\n    if (browserIsOffline()) return offline;\n\n    return fallback;\n}\n"],"mappings":"gCAgCA,IAAa,EAA6C,CACtD,QAAS,sEACT,WAAY,+CAChB,EAUa,EAAwB,wBAMxB,EAA2B,2BA8DxC,SAAS,GAA4B,CACjC,OAAO,OAAO,UAAc,KAAe,UAAU,SAAW,EACpE,CAkBA,SAAS,EACL,EACA,EACA,EACO,CACP,GAAI,IAAW,IAAM,IAAW,EAAA,gBAAgB,CAAM,EAAG,MAAO,GAChE,IAAM,EAAW,OAAO,OAAO,CAAM,EACrC,OAAO,EAAS,SAAW,GAAK,EAAS,EAAE,CAAC,KAAK,IAAM,CAC3D,CAoFA,SAAgB,EACZ,EACA,EACA,EACM,CACN,IAAM,EAAU,GAAS,SAAW,EAA0B,QAE9D,GAAI,EAAA,WAAW,CAAK,EAAG,CACnB,IAAM,EAAS,EAAM,OAAS,IAAA,GAAY,IAAA,GAAY,GAAS,QAAQ,EAAM,MAC7E,GAAI,IAAW,IAAA,GAAW,OAAO,EACjC,IAAM,EAAW,GAAS,WAAW,EAAM,QAC3C,GAAI,IAAa,IAAA,GAAW,OAAO,EACnC,GAAI,EAAM,SAAW,EAAG,OAAO,EAC/B,IAAM,EAAS,EAAM,OAAO,KAAK,EAiBjC,OAhBI,EAAM,QAAU,OAAO,KAAK,EAAM,MAAM,CAAC,CAAC,OAAS,EAE/C,GAAS,YAAc,IACvB,EAAoB,EAAM,OAAQ,EAAQ,EAAM,MAAM,EAE/C,EAEJ,GAAS,YAAc,EAA0B,WAGxD,GAAS,YAAc,IACvB,IAAW,IACX,IAAW,EAAA,gBAAgB,EAAM,MAAM,EAEhC,EAEJ,GAAG,EAAS,SAAS,EAAM,OAAO,EAC7C,CAIA,OAFI,EAAiB,EAAU,EAExB,CACX"}
+{"version":3,"file":"describe-api-error.cjs","names":["syntheticDetail","isApiError","require_errors","DEFAULT_API_ERROR_STRINGS","API_ERROR_OFFLINE_KEY","API_ERROR_VALIDATION_KEY","browserIsOffline","singleFieldSentence","detail","status","messages","fields","describeApiError","offline","options","error","mapped","byStatus","fallback"],"sources":["../../src/http/describe-api-error.ts"],"sourcesContent":["// The last mile of error handling: a typed error is what code reads, a sentence\n// is what a person reads, and every app was writing the funnel between the two.\n// The case everyone forgets is the request that never reached the server, which\n// without special handling renders as the nonsense \"erro 0\".\n\nimport { isApiError, syntheticDetail } from \"./errors\";\n\n/** The fixed sentences {@link describeApiError} may need. */\nexport interface ApiErrorStrings {\n    /** Shown when the request never reached the server. */\n    offline: string;\n    /**\n     * Shown when the backend rejected the payload field by field.\n     *\n     * The per-field messages are on `error.fields`, to be attached to the inputs\n     * themselves; this sentence is what the toast says.\n     *\n     * It does not apply to the one rejection that named a single field with a\n     * finished sentence — there the server's own `detail` is shown instead, since\n     * it is the same string `fields` carries. Pass `useDetail: false` to force\n     * this sentence in that case too.\n     */\n    validation: string;\n}\n\n/**\n * PT-BR defaults, used when no strings are supplied and no catalog answers.\n *\n * The SDK's copy is pt-BR everywhere else (`FilterBar`, `DataTable`, `Chat`), so\n * the default here matches rather than introducing an English string that only\n * shows up on a network failure.\n */\nexport const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings = {\n    offline: \"Sem conexão com o servidor. Verifique sua internet e tente de novo.\",\n    validation: \"Confira os campos destacados e tente de novo.\",\n};\n\n/**\n * Translation key the {@link useDescribeApiError} hook looks up.\n *\n * A catalog that does not define it falls back to\n * {@link DEFAULT_API_ERROR_STRINGS}, because `t` returns the key itself when the\n * lookup misses and printing `tempest.error.offline` at the user would be worse\n * than printing pt-BR at them.\n */\nexport const API_ERROR_OFFLINE_KEY = \"tempest.error.offline\";\n\n/**\n * Translation key for the validation sentence, looked up the same way as\n * {@link API_ERROR_OFFLINE_KEY}.\n */\nexport const API_ERROR_VALIDATION_KEY = \"tempest.error.validation\";\n\n/**\n * Everything {@link describeApiError} accepts beyond the error and the fallback.\n *\n * Extends the fixed sentences rather than sitting beside them, so a caller that\n * already passed `{ offline, validation }` keeps compiling untouched.\n */\nexport interface DescribeApiErrorOptions extends Partial<ApiErrorStrings> {\n    /**\n     * Maps the backend's programmatic `code` to a sentence in your language.\n     *\n     * The client already surfaces `code` on `ApiError`, but without this every\n     * app writes the same `switch` over it. A hit here wins over every other\n     * step: it is the only sentence written for that exact case, by someone who\n     * knew both the backend contract and the screen it lands on.\n     */\n    codes?: Readonly<Record<string, string>>;\n    /**\n     * Maps an HTTP status to a sentence, for the failures that arrive with no\n     * useful body.\n     *\n     * `codes` covers the cases the backend named; this covers the ones it did\n     * not. The reference case is the `403` of an admin-only route: the body\n     * carries a generic `detail` (or none), so the funnel fell through to the\n     * fallback and an administrator read \"Não foi possível carregar\" when the\n     * fact that answers their question is \"esta listagem é só para\n     * administradores\".\n     *\n     * Checked after `codes` and **before** the backend's `detail`: a generic\n     * sentence emitted by the framework is worse than the one the app wrote for\n     * that status. `useDetail: false` remains the way to suppress `detail`\n     * entirely.\n     *\n     * A `0` key is honoured like any other, ahead of the offline sentence —\n     * `statuses` is the caller's explicit map, and the fixed `offline` string is\n     * already the way to reword that case. Status `0` covers a request that\n     * never landed **and** one abandoned by the client timeout, so an app that\n     * maps it is taking both.\n     */\n    statuses?: Readonly<Record<number, string>>;\n    /**\n     * Whether the backend's `detail` may be shown when no `code` matched.\n     * Default `true`.\n     *\n     * Set it to `false` when `detail` is written for developers rather than\n     * users, or when it could echo internals — the result is then always either\n     * a sentence you wrote or the fallback.\n     */\n    useDetail?: boolean;\n}\n\n/**\n * Whether the browser currently reports itself as offline.\n *\n * `fetch` rejects a network failure with a plain `TypeError` whose message\n * differs per browser (\"Failed to fetch\", \"NetworkError when attempting to fetch\n * resource.\", \"Load failed\"), so sniffing the message is not portable. The online\n * flag is, and it is the signal that matters for the sentence being chosen.\n *\n * @returns `true` only when the environment positively says it is offline.\n */\nfunction browserIsOffline(): boolean {\n    return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/**\n * Whether `fields` is the flattened single-field envelope, carrying `detail`.\n *\n * The check is identity rather than shape-sniffing. `collectFields` has exactly\n * two sources: FastAPI's `detail` **list**, whose entries are the per-issue\n * messages, and the flattened envelope, whose one entry is built from the same\n * string that becomes `ApiError.detail`. So one entry equal to `detail` can only\n * have come from the second, and returning `detail` there shows the string the\n * form is already about to attach to that input.\n *\n * @param fields - The error's field messages.\n * @param detail - `error.detail`, already trimmed.\n * @param status - The HTTP status, to recognise the synthetic `Erro <status>`\n *     that stands in when the body carried no message at all.\n * @returns Whether `detail` is safe to show as the sentence.\n */\nfunction singleFieldSentence(\n    fields: Record<string, string>,\n    detail: string,\n    status: number,\n): boolean {\n    if (detail === \"\" || detail === syntheticDetail(status)) return false;\n    const messages = Object.values(fields);\n    return messages.length === 1 && messages[0].trim() === detail;\n}\n\n/**\n * Turn any caught value into a sentence worth showing.\n *\n * The funnel, in order:\n *\n * 0. `codes[error.code]` — the sentence you wrote for that exact backend case.\n *    Checked first because nothing the funnel derives can beat it, and because a\n *    request that never landed carries no `code` for it to shadow.\n * 0.5. `statuses[error.status]` — the sentence for a whole class of failure,\n *    for the errors that arrive with no useful body. It beats the backend's\n *    `detail`, because a generic line emitted by the framework is worse than the\n *    one the app wrote for that status, and it beats the offline sentence when\n *    the caller maps `0` explicitly.\n * 1. A request that never reached the server — `status === 0`, or a non-API\n *    error thrown while the browser reports itself offline — produces the\n *    offline sentence. This is the step apps skip, and skipping it renders\n *    \"erro 0\" or a raw `TypeError` at the user.\n * 2. A validation rejection — `error.fields` is set — produces the validation\n *    sentence, **not** `detail`. On a FastAPI `422` the `detail` line is assembled\n *    from the backend's field paths and the validator's own wording\n *    (`\"items.0.price: Input should be greater than 0\"`), which is right for a\n *    log and wrong for a person: it is half English in a pt-BR screen and it\n *    names internals. The per-field messages stay on `fields`, where a form can\n *    attach them to the inputs that failed.\n *\n *    **Unless the rejection named exactly one field and its message is\n *    `detail` itself**, in which case `detail` is returned. That is not a guess\n *    about the text: `collectFields` fills a single entry from `detail` only for\n *    the flattened envelope a `tempest-fastapi-sdk` backend sends, where the\n *    server wrote one finished sentence about one field (`\"CPF ou CNPJ\n *    inválido\"`). Returning it shows the same string that is already on\n *    `fields`, so nothing is invented and nothing is lost. The assembled FastAPI\n *    line never reaches this branch, because it comes from the `detail` **list**\n *    and its entries are the per-issue messages, not `detail`.\n *\n *    This is a fix, not a preference. Before `namedField` shipped in 0.54.0,\n *    `fields` was empty against that backend and the sentence reached the user\n *    through step 3; filling `fields` silently replaced it with \"Confira os\n *    campos destacados\", which presumes a screen that highlights fields — and\n *    no app highlighted anything on the day of the bump.\n *\n *    `useDetail: false` still suppresses it, and is the way to force the fixed\n *    sentence for a backend whose text is written for developers. `validation`\n *    does **not** override it, and that is on purpose: its own contract is the\n *    sentence for a payload rejected *field by field*, which one field carrying\n *    one finished sentence is not — and `useDescribeApiError` always passes\n *    `validation`, so treating it as an override would mean the branch never ran\n *    for any component, which is every caller that matters here.\n * 3. The backend's own `detail`, which is the most specific thing available and\n *    is already written for a person — unless `useDetail: false` says that text\n *    is for developers.\n * 4. `fallback`, with `(HTTP <status>)` appended when a status is known, so the\n *    screenshot in the support ticket carries the one fact a developer needs.\n *\n * Pure on purpose: it works in an interceptor, in a logger and anywhere outside\n * the React tree. {@link useDescribeApiError} is the same funnel with the\n * sentences resolved through `I18nProvider`.\n *\n * @example\n * catch (error) {\n *     toast(describeApiError(error, \"Não foi possível salvar o pedido\"));\n * }\n *\n * @example\n * catch (error) {\n *     toast(\n *         describeApiError(error, \"Não foi possível se candidatar\", {\n *             codes: {\n *                 SERVICE_FULL: \"Este serviço atingiu o limite de vagas.\",\n *                 CANDIDATE_ALREADY_EXISTS: \"Você já se candidatou a este serviço.\",\n *             },\n *             useDetail: false,\n *         }),\n *     );\n * }\n *\n * @param error - The caught value, of any shape.\n * @param fallback - What to say when the error carries nothing better.\n * @param options - A `codes` catalog, `useDetail`, and overrides for the fixed\n *     sentences.\n * @returns A sentence to show the user.\n */\nexport function describeApiError(\n    error: unknown,\n    fallback: string,\n    options?: DescribeApiErrorOptions,\n): string {\n    const offline = options?.offline ?? DEFAULT_API_ERROR_STRINGS.offline;\n\n    if (isApiError(error)) {\n        const mapped = error.code === undefined ? undefined : options?.codes?.[error.code];\n        if (mapped !== undefined) return mapped;\n        const byStatus = options?.statuses?.[error.status];\n        if (byStatus !== undefined) return byStatus;\n        if (error.status === 0) return offline;\n        const detail = error.detail.trim();\n        if (error.fields && Object.keys(error.fields).length > 0) {\n            if (\n                options?.useDetail !== false &&\n                singleFieldSentence(error.fields, detail, error.status)\n            ) {\n                return detail;\n            }\n            return options?.validation ?? DEFAULT_API_ERROR_STRINGS.validation;\n        }\n        if (\n            options?.useDetail !== false &&\n            detail !== \"\" &&\n            detail !== syntheticDetail(error.status)\n        ) {\n            return detail;\n        }\n        return `${fallback} (HTTP ${error.status})`;\n    }\n\n    if (browserIsOffline()) return offline;\n\n    return fallback;\n}\n"],"mappings":"A,gCAgCA,IAAaG,EAA6C,CACtD,QAAS,sEACT,WAAY,+CAChB,EAUaC,EAAwB,wBAMxBC,EAA2B,2BA8DxC,SAASC,GAA4B,CACjC,OAAO,OAAO,UAAc,KAAe,UAAU,SAAW,EACpE,CAkBA,SAASC,EACL,EACA,EACA,EACO,CACP,GAAIC,IAAW,IAAMA,IAAWR,EAAAA,gBAAgBS,CAAM,EAAG,MAAO,GAChE,IAAMC,EAAW,OAAO,OAAOC,CAAM,EACrC,OAAOD,EAAS,SAAW,GAAKA,EAAS,EAAE,CAAC,KAAK,IAAMF,CAC3D,CAoFA,SAAgBI,EACZ,EACA,EACA,EACM,CACN,IAAMC,EAAUC,GAAS,SAAWX,EAA0B,QAE9D,GAAIF,EAAAA,WAAWc,CAAK,EAAG,CACnB,IAAMC,EAASD,EAAM,OAAS,IAAA,GAAY,IAAA,GAAYD,GAAS,QAAQC,EAAM,MAC7E,GAAIC,IAAW,IAAA,GAAW,OAAOA,EACjC,IAAMC,EAAWH,GAAS,WAAWC,EAAM,QAC3C,GAAIE,IAAa,IAAA,GAAW,OAAOA,EACnC,GAAIF,EAAM,SAAW,EAAG,OAAOF,EAC/B,IAAML,EAASO,EAAM,OAAO,KAAK,EAiBjC,OAhBIA,EAAM,QAAU,OAAO,KAAKA,EAAM,MAAM,CAAC,CAAC,OAAS,EAE/CD,GAAS,YAAc,IACvBP,EAAoBQ,EAAM,OAAQP,EAAQO,EAAM,MAAM,EAE/CP,EAEJM,GAAS,YAAcX,EAA0B,WAGxDW,GAAS,YAAc,IACvBN,IAAW,IACXA,IAAWR,EAAAA,gBAAgBe,EAAM,MAAM,EAEhCP,EAEJ,GAAGU,EAAS,SAASH,EAAM,OAAO,EAC7C,CAIA,OAFIT,EAAiB,EAAUO,EAExBK,CACX,C"}

package/dist/http/describe-api-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"describe-api-error.js","names":[],"sources":["../../src/http/describe-api-error.ts"],"sourcesContent":["// The last mile of error handling: a typed error is what code reads, a sentence\n// is what a person reads, and every app was writing the funnel between the two.\n// The case everyone forgets is the request that never reached the server, which\n// without special handling renders as the nonsense \"erro 0\".\n\nimport { isApiError, syntheticDetail } from \"./errors\";\n\n/** The fixed sentences {@link describeApiError} may need. */\nexport interface ApiErrorStrings {\n    /** Shown when the request never reached the server. */\n    offline: string;\n    /**\n     * Shown when the backend rejected the payload field by field.\n     *\n     * The per-field messages are on `error.fields`, to be attached to the inputs\n     * themselves; this sentence is what the toast says.\n     *\n     * It does not apply to the one rejection that named a single field with a\n     * finished sentence — there the server's own `detail` is shown instead, since\n     * it is the same string `fields` carries. Pass `useDetail: false` to force\n     * this sentence in that case too.\n     */\n    validation: string;\n}\n\n/**\n * PT-BR defaults, used when no strings are supplied and no catalog answers.\n *\n * The SDK's copy is pt-BR everywhere else (`FilterBar`, `DataTable`, `Chat`), so\n * the default here matches rather than introducing an English string that only\n * shows up on a network failure.\n */\nexport const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings = {\n    offline: \"Sem conexão com o servidor. Verifique sua internet e tente de novo.\",\n    validation: \"Confira os campos destacados e tente de novo.\",\n};\n\n/**\n * Translation key the {@link useDescribeApiError} hook looks up.\n *\n * A catalog that does not define it falls back to\n * {@link DEFAULT_API_ERROR_STRINGS}, because `t` returns the key itself when the\n * lookup misses and printing `tempest.error.offline` at the user would be worse\n * than printing pt-BR at them.\n */\nexport const API_ERROR_OFFLINE_KEY = \"tempest.error.offline\";\n\n/**\n * Translation key for the validation sentence, looked up the same way as\n * {@link API_ERROR_OFFLINE_KEY}.\n */\nexport const API_ERROR_VALIDATION_KEY = \"tempest.error.validation\";\n\n/**\n * Everything {@link describeApiError} accepts beyond the error and the fallback.\n *\n * Extends the fixed sentences rather than sitting beside them, so a caller that\n * already passed `{ offline, validation }` keeps compiling untouched.\n */\nexport interface DescribeApiErrorOptions extends Partial<ApiErrorStrings> {\n    /**\n     * Maps the backend's programmatic `code` to a sentence in your language.\n     *\n     * The client already surfaces `code` on `ApiError`, but without this every\n     * app writes the same `switch` over it. A hit here wins over every other\n     * step: it is the only sentence written for that exact case, by someone who\n     * knew both the backend contract and the screen it lands on.\n     */\n    codes?: Readonly<Record<string, string>>;\n    /**\n     * Maps an HTTP status to a sentence, for the failures that arrive with no\n     * useful body.\n     *\n     * `codes` covers the cases the backend named; this covers the ones it did\n     * not. The reference case is the `403` of an admin-only route: the body\n     * carries a generic `detail` (or none), so the funnel fell through to the\n     * fallback and an administrator read \"Não foi possível carregar\" when the\n     * fact that answers their question is \"esta listagem é só para\n     * administradores\".\n     *\n     * Checked after `codes` and **before** the backend's `detail`: a generic\n     * sentence emitted by the framework is worse than the one the app wrote for\n     * that status. `useDetail: false` remains the way to suppress `detail`\n     * entirely.\n     *\n     * A `0` key is honoured like any other, ahead of the offline sentence —\n     * `statuses` is the caller's explicit map, and the fixed `offline` string is\n     * already the way to reword that case. Status `0` covers a request that\n     * never landed **and** one abandoned by the client timeout, so an app that\n     * maps it is taking both.\n     */\n    statuses?: Readonly<Record<number, string>>;\n    /**\n     * Whether the backend's `detail` may be shown when no `code` matched.\n     * Default `true`.\n     *\n     * Set it to `false` when `detail` is written for developers rather than\n     * users, or when it could echo internals — the result is then always either\n     * a sentence you wrote or the fallback.\n     */\n    useDetail?: boolean;\n}\n\n/**\n * Whether the browser currently reports itself as offline.\n *\n * `fetch` rejects a network failure with a plain `TypeError` whose message\n * differs per browser (\"Failed to fetch\", \"NetworkError when attempting to fetch\n * resource.\", \"Load failed\"), so sniffing the message is not portable. The online\n * flag is, and it is the signal that matters for the sentence being chosen.\n *\n * @returns `true` only when the environment positively says it is offline.\n */\nfunction browserIsOffline(): boolean {\n    return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/**\n * Whether `fields` is the flattened single-field envelope, carrying `detail`.\n *\n * The check is identity rather than shape-sniffing. `collectFields` has exactly\n * two sources: FastAPI's `detail` **list**, whose entries are the per-issue\n * messages, and the flattened envelope, whose one entry is built from the same\n * string that becomes `ApiError.detail`. So one entry equal to `detail` can only\n * have come from the second, and returning `detail` there shows the string the\n * form is already about to attach to that input.\n *\n * @param fields - The error's field messages.\n * @param detail - `error.detail`, already trimmed.\n * @param status - The HTTP status, to recognise the synthetic `Erro <status>`\n *     that stands in when the body carried no message at all.\n * @returns Whether `detail` is safe to show as the sentence.\n */\nfunction singleFieldSentence(\n    fields: Record<string, string>,\n    detail: string,\n    status: number,\n): boolean {\n    if (detail === \"\" || detail === syntheticDetail(status)) return false;\n    const messages = Object.values(fields);\n    return messages.length === 1 && messages[0].trim() === detail;\n}\n\n/**\n * Turn any caught value into a sentence worth showing.\n *\n * The funnel, in order:\n *\n * 0. `codes[error.code]` — the sentence you wrote for that exact backend case.\n *    Checked first because nothing the funnel derives can beat it, and because a\n *    request that never landed carries no `code` for it to shadow.\n * 0.5. `statuses[error.status]` — the sentence for a whole class of failure,\n *    for the errors that arrive with no useful body. It beats the backend's\n *    `detail`, because a generic line emitted by the framework is worse than the\n *    one the app wrote for that status, and it beats the offline sentence when\n *    the caller maps `0` explicitly.\n * 1. A request that never reached the server — `status === 0`, or a non-API\n *    error thrown while the browser reports itself offline — produces the\n *    offline sentence. This is the step apps skip, and skipping it renders\n *    \"erro 0\" or a raw `TypeError` at the user.\n * 2. A validation rejection — `error.fields` is set — produces the validation\n *    sentence, **not** `detail`. On a FastAPI `422` the `detail` line is assembled\n *    from the backend's field paths and the validator's own wording\n *    (`\"items.0.price: Input should be greater than 0\"`), which is right for a\n *    log and wrong for a person: it is half English in a pt-BR screen and it\n *    names internals. The per-field messages stay on `fields`, where a form can\n *    attach them to the inputs that failed.\n *\n *    **Unless the rejection named exactly one field and its message is\n *    `detail` itself**, in which case `detail` is returned. That is not a guess\n *    about the text: `collectFields` fills a single entry from `detail` only for\n *    the flattened envelope a `tempest-fastapi-sdk` backend sends, where the\n *    server wrote one finished sentence about one field (`\"CPF ou CNPJ\n *    inválido\"`). Returning it shows the same string that is already on\n *    `fields`, so nothing is invented and nothing is lost. The assembled FastAPI\n *    line never reaches this branch, because it comes from the `detail` **list**\n *    and its entries are the per-issue messages, not `detail`.\n *\n *    This is a fix, not a preference. Before `namedField` shipped in 0.54.0,\n *    `fields` was empty against that backend and the sentence reached the user\n *    through step 3; filling `fields` silently replaced it with \"Confira os\n *    campos destacados\", which presumes a screen that highlights fields — and\n *    no app highlighted anything on the day of the bump.\n *\n *    `useDetail: false` still suppresses it, and is the way to force the fixed\n *    sentence for a backend whose text is written for developers. `validation`\n *    does **not** override it, and that is on purpose: its own contract is the\n *    sentence for a payload rejected *field by field*, which one field carrying\n *    one finished sentence is not — and `useDescribeApiError` always passes\n *    `validation`, so treating it as an override would mean the branch never ran\n *    for any component, which is every caller that matters here.\n * 3. The backend's own `detail`, which is the most specific thing available and\n *    is already written for a person — unless `useDetail: false` says that text\n *    is for developers.\n * 4. `fallback`, with `(HTTP <status>)` appended when a status is known, so the\n *    screenshot in the support ticket carries the one fact a developer needs.\n *\n * Pure on purpose: it works in an interceptor, in a logger and anywhere outside\n * the React tree. {@link useDescribeApiError} is the same funnel with the\n * sentences resolved through `I18nProvider`.\n *\n * @example\n * catch (error) {\n *     toast(describeApiError(error, \"Não foi possível salvar o pedido\"));\n * }\n *\n * @example\n * catch (error) {\n *     toast(\n *         describeApiError(error, \"Não foi possível se candidatar\", {\n *             codes: {\n *                 SERVICE_FULL: \"Este serviço atingiu o limite de vagas.\",\n *                 CANDIDATE_ALREADY_EXISTS: \"Você já se candidatou a este serviço.\",\n *             },\n *             useDetail: false,\n *         }),\n *     );\n * }\n *\n * @param error - The caught value, of any shape.\n * @param fallback - What to say when the error carries nothing better.\n * @param options - A `codes` catalog, `useDetail`, and overrides for the fixed\n *     sentences.\n * @returns A sentence to show the user.\n */\nexport function describeApiError(\n    error: unknown,\n    fallback: string,\n    options?: DescribeApiErrorOptions,\n): string {\n    const offline = options?.offline ?? DEFAULT_API_ERROR_STRINGS.offline;\n\n    if (isApiError(error)) {\n        const mapped = error.code === undefined ? undefined : options?.codes?.[error.code];\n        if (mapped !== undefined) return mapped;\n        const byStatus = options?.statuses?.[error.status];\n        if (byStatus !== undefined) return byStatus;\n        if (error.status === 0) return offline;\n        const detail = error.detail.trim();\n        if (error.fields && Object.keys(error.fields).length > 0) {\n            if (\n                options?.useDetail !== false &&\n                singleFieldSentence(error.fields, detail, error.status)\n            ) {\n                return detail;\n            }\n            return options?.validation ?? DEFAULT_API_ERROR_STRINGS.validation;\n        }\n        if (\n            options?.useDetail !== false &&\n            detail !== \"\" &&\n            detail !== syntheticDetail(error.status)\n        ) {\n            return detail;\n        }\n        return `${fallback} (HTTP ${error.status})`;\n    }\n\n    if (browserIsOffline()) return offline;\n\n    return fallback;\n}\n"],"mappings":";;AAgCA,IAAa,IAA6C;CACtD,SAAS;CACT,YAAY;AAChB,GAUa,IAAwB,yBAMxB,IAA2B;AA8DxC,SAAS,IAA4B;CACjC,OAAO,OAAO,YAAc,OAAe,UAAU,WAAW;AACpE;AAkBA,SAAS,EACL,GACA,GACA,GACO;CACP,IAAI,MAAW,MAAM,MAAW,EAAgB,CAAM,GAAG,OAAO;CAChE,IAAM,IAAW,OAAO,OAAO,CAAM;CACrC,OAAO,EAAS,WAAW,KAAK,EAAS,EAAE,CAAC,KAAK,MAAM;AAC3D;AAoFA,SAAgB,EACZ,GACA,GACA,GACM;CACN,IAAM,IAAU,GAAS,WAAW,EAA0B;CAE9D,IAAI,EAAW,CAAK,GAAG;EACnB,IAAM,IAAS,EAAM,SAAS,KAAA,IAAY,KAAA,IAAY,GAAS,QAAQ,EAAM;EAC7E,IAAI,MAAW,KAAA,GAAW,OAAO;EACjC,IAAM,IAAW,GAAS,WAAW,EAAM;EAC3C,IAAI,MAAa,KAAA,GAAW,OAAO;EACnC,IAAI,EAAM,WAAW,GAAG,OAAO;EAC/B,IAAM,IAAS,EAAM,OAAO,KAAK;EAiBjC,OAhBI,EAAM,UAAU,OAAO,KAAK,EAAM,MAAM,CAAC,CAAC,SAAS,IAE/C,GAAS,cAAc,MACvB,EAAoB,EAAM,QAAQ,GAAQ,EAAM,MAAM,IAE/C,IAEJ,GAAS,cAAc,EAA0B,aAGxD,GAAS,cAAc,MACvB,MAAW,MACX,MAAW,EAAgB,EAAM,MAAM,IAEhC,IAEJ,GAAG,EAAS,SAAS,EAAM,OAAO;CAC7C;CAIA,OAFI,EAAiB,IAAU,IAExB;AACX"}
+{"version":3,"file":"describe-api-error.js","names":["DEFAULT_API_ERROR_STRINGS","API_ERROR_OFFLINE_KEY","API_ERROR_VALIDATION_KEY","browserIsOffline","singleFieldSentence","detail","syntheticDetail","status","messages","fields","describeApiError","offline","options","isApiError","error","mapped","byStatus","fallback"],"sources":["../../src/http/describe-api-error.ts"],"sourcesContent":["// The last mile of error handling: a typed error is what code reads, a sentence\n// is what a person reads, and every app was writing the funnel between the two.\n// The case everyone forgets is the request that never reached the server, which\n// without special handling renders as the nonsense \"erro 0\".\n\nimport { isApiError, syntheticDetail } from \"./errors\";\n\n/** The fixed sentences {@link describeApiError} may need. */\nexport interface ApiErrorStrings {\n    /** Shown when the request never reached the server. */\n    offline: string;\n    /**\n     * Shown when the backend rejected the payload field by field.\n     *\n     * The per-field messages are on `error.fields`, to be attached to the inputs\n     * themselves; this sentence is what the toast says.\n     *\n     * It does not apply to the one rejection that named a single field with a\n     * finished sentence — there the server's own `detail` is shown instead, since\n     * it is the same string `fields` carries. Pass `useDetail: false` to force\n     * this sentence in that case too.\n     */\n    validation: string;\n}\n\n/**\n * PT-BR defaults, used when no strings are supplied and no catalog answers.\n *\n * The SDK's copy is pt-BR everywhere else (`FilterBar`, `DataTable`, `Chat`), so\n * the default here matches rather than introducing an English string that only\n * shows up on a network failure.\n */\nexport const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings = {\n    offline: \"Sem conexão com o servidor. Verifique sua internet e tente de novo.\",\n    validation: \"Confira os campos destacados e tente de novo.\",\n};\n\n/**\n * Translation key the {@link useDescribeApiError} hook looks up.\n *\n * A catalog that does not define it falls back to\n * {@link DEFAULT_API_ERROR_STRINGS}, because `t` returns the key itself when the\n * lookup misses and printing `tempest.error.offline` at the user would be worse\n * than printing pt-BR at them.\n */\nexport const API_ERROR_OFFLINE_KEY = \"tempest.error.offline\";\n\n/**\n * Translation key for the validation sentence, looked up the same way as\n * {@link API_ERROR_OFFLINE_KEY}.\n */\nexport const API_ERROR_VALIDATION_KEY = \"tempest.error.validation\";\n\n/**\n * Everything {@link describeApiError} accepts beyond the error and the fallback.\n *\n * Extends the fixed sentences rather than sitting beside them, so a caller that\n * already passed `{ offline, validation }` keeps compiling untouched.\n */\nexport interface DescribeApiErrorOptions extends Partial<ApiErrorStrings> {\n    /**\n     * Maps the backend's programmatic `code` to a sentence in your language.\n     *\n     * The client already surfaces `code` on `ApiError`, but without this every\n     * app writes the same `switch` over it. A hit here wins over every other\n     * step: it is the only sentence written for that exact case, by someone who\n     * knew both the backend contract and the screen it lands on.\n     */\n    codes?: Readonly<Record<string, string>>;\n    /**\n     * Maps an HTTP status to a sentence, for the failures that arrive with no\n     * useful body.\n     *\n     * `codes` covers the cases the backend named; this covers the ones it did\n     * not. The reference case is the `403` of an admin-only route: the body\n     * carries a generic `detail` (or none), so the funnel fell through to the\n     * fallback and an administrator read \"Não foi possível carregar\" when the\n     * fact that answers their question is \"esta listagem é só para\n     * administradores\".\n     *\n     * Checked after `codes` and **before** the backend's `detail`: a generic\n     * sentence emitted by the framework is worse than the one the app wrote for\n     * that status. `useDetail: false` remains the way to suppress `detail`\n     * entirely.\n     *\n     * A `0` key is honoured like any other, ahead of the offline sentence —\n     * `statuses` is the caller's explicit map, and the fixed `offline` string is\n     * already the way to reword that case. Status `0` covers a request that\n     * never landed **and** one abandoned by the client timeout, so an app that\n     * maps it is taking both.\n     */\n    statuses?: Readonly<Record<number, string>>;\n    /**\n     * Whether the backend's `detail` may be shown when no `code` matched.\n     * Default `true`.\n     *\n     * Set it to `false` when `detail` is written for developers rather than\n     * users, or when it could echo internals — the result is then always either\n     * a sentence you wrote or the fallback.\n     */\n    useDetail?: boolean;\n}\n\n/**\n * Whether the browser currently reports itself as offline.\n *\n * `fetch` rejects a network failure with a plain `TypeError` whose message\n * differs per browser (\"Failed to fetch\", \"NetworkError when attempting to fetch\n * resource.\", \"Load failed\"), so sniffing the message is not portable. The online\n * flag is, and it is the signal that matters for the sentence being chosen.\n *\n * @returns `true` only when the environment positively says it is offline.\n */\nfunction browserIsOffline(): boolean {\n    return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/**\n * Whether `fields` is the flattened single-field envelope, carrying `detail`.\n *\n * The check is identity rather than shape-sniffing. `collectFields` has exactly\n * two sources: FastAPI's `detail` **list**, whose entries are the per-issue\n * messages, and the flattened envelope, whose one entry is built from the same\n * string that becomes `ApiError.detail`. So one entry equal to `detail` can only\n * have come from the second, and returning `detail` there shows the string the\n * form is already about to attach to that input.\n *\n * @param fields - The error's field messages.\n * @param detail - `error.detail`, already trimmed.\n * @param status - The HTTP status, to recognise the synthetic `Erro <status>`\n *     that stands in when the body carried no message at all.\n * @returns Whether `detail` is safe to show as the sentence.\n */\nfunction singleFieldSentence(\n    fields: Record<string, string>,\n    detail: string,\n    status: number,\n): boolean {\n    if (detail === \"\" || detail === syntheticDetail(status)) return false;\n    const messages = Object.values(fields);\n    return messages.length === 1 && messages[0].trim() === detail;\n}\n\n/**\n * Turn any caught value into a sentence worth showing.\n *\n * The funnel, in order:\n *\n * 0. `codes[error.code]` — the sentence you wrote for that exact backend case.\n *    Checked first because nothing the funnel derives can beat it, and because a\n *    request that never landed carries no `code` for it to shadow.\n * 0.5. `statuses[error.status]` — the sentence for a whole class of failure,\n *    for the errors that arrive with no useful body. It beats the backend's\n *    `detail`, because a generic line emitted by the framework is worse than the\n *    one the app wrote for that status, and it beats the offline sentence when\n *    the caller maps `0` explicitly.\n * 1. A request that never reached the server — `status === 0`, or a non-API\n *    error thrown while the browser reports itself offline — produces the\n *    offline sentence. This is the step apps skip, and skipping it renders\n *    \"erro 0\" or a raw `TypeError` at the user.\n * 2. A validation rejection — `error.fields` is set — produces the validation\n *    sentence, **not** `detail`. On a FastAPI `422` the `detail` line is assembled\n *    from the backend's field paths and the validator's own wording\n *    (`\"items.0.price: Input should be greater than 0\"`), which is right for a\n *    log and wrong for a person: it is half English in a pt-BR screen and it\n *    names internals. The per-field messages stay on `fields`, where a form can\n *    attach them to the inputs that failed.\n *\n *    **Unless the rejection named exactly one field and its message is\n *    `detail` itself**, in which case `detail` is returned. That is not a guess\n *    about the text: `collectFields` fills a single entry from `detail` only for\n *    the flattened envelope a `tempest-fastapi-sdk` backend sends, where the\n *    server wrote one finished sentence about one field (`\"CPF ou CNPJ\n *    inválido\"`). Returning it shows the same string that is already on\n *    `fields`, so nothing is invented and nothing is lost. The assembled FastAPI\n *    line never reaches this branch, because it comes from the `detail` **list**\n *    and its entries are the per-issue messages, not `detail`.\n *\n *    This is a fix, not a preference. Before `namedField` shipped in 0.54.0,\n *    `fields` was empty against that backend and the sentence reached the user\n *    through step 3; filling `fields` silently replaced it with \"Confira os\n *    campos destacados\", which presumes a screen that highlights fields — and\n *    no app highlighted anything on the day of the bump.\n *\n *    `useDetail: false` still suppresses it, and is the way to force the fixed\n *    sentence for a backend whose text is written for developers. `validation`\n *    does **not** override it, and that is on purpose: its own contract is the\n *    sentence for a payload rejected *field by field*, which one field carrying\n *    one finished sentence is not — and `useDescribeApiError` always passes\n *    `validation`, so treating it as an override would mean the branch never ran\n *    for any component, which is every caller that matters here.\n * 3. The backend's own `detail`, which is the most specific thing available and\n *    is already written for a person — unless `useDetail: false` says that text\n *    is for developers.\n * 4. `fallback`, with `(HTTP <status>)` appended when a status is known, so the\n *    screenshot in the support ticket carries the one fact a developer needs.\n *\n * Pure on purpose: it works in an interceptor, in a logger and anywhere outside\n * the React tree. {@link useDescribeApiError} is the same funnel with the\n * sentences resolved through `I18nProvider`.\n *\n * @example\n * catch (error) {\n *     toast(describeApiError(error, \"Não foi possível salvar o pedido\"));\n * }\n *\n * @example\n * catch (error) {\n *     toast(\n *         describeApiError(error, \"Não foi possível se candidatar\", {\n *             codes: {\n *                 SERVICE_FULL: \"Este serviço atingiu o limite de vagas.\",\n *                 CANDIDATE_ALREADY_EXISTS: \"Você já se candidatou a este serviço.\",\n *             },\n *             useDetail: false,\n *         }),\n *     );\n * }\n *\n * @param error - The caught value, of any shape.\n * @param fallback - What to say when the error carries nothing better.\n * @param options - A `codes` catalog, `useDetail`, and overrides for the fixed\n *     sentences.\n * @returns A sentence to show the user.\n */\nexport function describeApiError(\n    error: unknown,\n    fallback: string,\n    options?: DescribeApiErrorOptions,\n): string {\n    const offline = options?.offline ?? DEFAULT_API_ERROR_STRINGS.offline;\n\n    if (isApiError(error)) {\n        const mapped = error.code === undefined ? undefined : options?.codes?.[error.code];\n        if (mapped !== undefined) return mapped;\n        const byStatus = options?.statuses?.[error.status];\n        if (byStatus !== undefined) return byStatus;\n        if (error.status === 0) return offline;\n        const detail = error.detail.trim();\n        if (error.fields && Object.keys(error.fields).length > 0) {\n            if (\n                options?.useDetail !== false &&\n                singleFieldSentence(error.fields, detail, error.status)\n            ) {\n                return detail;\n            }\n            return options?.validation ?? DEFAULT_API_ERROR_STRINGS.validation;\n        }\n        if (\n            options?.useDetail !== false &&\n            detail !== \"\" &&\n            detail !== syntheticDetail(error.status)\n        ) {\n            return detail;\n        }\n        return `${fallback} (HTTP ${error.status})`;\n    }\n\n    if (browserIsOffline()) return offline;\n\n    return fallback;\n}\n"],"mappings":";;AAgCA,IAAaA,IAA6C;CACtD,SAAS;CACT,YAAY;AAChB,GAUaC,IAAwB,yBAMxBC,IAA2B;AA8DxC,SAASC,IAA4B;CACjC,OAAO,OAAO,YAAc,OAAe,UAAU,WAAW;AACpE;AAkBA,SAASC,EACL,GACA,GACA,GACO;CACP,IAAIC,MAAW,MAAMA,MAAWC,EAAgBC,CAAM,GAAG,OAAO;CAChE,IAAMC,IAAW,OAAO,OAAOC,CAAM;CACrC,OAAOD,EAAS,WAAW,KAAKA,EAAS,EAAE,CAAC,KAAK,MAAMH;AAC3D;AAoFA,SAAgBK,EACZ,GACA,GACA,GACM;CACN,IAAMC,IAAUC,GAAS,WAAWZ,EAA0B;CAE9D,IAAIa,EAAWC,CAAK,GAAG;EACnB,IAAMC,IAASD,EAAM,SAAS,KAAA,IAAY,KAAA,IAAYF,GAAS,QAAQE,EAAM;EAC7E,IAAIC,MAAW,KAAA,GAAW,OAAOA;EACjC,IAAMC,IAAWJ,GAAS,WAAWE,EAAM;EAC3C,IAAIE,MAAa,KAAA,GAAW,OAAOA;EACnC,IAAIF,EAAM,WAAW,GAAG,OAAOH;EAC/B,IAAMN,IAASS,EAAM,OAAO,KAAK;EAiBjC,OAhBIA,EAAM,UAAU,OAAO,KAAKA,EAAM,MAAM,CAAC,CAAC,SAAS,IAE/CF,GAAS,cAAc,MACvBR,EAAoBU,EAAM,QAAQT,GAAQS,EAAM,MAAM,IAE/CT,IAEJO,GAAS,cAAcZ,EAA0B,aAGxDY,GAAS,cAAc,MACvBP,MAAW,MACXA,MAAWC,EAAgBQ,EAAM,MAAM,IAEhCT,IAEJ,GAAGY,EAAS,SAASH,EAAM,OAAO;CAC7C;CAIA,OAFIX,EAAiB,IAAUQ,IAExBM;AACX"}

package/dist/http/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","names":[],"sources":["../../src/http/errors.ts"],"sourcesContent":["import type { ApiError } from \"./types\";\n\n/**\n * Error thrown by {@link createApiClient} / {@link uploadWithProgress} on a\n * non-2xx response. Mirrors the Tempest FastAPI SDK error envelope\n * (`{ detail, code, details.request_id }`) so callers get a typed `code` and a\n * `requestId` for log correlation, while still being a real `Error` (stack\n * trace, `instanceof Error`).\n *\n * @example\n * try {\n *     await api.post(\"/users\", { body });\n * } catch (err) {\n *     if (isApiError(err) && err.code === \"EMAIL_TAKEN\") {\n *         showFieldError(\"email\", err.detail);\n *     }\n * }\n */\nexport class TempestApiError extends Error implements ApiError {\n    readonly status: number;\n    readonly detail: string;\n    readonly code?: string;\n    readonly requestId?: string;\n    readonly fields?: Record<string, string>;\n    readonly body?: unknown;\n\n    constructor(init: ApiError) {\n        super(init.detail);\n        this.name = \"TempestApiError\";\n        this.status = init.status;\n        this.detail = init.detail;\n        this.code = init.code;\n        this.requestId = init.requestId;\n        this.fields = init.fields;\n        this.body = init.body;\n    }\n}\n\n/**\n * Thrown when the session that started an operation is no longer the current\n * one by the time it settles: a `refresh` hook (rethrown by\n * {@link createApiClient}), or a `createTempestAuth` `login()` whose session\n * was replaced while it waited on the previous session's teardown.\n *\n * A refresh is a network round trip, and the session can end or change hands\n * during it: the user signs out, or signs out and another account signs in. The\n * tokens that refresh brings back belong to the session that ended, so they are\n * discarded instead of installed, and the request that was waiting on them is\n * not replayed — replaying it would send it as whoever is signed in now.\n *\n * This is deliberately not an unauthorized outcome. The client does **not** call\n * `onUnauthorized` for it: that callback ends the session, and the current\n * session — possibly a different account that just signed in — did nothing\n * wrong. Treat it like an aborted request: drop the result, show nothing.\n *\n * @example\n * try {\n *     await api.get(\"/api/orders\");\n * } catch (err) {\n *     if (err instanceof SessionSupersededError) return;\n *     throw err;\n * }\n */\nexport class SessionSupersededError extends Error {\n    constructor() {\n        super(\"A sessão mudou antes de a operação terminar.\");\n        this.name = \"SessionSupersededError\";\n    }\n}\n\n/**\n * Type guard for the {@link ApiError} shape. Matches both {@link TempestApiError}\n * instances and plain objects carrying `status` + `detail`.\n *\n * @param error - The unknown value (typically a caught error).\n * @returns Whether `error` conforms to the `ApiError` contract.\n */\nexport function isApiError(error: unknown): error is ApiError {\n    return (\n        typeof error === \"object\" &&\n        error !== null &&\n        typeof (error as ApiError).status === \"number\" &&\n        typeof (error as ApiError).detail === \"string\"\n    );\n}\n\n/**\n * Location prefixes FastAPI puts at the head of a validation error's `loc`,\n * naming the part of the request rather than the field. Dropped from the\n * rendered path, so `[\"body\", \"email\"]` reads as `email`.\n */\nconst LOC_ROOTS: ReadonlySet<string> = new Set([\"body\", \"query\", \"path\", \"header\", \"cookie\"]);\n\n/**\n * Render a FastAPI validation error's `loc` tuple as a dotted field path.\n *\n * @param loc - The raw `loc` value from one validation error entry.\n * @returns The dotted path (`\"items.0.price\"`), or undefined when `loc` carries\n *     nothing addressable.\n */\nfunction formatLoc(loc: unknown): string | undefined {\n    if (!Array.isArray(loc)) return undefined;\n    const parts = loc\n        .filter(\n            (part): part is string | number => typeof part === \"string\" || typeof part === \"number\",\n        )\n        .filter((part, index) => !(index === 0 && LOC_ROOTS.has(String(part))));\n    return parts.length > 0 ? parts.join(\".\") : undefined;\n}\n\n/**\n * How deep {@link normalizeDetail} follows a nested `detail` before giving up.\n *\n * A real envelope needs two or three levels: the list, an entry, the entry's\n * own `detail`. The cap exists because the body is untrusted input arriving on\n * the error path — a response nesting `{\"detail\":{\"detail\":…}}` twenty thousand\n * deep (a 220 KB body) overflowed the stack, and a `RangeError` thrown while\n * *building* the error is worse than the error: the caller's `catch` stops\n * receiving a `TempestApiError`, so `isApiError` is false, `describeApiError`\n * has nothing to read and the `401` handling never runs.\n */\nconst MAX_DETAIL_DEPTH = 4;\n\n/**\n * Pull field-level messages out of a validation `detail` **list**.\n *\n * FastAPI's `422` body is `detail: [{ loc, msg, type }]`, which is exactly what\n * a form needs and exactly what the flattened `detail` string destroys. Only the\n * top level is read: a validation error names one field per entry, and following\n * nesting here would invent paths the backend never sent.\n *\n * This is one of two ways a body names a field — see {@link collectFields}, which\n * is the entry point and falls back to the singular keys when the list names\n * nothing addressable.\n *\n * @param raw - The `detail` value from the error body.\n * @returns Field path to message, or undefined when the body is not a\n *     validation list (or carries no entry naming a field).\n */\nfunction collectListFields(raw: unknown): Record<string, string> | undefined {\n    if (!Array.isArray(raw)) return undefined;\n\n    const fields: Record<string, string> = {};\n    for (const entry of raw) {\n        if (typeof entry !== \"object\" || entry === null) continue;\n        const record = entry as Record<string, unknown>;\n        const field = formatLoc(record.loc);\n        if (field === undefined || field in fields) continue;\n        const message = normalizeDetail(record.msg) ?? normalizeDetail(record.message);\n        if (message === undefined) continue;\n        fields[field] = message;\n    }\n\n    return Object.keys(fields).length > 0 ? fields : undefined;\n}\n\n/**\n * Narrow a value to a plain object — a record, and not an array.\n *\n * Arrays are excluded because `typeof [] === \"object\"` while a list means\n * something else entirely here: FastAPI's `detail` list is read by\n * {@link collectListFields}, and reading `.field` off it would only ever be\n * undefined.\n *\n * @param value - The candidate value from the error body.\n * @returns The value as a record, or undefined when it is not a plain object.\n */\nfunction plainRecord(value: unknown): Record<string, unknown> | undefined {\n    return typeof value === \"object\" && value !== null && !Array.isArray(value)\n        ? (value as Record<string, unknown>)\n        : undefined;\n}\n\n/**\n * Read the field a **singular** error envelope names.\n *\n * A backend built on `tempest-fastapi-sdk` never answers with FastAPI's `detail`\n * list once it owns the handler: it names the guilty field in a key beside the\n * message. Three shapes are seen in the wild, and they are read inner-out:\n *\n * 1. `detail.field` — the field sits in the same object as the message it\n *    describes (`{ detail: { detail: \"Cidade não encontrada…\", field: \"city\" } }`),\n *    so it is the least ambiguous claim about which message belongs to which input.\n * 2. `field` at the top level — a flattened `RequestValidationError`\n *    (`{ detail: \"Value error, … for field 'phone' in 'body'\", field: \"phone\" }`)\n *    makes the same claim one level out.\n * 3. `details.field` — `details` is the envelope's free-form context bag, not a\n *    validation channel, and its `field` may be about something no input on screen\n *    carries (an unknown sort column, say). It answers last for exactly that reason.\n *\n * `location` (`\"body -> phone\"`) is deliberately not parsed: it renders the same\n * path `field` already names, no observed envelope sends it without `field`, and\n * splitting an arrow-separated string would invent a path the backend never sent.\n *\n * @param body - The parsed error body, or null when it was not an object.\n * @returns The field name, or undefined when none of the three keys carried a\n *     non-empty string — anything else is not usable as a key on `fields`.\n */\nfunction namedField(body: Record<string, unknown> | null): string | undefined {\n    if (body === null) return undefined;\n    const candidates: readonly unknown[] = [\n        plainRecord(body.detail)?.field,\n        body.field,\n        plainRecord(body.details)?.field,\n    ];\n    for (const candidate of candidates) {\n        if (typeof candidate === \"string\" && candidate !== \"\") return candidate;\n    }\n    return undefined;\n}\n\n/**\n * Drop the machine-readable tail a `tempest-fastapi-sdk` backend appends.\n *\n * That backend flattens a field error into\n * `\"CPF ou CNPJ inválido for field 'cpf_cnpj' in 'body'\"` — a finished sentence\n * in the app's language with an English clause glued to the end. The clause\n * carries nothing new: the same two values arrive as `field` and `location` on\n * the envelope, which is where `ApiError.fields` reads them from. Left in, it\n * reaches the user, and every consuming app grew its own regex to shave it off.\n *\n * The trim only fires when the field the tail names is the field the envelope\n * resolved to. That is what keeps it from deleting text it cannot account for:\n * a tail naming some other field is either a different envelope shape or a\n * sentence that genuinely reads that way, and both are left alone.\n *\n * @param message - The readable message, or undefined when the body had none.\n * @param field - The field name {@link namedField} resolved, if any.\n * @returns The message without the tail, or the message unchanged.\n */\nfunction trimFieldSuffix(\n    message: string | undefined,\n    field: string | undefined,\n): string | undefined {\n    if (message === undefined || field === undefined) return message;\n    const escaped = field.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n    const trimmed = message\n        .replace(new RegExp(`\\\\s+for field '${escaped}'(?:\\\\s+in\\\\s+'[^']*')?\\\\.?\\\\s*$`), \"\")\n        .trim();\n    return trimmed === \"\" ? message : trimmed;\n}\n\n/**\n * Index the body's field-level messages, whichever envelope carried them.\n *\n * The single entry point behind `ApiError.fields`, and it applies two rules the\n * tests pin:\n *\n * - FastAPI's `detail` list wins whenever it names at least one addressable\n *   field. A plain FastAPI app still answers a schema-level `422` with that list\n *   even on a `tempest-fastapi-sdk` backend, so it stays authoritative.\n * - A named field with no readable message produces nothing. The only string\n *   left at that point is the synthetic `Erro <status>`, and `{ phone: \"Erro 422\" }`\n *   on an input is noise rather than an error message.\n *\n * @param body - The parsed error body, or null when it was not an object.\n * @param message - The readable message the same body produced, before the\n *     synthetic fallback — the string that also becomes `ApiError.detail`.\n * @returns Field name to message, or undefined when nothing named a field.\n */\nfunction collectFields(\n    body: Record<string, unknown> | null,\n    message: string | undefined,\n): Record<string, string> | undefined {\n    const listed = collectListFields(body?.detail);\n    if (listed !== undefined) return listed;\n    const field = namedField(body);\n    if (field === undefined || message === undefined) return undefined;\n    return { [field]: message };\n}\n\n/**\n * Collapse a backend `detail` of any shape into a single readable line.\n *\n * FastAPI answers a `422` with `detail` as a **list** of\n * `{ loc, msg, type }` entries, not a string. Passing that through `String()`\n * yields `\"[object Object]\"` — an error message that tells the user nothing and\n * hides which field failed. Each entry becomes `\"<field>: <msg>\"` and the\n * entries are joined with `\"; \"`; a nested object is read through its\n * `msg`/`message`/`detail` string.\n *\n * @param raw - The `detail` (or `message`) value from the error body.\n * @param depth - Current nesting level. Past {@link MAX_DETAIL_DEPTH} the value\n *     is treated as unreadable instead of followed further.\n * @returns The rendered message, or undefined when nothing readable is there —\n *     letting the caller fall back to the synthetic `Erro <status>`.\n */\nfunction normalizeDetail(raw: unknown, depth: number = 0): string | undefined {\n    if (raw === null || raw === undefined) return undefined;\n    if (typeof raw === \"string\") return raw === \"\" ? undefined : raw;\n    if (typeof raw === \"number\" || typeof raw === \"boolean\") return String(raw);\n    if (depth >= MAX_DETAIL_DEPTH) return undefined;\n\n    if (Array.isArray(raw)) {\n        const lines = raw\n            .map((entry) => {\n                const message = normalizeDetail(entry, depth + 1);\n                if (message === undefined) return undefined;\n                const field =\n                    typeof entry === \"object\" && entry !== null\n                        ? formatLoc((entry as Record<string, unknown>).loc)\n                        : undefined;\n                return field === undefined ? message : `${field}: ${message}`;\n            })\n            .filter((line): line is string => line !== undefined);\n        return lines.length > 0 ? lines.join(\"; \") : undefined;\n    }\n\n    if (typeof raw === \"object\") {\n        const entry = raw as Record<string, unknown>;\n        return (\n            normalizeDetail(entry.msg, depth + 1) ??\n            normalizeDetail(entry.message, depth + 1) ??\n            normalizeDetail(entry.detail, depth + 1)\n        );\n    }\n\n    return undefined;\n}\n\n/**\n * Statuses worth a second attempt, as a set for the sub-500 cases.\n *\n * A network failure (status `0`), a request timeout, a too-early replay, and a\n * rate limit — which usually carries the `Retry-After` the backoff honours.\n * Everything else below 500 is the server refusing on purpose.\n */\nconst RETRIABLE_STATUSES: ReadonlySet<number> = new Set([0, 408, 425, 429]);\n\n/**\n * Whether an HTTP status describes a condition a replay can plausibly fix.\n *\n * The single owner of that decision. It used to be spelled out in three places —\n * the client's own policy, the react-query default and the bare `retry()` helper\n * — and they had already drifted: the query default was missing `425`, so the\n * same `425 Too Early` was replayed through `createApiClient({ retry: true })`\n * and not replayed through `useQuery`. Same app, same error, two behaviours, and\n * no test caught it because each file asserted against its own copy.\n *\n * Deliberately about the status and nothing else. Whether a *non*-API error is\n * worth replaying, and whether the request's method may be replayed at all, are\n * the caller's calls: {@link createApiClient} refuses a non-idempotent method,\n * while a bare `retry()` has no method to inspect.\n *\n * @example\n * await api.get(\"/report\", {\n *     retry: { shouldRetry: (error) => isApiError(error) && isRetriableStatus(error.status) },\n * });\n *\n * @param status - The HTTP status, where `0` means the request never landed.\n * @returns Whether a retry is worth attempting.\n */\nexport function isRetriableStatus(status: number): boolean {\n    return RETRIABLE_STATUSES.has(status) || status >= 500;\n}\n\n/**\n * Detail text synthesised when a response body carries none.\n *\n * Exported because {@link describeApiError} has to recognise it: a detail the\n * server never sent says strictly less than the caller's own fallback, so the\n * funnel drops it. Comparing against a copied literal would silently stop\n * matching the day this sentence is reworded — no type error, no failing test.\n *\n * @param status - The HTTP status of the error.\n * @returns The synthetic detail for that status.\n */\nexport function syntheticDetail(status: number): string {\n    return `Erro ${status}`;\n}\n\n/**\n * Parse an error body + response into the Tempest {@link ApiError} envelope.\n *\n * Reads `detail`/`message`, the programmatic `code`, and the correlation id\n * from `details.request_id` (falling back to the `X-Request-ID` header, then\n * the id the client sent).\n *\n * A `422` from FastAPI carries `detail` as a list of `{ loc, msg, type }`\n * entries, so it is flattened to `\"<field>: <msg>; <field>: <msg>\"` instead of\n * being stringified into `\"[object Object]\"`, and the same entries are indexed\n * on `fields` (`{ email: \"Field required\" }`) for a form to consume without\n * parsing that line back apart. The untouched body stays on `body`.\n *\n * A backend that owns its handlers — every `tempest-fastapi-sdk` app — sends no\n * such list, and names the field in a key instead:\n *\n * ```json\n * { \"detail\": \"Value error, … for field 'phone' in 'body'\", \"field\": \"phone\" }\n * { \"detail\": { \"detail\": \"Cidade não encontrada…\", \"field\": \"city\" },\n *   \"code\": \"VALIDATION_ERROR\", \"details\": { \"field\": \"city\" } }\n * ```\n *\n * Those are indexed too, keyed by the field the backend named and valued with the\n * same sentence that becomes `detail`. Precedence is the list first, then\n * `detail.field`, `field`, `details.field` — see {@link collectFields}.\n *\n * A flattened `detail` from the list is developer-facing: it carries the\n * backend's field paths and the validator's own wording. `describeApiError` knows\n * not to show it to a person when `fields` is set — which now also covers a\n * business error that named a field, whose `detail` was a finished sentence. That\n * sentence is not lost: it is on `fields`, attached to the input that failed.\n *\n * @param status - HTTP status code.\n * @param body - The parsed error body (object, string, or null).\n * @param headers - The response headers (for the `X-Request-ID` fallback).\n * @param sentRequestId - The id the client sent on the request, if any.\n * @returns A fully-populated `ApiError`.\n *\n * @tempest-limits param-count — the arguments are the response as it arrives\n * (`status`, `body`, `headers`) plus the id the request was sent with, and they are\n * passed at exactly three places, all of them a client's response path\n * (`createApiClient`, `uploadWithProgress`, `createResumableUpload`). Wrapping them\n * in an options object would name each argument twice at every call site to say\n * nothing new.\n */\nexport function buildApiError(\n    status: number,\n    body: unknown,\n    headers?: Headers | { get(name: string): string | null },\n    sentRequestId?: string,\n): ApiError {\n    const obj =\n        typeof body === \"object\" && body !== null ? (body as Record<string, unknown>) : null;\n    const message = trimFieldSuffix(\n        normalizeDetail(obj?.detail) ?? normalizeDetail(obj?.message),\n        namedField(obj),\n    );\n    const detail = message ?? syntheticDetail(status);\n    const code = typeof obj?.code === \"string\" ? obj.code : undefined;\n    const details =\n        typeof obj?.details === \"object\" && obj.details !== null\n            ? (obj.details as Record<string, unknown>)\n            : null;\n    const requestId =\n        (typeof details?.request_id === \"string\" ? details.request_id : undefined) ??\n        headers?.get(\"X-Request-ID\") ??\n        sentRequestId ??\n        undefined;\n\n    return {\n        status,\n        detail,\n        code,\n        requestId: requestId ?? undefined,\n        retryAfter: parseRetryAfter(headers?.get(\"Retry-After\")),\n        fields: collectFields(obj, message),\n        body,\n    };\n}\n\n/**\n * Parse a `Retry-After` header into seconds. Accepts a delta-seconds integer\n * (`\"120\"`) or an HTTP-date (`\"Wed, 21 Oct 2015 07:28:00 GMT\"`).\n *\n * @param value - The raw header value, or null.\n * @returns The delay in seconds (>= 0), or undefined when absent/unparseable.\n */\nexport function parseRetryAfter(value: string | null | undefined): number | undefined {\n    if (!value) return undefined;\n    const trimmed = value.trim();\n    if (/^\\d+$/.test(trimmed)) return Number(trimmed);\n    const when = Date.parse(trimmed);\n    if (Number.isNaN(when)) return undefined;\n    return Math.max(0, Math.round((when - Date.now()) / 1000));\n}\n"],"mappings":"AAkBA,IAAa,EAAb,cAAqC,KAA0B,CAC3D,OACA,OACA,KACA,UACA,OACA,KAEA,YAAY,EAAgB,CACxB,MAAM,EAAK,MAAM,EACjB,KAAK,KAAO,kBACZ,KAAK,OAAS,EAAK,OACnB,KAAK,OAAS,EAAK,OACnB,KAAK,KAAO,EAAK,KACjB,KAAK,UAAY,EAAK,UACtB,KAAK,OAAS,EAAK,OACnB,KAAK,KAAO,EAAK,IACrB,CACJ,EA2Ba,EAAb,cAA4C,KAAM,CAC9C,aAAc,CACV,MAAM,8CAA8C,EACpD,KAAK,KAAO,wBAChB,CACJ,EASA,SAAgB,EAAW,EAAmC,CAC1D,OACI,OAAO,GAAU,YACjB,GACA,OAAQ,EAAmB,QAAW,UACtC,OAAQ,EAAmB,QAAW,QAE9C,CAOA,IAAM,EAAiC,IAAI,IAAI,CAAC,OAAQ,QAAS,OAAQ,SAAU,QAAQ,CAAC,EAS5F,SAAS,EAAU,EAAkC,CACjD,GAAI,CAAC,MAAM,QAAQ,CAAG,EAAG,OACzB,IAAM,EAAQ,EACT,OACI,GAAkC,OAAO,GAAS,UAAY,OAAO,GAAS,QACnF,CAAC,CACA,QAAQ,EAAM,IAAU,EAAE,IAAU,GAAK,EAAU,IAAI,OAAO,CAAI,CAAC,EAAE,EAC1E,OAAO,EAAM,OAAS,EAAI,EAAM,KAAK,GAAG,EAAI,IAAA,EAChD,CAaA,IAAM,EAAmB,EAkBzB,SAAS,EAAkB,EAAkD,CACzE,GAAI,CAAC,MAAM,QAAQ,CAAG,EAAG,OAEzB,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAS,EAAK,CACrB,GAAI,OAAO,GAAU,WAAY,EAAgB,SACjD,IAAM,EAAS,EACT,EAAQ,EAAU,EAAO,GAAG,EAClC,GAAI,IAAU,IAAA,IAAa,KAAS,EAAQ,SAC5C,IAAM,EAAU,EAAgB,EAAO,GAAG,GAAK,EAAgB,EAAO,OAAO,EACzE,IAAY,IAAA,KAChB,EAAO,GAAS,EACpB,CAEA,OAAO,OAAO,KAAK,CAAM,CAAC,CAAC,OAAS,EAAI,EAAS,IAAA,EACrD,CAaA,SAAS,EAAY,EAAqD,CACtE,OAAO,OAAO,GAAU,UAAY,GAAkB,CAAC,MAAM,QAAQ,CAAK,EACnE,EACD,IAAA,EACV,CA2BA,SAAS,EAAW,EAA0D,CAC1E,GAAI,IAAS,KAAM,OACnB,IAAM,EAAiC,CACnC,EAAY,EAAK,MAAM,CAAC,EAAE,MAC1B,EAAK,MACL,EAAY,EAAK,OAAO,CAAC,EAAE,KAC/B,EACA,IAAK,IAAM,KAAa,EACpB,GAAI,OAAO,GAAc,UAAY,IAAc,GAAI,OAAO,CAGtE,CAqBA,SAAS,EACL,EACA,EACkB,CAClB,GAAI,IAAY,IAAA,IAAa,IAAU,IAAA,GAAW,OAAO,EACzD,IAAM,EAAU,EAAM,QAAQ,sBAAuB,MAAM,EACrD,EAAU,EACX,QAAY,OAAO,kBAAkB,EAAQ,iCAAiC,EAAG,EAAE,CAAC,CACpF,KAAK,EACV,OAAO,IAAY,GAAK,EAAU,CACtC,CAoBA,SAAS,EACL,EACA,EACkC,CAClC,IAAM,EAAS,EAAkB,GAAM,MAAM,EAC7C,GAAI,IAAW,IAAA,GAAW,OAAO,EACjC,IAAM,EAAQ,EAAW,CAAI,EACzB,OAAU,IAAA,IAAa,IAAY,IAAA,GACvC,MAAO,EAAG,GAAQ,CAAQ,CAC9B,CAkBA,SAAS,EAAgB,EAAc,EAAgB,EAAuB,CACtE,MAAQ,KACZ,IAAI,OAAO,GAAQ,SAAU,OAAO,IAAQ,GAAK,IAAA,GAAY,EAC7D,GAAI,OAAO,GAAQ,UAAY,OAAO,GAAQ,UAAW,OAAO,OAAO,CAAG,EACtE,QAAS,GAEb,IAAI,MAAM,QAAQ,CAAG,EAAG,CACpB,IAAM,EAAQ,EACT,IAAK,GAAU,CACZ,IAAM,EAAU,EAAgB,EAAO,EAAQ,CAAC,EAChD,GAAI,IAAY,IAAA,GAAW,OAC3B,IAAM,EACF,OAAO,GAAU,UAAY,EACvB,EAAW,EAAkC,GAAG,EAChD,IAAA,GACV,OAAO,IAAU,IAAA,GAAY,EAAU,GAAG,EAAM,IAAI,GACxD,CAAC,CAAC,CACD,OAAQ,GAAyB,IAAS,IAAA,EAAS,EACxD,OAAO,EAAM,OAAS,EAAI,EAAM,KAAK,IAAI,EAAI,IAAA,EACjD,CAEA,GAAI,OAAO,GAAQ,SAAU,CACzB,IAAM,EAAQ,EACd,OACI,EAAgB,EAAM,IAAK,EAAQ,CAAC,GACpC,EAAgB,EAAM,QAAS,EAAQ,CAAC,GACxC,EAAgB,EAAM,OAAQ,EAAQ,CAAC,CAE/C,CATA,CAjB6D,CA6BjE,CASA,IAAM,EAA0C,IAAI,IAAI,CAAC,EAAG,IAAK,IAAK,GAAG,CAAC,EAyB1E,SAAgB,EAAkB,EAAyB,CACvD,OAAO,EAAmB,IAAI,CAAM,GAAK,GAAU,GACvD,CAaA,SAAgB,EAAgB,EAAwB,CACpD,MAAO,QAAQ,GACnB,CA+CA,SAAgB,EACZ,EACA,EACA,EACA,EACQ,CACR,IAAM,EACF,OAAO,GAAS,UAAY,EAAiB,EAAmC,KAC9E,EAAU,EACZ,EAAgB,GAAK,MAAM,GAAK,EAAgB,GAAK,OAAO,EAC5D,EAAW,CAAG,CAClB,EACM,EAAS,GAAW,EAAgB,CAAM,EAC1C,EAAO,OAAO,GAAK,MAAS,SAAW,EAAI,KAAO,IAAA,GAClD,EACF,OAAO,GAAK,SAAY,UAAY,EAAI,UAAY,KAC7C,EAAI,QACL,KAOV,MAAO,CACH,SACA,SACA,OACA,WATC,OAAO,GAAS,YAAe,SAAW,EAAQ,WAAa,IAAA,KAChE,GAAS,IAAI,cAAc,GAC3B,GACA,IAAA,IAMwB,IAAA,GACxB,WAAY,EAAgB,GAAS,IAAI,aAAa,CAAC,EACvD,OAAQ,EAAc,EAAK,CAAO,EAClC,MACJ,CACJ,CASA,SAAgB,EAAgB,EAAsD,CAClF,GAAI,CAAC,EAAO,OACZ,IAAM,EAAU,EAAM,KAAK,EAC3B,GAAI,QAAQ,KAAK,CAAO,EAAG,OAAO,OAAO,CAAO,EAChD,IAAM,EAAO,KAAK,MAAM,CAAO,EAC3B,WAAO,MAAM,CAAI,EACrB,OAAO,KAAK,IAAI,EAAG,KAAK,OAAO,EAAO,KAAK,IAAI,GAAK,GAAI,CAAC,CAC7D"}
+{"version":3,"file":"errors.cjs","names":["TempestApiError","init","SessionSupersededError","isApiError","error","LOC_ROOTS","formatLoc","loc","parts","part","index","MAX_DETAIL_DEPTH","collectListFields","raw","fields","entry","record","field","message","normalizeDetail","plainRecord","value","namedField","body","candidates","candidate","trimFieldSuffix","escaped","trimmed","collectFields","listed","lines","depth","line","RETRIABLE_STATUSES","isRetriableStatus","status","syntheticDetail","buildApiError","obj","detail","code","details","headers","sentRequestId","parseRetryAfter","when"],"sources":["../../src/http/errors.ts"],"sourcesContent":["import type { ApiError } from \"./types\";\n\n/**\n * Error thrown by {@link createApiClient} / {@link uploadWithProgress} on a\n * non-2xx response. Mirrors the Tempest FastAPI SDK error envelope\n * (`{ detail, code, details.request_id }`) so callers get a typed `code` and a\n * `requestId` for log correlation, while still being a real `Error` (stack\n * trace, `instanceof Error`).\n *\n * @example\n * try {\n *     await api.post(\"/users\", { body });\n * } catch (err) {\n *     if (isApiError(err) && err.code === \"EMAIL_TAKEN\") {\n *         showFieldError(\"email\", err.detail);\n *     }\n * }\n */\nexport class TempestApiError extends Error implements ApiError {\n    readonly status: number;\n    readonly detail: string;\n    readonly code?: string;\n    readonly requestId?: string;\n    readonly fields?: Record<string, string>;\n    readonly body?: unknown;\n\n    constructor(init: ApiError) {\n        super(init.detail);\n        this.name = \"TempestApiError\";\n        this.status = init.status;\n        this.detail = init.detail;\n        this.code = init.code;\n        this.requestId = init.requestId;\n        this.fields = init.fields;\n        this.body = init.body;\n    }\n}\n\n/**\n * Thrown when the session that started an operation is no longer the current\n * one by the time it settles: a `refresh` hook (rethrown by\n * {@link createApiClient}), or a `createTempestAuth` `login()` whose session\n * was replaced while it waited on the previous session's teardown.\n *\n * A refresh is a network round trip, and the session can end or change hands\n * during it: the user signs out, or signs out and another account signs in. The\n * tokens that refresh brings back belong to the session that ended, so they are\n * discarded instead of installed, and the request that was waiting on them is\n * not replayed — replaying it would send it as whoever is signed in now.\n *\n * This is deliberately not an unauthorized outcome. The client does **not** call\n * `onUnauthorized` for it: that callback ends the session, and the current\n * session — possibly a different account that just signed in — did nothing\n * wrong. Treat it like an aborted request: drop the result, show nothing.\n *\n * @example\n * try {\n *     await api.get(\"/api/orders\");\n * } catch (err) {\n *     if (err instanceof SessionSupersededError) return;\n *     throw err;\n * }\n */\nexport class SessionSupersededError extends Error {\n    constructor() {\n        super(\"A sessão mudou antes de a operação terminar.\");\n        this.name = \"SessionSupersededError\";\n    }\n}\n\n/**\n * Type guard for the {@link ApiError} shape. Matches both {@link TempestApiError}\n * instances and plain objects carrying `status` + `detail`.\n *\n * @param error - The unknown value (typically a caught error).\n * @returns Whether `error` conforms to the `ApiError` contract.\n */\nexport function isApiError(error: unknown): error is ApiError {\n    return (\n        typeof error === \"object\" &&\n        error !== null &&\n        typeof (error as ApiError).status === \"number\" &&\n        typeof (error as ApiError).detail === \"string\"\n    );\n}\n\n/**\n * Location prefixes FastAPI puts at the head of a validation error's `loc`,\n * naming the part of the request rather than the field. Dropped from the\n * rendered path, so `[\"body\", \"email\"]` reads as `email`.\n */\nconst LOC_ROOTS: ReadonlySet<string> = new Set([\"body\", \"query\", \"path\", \"header\", \"cookie\"]);\n\n/**\n * Render a FastAPI validation error's `loc` tuple as a dotted field path.\n *\n * @param loc - The raw `loc` value from one validation error entry.\n * @returns The dotted path (`\"items.0.price\"`), or undefined when `loc` carries\n *     nothing addressable.\n */\nfunction formatLoc(loc: unknown): string | undefined {\n    if (!Array.isArray(loc)) return undefined;\n    const parts = loc\n        .filter(\n            (part): part is string | number => typeof part === \"string\" || typeof part === \"number\",\n        )\n        .filter((part, index) => !(index === 0 && LOC_ROOTS.has(String(part))));\n    return parts.length > 0 ? parts.join(\".\") : undefined;\n}\n\n/**\n * How deep {@link normalizeDetail} follows a nested `detail` before giving up.\n *\n * A real envelope needs two or three levels: the list, an entry, the entry's\n * own `detail`. The cap exists because the body is untrusted input arriving on\n * the error path — a response nesting `{\"detail\":{\"detail\":…}}` twenty thousand\n * deep (a 220 KB body) overflowed the stack, and a `RangeError` thrown while\n * *building* the error is worse than the error: the caller's `catch` stops\n * receiving a `TempestApiError`, so `isApiError` is false, `describeApiError`\n * has nothing to read and the `401` handling never runs.\n */\nconst MAX_DETAIL_DEPTH = 4;\n\n/**\n * Pull field-level messages out of a validation `detail` **list**.\n *\n * FastAPI's `422` body is `detail: [{ loc, msg, type }]`, which is exactly what\n * a form needs and exactly what the flattened `detail` string destroys. Only the\n * top level is read: a validation error names one field per entry, and following\n * nesting here would invent paths the backend never sent.\n *\n * This is one of two ways a body names a field — see {@link collectFields}, which\n * is the entry point and falls back to the singular keys when the list names\n * nothing addressable.\n *\n * @param raw - The `detail` value from the error body.\n * @returns Field path to message, or undefined when the body is not a\n *     validation list (or carries no entry naming a field).\n */\nfunction collectListFields(raw: unknown): Record<string, string> | undefined {\n    if (!Array.isArray(raw)) return undefined;\n\n    const fields: Record<string, string> = {};\n    for (const entry of raw) {\n        if (typeof entry !== \"object\" || entry === null) continue;\n        const record = entry as Record<string, unknown>;\n        const field = formatLoc(record.loc);\n        if (field === undefined || field in fields) continue;\n        const message = normalizeDetail(record.msg) ?? normalizeDetail(record.message);\n        if (message === undefined) continue;\n        fields[field] = message;\n    }\n\n    return Object.keys(fields).length > 0 ? fields : undefined;\n}\n\n/**\n * Narrow a value to a plain object — a record, and not an array.\n *\n * Arrays are excluded because `typeof [] === \"object\"` while a list means\n * something else entirely here: FastAPI's `detail` list is read by\n * {@link collectListFields}, and reading `.field` off it would only ever be\n * undefined.\n *\n * @param value - The candidate value from the error body.\n * @returns The value as a record, or undefined when it is not a plain object.\n */\nfunction plainRecord(value: unknown): Record<string, unknown> | undefined {\n    return typeof value === \"object\" && value !== null && !Array.isArray(value)\n        ? (value as Record<string, unknown>)\n        : undefined;\n}\n\n/**\n * Read the field a **singular** error envelope names.\n *\n * A backend built on `tempest-fastapi-sdk` never answers with FastAPI's `detail`\n * list once it owns the handler: it names the guilty field in a key beside the\n * message. Three shapes are seen in the wild, and they are read inner-out:\n *\n * 1. `detail.field` — the field sits in the same object as the message it\n *    describes (`{ detail: { detail: \"Cidade não encontrada…\", field: \"city\" } }`),\n *    so it is the least ambiguous claim about which message belongs to which input.\n * 2. `field` at the top level — a flattened `RequestValidationError`\n *    (`{ detail: \"Value error, … for field 'phone' in 'body'\", field: \"phone\" }`)\n *    makes the same claim one level out.\n * 3. `details.field` — `details` is the envelope's free-form context bag, not a\n *    validation channel, and its `field` may be about something no input on screen\n *    carries (an unknown sort column, say). It answers last for exactly that reason.\n *\n * `location` (`\"body -> phone\"`) is deliberately not parsed: it renders the same\n * path `field` already names, no observed envelope sends it without `field`, and\n * splitting an arrow-separated string would invent a path the backend never sent.\n *\n * @param body - The parsed error body, or null when it was not an object.\n * @returns The field name, or undefined when none of the three keys carried a\n *     non-empty string — anything else is not usable as a key on `fields`.\n */\nfunction namedField(body: Record<string, unknown> | null): string | undefined {\n    if (body === null) return undefined;\n    const candidates: readonly unknown[] = [\n        plainRecord(body.detail)?.field,\n        body.field,\n        plainRecord(body.details)?.field,\n    ];\n    for (const candidate of candidates) {\n        if (typeof candidate === \"string\" && candidate !== \"\") return candidate;\n    }\n    return undefined;\n}\n\n/**\n * Drop the machine-readable tail a `tempest-fastapi-sdk` backend appends.\n *\n * That backend flattens a field error into\n * `\"CPF ou CNPJ inválido for field 'cpf_cnpj' in 'body'\"` — a finished sentence\n * in the app's language with an English clause glued to the end. The clause\n * carries nothing new: the same two values arrive as `field` and `location` on\n * the envelope, which is where `ApiError.fields` reads them from. Left in, it\n * reaches the user, and every consuming app grew its own regex to shave it off.\n *\n * The trim only fires when the field the tail names is the field the envelope\n * resolved to. That is what keeps it from deleting text it cannot account for:\n * a tail naming some other field is either a different envelope shape or a\n * sentence that genuinely reads that way, and both are left alone.\n *\n * @param message - The readable message, or undefined when the body had none.\n * @param field - The field name {@link namedField} resolved, if any.\n * @returns The message without the tail, or the message unchanged.\n */\nfunction trimFieldSuffix(\n    message: string | undefined,\n    field: string | undefined,\n): string | undefined {\n    if (message === undefined || field === undefined) return message;\n    const escaped = field.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n    const trimmed = message\n        .replace(new RegExp(`\\\\s+for field '${escaped}'(?:\\\\s+in\\\\s+'[^']*')?\\\\.?\\\\s*$`), \"\")\n        .trim();\n    return trimmed === \"\" ? message : trimmed;\n}\n\n/**\n * Index the body's field-level messages, whichever envelope carried them.\n *\n * The single entry point behind `ApiError.fields`, and it applies two rules the\n * tests pin:\n *\n * - FastAPI's `detail` list wins whenever it names at least one addressable\n *   field. A plain FastAPI app still answers a schema-level `422` with that list\n *   even on a `tempest-fastapi-sdk` backend, so it stays authoritative.\n * - A named field with no readable message produces nothing. The only string\n *   left at that point is the synthetic `Erro <status>`, and `{ phone: \"Erro 422\" }`\n *   on an input is noise rather than an error message.\n *\n * @param body - The parsed error body, or null when it was not an object.\n * @param message - The readable message the same body produced, before the\n *     synthetic fallback — the string that also becomes `ApiError.detail`.\n * @returns Field name to message, or undefined when nothing named a field.\n */\nfunction collectFields(\n    body: Record<string, unknown> | null,\n    message: string | undefined,\n): Record<string, string> | undefined {\n    const listed = collectListFields(body?.detail);\n    if (listed !== undefined) return listed;\n    const field = namedField(body);\n    if (field === undefined || message === undefined) return undefined;\n    return { [field]: message };\n}\n\n/**\n * Collapse a backend `detail` of any shape into a single readable line.\n *\n * FastAPI answers a `422` with `detail` as a **list** of\n * `{ loc, msg, type }` entries, not a string. Passing that through `String()`\n * yields `\"[object Object]\"` — an error message that tells the user nothing and\n * hides which field failed. Each entry becomes `\"<field>: <msg>\"` and the\n * entries are joined with `\"; \"`; a nested object is read through its\n * `msg`/`message`/`detail` string.\n *\n * @param raw - The `detail` (or `message`) value from the error body.\n * @param depth - Current nesting level. Past {@link MAX_DETAIL_DEPTH} the value\n *     is treated as unreadable instead of followed further.\n * @returns The rendered message, or undefined when nothing readable is there —\n *     letting the caller fall back to the synthetic `Erro <status>`.\n */\nfunction normalizeDetail(raw: unknown, depth: number = 0): string | undefined {\n    if (raw === null || raw === undefined) return undefined;\n    if (typeof raw === \"string\") return raw === \"\" ? undefined : raw;\n    if (typeof raw === \"number\" || typeof raw === \"boolean\") return String(raw);\n    if (depth >= MAX_DETAIL_DEPTH) return undefined;\n\n    if (Array.isArray(raw)) {\n        const lines = raw\n            .map((entry) => {\n                const message = normalizeDetail(entry, depth + 1);\n                if (message === undefined) return undefined;\n                const field =\n                    typeof entry === \"object\" && entry !== null\n                        ? formatLoc((entry as Record<string, unknown>).loc)\n                        : undefined;\n                return field === undefined ? message : `${field}: ${message}`;\n            })\n            .filter((line): line is string => line !== undefined);\n        return lines.length > 0 ? lines.join(\"; \") : undefined;\n    }\n\n    if (typeof raw === \"object\") {\n        const entry = raw as Record<string, unknown>;\n        return (\n            normalizeDetail(entry.msg, depth + 1) ??\n            normalizeDetail(entry.message, depth + 1) ??\n            normalizeDetail(entry.detail, depth + 1)\n        );\n    }\n\n    return undefined;\n}\n\n/**\n * Statuses worth a second attempt, as a set for the sub-500 cases.\n *\n * A network failure (status `0`), a request timeout, a too-early replay, and a\n * rate limit — which usually carries the `Retry-After` the backoff honours.\n * Everything else below 500 is the server refusing on purpose.\n */\nconst RETRIABLE_STATUSES: ReadonlySet<number> = new Set([0, 408, 425, 429]);\n\n/**\n * Whether an HTTP status describes a condition a replay can plausibly fix.\n *\n * The single owner of that decision. It used to be spelled out in three places —\n * the client's own policy, the react-query default and the bare `retry()` helper\n * — and they had already drifted: the query default was missing `425`, so the\n * same `425 Too Early` was replayed through `createApiClient({ retry: true })`\n * and not replayed through `useQuery`. Same app, same error, two behaviours, and\n * no test caught it because each file asserted against its own copy.\n *\n * Deliberately about the status and nothing else. Whether a *non*-API error is\n * worth replaying, and whether the request's method may be replayed at all, are\n * the caller's calls: {@link createApiClient} refuses a non-idempotent method,\n * while a bare `retry()` has no method to inspect.\n *\n * @example\n * await api.get(\"/report\", {\n *     retry: { shouldRetry: (error) => isApiError(error) && isRetriableStatus(error.status) },\n * });\n *\n * @param status - The HTTP status, where `0` means the request never landed.\n * @returns Whether a retry is worth attempting.\n */\nexport function isRetriableStatus(status: number): boolean {\n    return RETRIABLE_STATUSES.has(status) || status >= 500;\n}\n\n/**\n * Detail text synthesised when a response body carries none.\n *\n * Exported because {@link describeApiError} has to recognise it: a detail the\n * server never sent says strictly less than the caller's own fallback, so the\n * funnel drops it. Comparing against a copied literal would silently stop\n * matching the day this sentence is reworded — no type error, no failing test.\n *\n * @param status - The HTTP status of the error.\n * @returns The synthetic detail for that status.\n */\nexport function syntheticDetail(status: number): string {\n    return `Erro ${status}`;\n}\n\n/**\n * Parse an error body + response into the Tempest {@link ApiError} envelope.\n *\n * Reads `detail`/`message`, the programmatic `code`, and the correlation id\n * from `details.request_id` (falling back to the `X-Request-ID` header, then\n * the id the client sent).\n *\n * A `422` from FastAPI carries `detail` as a list of `{ loc, msg, type }`\n * entries, so it is flattened to `\"<field>: <msg>; <field>: <msg>\"` instead of\n * being stringified into `\"[object Object]\"`, and the same entries are indexed\n * on `fields` (`{ email: \"Field required\" }`) for a form to consume without\n * parsing that line back apart. The untouched body stays on `body`.\n *\n * A backend that owns its handlers — every `tempest-fastapi-sdk` app — sends no\n * such list, and names the field in a key instead:\n *\n * ```json\n * { \"detail\": \"Value error, … for field 'phone' in 'body'\", \"field\": \"phone\" }\n * { \"detail\": { \"detail\": \"Cidade não encontrada…\", \"field\": \"city\" },\n *   \"code\": \"VALIDATION_ERROR\", \"details\": { \"field\": \"city\" } }\n * ```\n *\n * Those are indexed too, keyed by the field the backend named and valued with the\n * same sentence that becomes `detail`. Precedence is the list first, then\n * `detail.field`, `field`, `details.field` — see {@link collectFields}.\n *\n * A flattened `detail` from the list is developer-facing: it carries the\n * backend's field paths and the validator's own wording. `describeApiError` knows\n * not to show it to a person when `fields` is set — which now also covers a\n * business error that named a field, whose `detail` was a finished sentence. That\n * sentence is not lost: it is on `fields`, attached to the input that failed.\n *\n * @param status - HTTP status code.\n * @param body - The parsed error body (object, string, or null).\n * @param headers - The response headers (for the `X-Request-ID` fallback).\n * @param sentRequestId - The id the client sent on the request, if any.\n * @returns A fully-populated `ApiError`.\n *\n * @tempest-limits param-count — the arguments are the response as it arrives\n * (`status`, `body`, `headers`) plus the id the request was sent with, and they are\n * passed at exactly three places, all of them a client's response path\n * (`createApiClient`, `uploadWithProgress`, `createResumableUpload`). Wrapping them\n * in an options object would name each argument twice at every call site to say\n * nothing new.\n */\nexport function buildApiError(\n    status: number,\n    body: unknown,\n    headers?: Headers | { get(name: string): string | null },\n    sentRequestId?: string,\n): ApiError {\n    const obj =\n        typeof body === \"object\" && body !== null ? (body as Record<string, unknown>) : null;\n    const message = trimFieldSuffix(\n        normalizeDetail(obj?.detail) ?? normalizeDetail(obj?.message),\n        namedField(obj),\n    );\n    const detail = message ?? syntheticDetail(status);\n    const code = typeof obj?.code === \"string\" ? obj.code : undefined;\n    const details =\n        typeof obj?.details === \"object\" && obj.details !== null\n            ? (obj.details as Record<string, unknown>)\n            : null;\n    const requestId =\n        (typeof details?.request_id === \"string\" ? details.request_id : undefined) ??\n        headers?.get(\"X-Request-ID\") ??\n        sentRequestId ??\n        undefined;\n\n    return {\n        status,\n        detail,\n        code,\n        requestId: requestId ?? undefined,\n        retryAfter: parseRetryAfter(headers?.get(\"Retry-After\")),\n        fields: collectFields(obj, message),\n        body,\n    };\n}\n\n/**\n * Parse a `Retry-After` header into seconds. Accepts a delta-seconds integer\n * (`\"120\"`) or an HTTP-date (`\"Wed, 21 Oct 2015 07:28:00 GMT\"`).\n *\n * @param value - The raw header value, or null.\n * @returns The delay in seconds (>= 0), or undefined when absent/unparseable.\n */\nexport function parseRetryAfter(value: string | null | undefined): number | undefined {\n    if (!value) return undefined;\n    const trimmed = value.trim();\n    if (/^\\d+$/.test(trimmed)) return Number(trimmed);\n    const when = Date.parse(trimmed);\n    if (Number.isNaN(when)) return undefined;\n    return Math.max(0, Math.round((when - Date.now()) / 1000));\n}\n"],"mappings":"AAkBA,IAAaA,EAAb,cAAqC,KAA0B,CAC3D,OACA,OACA,KACA,UACA,OACA,KAEA,YAAY,EAAgB,CACxB,MAAMC,EAAK,MAAM,EACjB,KAAK,KAAO,kBACZ,KAAK,OAASA,EAAK,OACnB,KAAK,OAASA,EAAK,OACnB,KAAK,KAAOA,EAAK,KACjB,KAAK,UAAYA,EAAK,UACtB,KAAK,OAASA,EAAK,OACnB,KAAK,KAAOA,EAAK,IACrB,CACJ,EA2BaC,EAAb,cAA4C,KAAM,CAC9C,aAAc,CACV,MAAM,8CAA8C,EACpD,KAAK,KAAO,wBAChB,CACJ,EASA,SAAgBC,EAAW,EAAmC,CAC1D,OACI,OAAOC,GAAU,YACjBA,GACA,OAAQA,EAAmB,QAAW,UACtC,OAAQA,EAAmB,QAAW,QAE9C,CAOA,IAAMC,EAAiC,IAAI,IAAI,CAAC,OAAQ,QAAS,OAAQ,SAAU,QAAQ,CAAC,EAS5F,SAASC,EAAU,EAAkC,CACjD,GAAI,CAAC,MAAM,QAAQC,CAAG,EAAG,OACzB,IAAMC,EAAQD,EACT,OACI,GAAkC,OAAOE,GAAS,UAAY,OAAOA,GAAS,QACnF,CAAC,CACA,QAAQ,EAAM,IAAU,EAAEC,IAAU,GAAKL,EAAU,IAAI,OAAOI,CAAI,CAAC,EAAE,EAC1E,OAAOD,EAAM,OAAS,EAAIA,EAAM,KAAK,GAAG,EAAI,IAAA,EAChD,CAaA,IAAMG,EAAmB,EAkBzB,SAASC,EAAkB,EAAkD,CACzE,GAAI,CAAC,MAAM,QAAQC,CAAG,EAAG,OAEzB,IAAMC,EAAiC,CAAC,EACxC,IAAK,IAAMC,KAASF,EAAK,CACrB,GAAI,OAAOE,GAAU,WAAYA,EAAgB,SACjD,IAAMC,EAASD,EACTE,EAAQX,EAAUU,EAAO,GAAG,EAClC,GAAIC,IAAU,IAAA,IAAaA,KAASH,EAAQ,SAC5C,IAAMI,EAAUC,EAAgBH,EAAO,GAAG,GAAKG,EAAgBH,EAAO,OAAO,EACzEE,IAAY,IAAA,KAChB,EAAOD,GAASC,EACpB,CAEA,OAAO,OAAO,KAAKJ,CAAM,CAAC,CAAC,OAAS,EAAIA,EAAS,IAAA,EACrD,CAaA,SAASM,EAAY,EAAqD,CACtE,OAAO,OAAOC,GAAU,UAAYA,GAAkB,CAAC,MAAM,QAAQA,CAAK,EACnEA,EACD,IAAA,EACV,CA2BA,SAASC,EAAW,EAA0D,CAC1E,GAAIC,IAAS,KAAM,OACnB,IAAMC,EAAiC,CACnCJ,EAAYG,EAAK,MAAM,CAAC,EAAE,MAC1BA,EAAK,MACLH,EAAYG,EAAK,OAAO,CAAC,EAAE,KAC/B,EACA,IAAK,IAAME,KAAaD,EACpB,GAAI,OAAOC,GAAc,UAAYA,IAAc,GAAI,OAAOA,CAGtE,CAqBA,SAASC,EACL,EACA,EACkB,CAClB,GAAIR,IAAY,IAAA,IAAaD,IAAU,IAAA,GAAW,OAAOC,EACzD,IAAMS,EAAUV,EAAM,QAAQ,sBAAuB,MAAM,EACrDW,EAAUV,EACX,QAAY,OAAO,kBAAkBS,EAAQ,iCAAiC,EAAG,EAAE,CAAC,CACpF,KAAK,EACV,OAAOC,IAAY,GAAKV,EAAUU,CACtC,CAoBA,SAASC,EACL,EACA,EACkC,CAClC,IAAMC,EAASlB,EAAkBW,GAAM,MAAM,EAC7C,GAAIO,IAAW,IAAA,GAAW,OAAOA,EACjC,IAAMb,EAAQK,EAAWC,CAAI,EAC7B,GAAIN,IAAU,IAAA,IAAaC,IAAY,IAAA,GACvC,MAAO,EAAGD,GAAQC,CAAQ,CAC9B,CAkBA,SAASC,EAAgB,EAAc,EAAgB,EAAuB,CAC1E,GAAIN,GAAQ,KACZ,IAAI,OAAOA,GAAQ,SAAU,OAAOA,IAAQ,GAAK,IAAA,GAAYA,EAC7D,GAAI,OAAOA,GAAQ,UAAY,OAAOA,GAAQ,UAAW,OAAO,OAAOA,CAAG,EAC1E,GAAI,KAASF,GAEb,IAAI,MAAM,QAAQE,CAAG,EAAG,CACpB,IAAMkB,EAAQlB,EACT,IAAK,GAAU,CACZ,IAAMK,EAAUC,EAAgBJ,EAAOiB,EAAQ,CAAC,EAChD,GAAId,IAAY,IAAA,GAAW,OAC3B,IAAMD,EACF,OAAOF,GAAU,UAAYA,EACvBT,EAAWS,EAAkC,GAAG,EAChD,IAAA,GACV,OAAOE,IAAU,IAAA,GAAYC,EAAU,GAAGD,EAAM,IAAIC,GACxD,CAAC,CAAC,CACD,OAAQ,GAAyBe,IAAS,IAAA,EAAS,EACxD,OAAOF,EAAM,OAAS,EAAIA,EAAM,KAAK,IAAI,EAAI,IAAA,EACjD,CAEA,GAAI,OAAOlB,GAAQ,SAAU,CACzB,IAAME,EAAQF,EACd,OACIM,EAAgBJ,EAAM,IAAKiB,EAAQ,CAAC,GACpCb,EAAgBJ,EAAM,QAASiB,EAAQ,CAAC,GACxCb,EAAgBJ,EAAM,OAAQiB,EAAQ,CAAC,CAE/C,CATA,CAjB6D,CA6BjE,CASA,IAAME,EAA0C,IAAI,IAAI,CAAC,EAAG,IAAK,IAAK,GAAG,CAAC,EAyB1E,SAAgBC,EAAkB,EAAyB,CACvD,OAAOD,EAAmB,IAAIE,CAAM,GAAKA,GAAU,GACvD,CAaA,SAAgBC,EAAgB,EAAwB,CACpD,MAAO,QAAQD,GACnB,CA+CA,SAAgBE,EACZ,EACA,EACA,EACA,EACQ,CACR,IAAMC,EACF,OAAOhB,GAAS,UAAYA,EAAiBA,EAAmC,KAC9EL,EAAUQ,EACZP,EAAgBoB,GAAK,MAAM,GAAKpB,EAAgBoB,GAAK,OAAO,EAC5DjB,EAAWiB,CAAG,CAClB,EACMC,EAAStB,GAAWmB,EAAgBD,CAAM,EAC1CK,EAAO,OAAOF,GAAK,MAAS,SAAWA,EAAI,KAAO,IAAA,GAClDG,EACF,OAAOH,GAAK,SAAY,UAAYA,EAAI,UAAY,KAC7CA,EAAI,QACL,KAOV,MAAO,CACH,SACA,SACA,OACA,WATC,OAAOG,GAAS,YAAe,SAAWA,EAAQ,WAAa,IAAA,KAChEC,GAAS,IAAI,cAAc,GAC3BC,GACA,IAAA,IAMwB,IAAA,GACxB,WAAYC,EAAgBF,GAAS,IAAI,aAAa,CAAC,EACvD,OAAQd,EAAcU,EAAKrB,CAAO,EAClC,MACJ,CACJ,CASA,SAAgB2B,EAAgB,EAAsD,CAClF,GAAI,CAACxB,EAAO,OACZ,IAAMO,EAAUP,EAAM,KAAK,EAC3B,GAAI,QAAQ,KAAKO,CAAO,EAAG,OAAO,OAAOA,CAAO,EAChD,IAAMkB,EAAO,KAAK,MAAMlB,CAAO,EAC/B,GAAI,QAAO,MAAMkB,CAAI,EACrB,OAAO,KAAK,IAAI,EAAG,KAAK,OAAOA,EAAO,KAAK,IAAI,GAAK,GAAI,CAAC,CAC7D,C"}