tempest-react-sdk 0.57.0 → 0.59.0

package/dist/hooks/use-push-to-talk.cjs

@@ -1,2 +1,2 @@
-let e=require("react");var t=[{code:`Space`,label:`Espaço`},{code:`ControlLeft`,label:`Ctrl esquerdo`},{code:`AltLeft`,label:`Alt esquerdo`},{code:`ShiftLeft`,label:`Shift esquerdo`},{code:`Backquote`,label:"Crase (`)"}],n=`Space`;function r(e){return t.find(t=>t.code===e)?.label??e}function i(e){if(!(e instanceof HTMLElement))return!1;if(e.isContentEditable)return!0;let t=e.tagName;return t===`INPUT`||t===`TEXTAREA`||t===`SELECT`}function a({code:t=n,onDown:r,onUp:a,enabled:o=!0}){let s=(0,e.useRef)({onDown:r,onUp:a});(0,e.useEffect)(()=>{s.current={onDown:r,onUp:a}}),(0,e.useEffect)(()=>{if(!o||typeof window>`u`)return;let e=!1,n=()=>{e&&(e=!1,s.current.onUp())},r=n=>{n.code!==t||n.repeat||i(n.target)||(n.preventDefault(),!e&&(e=!0,s.current.onDown()))},a=r=>{r.code!==t||!e||(r.preventDefault(),n())};return window.addEventListener(`keydown`,r),window.addEventListener(`keyup`,a),window.addEventListener(`blur`,n),()=>{window.removeEventListener(`keydown`,r),window.removeEventListener(`keyup`,a),window.removeEventListener(`blur`,n),n()}},[t,o])}exports.DEFAULT_PUSH_TO_TALK_KEY=n,exports.PUSH_TO_TALK_KEYS=t,exports.pushToTalkKeyLabel=r,exports.usePushToTalk=a;
+let e=require("react");var t=[{code:`Space`,label:`Espaço`},{code:`ControlLeft`,label:`Ctrl esquerdo`},{code:`AltLeft`,label:`Alt esquerdo`},{code:`ShiftLeft`,label:`Shift esquerdo`},{code:`Backquote`,label:"Crase (`)"}],n=`Space`;function r(e){return t.find(t=>t.code===e)?.label??e}function i(e){if(!(e instanceof HTMLElement))return!1;if(e.isContentEditable)return!0;let t=e.tagName;return t===`INPUT`||t===`TEXTAREA`||t===`SELECT`}function a({code:t=n,onDown:r,onUp:a,enabled:o=!0}){let s=(0,e.useRef)({onDown:r,onUp:a});(0,e.useEffect)(()=>{s.current={onDown:r,onUp:a}}),(0,e.useEffect)(()=>{if(!o||typeof window>`u`)return;let e=!1,n=()=>{e&&(e=!1,s.current.onUp())},r=n=>{n.code!==t||n.repeat||i(n.target)||(n.preventDefault(),!e&&(e=!0,s.current.onDown()))},a=r=>{r.code===t&&e&&(r.preventDefault(),n())};return window.addEventListener(`keydown`,r),window.addEventListener(`keyup`,a),window.addEventListener(`blur`,n),()=>{window.removeEventListener(`keydown`,r),window.removeEventListener(`keyup`,a),window.removeEventListener(`blur`,n),n()}},[t,o])}exports.DEFAULT_PUSH_TO_TALK_KEY=n,exports.PUSH_TO_TALK_KEYS=t,exports.pushToTalkKeyLabel=r,exports.usePushToTalk=a;
 //# sourceMappingURL=use-push-to-talk.cjs.map

