@starko-one/sdk 0.0.0-stage → 0.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +248 -0
  2. package/LICENSE +17 -0
  3. package/NOTICE +58 -0
  4. package/README.md +81 -2
  5. package/dist/api-BAFm4Lxj.d.ts +558 -0
  6. package/dist/api-DNrctwJu.d.cts +558 -0
  7. package/dist/browser/index.cjs +168 -0
  8. package/dist/browser/index.d.cts +131 -0
  9. package/dist/browser/index.d.ts +131 -0
  10. package/dist/browser/index.js +7 -0
  11. package/dist/build/rollup.cjs +22 -0
  12. package/dist/build/rollup.d.cts +34 -0
  13. package/dist/build/rollup.d.ts +34 -0
  14. package/dist/build/rollup.js +3 -0
  15. package/dist/build/vite.cjs +51 -0
  16. package/dist/build/vite.d.cts +23 -0
  17. package/dist/build/vite.d.ts +23 -0
  18. package/dist/build/vite.js +46 -0
  19. package/dist/build/webpack.cjs +18 -0
  20. package/dist/build/webpack.d.cts +39 -0
  21. package/dist/build/webpack.d.ts +39 -0
  22. package/dist/build/webpack.js +3 -0
  23. package/dist/chunk-2PM4FRM5.cjs +431 -0
  24. package/dist/chunk-335HNCOJ.js +249 -0
  25. package/dist/chunk-3AW5B2WW.js +115 -0
  26. package/dist/chunk-3R5TQAWD.js +216 -0
  27. package/dist/chunk-6H5MOPTQ.cjs +1230 -0
  28. package/dist/chunk-7TKNT3QJ.cjs +2487 -0
  29. package/dist/chunk-A4WLNFMU.cjs +220 -0
  30. package/dist/chunk-ALYFFOPR.cjs +134 -0
  31. package/dist/chunk-BVVFVRMO.js +1113 -0
  32. package/dist/chunk-CIHNKN62.cjs +15 -0
  33. package/dist/chunk-CMGCH6HD.js +1212 -0
  34. package/dist/chunk-D6QAPQ7L.cjs +56 -0
  35. package/dist/chunk-DUO5V6WZ.js +213 -0
  36. package/dist/chunk-EC2WZ6PG.js +90 -0
  37. package/dist/chunk-EFURLFJT.cjs +187 -0
  38. package/dist/chunk-EROUORMY.js +53 -0
  39. package/dist/chunk-LXBXFOAP.cjs +96 -0
  40. package/dist/chunk-MF6SA6DB.js +563 -0
  41. package/dist/chunk-N5R6ORIB.js +413 -0
  42. package/dist/chunk-N6R6BWHK.cjs +142 -0
  43. package/dist/chunk-QAGGN2T7.cjs +225 -0
  44. package/dist/chunk-QV4HRIDD.cjs +659 -0
  45. package/dist/chunk-TKNDYQB3.cjs +583 -0
  46. package/dist/chunk-UI5YC4TH.js +131 -0
  47. package/dist/chunk-VEHZYLK6.cjs +1151 -0
  48. package/dist/chunk-VNCWOGTI.js +12 -0
  49. package/dist/chunk-VWNIOGE6.js +180 -0
  50. package/dist/chunk-WDKRKGYF.js +608 -0
  51. package/dist/chunk-XOZIXBUK.js +2462 -0
  52. package/dist/chunk-ZS3K3SDR.cjs +258 -0
  53. package/dist/cli/index.cjs +2780 -0
  54. package/dist/common-DLFAqL2d.d.cts +36 -0
  55. package/dist/common-DbSXkaw6.d.ts +36 -0
  56. package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
  57. package/dist/dedupe-DoYiSx-9.d.ts +13 -0
  58. package/dist/handler-BcnsnvhF.d.cts +82 -0
  59. package/dist/handler-qHzilC9T.d.ts +82 -0
  60. package/dist/index.cjs +309 -0
  61. package/dist/index.d.cts +187 -0
  62. package/dist/index.d.ts +187 -0
  63. package/dist/index.js +4 -0
  64. package/dist/next/client.cjs +113 -0
  65. package/dist/next/client.d.cts +26 -0
  66. package/dist/next/client.d.ts +26 -0
  67. package/dist/next/client.js +41 -0
  68. package/dist/next/config.cjs +277 -0
  69. package/dist/next/config.d.cts +193 -0
  70. package/dist/next/config.d.ts +193 -0
  71. package/dist/next/config.js +263 -0
  72. package/dist/next/index.cjs +148 -0
  73. package/dist/next/index.d.cts +32 -0
  74. package/dist/next/index.d.ts +32 -0
  75. package/dist/next/index.js +59 -0
  76. package/dist/node/index.cjs +257 -0
  77. package/dist/node/index.d.cts +145 -0
  78. package/dist/node/index.d.ts +145 -0
  79. package/dist/node/index.js +83 -0
  80. package/dist/options-BUhWuWJX.d.cts +79 -0
  81. package/dist/options-BUhWuWJX.d.ts +79 -0
  82. package/dist/react/index.cjs +107 -0
  83. package/dist/react/index.d.cts +84 -0
  84. package/dist/react/index.d.ts +84 -0
  85. package/dist/react/index.js +103 -0
  86. package/dist/scope-D1ouJm2h.d.cts +628 -0
  87. package/dist/scope-D1ouJm2h.d.ts +628 -0
  88. package/dist/server-edge-7624N3WF.cjs +51 -0
  89. package/dist/server-edge-BEEXWL7T.js +48 -0
  90. package/dist/server-node-ET4LIPEC.cjs +27 -0
  91. package/dist/server-node-TQUVMZUC.js +24 -0
  92. package/dist/session-C_WzbEN2.d.cts +4 -0
  93. package/dist/session-C_WzbEN2.d.ts +4 -0
  94. package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
  95. package/dist/session-propagation-RM5py1bp.d.ts +30 -0
  96. package/dist/starko.min.js +6 -0
  97. package/docs/browser.md +386 -0
  98. package/docs/configuration.md +310 -0
  99. package/docs/nextjs.md +488 -0
  100. package/docs/node.md +427 -0
  101. package/docs/other-backends.md +232 -0
  102. package/docs/privacy.md +112 -0
  103. package/docs/react.md +187 -0
  104. package/docs/source-maps.md +482 -0
  105. package/docs/troubleshooting.md +263 -0
  106. package/docs/widget.md +84 -0
  107. package/docs/wire-format.md +547 -0
  108. package/package.json +191 -4
