{"_id":"@cap-antonio/frontend-incident-reporter","_rev":"5-0c1447971c124be57947abd32b346aef","name":"@cap-antonio/frontend-incident-reporter","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@cap-antonio/frontend-incident-reporter","version":"0.1.0","_id":"@cap-antonio/frontend-incident-reporter@0.1.0","maintainers":[{"name":"cap-antonio","email":"anton@mnyxlabs.com"}],"homepage":"https://github.com/cap-antonio/fe-incident-traicing#readme","bugs":{"url":"https://github.com/cap-antonio/fe-incident-traicing/issues"},"dist":{"shasum":"5117bacf1a692443419a8110dd76aa9b597e1f13","tarball":"https://registry.npmjs.org/@cap-antonio/frontend-incident-reporter/-/frontend-incident-reporter-0.1.0.tgz","fileCount":30,"integrity":"sha512-1qpY/9IA8WXasfg7R9cgXvD8MVUf91SZ5gw9f6oKPoGCk7baVK/mR/roD2pHjqFSCdr/gVa6djnuAZjVFxInag==","signatures":[{"sig":"MEYCIQCvAI8f28r4Uab/lIR1efsSzVTXPKxGpnFLvMVeiBxAhgIhAJDg1tUKRzfvBUKox3yE+/zrHQ2E2UMDCf272dCn9bjl","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43084},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.js"}},"gitHead":"d3096fb26f145ea326dd6e043996896fec42cff6","private":false,"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"cap-antonio","email":"anton@mnyxlabs.com"},"repository":{"url":"git+https://github.com/cap-antonio/fe-incident-traicing.git","type":"git"},"_npmVersion":"10.9.3","description":"Browser-first frontend companion for be-incident-tracing.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.9.2","@types/react":"^19.1.10"},"peerDependencies":{"react":">=18.0.0 || >=19.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/frontend-incident-reporter_0.1.0_1786695958267_0.32462771282606506","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cap-antonio/frontend-incident-reporter","version":"0.1.1","_id":"@cap-antonio/frontend-incident-reporter@0.1.1","maintainers":[{"name":"cap-antonio","email":"anton@mnyxlabs.com"}],"homepage":"https://github.com/cap-antonio/fe-incident-traicing#readme","bugs":{"url":"https://github.com/cap-antonio/fe-incident-traicing/issues"},"dist":{"shasum":"121b693184c36e8ca7fdf87b04efb5a8841e7c24","tarball":"https://registry.npmjs.org/@cap-antonio/frontend-incident-reporter/-/frontend-incident-reporter-0.1.1.tgz","fileCount":30,"integrity":"sha512-vlvqGAIimuRM2f/OW0Ky0UsRYpoqvyA4wmjqW4ehRF4t6F9+6e+GwvRA/Vt8DayzO0vB7IHqocF4dOisTww08g==","signatures":[{"sig":"MEUCIGfQhJKe7lIs8R2A71PNzg3Wvkz1VR2+J/OS35M5GbLlAiEAmG0Xax62FVihsbwh1SwkgEJCGN7ePxHvWgQS5kvL7HA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43340},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.js"}},"gitHead":"d3096fb26f145ea326dd6e043996896fec42cff6","private":false,"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"cap-antonio","email":"anton@mnyxlabs.com"},"repository":{"url":"git+https://github.com/cap-antonio/fe-incident-traicing.git","type":"git"},"_npmVersion":"10.9.3","description":"Browser-first frontend companion for be-incident-tracing.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.9.2","@types/react":"^19.1.10"},"peerDependencies":{"react":">=18.0.0 || >=19.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/frontend-incident-reporter_0.1.1_1786721426548_0.5037384313070774","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@cap-antonio/frontend-incident-reporter","version":"0.1.3","_id":"@cap-antonio/frontend-incident-reporter@0.1.3","maintainers":[{"name":"cap-antonio","email":"anton@mnyxlabs.com"}],"homepage":"https://github.com/cap-antonio/fe-incident-traicing#readme","bugs":{"url":"https://github.com/cap-antonio/fe-incident-traicing/issues"},"dist":{"shasum":"8c71dad5d36e47c595a84c4e0b8205c2a8bc55f0","tarball":"https://registry.npmjs.org/@cap-antonio/frontend-incident-reporter/-/frontend-incident-reporter-0.1.3.tgz","fileCount":30,"integrity":"sha512-5IgziB6r2SoEzWkB6m2b22XhpORsjwh0nQjYUzzdlrLpDyEGYW1lGi1kPROjN2tgNMUFbVxNCmyJPtV5TU/w0w==","signatures":[{"sig":"MEUCIHQXnxjJ3SSJarNtNjZr2wBQ3PSVmM7B3U8qv9CICAMUAiEAzTDbL7sb9neaSDpaXkWiq2eL6rlp05Vvupp73w/G9kM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45759},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.js"}},"gitHead":"009969350a0a6187f020a05111ab63179a46e565","private":false,"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"cap-antonio","email":"anton@mnyxlabs.com"},"repository":{"url":"git+https://github.com/cap-antonio/fe-incident-traicing.git","type":"git"},"_npmVersion":"10.9.3","description":"Browser-first frontend companion for be-incident-tracing.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.9.2","@types/react":"^19.1.10"},"peerDependencies":{"react":">=18.0.0 || >=19.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/frontend-incident-reporter_0.1.3_1787742995893_0.8453724350250598","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cap-antonio/frontend-incident-reporter","version":"0.2.0","_id":"@cap-antonio/frontend-incident-reporter@0.2.0","maintainers":[{"name":"cap-antonio","email":"anton@mnyxlabs.com"}],"homepage":"https://github.com/cap-antonio/fe-incident-traicing#readme","bugs":{"url":"https://github.com/cap-antonio/fe-incident-traicing/issues"},"dist":{"shasum":"71c0f497b1df1f2ac37c1f1fe704dba1ea49a3f5","tarball":"https://registry.npmjs.org/@cap-antonio/frontend-incident-reporter/-/frontend-incident-reporter-0.2.0.tgz","fileCount":34,"integrity":"sha512-u5ESHFlhoWnIBZAKVkIQBt+EtmTF4MIJuRNo8ANRYhwLVnT9dLOQJIEvM27tswj5yh0fBw7+NnVht8p+rQeMeA==","signatures":[{"sig":"MEQCID3FW4MBRdW38o6X14Hb8oNlsb4j6huNvs9AMHw0sOK2AiA8RzfqGdg3Jug5uF2iJ+TKmfP0Vp8mhpHYFkpNQKbTYQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":79668},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.js"}},"gitHead":"af222680095dce75046a4aeb1cdca2e0d8cec05e","private":false,"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"cap-antonio","email":"anton@mnyxlabs.com"},"repository":{"url":"git+https://github.com/cap-antonio/fe-incident-traicing.git","type":"git"},"_npmVersion":"10.9.3","description":"Browser-first frontend companion for be-incident-tracing.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.9.2","@types/react":"^19.1.10"},"peerDependencies":{"react":">=18.0.0 || >=19.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/frontend-incident-reporter_0.2.0_1787744231128_0.536822934670171","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@cap-antonio/frontend-incident-reporter","version":"0.2.1","description":"Browser-first frontend companion for be-incident-tracing.","type":"module","private":false,"publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"repository":{"type":"git","url":"git+https://github.com/cap-antonio/fe-incident-traicing.git"},"homepage":"https://github.com/cap-antonio/fe-incident-traicing#readme","bugs":{"url":"https://github.com/cap-antonio/fe-incident-traicing/issues"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.js"}},"types":"./dist/index.d.ts","sideEffects":false,"scripts":{"build":"tsc -p tsconfig.json","prepublishOnly":"npm run typecheck && npm run test && npm run build","test":"vitest run","typecheck":"tsc -p tsconfig.json --noEmit"},"peerDependencies":{"react":">=18.0.0 || >=19.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"devDependencies":{"@types/react":"^19.1.10","typescript":"^5.9.2","vitest":"^3.2.4"},"_id":"@cap-antonio/frontend-incident-reporter@0.2.1","gitHead":"38f7c34dde313df8d79261d51c03ac87085512d1","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-X8UbV/dCXe2Y7tyM7VFvznD65xexAyS7V76xYsuZwT+1fBeVSyxU67lEJkLf/n2WKWdpHVRoKstlWHlVYa3nxg==","shasum":"d3c40285327257082ddde699b0b83dad4d83a78c","tarball":"https://registry.npmjs.org/@cap-antonio/frontend-incident-reporter/-/frontend-incident-reporter-0.2.1.tgz","fileCount":35,"unpackedSize":97043,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFOHIABFBzLg1HkG1OwTMuaZJSePGJYfS7o47PkywoTSAiEA9OH2HsNAumrvJc14UemBc+ityPPLVHGnw9c2AyQjOeE="}]},"_npmUser":{"name":"cap-antonio","email":"anton@mnyxlabs.com"},"directories":{},"maintainers":[{"name":"cap-antonio","email":"anton@mnyxlabs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/frontend-incident-reporter_0.2.1_1787745866341_0.4859397709532616"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T08:25:58.060Z","modified":"2026-08-26T12:04:26.654Z","0.1.0":"2026-08-14T08:25:58.385Z","0.1.1":"2026-08-14T15:30:26.692Z","0.1.3":"2026-08-26T11:16:36.038Z","0.2.0":"2026-08-26T11:37:11.278Z","0.2.1":"2026-08-26T12:04:26.486Z"},"bugs":{"url":"https://github.com/cap-antonio/fe-incident-traicing/issues"},"homepage":"https://github.com/cap-antonio/fe-incident-traicing#readme","repository":{"type":"git","url":"git+https://github.com/cap-antonio/fe-incident-traicing.git"},"description":"Browser-first frontend companion for be-incident-tracing.","maintainers":[{"name":"cap-antonio","email":"anton@mnyxlabs.com"}],"readme":"# @cap-antonio/frontend-incident-reporter\n\nSmall browser-first frontend incident reporter.\n\nThis package is the frontend companion for [`cap-antonio/be-incident-tracing`](https://github.com/cap-antonio/be-incident-tracing). It captures browser errors and sends them to the backend incident tracing endpoint.\n\nThe core entrypoint has no React or Next.js dependency. React integration is available from `@cap-antonio/frontend-incident-reporter/react`.\n\nThe frontend error report endpoint should match the route generated from the backend Swagger/OpenAPI schema. Pass it directly in `endpoint`, or read it from your app environment variables such as `VITE_INCIDENT_API_URL` or `NEXT_PUBLIC_INCIDENT_API_URL`.\n\n## Changelog\n\n[CHANGELOG.md](./CHANGELOG.md), newest first. It ships with the package, and\n`npm test` fails when it and `package.json` disagree about the current version —\nin either direction.\n\n## Install\n\nInstall from the public npm registry:\n\n```bash\nnpm install @cap-antonio/frontend-incident-reporter\n```\n\n## Plain Browser\n\n```ts\nimport {\n createFrontendIncidentReporter,\n installFrontendIncidentHandlers,\n} from \"@cap-antonio/frontend-incident-reporter\"\n\nconst reporter = createFrontendIncidentReporter({\n endpoint: \"/api/incident-tracing/frontend-error\",\n token: \"public-incident-token\",\n release: \"2026.08.13\",\n metadata: {\n project: \"sidmaink\",\n },\n})\n\nconst cleanup = installFrontendIncidentHandlers({ reporter })\n```\n\n## React\n\n```tsx\nimport { createFrontendIncidentReporter } from \"@cap-antonio/frontend-incident-reporter\"\nimport { FrontendIncidentProvider } from \"@cap-antonio/frontend-incident-reporter/react\"\n\nconst reporter = createFrontendIncidentReporter({\n endpoint: import.meta.env.VITE_INCIDENT_API_URL ?? \"\",\n token: import.meta.env.VITE_FRONTEND_INCIDENT_TOKEN ?? \"\",\n release: import.meta.env.VITE_FRONTEND_RELEASE ?? \"\",\n})\n\nexport function App() {\n return (\n \n \n \n )\n}\n```\n\nYou can also pass `config` directly to the provider. It installs the global\nhandlers once for the life of the page and returns `children` — inline object\nprops are fine, they are read through a ref rather than through effect\ndependencies, so there is nothing to hoist into a module constant.\n\nChunk-load recovery is on by default; nothing needs to be passed for it.\n\n## Next App Router\n\nThe package does not import `next/script`. Insert the pre-hydration script app-side:\n\n```tsx\nimport Script from \"next/script\"\nimport { getFrontendIncidentBootstrapScript } from \"@cap-antonio/frontend-incident-reporter\"\n\nexport function FrontendIncidentBootstrap() {\n return (\n \n )\n}\n```\n\nThen install handlers from a client provider:\n\n```tsx\n\"use client\"\n\nimport { FrontendIncidentProvider } from \"@cap-antonio/frontend-incident-reporter/react\"\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n )\n}\n```\n\n## Error Boundary\n\n```tsx\n\"use client\"\n\nimport { useFrontendIncidentBoundary } from \"@cap-antonio/frontend-incident-reporter/react\"\n\nexport default function ErrorBoundary({\n error,\n}: {\n error: Error & { digest?: string }\n}) {\n useFrontendIncidentBoundary(error, {\n component: \"AppRouterErrorBoundary\",\n reporter,\n })\n\n return
Something went wrong.
\n}\n```\n\nThe hook recovers from a chunk-load failure first and otherwise reports the\nerror with `component`, Next's `digest` and the page description. Pass `config`\ninstead of `reporter` to have it build one, or `chunkLoadRecovery: false` to\nreport chunk failures rather than reload.\n\nTake the reporter as a prop or a module import rather than a context: Next's\n`global-error` replaces the whole document and mounts outside any provider, so a\ncontext would be empty in the one boundary that matters most.\n\n## API Notes\n\nReporter requests are sent as `POST` JSON with:\n\n- `content-type: application/json`\n- `x-incident-token: `\n- `cache: \"no-store\"`\n- `credentials: \"omit\"`\n- `keepalive: true`\n\nPayload shape:\n\n```json\n{\n \"message\": \"string\",\n \"stack\": \"string\",\n \"url\": \"string\",\n \"release\": \"string\",\n \"metadata\": {}\n}\n```\n\nNetwork/reporting failures are swallowed. Identical incidents are debounced for 60 seconds by default.\n\n### Environment metadata\n\nEvery report carries a description of the page it happened on, folded into\n`metadata`. A stack trace says where an error was thrown and nothing about the\nconditions that produced it; these fields are what turn \"Minified React error\n#418\" into a diagnosis.\n\nRead at the moment of the error:\n\n| Field | Answers |\n| -------------- | ------------------------------------------------------------------------------------------------- |\n| `readyState` | Did this happen before the document finished loading — i.e. during hydration? |\n| `uptimeMs` | Milliseconds since navigation. A crash at 300 ms and one after twenty minutes are different bugs. |\n| `viewport` | `1280x720`. Mobile-only layout failures. |\n| `visibility` | Was the tab in the background? Timers, animation frames and canvases behave differently there. |\n| `online` | The first thing to check on a failed chunk or request. |\n| `documentLang` | The language actually served. |\n\nRead once, at `DOMContentLoaded`, and reported with every incident on that page:\n\n| Field | Answers |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `htmlClass` | The `` class list, capped at 160 chars. Chrome's page translation adds `translated-ltr`; several extensions mark this element too. |\n| `fontTagCount` | Number of `` elements. Google Translate wraps every text node in one, so a non-zero count on a page that has none of its own means the document was rewritten under the app. |\n| `bodyChildCount` | Nodes appended to `` by something other than the app. |\n\nAdded when the report is sent:\n\n| Field | Answers |\n| ---------------- | ----------------------------------------------------------------------------------------------------- |\n| `language` | `navigator.language`. Against `documentLang`, this predicts whether the browser offered to translate. |\n| `connection` | `effectiveType` (`4g`, `2g`, …), where available. |\n| `navigationType` | `navigate`, `reload` or `back_forward` — a fresh load, a retry, or a restored document. |\n| `sessionId` | Random per tab, kept in `sessionStorage`. Groups several reports into one sitting. |\n| `incidentSeq` | The nth incident in that tab. In a cascade only the first one is usually real. |\n\nCounts, enums and flags only — never text from the page. A title, a heading, a\nform value or a referrer is written by the person using the app, and an incident\nchannel is not where they agreed to put it. `htmlClass` is the one string, and it\nis markup authored by the app or by an extension.\n\n#### Why the tampering fields are read at load and not at the error\n\nThe three page-tampering fields are the reason this section exists, and reading\nthem when the error fires makes them useless. A hydration mismatch is a\n_recoverable_ React error: React discards the server HTML, re-renders the subtree\nfrom scratch — deleting the nodes an extension injected and restoring the\nattributes it owns — and only then calls `onRecoverableError`, which is what puts\nthe error on `window.onerror`. By the time anything can observe the document, the\nfailure has cleaned up its own evidence. Measured live, `fontTagCount` reads zero\non a page that was fully translated a millisecond earlier. That was observed, not\ntheorised.\n\nSo the bootstrap script takes the baseline once, at `DOMContentLoaded` — after the\nparser has finished and after any extension that runs at document-end has had its\nturn, but before the app's bundle executes. **Without the bootstrap script there\nis no such moment**: the package falls back to a reading taken when the first\nincident is built, which is already after hydration. A Next app that wants a real\nanswer here has to render `getFrontendIncidentBootstrapScript()`.\n\nErrors thrown before hydration are queued and only sent once the app has loaded,\nso their `readyState`, `uptimeMs` and `visibility` are captured at push time too.\nThe queued values always win over the live reading.\n\nTurn it off, or replace the collector:\n\n```ts\ncreateFrontendIncidentReporter({ endpoint, token, environment: false })\n\ncreateFrontendIncidentReporter({\n endpoint,\n token,\n environment: () => ({\n ...collectIncidentEnvironment(),\n tenant: currentTenantId(),\n }),\n})\n```\n\nThe snapshot and the baseline add about 930 bytes to the inline bootstrap script,\nroughly 280 after gzip. Pass\n`getFrontendIncidentBootstrapScript({ environment: false })` to leave both out.\n\nSensitive query params are redacted in reported URLs:\n\n- `token`\n- `access_token`\n- `refresh_token`\n- `id_token`\n- `password`\n- `authorization`\n- `auth`\n\nAdd params:\n\n```ts\ncreateFrontendIncidentReporter({\n endpoint,\n token,\n sensitiveQueryParams: [\"session_id\"],\n})\n```\n\nReplace the default list:\n\n```ts\ncreateFrontendIncidentReporter({\n endpoint,\n token,\n sensitiveQueryParams: [\"session_id\"],\n sensitiveQueryParamMode: \"replace\",\n})\n```\n\nChunk-load recovery reloads once per path and chunk error signature using `sessionStorage`. The cache-busting query param defaults to `__frontend_chunk_reload` and can be changed with `queryParam`.\n\nRecovery runs before every report — global `error`, `unhandledrejection`, drained\nbootstrap incidents, and `useFrontendIncidentBoundary`. If it starts a reload, the\nincident is not reported. If the same failure repeats after the one-time guard, it\nis reported normally.\n\nIt is **on by default**, and was opt-in before 0.2.1. A stale document is not\nsomething anyone can act on, so an incident channel full of `Loading chunk … failed`\nis an incident channel people stop reading. Pass `chunkLoadRecovery: false` to\nreport them instead.\n\nLeave the options at their defaults unless every entry point changes together: the\none-reload guard is keyed by `storageKeyPrefix` and the path, so a boundary with a\nprefix of its own gets a reload of its own and the guard stops meaning anything.\n","readmeFilename":"README.md"}