package/dist/hooks/use-push-to-talk.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-push-to-talk.cjs","names":[],"sources":["../../src/hooks/use-push-to-talk.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/** A key offered for push-to-talk, with the label a settings screen shows. */\nexport interface PushToTalkKey {\n    /** `KeyboardEvent.code`, which is layout-independent. */\n    code: string;\n    /** What to show a person. `code` itself is not a label. */\n    label: string;\n}\n\n/**\n * The keys worth offering for push-to-talk.\n *\n * Identified by `code` rather than `key` so a binding survives a layout change:\n * on an ABNT2 keyboard the `key` reported for the backquote position is not what\n * a US layout reports, while `Backquote` is the same physical key everywhere.\n *\n * Left-hand modifiers only. The right-hand ones sit under the hand that is\n * usually on the mouse, and a modifier that is also a shortcut prefix\n * (`ControlLeft` with a browser shortcut) is a deliberate trade the caller makes\n * by choosing it.\n */\nexport const PUSH_TO_TALK_KEYS: readonly PushToTalkKey[] = [\n    { code: \"Space\", label: \"Espaço\" },\n    { code: \"ControlLeft\", label: \"Ctrl esquerdo\" },\n    { code: \"AltLeft\", label: \"Alt esquerdo\" },\n    { code: \"ShiftLeft\", label: \"Shift esquerdo\" },\n    { code: \"Backquote\", label: \"Crase (`)\" },\n];\n\n/** The key a caller gets when it does not choose one. */\nexport const DEFAULT_PUSH_TO_TALK_KEY = \"Space\";\n\n/**\n * The label to show for a `KeyboardEvent.code`.\n *\n * @param code - The bound key's code.\n * @returns Its label, or the code itself for a key this list does not name —\n *     showing `\"F13\"` beats showing nothing.\n */\nexport function pushToTalkKeyLabel(code: string): string {\n    return PUSH_TO_TALK_KEYS.find((key) => key.code === code)?.label ?? code;\n}\n\n/**\n * Whether a keystroke is meant for something the person is typing into.\n *\n * Without this a push-to-talk key bound to Space opens the microphone every time\n * somebody writes a message — and the space never reaches the text field,\n * because the handler preventDefault'd it.\n *\n * @param target - The event's target.\n * @returns `true` when the keystroke belongs to a field, not to the app.\n */\nfunction isTypingTarget(target: EventTarget | null): boolean {\n    if (!(target instanceof HTMLElement)) return false;\n    if (target.isContentEditable) return true;\n    const tag = target.tagName;\n    return tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\";\n}\n\n/** Options for {@link usePushToTalk}. */\nexport interface UsePushToTalkOptions {\n    /** `KeyboardEvent.code` to hold. Default {@link DEFAULT_PUSH_TO_TALK_KEY}. */\n    code?: string;\n    /** Called once when the key goes down. */\n    onDown: () => void;\n    /** Called when the key comes up, the window blurs, or the hook unmounts. */\n    onUp: () => void;\n    /**\n     * Whether the binding is live. Default `true`.\n     *\n     * Turning it off releases first, so flipping a call from push-to-talk to an\n     * open microphone while the key is held does not leave `onUp` unfired.\n     */\n    enabled?: boolean;\n}\n\n/**\n * Hold a key to transmit; release it to go silent again.\n *\n * Looks like `keydown`/`keyup` and is not, because three things go wrong:\n *\n * 1. **`blur` has to release.** Alt-tabbing away while holding the key means the\n *    browser never sees the `keyup`, and the microphone stays open for as long as\n *    the person is looking at another window — exactly what push-to-talk exists\n *    to prevent.\n * 2. **Auto-repeat has to be ignored.** A held key repeats at the keyboard's rate,\n *    and without the `repeat` check `onDown` fires on every one of them.\n * 3. **A text field has to win.** Space bound to push-to-talk with the focus in an\n *    `<input>` means the space never reaches the message being written.\n *\n * Unmounting releases too, for the same reason `blur` does: the callback that\n * stops transmitting has to run even when the component holding it goes away\n * mid-press.\n *\n * The callbacks are read through a ref that a commit-time effect refreshes, so\n * passing inline arrows neither tears the listeners down on every render nor\n * writes to the ref during one — a render React discards would leave the ref\n * pointing at callbacks that never became the UI.\n *\n * @param options - See {@link UsePushToTalkOptions}.\n *\n * @example\n * usePushToTalk({\n *     code: \"Space\",\n *     onDown: () => setMicEnabled(true),\n *     onUp: () => setMicEnabled(false),\n * });\n */\nexport function usePushToTalk({\n    code = DEFAULT_PUSH_TO_TALK_KEY,\n    onDown,\n    onUp,\n    enabled = true,\n}: UsePushToTalkOptions): void {\n    const callbacks = useRef({ onDown, onUp });\n    useEffect(() => {\n        callbacks.current = { onDown, onUp };\n    });\n\n    useEffect(() => {\n        if (!enabled || typeof window === \"undefined\") return;\n        let held = false;\n\n        const release = (): void => {\n            if (!held) return;\n            held = false;\n            callbacks.current.onUp();\n        };\n\n        const handleKeyDown = (event: KeyboardEvent): void => {\n            if (event.code !== code || event.repeat) return;\n            if (isTypingTarget(event.target)) return;\n            event.preventDefault();\n            if (held) return;\n            held = true;\n            callbacks.current.onDown();\n        };\n\n        /**\n         * Release on the way up, and never mind where the keystroke landed.\n         *\n         * The field guard belongs on the way **down** — it is what stops a\n         * push-to-talk bound to Space from opening the microphone every time\n         * somebody writes a message. On the way up it did the opposite of its\n         * job: `keyup` is delivered to whatever is focused when the key rises,\n         * not to what was focused when it fell, so clicking into an input while\n         * still holding sent the release into the guard and left `held` true.\n         * The microphone stayed open until the window blurred.\n         *\n         * `held` is the guard this needs. If we never opened the microphone\n         * there is nothing to close, and `release()` already returns on that —\n         * so the only thing left to decide is `preventDefault`, which is\n         * honest only for a keystroke we actually acted on.\n         */\n        const handleKeyUp = (event: KeyboardEvent): void => {\n            if (event.code !== code || !held) return;\n            event.preventDefault();\n            release();\n        };\n\n        window.addEventListener(\"keydown\", handleKeyDown);\n        window.addEventListener(\"keyup\", handleKeyUp);\n        window.addEventListener(\"blur\", release);\n\n        return () => {\n            window.removeEventListener(\"keydown\", handleKeyDown);\n            window.removeEventListener(\"keyup\", handleKeyUp);\n            window.removeEventListener(\"blur\", release);\n            release();\n        };\n    }, [code, enabled]);\n}\n"],"mappings":"uBAsBA,IAAa,EAA8C,CACvD,CAAE,KAAM,QAAS,MAAO,QAAS,EACjC,CAAE,KAAM,cAAe,MAAO,eAAgB,EAC9C,CAAE,KAAM,UAAW,MAAO,cAAe,EACzC,CAAE,KAAM,YAAa,MAAO,gBAAiB,EAC7C,CAAE,KAAM,YAAa,MAAO,WAAY,CAC5C,EAGa,EAA2B,QASxC,SAAgB,EAAmB,EAAsB,CACrD,OAAO,EAAkB,KAAM,GAAQ,EAAI,OAAS,CAAI,CAAC,EAAE,OAAS,CACxE,CAYA,SAAS,EAAe,EAAqC,CACzD,GAAI,EAAE,aAAkB,aAAc,MAAO,GAC7C,GAAI,EAAO,kBAAmB,MAAO,GACrC,IAAM,EAAM,EAAO,QACnB,OAAO,IAAQ,SAAW,IAAQ,YAAc,IAAQ,QAC5D,CAmDA,SAAgB,EAAc,CAC1B,OAAO,EACP,SACA,OACA,UAAU,IACiB,CAC3B,IAAM,GAAA,EAAY,EAAA,OAAA,CAAO,CAAE,SAAQ,MAAK,CAAC,GACzC,EAAA,EAAA,UAAA,KAAgB,CACZ,EAAU,QAAU,CAAE,SAAQ,MAAK,CACvC,CAAC,GAED,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,CAAC,GAAW,OAAO,OAAW,IAAa,OAC/C,IAAI,EAAO,GAEL,MAAsB,CACnB,IACL,EAAO,GACP,EAAU,QAAQ,KAAK,EAC3B,EAEM,EAAiB,GAA+B,CAC9C,EAAM,OAAS,GAAQ,EAAM,QAC7B,EAAe,EAAM,MAAM,IAC/B,EAAM,eAAe,EACjB,KACJ,EAAO,GACP,EAAU,QAAQ,OAAO,GAC7B,EAkBM,EAAe,GAA+B,CAC5C,EAAM,OAAS,GAAQ,CAAC,IAC5B,EAAM,eAAe,EACrB,EAAQ,EACZ,EAMA,OAJA,OAAO,iBAAiB,UAAW,CAAa,EAChD,OAAO,iBAAiB,QAAS,CAAW,EAC5C,OAAO,iBAAiB,OAAQ,CAAO,MAE1B,CACT,OAAO,oBAAoB,UAAW,CAAa,EACnD,OAAO,oBAAoB,QAAS,CAAW,EAC/C,OAAO,oBAAoB,OAAQ,CAAO,EAC1C,EAAQ,CACZ,CACJ,EAAG,CAAC,EAAM,CAAO,CAAC,CACtB"}
+{"version":3,"file":"use-push-to-talk.cjs","names":[],"sources":["../../src/hooks/use-push-to-talk.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/** A key offered for push-to-talk, with the label a settings screen shows. */\nexport interface PushToTalkKey {\n    /** `KeyboardEvent.code`, which is layout-independent. */\n    code: string;\n    /** What to show a person. `code` itself is not a label. */\n    label: string;\n}\n\n/**\n * The keys worth offering for push-to-talk.\n *\n * Identified by `code` rather than `key` so a binding survives a layout change:\n * on an ABNT2 keyboard the `key` reported for the backquote position is not what\n * a US layout reports, while `Backquote` is the same physical key everywhere.\n *\n * Left-hand modifiers only. The right-hand ones sit under the hand that is\n * usually on the mouse, and a modifier that is also a shortcut prefix\n * (`ControlLeft` with a browser shortcut) is a deliberate trade the caller makes\n * by choosing it.\n */\nexport const PUSH_TO_TALK_KEYS: readonly PushToTalkKey[] = [\n    { code: \"Space\", label: \"Espaço\" },\n    { code: \"ControlLeft\", label: \"Ctrl esquerdo\" },\n    { code: \"AltLeft\", label: \"Alt esquerdo\" },\n    { code: \"ShiftLeft\", label: \"Shift esquerdo\" },\n    { code: \"Backquote\", label: \"Crase (`)\" },\n];\n\n/** The key a caller gets when it does not choose one. */\nexport const DEFAULT_PUSH_TO_TALK_KEY = \"Space\";\n\n/**\n * The label to show for a `KeyboardEvent.code`.\n *\n * @param code - The bound key's code.\n * @returns Its label, or the code itself for a key this list does not name —\n *     showing `\"F13\"` beats showing nothing.\n */\nexport function pushToTalkKeyLabel(code: string): string {\n    return PUSH_TO_TALK_KEYS.find((key) => key.code === code)?.label ?? code;\n}\n\n/**\n * Whether a keystroke is meant for something the person is typing into.\n *\n * Without this a push-to-talk key bound to Space opens the microphone every time\n * somebody writes a message — and the space never reaches the text field,\n * because the handler preventDefault'd it.\n *\n * @param target - The event's target.\n * @returns `true` when the keystroke belongs to a field, not to the app.\n */\nfunction isTypingTarget(target: EventTarget | null): boolean {\n    if (!(target instanceof HTMLElement)) return false;\n    if (target.isContentEditable) return true;\n    const tag = target.tagName;\n    return tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\";\n}\n\n/** Options for {@link usePushToTalk}. */\nexport interface UsePushToTalkOptions {\n    /** `KeyboardEvent.code` to hold. Default {@link DEFAULT_PUSH_TO_TALK_KEY}. */\n    code?: string;\n    /** Called once when the key goes down. */\n    onDown: () => void;\n    /** Called when the key comes up, the window blurs, or the hook unmounts. */\n    onUp: () => void;\n    /**\n     * Whether the binding is live. Default `true`.\n     *\n     * Turning it off releases first, so flipping a call from push-to-talk to an\n     * open microphone while the key is held does not leave `onUp` unfired.\n     */\n    enabled?: boolean;\n}\n\n/**\n * Hold a key to transmit; release it to go silent again.\n *\n * Looks like `keydown`/`keyup` and is not, because three things go wrong:\n *\n * 1. **`blur` has to release.** Alt-tabbing away while holding the key means the\n *    browser never sees the `keyup`, and the microphone stays open for as long as\n *    the person is looking at another window — exactly what push-to-talk exists\n *    to prevent.\n * 2. **Auto-repeat has to be ignored.** A held key repeats at the keyboard's rate,\n *    and without the `repeat` check `onDown` fires on every one of them.\n * 3. **A text field has to win.** Space bound to push-to-talk with the focus in an\n *    `<input>` means the space never reaches the message being written.\n *\n * Unmounting releases too, for the same reason `blur` does: the callback that\n * stops transmitting has to run even when the component holding it goes away\n * mid-press.\n *\n * The callbacks are read through a ref that a commit-time effect refreshes, so\n * passing inline arrows neither tears the listeners down on every render nor\n * writes to the ref during one — a render React discards would leave the ref\n * pointing at callbacks that never became the UI.\n *\n * @param options - See {@link UsePushToTalkOptions}.\n *\n * @example\n * usePushToTalk({\n *     code: \"Space\",\n *     onDown: () => setMicEnabled(true),\n *     onUp: () => setMicEnabled(false),\n * });\n */\nexport function usePushToTalk({\n    code = DEFAULT_PUSH_TO_TALK_KEY,\n    onDown,\n    onUp,\n    enabled = true,\n}: UsePushToTalkOptions): void {\n    const callbacks = useRef({ onDown, onUp });\n    useEffect(() => {\n        callbacks.current = { onDown, onUp };\n    });\n\n    useEffect(() => {\n        if (!enabled || typeof window === \"undefined\") return;\n        let held = false;\n\n        const release = (): void => {\n            if (!held) return;\n            held = false;\n            callbacks.current.onUp();\n        };\n\n        const handleKeyDown = (event: KeyboardEvent): void => {\n            if (event.code !== code || event.repeat) return;\n            if (isTypingTarget(event.target)) return;\n            event.preventDefault();\n            if (held) return;\n            held = true;\n            callbacks.current.onDown();\n        };\n\n        /**\n         * Release on the way up, and never mind where the keystroke landed.\n         *\n         * The field guard belongs on the way **down** — it is what stops a\n         * push-to-talk bound to Space from opening the microphone every time\n         * somebody writes a message. On the way up it did the opposite of its\n         * job: `keyup` is delivered to whatever is focused when the key rises,\n         * not to what was focused when it fell, so clicking into an input while\n         * still holding sent the release into the guard and left `held` true.\n         * The microphone stayed open until the window blurred.\n         *\n         * `held` is the guard this needs. If we never opened the microphone\n         * there is nothing to close, and `release()` already returns on that —\n         * so the only thing left to decide is `preventDefault`, which is\n         * honest only for a keystroke we actually acted on.\n         */\n        const handleKeyUp = (event: KeyboardEvent): void => {\n            if (event.code !== code || !held) return;\n            event.preventDefault();\n            release();\n        };\n\n        window.addEventListener(\"keydown\", handleKeyDown);\n        window.addEventListener(\"keyup\", handleKeyUp);\n        window.addEventListener(\"blur\", release);\n\n        return () => {\n            window.removeEventListener(\"keydown\", handleKeyDown);\n            window.removeEventListener(\"keyup\", handleKeyUp);\n            window.removeEventListener(\"blur\", release);\n            release();\n        };\n    }, [code, enabled]);\n}\n"],"mappings":"uBAsBA,IAAa,EAA8C,CACvD,CAAE,KAAM,QAAS,MAAO,QAAS,EACjC,CAAE,KAAM,cAAe,MAAO,eAAgB,EAC9C,CAAE,KAAM,UAAW,MAAO,cAAe,EACzC,CAAE,KAAM,YAAa,MAAO,gBAAiB,EAC7C,CAAE,KAAM,YAAa,MAAO,WAAY,CAC5C,EAGa,EAA2B,QASxC,SAAgB,EAAmB,EAAsB,CACrD,OAAO,EAAkB,KAAM,GAAQ,EAAI,OAAS,CAAI,CAAC,EAAE,OAAS,CACxE,CAYA,SAAS,EAAe,EAAqC,CACzD,GAAI,EAAE,aAAkB,aAAc,MAAO,GAC7C,GAAI,EAAO,kBAAmB,MAAO,GACrC,IAAM,EAAM,EAAO,QACnB,OAAO,IAAQ,SAAW,IAAQ,YAAc,IAAQ,QAC5D,CAmDA,SAAgB,EAAc,CAC1B,OAAO,EACP,SACA,OACA,UAAU,IACiB,CAC3B,IAAM,GAAA,EAAY,EAAA,OAAA,CAAO,CAAE,SAAQ,MAAK,CAAC,GACzC,EAAA,EAAA,UAAA,KAAgB,CACZ,EAAU,QAAU,CAAE,SAAQ,MAAK,CACvC,CAAC,GAED,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,CAAC,GAAW,OAAO,OAAW,IAAa,OAC/C,IAAI,EAAO,GAEL,MAAsB,CACnB,IACL,EAAO,GACP,EAAU,QAAQ,KAAK,EAC3B,EAEM,EAAiB,GAA+B,CAC9C,EAAM,OAAS,GAAQ,EAAM,QAC7B,EAAe,EAAM,MAAM,IAC/B,EAAM,eAAe,EACjB,KACJ,EAAO,GACP,EAAU,QAAQ,OAAO,GAC7B,EAkBM,EAAe,GAA+B,CAC5C,EAAM,OAAS,GAAS,IAC5B,EAAM,eAAe,EACrB,EAAQ,EACZ,EAMA,OAJA,OAAO,iBAAiB,UAAW,CAAa,EAChD,OAAO,iBAAiB,QAAS,CAAW,EAC5C,OAAO,iBAAiB,OAAQ,CAAO,MAE1B,CACT,OAAO,oBAAoB,UAAW,CAAa,EACnD,OAAO,oBAAoB,QAAS,CAAW,EAC/C,OAAO,oBAAoB,OAAQ,CAAO,EAC1C,EAAQ,CACZ,CACJ,EAAG,CAAC,EAAM,CAAO,CAAC,CACtB"}