@@ -0,0 +1,310 @@
1
+ # Configuration reference
2
+
3
+ Every option of every entry point, with its default, and every integration.
4
+ The tables are checked against the source by a test, so an option missing
5
+ here, or listed here but not in the code, fails the build.
6
+
7
+ - [Browser and `next/client`](#browser-and-nextclient)
8
+ - [Node.js](#nodejs)
9
+ - [Next.js server: `register`](#nextjs-server-register)
10
+ - [Build plugins and `withStarko`](#build-plugins-and-withstarko)
11
+ - [Environment variables](#environment-variables)
12
+ - [Integrations](#integrations)
13
+ - [Adding and removing integrations](#adding-and-removing-integrations)
14
+
15
+ ## Browser and `next/client`
16
+
17
+ `init` from `@starko-one/sdk/browser`, `@starko-one/sdk/next/client` and the
18
+ script-tag bundle.
19
+
20
+ <!-- options: BrowserOptions -->
21
+ | Option | Type | Default | Meaning |
22
+ | --- | --- | --- | --- |
23
+ | `workspaceKey` | `string` | required | Workspace key (public): the workspace id shown in Starko under Settings. Without it the SDK does not start. |
24
+ | `host` | `string` | `"https://v2.starko.one"` | Starko host. Must answer without redirecting. |
25
+ | `release` | `string` | the release a build plugin wrote into the bundle, if any (read for each event) | Version of your app. Use the release the source maps were uploaded for. |
26
+ | `environment` | `string` | none | `production`, `staging`, `preview`, … Not `NODE_ENV` on a host with preview deployments: it is `production` there too ([nextjs.md](./nextjs.md#environment-production-or-preview)). |
27
+ | `enabled` | `boolean` | `true` | `false`: install nothing, capture nothing. |
28
+ | `debug` | `boolean` | `false` | Log what the SDK does (and its own failures) to the console. |
29
+ | `sampleRate` | `number` | `1` | Share of events sent, 0 to 1. Multiplied by the workspace's remote sample rate. |
30
+ | `maxBreadcrumbs` | `number` | `50` | Breadcrumbs kept. At most 50. |
31
+ | `beforeSend` | `(event, hint) => event \| null \| Promise<event \| null>` | none | Last step before an event is queued. Return `null` to drop it. If it throws, the event is dropped. |
32
+ | `beforeSendTimeoutMs` | `number` | `5000` | An async `beforeSend` that has not settled after this many ms is abandoned and its event dropped. |
33
+ | `beforeBreadcrumb` | `(breadcrumb, hint?) => breadcrumb \| null` | none | Edit a breadcrumb, or return `null` to drop it, before it is stored. |
34
+ | `ignoreErrors` | `Array<string \| RegExp>` | `[]` | Drop events whose `Type: message` or message contains a string or matches a RegExp. |
35
+ | `allowUrls` | `Array<string \| RegExp>` | `[]` (no restriction) | Only send events whose most recent frame's file matches one of these. |
36
+ | `denyUrls` | `Array<string \| RegExp>` | `[]` | Drop events whose most recent frame's file matches one of these. |
37
+ | `integrations` | `Integration[] \| (defaults) => Integration[]` | none | An array is added to the defaults (an integration with a default's name replaces it). A function receives the defaults and returns the list to use. |
38
+ | `defaultIntegrations` | `false \| Integration[]` | the browser defaults | `false`: no default integrations. An array replaces the defaults. |
39
+ | `transport` | `(options) => Transport` | the `fetch` transport | Custom transport factory (tests, proxies). |
40
+ | `remoteConfig` | `boolean` | `true` | Read the workspace's remote config at `init`; events wait for it (at most 30, at most 10 s). |
41
+ | `user` | `{ id?, email?, name? } \| null` | none | The signed-in user at start. |
42
+ | `userHash` | `string` | none | The user hash for `user` (applied only together with `user`). See [browser.md](./browser.md#identify-the-user). |
43
+ | `maxEventsPerLifetime` | `number` | `100` | Events sent per page load. |
44
+ | `maxEventsPerMinute` | `number` | none | Events sent in any 60 s, all error types together. |
45
+ | `maxQueueSize` | `number` | `100` | Events waiting in memory; past it the oldest are dropped. |
46
+ | `flushInterval` | `number` | `1000` | Milliseconds before a partial batch is sent. |
47
+ | `requestTimeoutMs` | `number` | `12000` | A request to Starko not answered after this many ms is aborted and retried as a network failure. |
48
+
49
+ `next/client`'s `init` takes the same options and adds `NextControlFlow` to
50
+ the defaults.
51
+
52
+ ## Node.js
53
+
54
+ `init` from `@starko-one/sdk/node`.
55
+
56
+ <!-- options: NodeOptions -->
57
+ | Option | Type | Default | Meaning |
58
+ | --- | --- | --- | --- |
59
+ | `workspaceKey` | `string` | required | Workspace key (public). Without it the SDK does not start. |
60
+ | `apiKey` | `string` | none | Secret key (`sk_starko_…`) with the `errors:write` scope. Starko then trusts the `user.id` your server sets. Never in a browser. See [node.md](./node.md#the-secret-key-apikey). |
61
+ | `host` | `string` | `"https://v2.starko.one"` | Starko host. Must answer without redirecting. |
62
+ | `release` | `string` | `STARKO_RELEASE`, then the release a build plugin wrote into the bundle (read for each event) | Version of your app. |
63
+ | `environment` | `string` | none | `production`, `staging`, `preview`, … Not `NODE_ENV` on a host with preview deployments: it is `production` there too ([nextjs.md](./nextjs.md#environment-production-or-preview)). |
64
+ | `serverName` | `string` | the host name (`os.hostname()`) | `server_name` on every event. |
65
+ | `enabled` | `boolean` | `true` | `false`: install nothing, capture nothing. |
66
+ | `debug` | `boolean` | `false` | Log what the SDK does to the console. |
67
+ | `sampleRate` | `number` | `1` | Share of events sent, 0 to 1. Multiplied by the workspace's remote sample rate. |
68
+ | `maxBreadcrumbs` | `number` | `50` | Breadcrumbs kept. At most 50. |
69
+ | `beforeSend` | `(event, hint) => event \| null \| Promise<event \| null>` | none | Last step before an event is queued. Runs after source lines are added. If it throws, the event is dropped. |
70
+ | `beforeSendTimeoutMs` | `number` | `5000` | An async `beforeSend` (or the source-line read before it) not settled after this many ms is abandoned and its event dropped. |
71
+ | `beforeBreadcrumb` | `(breadcrumb, hint?) => breadcrumb \| null` | none | Edit or drop a breadcrumb before it is stored. |
72
+ | `ignoreErrors` | `Array<string \| RegExp>` | `[]` | Drop events whose `Type: message` or message contains a string or matches a RegExp. |
73
+ | `allowUrls` | `Array<string \| RegExp>` | `[]` (no restriction) | Only send events whose most recent frame's file path matches one of these. |
74
+ | `denyUrls` | `Array<string \| RegExp>` | `[]` | Drop events whose most recent frame's file path matches one of these. |
75
+ | `integrations` | `Integration[] \| (defaults) => Integration[]` | none | As in the browser. |
76
+ | `defaultIntegrations` | `false \| Integration[]` | the Node defaults | `false`: none. An array replaces the defaults. |
77
+ | `transport` | `(options) => Transport` | `node:http` / `node:https` | Custom transport factory. |
78
+ | `fetch` | `typeof fetch` | none | Send with this `fetch` instead of `node:http(s)` (a proxy). A request in flight then keeps the process alive until it ends (at most 10 s). |
79
+ | `remoteConfig` | `boolean` | `true` | Read the workspace's remote config just before the first send (an idle process makes no request). Exit-time flushes do not wait for it. |
80
+ | `user` | `{ id?, email?, name? } \| null` | none | A user for the whole process. |
81
+ | `userHash` | `string` | none | The user hash for `user` (applied only together with `user`). |
82
+ | `maxEventsPerLifetime` | `number` | none | Events sent over the life of the process. |
83
+ | `maxEventsPerMinute` | `number` | `300` | Events sent in any 60 s, all error types together. |
84
+ | `maxQueueSize` | `number` | `500` | Events waiting in memory; past it the oldest are dropped. |
85
+ | `flushInterval` | `number` | `1000` | Milliseconds before a partial batch is sent. |
86
+ | `requestTimeoutMs` | `number` | `10000` | A request not finished after this many ms is aborted and retried as a network failure. Connecting has its own 3 s limit. |
87
+ | `shutdownTimeout` | `number` | `2000` | Longest wait, in ms, for queued events when the event loop empties and on `SIGTERM` / `SIGINT` (without an app handler). `close(timeout)` and `flush(timeout)` take their own timeout (default 2000 ms). |
88
+ | `fatalFlushTimeout` | `number` | `1000` | Longest wait, in ms, for the crash event before the process exits after an uncaught error. |
89
+
90
+ ## Next.js server: `register`
91
+
92
+ `register` from `@starko-one/sdk/next` takes every [Node.js](#nodejs)
93
+ option, plus:
94
+
95
+ <!-- options: NextServerOptions - NodeOptions -->
96
+ | Option | Type | Default | Meaning |
97
+ | --- | --- | --- | --- |
98
+ | `flushTimeout` | `number` | `2000` | Longest background flush, in ms, that `onRequestError` hands to the platform's `waitUntil`. Without `waitUntil` on a serverless platform the hook waits at most the smaller of this and 500 ms. |
99
+
100
+ On the Edge runtime the same options are accepted, with these differences:
101
+ `STARKO_RELEASE` is not read, `defaultIntegrations` as an array is ignored,
102
+ `serverName`, `shutdownTimeout` and `fatalFlushTimeout` have no effect (there
103
+ is no host name, no process hooks), and requests are sent with the runtime's
104
+ `fetch`.
105
+
106
+ ## Build plugins and `withStarko`
107
+
108
+ `starkoVitePlugin(options)` (`@starko-one/sdk/vite`),
109
+ `starkoRollupPlugin(options)` (`@starko-one/sdk/rollup`),
110
+ `new StarkoWebpackPlugin(options)` (`@starko-one/sdk/webpack`) and
111
+ `withStarko(nextConfig, options)` (`@starko-one/sdk/next/config`).
112
+
113
+ <!-- options: StarkoWebpackPluginOptions -->
114
+ | Option | Type | Default | Meaning |
115
+ | --- | --- | --- | --- |
116
+ | `apiKey` | `string` | `STARKO_API_KEY` | Secret key with the `sourcemaps:write` scope. Without one nothing is changed and a warning is printed once. |
117
+ | `host` | `string` | `STARKO_HOST`, then `"https://v2.starko.one"` | Starko host. |
118
+ | `release` | `string` | `STARKO_RELEASE`, the CI commit, `git rev-parse HEAD` | Release of this build, also written into the bundles for `init`. |
119
+ | `enabled` | `boolean` | production builds only | Vite: `vite build` in production mode, not watch. Rollup: not in watch mode or with `NODE_ENV=development`. webpack: `mode: "production"`. `withStarko`: `next build`. |
120
+ | `deleteSourcemapsAfterUpload` | `boolean` | not set | `true`: delete every map after the upload attempt. Not set or `false`: keep the maps your config asked for. Maps the integration switched on are deleted in every case. See [the table](./source-maps.md#which-maps-are-deleted). |
121
+ | `include` | `string \| RegExp \| Array<string \| RegExp>` | every `.js`, `.mjs` and `.cjs` file | Bundles to process: globs (`*`, `**`, `?`) or RegExps, matched against the path relative to the output directory. |
122
+ | `exclude` | `string \| RegExp \| Array<string \| RegExp>` | `"**/node_modules/**"` | Bundles to skip. |
123
+ | `dryRun` | `boolean` | `false` | Inject, then log what would be uploaded without sending. Maps the integration switched on are still deleted. |
124
+ | `silent` | `boolean` | `false` | No logging. |
125
+ | `failOnError` | `boolean` | `false` | Fail the build when the upload fails. By default a failed upload warns and the build succeeds. |
126
+ | `uploadTimeoutMs` | `number` | `180000` | Deadline for the whole upload, in ms. When it passes the upload stops with a warning saying how far it got, and the build goes on; the next build sends only what is still missing. See [large builds](#large-builds). |
127
+ | `uploadConcurrency` | `number` | `16` with the bulk upload, `8` with v1 | Source maps sent at the same time, 1 to 16 (larger values are clamped): uploads to Starko's storage with the bulk upload, maps sent through the Starko host with v1. |
128
+ | `uploadProtocol` | `"auto" \| "bulk" \| "v1"` | `"auto"` | How maps are sent. `"auto"`: straight to Starko's storage through short-lived signed URLs (the bulk upload) when the server offers it, else through the Starko host (v1), decided once per upload and said in one log line; when uploads to the storage host keep failing (a proxy or firewall), every map not uploaded yet goes through v1 (the server lets v1 take over the ones already reserved), with a warning naming the host. `"bulk"`: never v1 (the upload fails instead). `"v1"`: never contacts the storage host. See [large builds](./source-maps.md#large-builds). |
129
+ | `upload` | `boolean` | `true` | webpack only: `false` injects without uploading (and deletes nothing), when something else uploads. |
130
+
131
+ ### Large builds
132
+
133
+ With the bulk upload (the default when the server offers it) each map
134
+ goes from the build straight to Starko's storage, so the build machine
135
+ must be able to reach the storage host as well as the Starko host. The
136
+ first upload of an app with thousands of source maps (a large Next.js app
137
+ has 5,000 or more) can still take longer than the default 3 minutes. When
138
+ the deadline passes, the build goes on and the log says how many maps were
139
+ uploaded, how many the server already had and how many were not sent; the
140
+ next build continues from there, since a completed map is never sent
141
+ again. After that first upload a build sends only the chunks that changed,
142
+ which takes seconds. A long upload prints its progress every 30 seconds.
143
+
144
+ To catch up in one build, raise `uploadTimeoutMs` (for example
145
+ `30 * 60_000`, within your host's build time limit). With v1, also raise
146
+ `uploadConcurrency` (up to `16`). With the bulk upload `uploadConcurrency`
147
+ is already at its most, and the speed of a first upload is set by how
148
+ fast Starko verifies maps (6 of a workspace's maps at a time) and how fast
149
+ the build machine reaches storage. Each request to Starko waits for its
150
+ route's longest run on the server plus 15 s (up to 135 s for
151
+ `bulk/finish`), so a slow answer is not mistaken for a lost connection.
152
+ Details and measurements: [source-maps.md](./source-maps.md#large-builds).
153
+
154
+ ## Environment variables
155
+
156
+ The SDK reads only these. Everything else is an option you pass.
157
+
158
+ | Variable | Read by | Meaning |
159
+ | --- | --- | --- |
160
+ | `STARKO_API_KEY` | the build plugins, `withStarko`, the CLI | Secret key with the `sourcemaps:write` scope, for the source-map upload. The runtime `apiKey` option of `init` and `register` is **not** read from it: pass `apiKey: process.env.STARKO_API_KEY` (or another variable) yourself. |
161
+ | `STARKO_HOST` | the build plugins, `withStarko`, the CLI | Where source maps are uploaded. Only there: the runtime `host` option of `init` (browser and Node), `register` and the script tag's `data-host` has **no** environment variable. Pass it yourself where it is not the default, for example `host: process.env.NEXT_PUBLIC_STARKO_HOST` in both Next.js instrumentation files. |
162
+ | `STARKO_RELEASE` | the build plugins, `withStarko`, the CLI; Node's `init` and Next's `register` on the Node.js runtime, at run time | The release, when none is passed. The browser and the Edge runtime do not read it. |
163
+ | `STARKO_BUILD_RELEASE` | `@starko-one/sdk/next`, `/next/client` | Written into your Next config's `env` by `withStarko`; you do not set it (see [nextjs.md](./nextjs.md#releases)). |
164
+
165
+ Nothing reads a workspace key or an `environment` from the environment.
166
+ To configure them per deployment, see
167
+ [nextjs.md](./nextjs.md#configure-it-from-environment-variables).
168
+
169
+ ## Integrations
170
+
171
+ An integration is an object with a `name` and hooks the SDK calls. The
172
+ defaults are installed by `init`; the factories below are exported so you
173
+ can configure one, add one that is not a default, or build your own list.
174
+
175
+ ### Browser (`@starko-one/sdk/browser`)
176
+
177
+ | Name | Factory | Default | What it does |
178
+ | --- | --- | --- | --- |
179
+ | `InboundFilters` | `inboundFiltersIntegration()` | yes | Drops noise: empty errors, cross-origin `Script error.`, browser extensions, `ResizeObserver` loops, aborted requests, network failures, errors inside Starko's own scripts. |
180
+ | `Dedupe` | `dedupeIntegration(options)` | yes | Drops an event identical to the one just before it: same exception types, messages and frames, fingerprint, user and session. |
181
+ | `GlobalHandlers` | `globalHandlersIntegration({ onerror, onunhandledrejection })` | yes | Captures uncaught errors and unhandled rejections (window listeners; `window.onerror` and other listeners keep running). |
182
+ | `Breadcrumbs` | `breadcrumbsIntegration({ console, dom, fetch, xhr, history })` | yes | Records clicks, navigation, `fetch`/XHR and console warnings and errors. |
183
+ | `HttpContext` | `httpContextIntegration()` | yes | Adds the page URL and referrer. |
184
+ | `WidgetBridge` | `widgetBridgeIntegration()` | yes | Meets the Starko widget: shared session id, the widget's customer token, telling the widget the SDK captures errors. See [widget.md](./widget.md). |
185
+ | `SessionPropagation` | `sessionPropagationIntegration()` | yes | Adds `x-starko-session-id` to same-origin `fetch` and XHR requests, so server errors link to this session. |
186
+ | `ConsoleErrorCapture` | `consoleErrorCaptureIntegration({ whenWidget })` | yes, with `whenWidget: true` | Captures `Error` objects passed to `console.error`. As a default, only while the Starko widget is on the page; added without options, always. |
187
+ | `FlushOnHide` | `flushOnHideIntegration()` | always added | Sends the queue with `keepalive` when the page is hidden; resumes sending when the browser comes back online. Added even with `defaultIntegrations: false`. |
188
+
189
+ `next/client` adds `NextControlFlow` (`nextControlFlowIntegration()`), which
190
+ drops Next's `redirect()`, `notFound()`, `forbidden()`, `unauthorized()` and
191
+ bail-outs.
192
+
193
+ Options of the configurable ones:
194
+
195
+ <!-- options: BreadcrumbsOptions -->
196
+ | Option | Type | Default | Meaning |
197
+ | --- | --- | --- | --- |
198
+ | `console` | `boolean` | `true` | `console.warn` and `console.error`. |
199
+ | `dom` | `boolean` | `true` | Clicks. |
200
+ | `fetch` | `boolean` | `true` | `fetch` requests. |
201
+ | `xhr` | `boolean` | `true` | `XMLHttpRequest` requests. |
202
+ | `history` | `boolean` | `true` | `pushState`, `replaceState` and back/forward. |
203
+
204
+ <!-- options: GlobalHandlersOptions -->
205
+ | Option | Type | Default | Meaning |
206
+ | --- | --- | --- | --- |
207
+ | `onerror` | `boolean` | `true` | Uncaught errors (the window `error` event). |
208
+ | `onunhandledrejection` | `boolean` | `true` | Unhandled promise rejections. |
209
+
210
+ ### Node.js (`@starko-one/sdk/node`)
211
+
212
+ | Name | Factory | Default | What it does |
213
+ | --- | --- | --- | --- |
214
+ | `Dedupe` | `dedupeIntegration(options)` | yes | Drops an event identical to the one just before it: same exception types, messages and frames, fingerprint, user and session, and the same request. The same failure for two customers, or in two requests, is two events. |
215
+ | `HttpServer` | `httpServerIntegration()` | yes | Gives every request of a `node:http`, `node:https` or `node:http2` server its own scope. Removing it removes the automatic isolation. |
216
+ | `OnUncaughtException` | `onUncaughtExceptionIntegration()` | yes | Captures uncaught exceptions; exits like Node when the app has no listener of its own. |
217
+ | `OnUnhandledRejection` | `onUnhandledRejectionIntegration({ mode })` | yes | Captures unhandled rejections without changing what Node does with them. |
218
+ | `RequestData` | `requestDataIntegration()` | yes | Adds the request's method, URL and route. |
219
+ | `NodeContext` | `nodeContextIntegration()` | yes | Adds the Node version, the OS and `server_name`. |
220
+ | `ConsoleBreadcrumbs` | `consoleBreadcrumbsIntegration()` | yes | Records `console.warn` and `console.error` as breadcrumbs (text, 200 characters). |
221
+ | `ContextLines` | `contextLinesIntegration(options)` | yes | Adds source lines around in-app frames. See [node.md](./node.md#source-lines). |
222
+ | `FlushOnExit` | `flushOnExitIntegration({ signals })` | yes | Sends queued events when the event loop empties and on `SIGTERM` / `SIGINT` without an app handler. |
223
+
224
+ `@starko-one/sdk/next`'s `register` adds `NextControlFlow` on both
225
+ runtimes. On the Edge runtime the defaults are only `Dedupe`, `RequestData`
226
+ and `NextControlFlow`.
227
+
228
+ <!-- options: ContextLinesOptions -->
229
+ | Option | Type | Default | Meaning |
230
+ | --- | --- | --- | --- |
231
+ | `lines` | `number` | `7` | Lines before and after the frame's line (at most 7). |
232
+ | `includeNodeModules` | `boolean` | `false` | Also read files under `node_modules`. |
233
+ | `roots` | `string[]` | `[]` | Directories besides the application root whose files may be read (a monorepo's packages). A filesystem root (`/`) is ignored. |
234
+ | `maxFileBytes` | `number` | `1048576` | Larger files are not read. |
235
+ | `maxFiles` | `number` | `10` | Distinct files read per event. |
236
+ | `cacheSize` | `number` | `100` | Files kept in the cache. |
237
+ | `cacheBytes` | `number` | `8388608` | Bytes of source text kept in the cache. |
238
+
239
+ <!-- options: DedupeOptions -->
240
+ | Option | Type | Default | Meaning |
241
+ | --- | --- | --- | --- |
242
+ | `requestKey` | `() => unknown` | none | Returns the identity of the request the current event belongs to, compared with `===`: events of different requests are never duplicates. The Node and Next.js defaults compare the current request scope. A `dedupeIntegration()` you create yourself compares requests only through a `requestKey` you pass: use `dedupeIntegration({ requestKey: currentRequestKey })`, with `currentRequestKey` from `@starko-one/sdk/node` or `/next`, to keep the default. |
243
+
244
+ <!-- options: FlushOnExitOptions -->
245
+ | Option | Type | Default | Meaning |
246
+ | --- | --- | --- | --- |
247
+ | `signals` | `boolean` | `true` | Flush on `SIGTERM` / `SIGINT` when the app does not listen for them. |
248
+
249
+ <!-- options: OnUnhandledRejectionOptions -->
250
+ | Option | Type | Default | Meaning |
251
+ | --- | --- | --- | --- |
252
+ | `mode` | `"throw" \| "strict" \| "warn" \| "warn-with-error-code" \| "none"` | read from `--unhandled-rejections` in `process.execArgv` and `NODE_OPTIONS`, else `"throw"` | Override the mode the SDK assumes. Meant for tests. |
253
+
254
+ ### Request helpers
255
+
256
+ <!-- options: WrapHandlerOptions -->
257
+ | `wrapHandler` option | Type | Default | Meaning |
258
+ | --- | --- | --- | --- |
259
+ | `flushTimeout` | `number` | `2000` | Longest wait, in ms, for queued events after each call. |
260
+ | `getRequestData` | `(...args) => { method?, url?, route?, sessionId? } \| undefined` | the first argument, when it is a request | Request data for a call whose first argument is not a request. |
261
+
262
+ <!-- options: ExpressErrorHandlerOptions -->
263
+ | `expressErrorHandler` option | Type | Default | Meaning |
264
+ | --- | --- | --- | --- |
265
+ | `shouldHandleError` | `(error) => boolean` | status 500 or more, or no status | Whether to capture an error. |
266
+
267
+ ## Adding and removing integrations
268
+
269
+ Remove a default by name:
270
+
271
+ ```ts
272
+ import * as Starko from "@starko-one/sdk/browser";
273
+
274
+ Starko.init({
275
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
276
+ integrations: (defaults) => defaults.filter((integration) => integration.name !== "SessionPropagation"),
277
+ });
278
+ ```
279
+
280
+ Configure a default by passing your own instance: an integration with the
281
+ same name as a default replaces it, in the default's place.
282
+
283
+ ```ts
284
+ import * as Starko from "@starko-one/sdk/node";
285
+ import { contextLinesIntegration, flushOnExitIntegration } from "@starko-one/sdk/node";
286
+
287
+ Starko.init({
288
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
289
+ integrations: [contextLinesIntegration({ roots: ["../shared"] }), flushOnExitIntegration({ signals: false })],
290
+ });
291
+ ```
292
+
293
+ Write your own: an object with a `name` and any of `setup(client)`,
294
+ `processEvent(event, hint, client)` (return `null` to drop the event) and
295
+ `teardown()`.
296
+
297
+ ```ts
298
+ import * as Starko from "@starko-one/sdk/browser";
299
+ import type { Integration } from "@starko-one/sdk/browser";
300
+
301
+ const tenantTag: Integration = {
302
+ name: "TenantTag",
303
+ processEvent(event) {
304
+ event.tags = { ...event.tags, tenant: document.documentElement.dataset.tenant ?? "unknown" };
305
+ return event;
306
+ },
307
+ };
308
+
309
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>", integrations: [tenantTag] });
310
+ ```