package/dist/hooks/use-push-to-talk.js

@@ -48,7 +48,7 @@ function o({ code: n = r, onDown: i, onUp: o, enabled: s = !0 }) {
 		}, r = (t) => {
 			t.code !== n || t.repeat || a(t.target) || (t.preventDefault(), !e && (e = !0, c.current.onDown()));
 		}, i = (r) => {
-			r.code !== n || !e || (r.preventDefault(), t());
+			r.code === n && e && (r.preventDefault(), t());
 		};
 		return window.addEventListener("keydown", r), window.addEventListener("keyup", i), window.addEventListener("blur", t), () => {
 			window.removeEventListener("keydown", r), window.removeEventListener("keyup", i), window.removeEventListener("blur", t), t();

package/dist/hooks/use-push-to-talk.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-push-to-talk.js","names":[],"sources":["../../src/hooks/use-push-to-talk.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/** A key offered for push-to-talk, with the label a settings screen shows. */\nexport interface PushToTalkKey {\n    /** `KeyboardEvent.code`, which is layout-independent. */\n    code: string;\n    /** What to show a person. `code` itself is not a label. */\n    label: string;\n}\n\n/**\n * The keys worth offering for push-to-talk.\n *\n * Identified by `code` rather than `key` so a binding survives a layout change:\n * on an ABNT2 keyboard the `key` reported for the backquote position is not what\n * a US layout reports, while `Backquote` is the same physical key everywhere.\n *\n * Left-hand modifiers only. The right-hand ones sit under the hand that is\n * usually on the mouse, and a modifier that is also a shortcut prefix\n * (`ControlLeft` with a browser shortcut) is a deliberate trade the caller makes\n * by choosing it.\n */\nexport const PUSH_TO_TALK_KEYS: readonly PushToTalkKey[] = [\n    { code: \"Space\", label: \"Espaço\" },\n    { code: \"ControlLeft\", label: \"Ctrl esquerdo\" },\n    { code: \"AltLeft\", label: \"Alt esquerdo\" },\n    { code: \"ShiftLeft\", label: \"Shift esquerdo\" },\n    { code: \"Backquote\", label: \"Crase (`)\" },\n];\n\n/** The key a caller gets when it does not choose one. */\nexport const DEFAULT_PUSH_TO_TALK_KEY = \"Space\";\n\n/**\n * The label to show for a `KeyboardEvent.code`.\n *\n * @param code - The bound key's code.\n * @returns Its label, or the code itself for a key this list does not name —\n *     showing `\"F13\"` beats showing nothing.\n */\nexport function pushToTalkKeyLabel(code: string): string {\n    return PUSH_TO_TALK_KEYS.find((key) => key.code === code)?.label ?? code;\n}\n\n/**\n * Whether a keystroke is meant for something the person is typing into.\n *\n * Without this a push-to-talk key bound to Space opens the microphone every time\n * somebody writes a message — and the space never reaches the text field,\n * because the handler preventDefault'd it.\n *\n * @param target - The event's target.\n * @returns `true` when the keystroke belongs to a field, not to the app.\n */\nfunction isTypingTarget(target: EventTarget | null): boolean {\n    if (!(target instanceof HTMLElement)) return false;\n    if (target.isContentEditable) return true;\n    const tag = target.tagName;\n    return tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\";\n}\n\n/** Options for {@link usePushToTalk}. */\nexport interface UsePushToTalkOptions {\n    /** `KeyboardEvent.code` to hold. Default {@link DEFAULT_PUSH_TO_TALK_KEY}. */\n    code?: string;\n    /** Called once when the key goes down. */\n    onDown: () => void;\n    /** Called when the key comes up, the window blurs, or the hook unmounts. */\n    onUp: () => void;\n    /**\n     * Whether the binding is live. Default `true`.\n     *\n     * Turning it off releases first, so flipping a call from push-to-talk to an\n     * open microphone while the key is held does not leave `onUp` unfired.\n     */\n    enabled?: boolean;\n}\n\n/**\n * Hold a key to transmit; release it to go silent again.\n *\n * Looks like `keydown`/`keyup` and is not, because three things go wrong:\n *\n * 1. **`blur` has to release.** Alt-tabbing away while holding the key means the\n *    browser never sees the `keyup`, and the microphone stays open for as long as\n *    the person is looking at another window — exactly what push-to-talk exists\n *    to prevent.\n * 2. **Auto-repeat has to be ignored.** A held key repeats at the keyboard's rate,\n *    and without the `repeat` check `onDown` fires on every one of them.\n * 3. **A text field has to win.** Space bound to push-to-talk with the focus in an\n *    `<input>` means the space never reaches the message being written.\n *\n * Unmounting releases too, for the same reason `blur` does: the callback that\n * stops transmitting has to run even when the component holding it goes away\n * mid-press.\n *\n * The callbacks are read through a ref that a commit-time effect refreshes, so\n * passing inline arrows neither tears the listeners down on every render nor\n * writes to the ref during one — a render React discards would leave the ref\n * pointing at callbacks that never became the UI.\n *\n * @param options - See {@link UsePushToTalkOptions}.\n *\n * @example\n * usePushToTalk({\n *     code: \"Space\",\n *     onDown: () => setMicEnabled(true),\n *     onUp: () => setMicEnabled(false),\n * });\n */\nexport function usePushToTalk({\n    code = DEFAULT_PUSH_TO_TALK_KEY,\n    onDown,\n    onUp,\n    enabled = true,\n}: UsePushToTalkOptions): void {\n    const callbacks = useRef({ onDown, onUp });\n    useEffect(() => {\n        callbacks.current = { onDown, onUp };\n    });\n\n    useEffect(() => {\n        if (!enabled || typeof window === \"undefined\") return;\n        let held = false;\n\n        const release = (): void => {\n            if (!held) return;\n            held = false;\n            callbacks.current.onUp();\n        };\n\n        const handleKeyDown = (event: KeyboardEvent): void => {\n            if (event.code !== code || event.repeat) return;\n            if (isTypingTarget(event.target)) return;\n            event.preventDefault();\n            if (held) return;\n            held = true;\n            callbacks.current.onDown();\n        };\n\n        /**\n         * Release on the way up, and never mind where the keystroke landed.\n         *\n         * The field guard belongs on the way **down** — it is what stops a\n         * push-to-talk bound to Space from opening the microphone every time\n         * somebody writes a message. On the way up it did the opposite of its\n         * job: `keyup` is delivered to whatever is focused when the key rises,\n         * not to what was focused when it fell, so clicking into an input while\n         * still holding sent the release into the guard and left `held` true.\n         * The microphone stayed open until the window blurred.\n         *\n         * `held` is the guard this needs. If we never opened the microphone\n         * there is nothing to close, and `release()` already returns on that —\n         * so the only thing left to decide is `preventDefault`, which is\n         * honest only for a keystroke we actually acted on.\n         */\n        const handleKeyUp = (event: KeyboardEvent): void => {\n            if (event.code !== code || !held) return;\n            event.preventDefault();\n            release();\n        };\n\n        window.addEventListener(\"keydown\", handleKeyDown);\n        window.addEventListener(\"keyup\", handleKeyUp);\n        window.addEventListener(\"blur\", release);\n\n        return () => {\n            window.removeEventListener(\"keydown\", handleKeyDown);\n            window.removeEventListener(\"keyup\", handleKeyUp);\n            window.removeEventListener(\"blur\", release);\n            release();\n        };\n    }, [code, enabled]);\n}\n"],"mappings":";;AAsBA,IAAa,IAA8C;CACvD;EAAE,MAAM;EAAS,OAAO;CAAS;CACjC;EAAE,MAAM;EAAe,OAAO;CAAgB;CAC9C;EAAE,MAAM;EAAW,OAAO;CAAe;CACzC;EAAE,MAAM;EAAa,OAAO;CAAiB;CAC7C;EAAE,MAAM;EAAa,OAAO;CAAY;AAC5C,GAGa,IAA2B;AASxC,SAAgB,EAAmB,GAAsB;CACrD,OAAO,EAAkB,MAAM,MAAQ,EAAI,SAAS,CAAI,CAAC,EAAE,SAAS;AACxE;AAYA,SAAS,EAAe,GAAqC;CACzD,IAAI,EAAE,aAAkB,cAAc,OAAO;CAC7C,IAAI,EAAO,mBAAmB,OAAO;CACrC,IAAM,IAAM,EAAO;CACnB,OAAO,MAAQ,WAAW,MAAQ,cAAc,MAAQ;AAC5D;AAmDA,SAAgB,EAAc,EAC1B,UAAO,GACP,WACA,SACA,aAAU,MACiB;CAC3B,IAAM,IAAY,EAAO;EAAE;EAAQ;CAAK,CAAC;CAKzC,AAJA,QAAgB;EACZ,EAAU,UAAU;GAAE;GAAQ;EAAK;CACvC,CAAC,GAED,QAAgB;EACZ,IAAI,CAAC,KAAW,OAAO,SAAW,KAAa;EAC/C,IAAI,IAAO,IAEL,UAAsB;GACnB,MACL,IAAO,IACP,EAAU,QAAQ,KAAK;EAC3B,GAEM,KAAiB,MAA+B;GAC9C,EAAM,SAAS,KAAQ,EAAM,UAC7B,EAAe,EAAM,MAAM,MAC/B,EAAM,eAAe,GACjB,OACJ,IAAO,IACP,EAAU,QAAQ,OAAO;EAC7B,GAkBM,KAAe,MAA+B;GAC5C,EAAM,SAAS,KAAQ,CAAC,MAC5B,EAAM,eAAe,GACrB,EAAQ;EACZ;EAMA,OAJA,OAAO,iBAAiB,WAAW,CAAa,GAChD,OAAO,iBAAiB,SAAS,CAAW,GAC5C,OAAO,iBAAiB,QAAQ,CAAO,SAE1B;GAIT,AAHA,OAAO,oBAAoB,WAAW,CAAa,GACnD,OAAO,oBAAoB,SAAS,CAAW,GAC/C,OAAO,oBAAoB,QAAQ,CAAO,GAC1C,EAAQ;EACZ;CACJ,GAAG,CAAC,GAAM,CAAO,CAAC;AACtB"}
+{"version":3,"file":"use-push-to-talk.js","names":[],"sources":["../../src/hooks/use-push-to-talk.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/** A key offered for push-to-talk, with the label a settings screen shows. */\nexport interface PushToTalkKey {\n    /** `KeyboardEvent.code`, which is layout-independent. */\n    code: string;\n    /** What to show a person. `code` itself is not a label. */\n    label: string;\n}\n\n/**\n * The keys worth offering for push-to-talk.\n *\n * Identified by `code` rather than `key` so a binding survives a layout change:\n * on an ABNT2 keyboard the `key` reported for the backquote position is not what\n * a US layout reports, while `Backquote` is the same physical key everywhere.\n *\n * Left-hand modifiers only. The right-hand ones sit under the hand that is\n * usually on the mouse, and a modifier that is also a shortcut prefix\n * (`ControlLeft` with a browser shortcut) is a deliberate trade the caller makes\n * by choosing it.\n */\nexport const PUSH_TO_TALK_KEYS: readonly PushToTalkKey[] = [\n    { code: \"Space\", label: \"Espaço\" },\n    { code: \"ControlLeft\", label: \"Ctrl esquerdo\" },\n    { code: \"AltLeft\", label: \"Alt esquerdo\" },\n    { code: \"ShiftLeft\", label: \"Shift esquerdo\" },\n    { code: \"Backquote\", label: \"Crase (`)\" },\n];\n\n/** The key a caller gets when it does not choose one. */\nexport const DEFAULT_PUSH_TO_TALK_KEY = \"Space\";\n\n/**\n * The label to show for a `KeyboardEvent.code`.\n *\n * @param code - The bound key's code.\n * @returns Its label, or the code itself for a key this list does not name —\n *     showing `\"F13\"` beats showing nothing.\n */\nexport function pushToTalkKeyLabel(code: string): string {\n    return PUSH_TO_TALK_KEYS.find((key) => key.code === code)?.label ?? code;\n}\n\n/**\n * Whether a keystroke is meant for something the person is typing into.\n *\n * Without this a push-to-talk key bound to Space opens the microphone every time\n * somebody writes a message — and the space never reaches the text field,\n * because the handler preventDefault'd it.\n *\n * @param target - The event's target.\n * @returns `true` when the keystroke belongs to a field, not to the app.\n */\nfunction isTypingTarget(target: EventTarget | null): boolean {\n    if (!(target instanceof HTMLElement)) return false;\n    if (target.isContentEditable) return true;\n    const tag = target.tagName;\n    return tag === \"INPUT\" || tag === \"TEXTAREA\" || tag === \"SELECT\";\n}\n\n/** Options for {@link usePushToTalk}. */\nexport interface UsePushToTalkOptions {\n    /** `KeyboardEvent.code` to hold. Default {@link DEFAULT_PUSH_TO_TALK_KEY}. */\n    code?: string;\n    /** Called once when the key goes down. */\n    onDown: () => void;\n    /** Called when the key comes up, the window blurs, or the hook unmounts. */\n    onUp: () => void;\n    /**\n     * Whether the binding is live. Default `true`.\n     *\n     * Turning it off releases first, so flipping a call from push-to-talk to an\n     * open microphone while the key is held does not leave `onUp` unfired.\n     */\n    enabled?: boolean;\n}\n\n/**\n * Hold a key to transmit; release it to go silent again.\n *\n * Looks like `keydown`/`keyup` and is not, because three things go wrong:\n *\n * 1. **`blur` has to release.** Alt-tabbing away while holding the key means the\n *    browser never sees the `keyup`, and the microphone stays open for as long as\n *    the person is looking at another window — exactly what push-to-talk exists\n *    to prevent.\n * 2. **Auto-repeat has to be ignored.** A held key repeats at the keyboard's rate,\n *    and without the `repeat` check `onDown` fires on every one of them.\n * 3. **A text field has to win.** Space bound to push-to-talk with the focus in an\n *    `<input>` means the space never reaches the message being written.\n *\n * Unmounting releases too, for the same reason `blur` does: the callback that\n * stops transmitting has to run even when the component holding it goes away\n * mid-press.\n *\n * The callbacks are read through a ref that a commit-time effect refreshes, so\n * passing inline arrows neither tears the listeners down on every render nor\n * writes to the ref during one — a render React discards would leave the ref\n * pointing at callbacks that never became the UI.\n *\n * @param options - See {@link UsePushToTalkOptions}.\n *\n * @example\n * usePushToTalk({\n *     code: \"Space\",\n *     onDown: () => setMicEnabled(true),\n *     onUp: () => setMicEnabled(false),\n * });\n */\nexport function usePushToTalk({\n    code = DEFAULT_PUSH_TO_TALK_KEY,\n    onDown,\n    onUp,\n    enabled = true,\n}: UsePushToTalkOptions): void {\n    const callbacks = useRef({ onDown, onUp });\n    useEffect(() => {\n        callbacks.current = { onDown, onUp };\n    });\n\n    useEffect(() => {\n        if (!enabled || typeof window === \"undefined\") return;\n        let held = false;\n\n        const release = (): void => {\n            if (!held) return;\n            held = false;\n            callbacks.current.onUp();\n        };\n\n        const handleKeyDown = (event: KeyboardEvent): void => {\n            if (event.code !== code || event.repeat) return;\n            if (isTypingTarget(event.target)) return;\n            event.preventDefault();\n            if (held) return;\n            held = true;\n            callbacks.current.onDown();\n        };\n\n        /**\n         * Release on the way up, and never mind where the keystroke landed.\n         *\n         * The field guard belongs on the way **down** — it is what stops a\n         * push-to-talk bound to Space from opening the microphone every time\n         * somebody writes a message. On the way up it did the opposite of its\n         * job: `keyup` is delivered to whatever is focused when the key rises,\n         * not to what was focused when it fell, so clicking into an input while\n         * still holding sent the release into the guard and left `held` true.\n         * The microphone stayed open until the window blurred.\n         *\n         * `held` is the guard this needs. If we never opened the microphone\n         * there is nothing to close, and `release()` already returns on that —\n         * so the only thing left to decide is `preventDefault`, which is\n         * honest only for a keystroke we actually acted on.\n         */\n        const handleKeyUp = (event: KeyboardEvent): void => {\n            if (event.code !== code || !held) return;\n            event.preventDefault();\n            release();\n        };\n\n        window.addEventListener(\"keydown\", handleKeyDown);\n        window.addEventListener(\"keyup\", handleKeyUp);\n        window.addEventListener(\"blur\", release);\n\n        return () => {\n            window.removeEventListener(\"keydown\", handleKeyDown);\n            window.removeEventListener(\"keyup\", handleKeyUp);\n            window.removeEventListener(\"blur\", release);\n            release();\n        };\n    }, [code, enabled]);\n}\n"],"mappings":";;AAsBA,IAAa,IAA8C;CACvD;EAAE,MAAM;EAAS,OAAO;CAAS;CACjC;EAAE,MAAM;EAAe,OAAO;CAAgB;CAC9C;EAAE,MAAM;EAAW,OAAO;CAAe;CACzC;EAAE,MAAM;EAAa,OAAO;CAAiB;CAC7C;EAAE,MAAM;EAAa,OAAO;CAAY;AAC5C,GAGa,IAA2B;AASxC,SAAgB,EAAmB,GAAsB;CACrD,OAAO,EAAkB,MAAM,MAAQ,EAAI,SAAS,CAAI,CAAC,EAAE,SAAS;AACxE;AAYA,SAAS,EAAe,GAAqC;CACzD,IAAI,EAAE,aAAkB,cAAc,OAAO;CAC7C,IAAI,EAAO,mBAAmB,OAAO;CACrC,IAAM,IAAM,EAAO;CACnB,OAAO,MAAQ,WAAW,MAAQ,cAAc,MAAQ;AAC5D;AAmDA,SAAgB,EAAc,EAC1B,UAAO,GACP,WACA,SACA,aAAU,MACiB;CAC3B,IAAM,IAAY,EAAO;EAAE;EAAQ;CAAK,CAAC;CAKzC,AAJA,QAAgB;EACZ,EAAU,UAAU;GAAE;GAAQ;EAAK;CACvC,CAAC,GAED,QAAgB;EACZ,IAAI,CAAC,KAAW,OAAO,SAAW,KAAa;EAC/C,IAAI,IAAO,IAEL,UAAsB;GACnB,MACL,IAAO,IACP,EAAU,QAAQ,KAAK;EAC3B,GAEM,KAAiB,MAA+B;GAC9C,EAAM,SAAS,KAAQ,EAAM,UAC7B,EAAe,EAAM,MAAM,MAC/B,EAAM,eAAe,GACjB,OACJ,IAAO,IACP,EAAU,QAAQ,OAAO;EAC7B,GAkBM,KAAe,MAA+B;GAC5C,EAAM,SAAS,KAAS,MAC5B,EAAM,eAAe,GACrB,EAAQ;EACZ;EAMA,OAJA,OAAO,iBAAiB,WAAW,CAAa,GAChD,OAAO,iBAAiB,SAAS,CAAW,GAC5C,OAAO,iBAAiB,QAAQ,CAAO,SAE1B;GAIT,AAHA,OAAO,oBAAoB,WAAW,CAAa,GACnD,OAAO,oBAAoB,SAAS,CAAW,GAC/C,OAAO,oBAAoB,QAAQ,CAAO,GAC1C,EAAQ;EACZ;CACJ,GAAG,CAAC,GAAM,CAAO,CAAC;AACtB"}

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

@@ -1,2 +1,2 @@
-const e=require("./errors.cjs");var t={offline:`Sem conexão com o servidor. Verifique sua internet e tente de novo.`,validation:`Confira os campos destacados e tente de novo.`},n=`tempest.error.offline`,r=`tempest.error.validation`;function i(){return typeof navigator<`u`&&navigator.onLine===!1}function a(n,r,a){let o=a?.offline??t.offline;if(e.isApiError(n)){let i=n.code===void 0?void 0:a?.codes?.[n.code];if(i!==void 0)return i;if(n.status===0)return o;if(n.fields&&Object.keys(n.fields).length>0)return a?.validation??t.validation;let s=n.detail.trim();return a?.useDetail!==!1&&s!==``&&s!==e.syntheticDetail(n.status)?s:`${r} (HTTP ${n.status})`}return i()?o:r}exports.API_ERROR_OFFLINE_KEY=n,exports.API_ERROR_VALIDATION_KEY=r,exports.DEFAULT_API_ERROR_STRINGS=t,exports.describeApiError=a;
+const e=require("./errors.cjs");var t={offline:`Sem conexão com o servidor. Verifique sua internet e tente de novo.`,validation:`Confira os campos destacados e tente de novo.`},n=`tempest.error.offline`,r=`tempest.error.validation`;function i(){return typeof navigator<`u`&&navigator.onLine===!1}function a(t,n,r){if(n===``||n===e.syntheticDetail(r))return!1;let i=Object.values(t);return i.length===1&&i[0].trim()===n}function o(n,r,o){let s=o?.offline??t.offline;if(e.isApiError(n)){let i=n.code===void 0?void 0:o?.codes?.[n.code];if(i!==void 0)return i;if(n.status===0)return s;let c=n.detail.trim();return n.fields&&Object.keys(n.fields).length>0?o?.useDetail!==!1&&a(n.fields,c,n.status)?c:o?.validation??t.validation:o?.useDetail!==!1&&c!==``&&c!==e.syntheticDetail(n.status)?c:`${r} (HTTP ${n.status})`}return i()?s:r}exports.API_ERROR_OFFLINE_KEY=n,exports.API_ERROR_VALIDATION_KEY=r,exports.DEFAULT_API_ERROR_STRINGS=t,exports.describeApiError=o;
 //# sourceMappingURL=describe-api-error.cjs.map

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    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     * 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 * 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 * 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 *    This step also catches a business error that named a single field, whose\n *    `detail` **was** a finished sentence (\"Cidade não encontrada para o estado\n *    informado.\"). The trade is deliberate: that sentence is now on `fields`,\n *    against the input it is about, which is where it does the most good. Three\n *    ways back, in order of preference: `codes: { VALIDATION_ERROR: \"…\" }` (step 0,\n *    which still wins), `validation: error.detail` at the call site, or reading\n *    `error.detail` yourself — it is untouched.\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        if (error.status === 0) return offline;\n        if (error.fields && Object.keys(error.fields).length > 0) {\n            return options?.validation ?? DEFAULT_API_ERROR_STRINGS.validation;\n        }\n        const detail = error.detail.trim();\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":"gCA2BA,IAAa,EAA6C,CACtD,QAAS,sEACT,WAAY,+CAChB,EAUa,EAAwB,wBAMxB,EAA2B,2BAuCxC,SAAS,GAA4B,CACjC,OAAO,OAAO,UAAc,KAAe,UAAU,SAAW,EACpE,CA+DA,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,GAAI,EAAM,SAAW,EAAG,OAAO,EAC/B,GAAI,EAAM,QAAU,OAAO,KAAK,EAAM,MAAM,CAAC,CAAC,OAAS,EACnD,OAAO,GAAS,YAAc,EAA0B,WAE5D,IAAM,EAAS,EAAM,OAAO,KAAK,EAQjC,OANI,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":[],"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     * 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 * 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        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,2BAuCxC,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,CA+EA,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,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"}

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

@@ -7,19 +7,23 @@ var n = {
 function a() {
 	return typeof navigator < "u" && navigator.onLine === !1;
 }
-function o(r, i, o) {
-	let s = o?.offline ?? n.offline;
+function o(e, n, r) {
+	if (n === "" || n === t(r)) return !1;
+	let i = Object.values(e);
+	return i.length === 1 && i[0].trim() === n;
+}
+function s(r, i, s) {
+	let c = s?.offline ?? n.offline;
 	if (e(r)) {
-		let e = r.code === void 0 ? void 0 : o?.codes?.[r.code];
+		let e = r.code === void 0 ? void 0 : s?.codes?.[r.code];
 		if (e !== void 0) return e;
-		if (r.status === 0) return s;
-		if (r.fields && Object.keys(r.fields).length > 0) return o?.validation ?? n.validation;
+		if (r.status === 0) return c;
 		let a = r.detail.trim();
-		return o?.useDetail !== !1 && a !== "" && a !== t(r.status) ? a : `${i} (HTTP ${r.status})`;
+		return r.fields && Object.keys(r.fields).length > 0 ? s?.useDetail !== !1 && o(r.fields, a, r.status) ? a : s?.validation ?? n.validation : s?.useDetail !== !1 && a !== "" && a !== t(r.status) ? a : `${i} (HTTP ${r.status})`;
 	}
-	return a() ? s : i;
+	return a() ? c : i;
 }
 //#endregion
-export { r as API_ERROR_OFFLINE_KEY, i as API_ERROR_VALIDATION_KEY, n as DEFAULT_API_ERROR_STRINGS, o as describeApiError };
+export { r as API_ERROR_OFFLINE_KEY, i as API_ERROR_VALIDATION_KEY, n as DEFAULT_API_ERROR_STRINGS, s as describeApiError };
 
 //# sourceMappingURL=describe-api-error.js.map

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    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     * 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 * 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 * 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 *    This step also catches a business error that named a single field, whose\n *    `detail` **was** a finished sentence (\"Cidade não encontrada para o estado\n *    informado.\"). The trade is deliberate: that sentence is now on `fields`,\n *    against the input it is about, which is where it does the most good. Three\n *    ways back, in order of preference: `codes: { VALIDATION_ERROR: \"…\" }` (step 0,\n *    which still wins), `validation: error.detail` at the call site, or reading\n *    `error.detail` yourself — it is untouched.\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        if (error.status === 0) return offline;\n        if (error.fields && Object.keys(error.fields).length > 0) {\n            return options?.validation ?? DEFAULT_API_ERROR_STRINGS.validation;\n        }\n        const detail = error.detail.trim();\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":";;AA2BA,IAAa,IAA6C;CACtD,SAAS;CACT,YAAY;AAChB,GAUa,IAAwB,yBAMxB,IAA2B;AAuCxC,SAAS,IAA4B;CACjC,OAAO,OAAO,YAAc,OAAe,UAAU,WAAW;AACpE;AA+DA,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,IAAI,EAAM,WAAW,GAAG,OAAO;EAC/B,IAAI,EAAM,UAAU,OAAO,KAAK,EAAM,MAAM,CAAC,CAAC,SAAS,GACnD,OAAO,GAAS,cAAc,EAA0B;EAE5D,IAAM,IAAS,EAAM,OAAO,KAAK;EAQjC,OANI,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":[],"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     * 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 * 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        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;AAuCxC,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;AA+EA,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,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"}

package/dist/http/errors.cjs

@@ -1,2 +1,2 @@
-var e=class extends Error{status;detail;code;requestId;fields;body;constructor(e){super(e.detail),this.name=`TempestApiError`,this.status=e.status,this.detail=e.detail,this.code=e.code,this.requestId=e.requestId,this.fields=e.fields,this.body=e.body}};function t(e){return typeof e==`object`&&!!e&&typeof e.status==`number`&&typeof e.detail==`string`}var n=new Set([`body`,`query`,`path`,`header`,`cookie`]);function r(e){if(!Array.isArray(e))return;let t=e.filter(e=>typeof e==`string`||typeof e==`number`).filter((e,t)=>!(t===0&&n.has(String(e))));return t.length>0?t.join(`.`):void 0}var i=4;function a(e){if(!Array.isArray(e))return;let t={};for(let n of e){if(typeof n!=`object`||!n)continue;let e=n,i=r(e.loc);if(i===void 0||i in t)continue;let a=l(e.msg)??l(e.message);a!==void 0&&(t[i]=a)}return Object.keys(t).length>0?t:void 0}function o(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:void 0}function s(e){if(e===null)return;let t=[o(e.detail)?.field,e.field,o(e.details)?.field];for(let e of t)if(typeof e==`string`&&e!==``)return e}function c(e,t){let n=a(e?.detail);if(n!==void 0)return n;let r=s(e);if(r!==void 0&&t!==void 0)return{[r]:t}}function l(e,t=0){if(e!=null){if(typeof e==`string`)return e===``?void 0:e;if(typeof e==`number`||typeof e==`boolean`)return String(e);if(!(t>=i)){if(Array.isArray(e)){let n=e.map(e=>{let n=l(e,t+1);if(n===void 0)return;let i=typeof e==`object`&&e?r(e.loc):void 0;return i===void 0?n:`${i}: ${n}`}).filter(e=>e!==void 0);return n.length>0?n.join(`; `):void 0}if(typeof e==`object`){let n=e;return l(n.msg,t+1)??l(n.message,t+1)??l(n.detail,t+1)}}}}var u=new Set([0,408,425,429]);function d(e){return u.has(e)||e>=500}function f(e){return`Erro ${e}`}function p(e,t,n,r){let i=typeof t==`object`&&t?t:null,a=l(i?.detail)??l(i?.message),o=a??f(e),s=typeof i?.code==`string`?i.code:void 0,u=typeof i?.details==`object`&&i.details!==null?i.details:null;return{status:e,detail:o,code:s,requestId:(typeof u?.request_id==`string`?u.request_id:void 0)??n?.get(`X-Request-ID`)??r??void 0??void 0,retryAfter:m(n?.get(`Retry-After`)),fields:c(i,a),body:t}}function m(e){if(!e)return;let t=e.trim();if(/^\d+$/.test(t))return Number(t);let n=Date.parse(t);if(!Number.isNaN(n))return Math.max(0,Math.round((n-Date.now())/1e3))}exports.TempestApiError=e,exports.buildApiError=p,exports.isApiError=t,exports.isRetriableStatus=d,exports.parseRetryAfter=m,exports.syntheticDetail=f;
+var e=class extends Error{status;detail;code;requestId;fields;body;constructor(e){super(e.detail),this.name=`TempestApiError`,this.status=e.status,this.detail=e.detail,this.code=e.code,this.requestId=e.requestId,this.fields=e.fields,this.body=e.body}};function t(e){return typeof e==`object`&&!!e&&typeof e.status==`number`&&typeof e.detail==`string`}var n=new Set([`body`,`query`,`path`,`header`,`cookie`]);function r(e){if(!Array.isArray(e))return;let t=e.filter(e=>typeof e==`string`||typeof e==`number`).filter((e,t)=>!(t===0&&n.has(String(e))));return t.length>0?t.join(`.`):void 0}var i=4;function a(e){if(!Array.isArray(e))return;let t={};for(let n of e){if(typeof n!=`object`||!n)continue;let e=n,i=r(e.loc);if(i===void 0||i in t)continue;let a=u(e.msg)??u(e.message);a!==void 0&&(t[i]=a)}return Object.keys(t).length>0?t:void 0}function o(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:void 0}function s(e){if(e===null)return;let t=[o(e.detail)?.field,e.field,o(e.details)?.field];for(let e of t)if(typeof e==`string`&&e!==``)return e}function c(e,t){if(e===void 0||t===void 0)return e;let n=t.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`),r=e.replace(RegExp(`\\s+for field '${n}'(?:\\s+in\\s+'[^']*')?\\.?\\s*$`),``).trim();return r===``?e:r}function l(e,t){let n=a(e?.detail);if(n!==void 0)return n;let r=s(e);if(r!==void 0&&t!==void 0)return{[r]:t}}function u(e,t=0){if(e!=null){if(typeof e==`string`)return e===``?void 0:e;if(typeof e==`number`||typeof e==`boolean`)return String(e);if(!(t>=i)){if(Array.isArray(e)){let n=e.map(e=>{let n=u(e,t+1);if(n===void 0)return;let i=typeof e==`object`&&e?r(e.loc):void 0;return i===void 0?n:`${i}: ${n}`}).filter(e=>e!==void 0);return n.length>0?n.join(`; `):void 0}if(typeof e==`object`){let n=e;return u(n.msg,t+1)??u(n.message,t+1)??u(n.detail,t+1)}}}}var d=new Set([0,408,425,429]);function f(e){return d.has(e)||e>=500}function p(e){return`Erro ${e}`}function m(e,t,n,r){let i=typeof t==`object`&&t?t:null,a=c(u(i?.detail)??u(i?.message),s(i)),o=a??p(e),d=typeof i?.code==`string`?i.code:void 0,f=typeof i?.details==`object`&&i.details!==null?i.details:null;return{status:e,detail:o,code:d,requestId:(typeof f?.request_id==`string`?f.request_id:void 0)??n?.get(`X-Request-ID`)??r??void 0??void 0,retryAfter:h(n?.get(`Retry-After`)),fields:l(i,a),body:t}}function h(e){if(!e)return;let t=e.trim();if(/^\d+$/.test(t))return Number(t);let n=Date.parse(t);if(!Number.isNaN(n))return Math.max(0,Math.round((n-Date.now())/1e3))}exports.TempestApiError=e,exports.buildApiError=m,exports.isApiError=t,exports.isRetriableStatus=f,exports.parseRetryAfter=h,exports.syntheticDetail=p;
 //# sourceMappingURL=errors.cjs.map

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 * 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 * 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 = normalizeDetail(obj?.detail) ?? normalizeDetail(obj?.message);\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":"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"}
+{"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 * 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":"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"}

package/dist/http/errors.js

@@ -33,7 +33,7 @@ function a(e) {
 		if (typeof n != "object" || !n) continue;
 		let e = n, i = r(e.loc);
 		if (i === void 0 || i in t) continue;
-		let a = l(e.msg) ?? l(e.message);
+		let a = u(e.msg) ?? u(e.message);
 		a !== void 0 && (t[i] = a);
 	}
 	return Object.keys(t).length > 0 ? t : void 0;
@@ -51,19 +51,24 @@ function s(e) {
 	for (let e of t) if (typeof e == "string" && e !== "") return e;
 }
 function c(e, t) {
+	if (e === void 0 || t === void 0) return e;
+	let n = t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), r = e.replace(RegExp(`\\s+for field '${n}'(?:\\s+in\\s+'[^']*')?\\.?\\s*$`), "").trim();
+	return r === "" ? e : r;
+}
+function l(e, t) {
 	let n = a(e?.detail);
 	if (n !== void 0) return n;
 	let r = s(e);
 	if (r !== void 0 && t !== void 0) return { [r]: t };
 }
-function l(e, t = 0) {
+function u(e, t = 0) {
 	if (e != null) {
 		if (typeof e == "string") return e === "" ? void 0 : e;
 		if (typeof e == "number" || typeof e == "boolean") return String(e);
 		if (!(t >= i)) {
 			if (Array.isArray(e)) {
 				let n = e.map((e) => {
-					let n = l(e, t + 1);
+					let n = u(e, t + 1);
 					if (n === void 0) return;
 					let i = typeof e == "object" && e ? r(e.loc) : void 0;
 					return i === void 0 ? n : `${i}: ${n}`;
@@ -72,36 +77,36 @@ function l(e, t = 0) {
 			}
 			if (typeof e == "object") {
 				let n = e;
-				return l(n.msg, t + 1) ?? l(n.message, t + 1) ?? l(n.detail, t + 1);
+				return u(n.msg, t + 1) ?? u(n.message, t + 1) ?? u(n.detail, t + 1);
 			}
 		}
 	}
 }
-var u = /* @__PURE__ */ new Set([
+var d = /* @__PURE__ */ new Set([
 	0,
 	408,
 	425,
 	429
 ]);
-function d(e) {
-	return u.has(e) || e >= 500;
-}
 function f(e) {
+	return d.has(e) || e >= 500;
+}
+function p(e) {
 	return `Erro ${e}`;
 }
-function p(e, t, n, r) {
-	let i = typeof t == "object" && t ? t : null, a = l(i?.detail) ?? l(i?.message), o = a ?? f(e), s = typeof i?.code == "string" ? i.code : void 0, u = typeof i?.details == "object" && i.details !== null ? i.details : null;
+function m(e, t, n, r) {
+	let i = typeof t == "object" && t ? t : null, a = c(u(i?.detail) ?? u(i?.message), s(i)), o = a ?? p(e), d = typeof i?.code == "string" ? i.code : void 0, f = typeof i?.details == "object" && i.details !== null ? i.details : null;
 	return {
 		status: e,
 		detail: o,
-		code: s,
-		requestId: (typeof u?.request_id == "string" ? u.request_id : void 0) ?? n?.get("X-Request-ID") ?? r ?? void 0 ?? void 0,
-		retryAfter: m(n?.get("Retry-After")),
-		fields: c(i, a),
+		code: d,
+		requestId: (typeof f?.request_id == "string" ? f.request_id : void 0) ?? n?.get("X-Request-ID") ?? r ?? void 0 ?? void 0,
+		retryAfter: h(n?.get("Retry-After")),
+		fields: l(i, a),
 		body: t
 	};
 }
-function m(e) {
+function h(e) {
 	if (!e) return;
 	let t = e.trim();
 	if (/^\d+$/.test(t)) return Number(t);
@@ -109,6 +114,6 @@ function m(e) {
 	if (!Number.isNaN(n)) return Math.max(0, Math.round((n - Date.now()) / 1e3));
 }
 //#endregion
-export { e as TempestApiError, p as buildApiError, t as isApiError, d as isRetriableStatus, m as parseRetryAfter, f as syntheticDetail };
+export { e as TempestApiError, m as buildApiError, t as isApiError, f as isRetriableStatus, h as parseRetryAfter, p as syntheticDetail };
 
 //# sourceMappingURL=errors.js.map

package/dist/http/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","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 * 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 * 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 = normalizeDetail(obj?.detail) ?? normalizeDetail(obj?.message);\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":"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"}
+{"version":3,"file":"errors.js","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 * 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":"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"}