@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,263 @@
1
+ # Troubleshooting
2
+
3
+ Start every investigation with `debug: true` in `init` (script tag:
4
+ `data-debug`). The SDK then logs to the console, every line starting with
5
+ `[starko]`: `started` once it runs, `dropped <why>` for each event it drops,
6
+ and the status of each request it sends. Remove `debug` again in production.
7
+
8
+ Some messages are printed even without `debug`: events dropped by a rate
9
+ limit (`events dropped by …`, at most once a minute per limit), and, once
10
+ each, other dropped events (`events dropped: …`), a host that redirects, a
11
+ secret key the ingest API refused, and, on the Edge runtime, a server user
12
+ set outside a request.
13
+
14
+ ## 1. Nothing arrives
15
+
16
+ Work down this list:
17
+
18
+ 1. **Did the SDK start?** With `debug: true`, look for `[starko] started`.
19
+ `[starko] no workspaceKey` means the key is missing. `init` must run
20
+ before the error happens: errors thrown before it are not captured.
21
+ 2. **Is the workspace key right?** It is the workspace id shown in Starko
22
+ under Settings. A wrong key gets `401` with reason `unknown_workspace`;
23
+ the SDK then stops sending for the rest of the page load or process
24
+ (`[starko] 401 unknown_workspace: off`).
25
+ 3. **Is the secret key right?** (servers with `apiKey`) A wrong, revoked or
26
+ malformed `apiKey` gets `401` with reason `invalid`. The SDK drops each
27
+ batch it was refused for, without retrying, and prints
28
+ ``[starko] 401: secret key refused, events dropped. Check `apiKey`.``
29
+ once, even without `debug`. Later batches are sent and refused the same
30
+ way. Fix `apiKey`, or remove it: without it, events are accepted like a
31
+ browser's.
32
+ 4. **Is error tracking enabled for the workspace?** If not, the remote
33
+ config says so (`[starko] config: disabled`) or the ingest API answers
34
+ `403` with reason `disabled`, and the SDK switches itself off.
35
+ 5. **Is the page's origin allowed?** If the workspace restricts which
36
+ origins may send errors, a page on another origin (a preview deployment,
37
+ `localhost`) gets `403` with reason `origin_not_allowed`, and the SDK
38
+ stops for that page load.
39
+ 6. **Is the request blocked before it leaves?** Ad blockers and privacy
40
+ extensions may block requests to error-tracking endpoints. In the
41
+ browser's network tab, look for the `POST …/api/v1/ingest/errors`
42
+ request: blocked, or never sent. Errors from those visitors do not
43
+ arrive.
44
+ 7. **Was the event dropped on purpose?** With `debug: true` each drop says
45
+ why: `InboundFilters` (noise, see [browser.md](./browser.md#filter-noise)),
46
+ `ignoreErrors`, `allowUrls` / `denyUrls`, `suppress` (a rule set for the
47
+ workspace), `sample`, `beforeSend`, or a rate limit.
48
+ 8. **Did it have time to leave?** Events are sent a second after capture.
49
+ A script or serverless function that ends at once loses them unless it
50
+ flushes; see [5](#5-events-missing-when-a-process-or-function-ends).
51
+
52
+ ## 2. Stack traces are minified
53
+
54
+ Upload source maps at build time: [source-maps.md](./source-maps.md), and its
55
+ [troubleshooting](./source-maps.md#troubleshooting-unresolved-frames) for
56
+ frames that stay unresolved.
57
+
58
+ ## 3. The same error is reported twice
59
+
60
+ - **With the Starko widget on the page:** see
61
+ [widget.md](./widget.md#duplicate-reports).
62
+ - **Two copies of `init`** in different bundles: one client replaces the
63
+ other, which is fine; but two different Starko SDK versions of different
64
+ compatibility lines (`0.1.x` next to `1.x`, for example) keep separate
65
+ state and both report. Use one version.
66
+ - **Your own handler and the SDK:** the SDK reports the same error object
67
+ once, however many times it is captured. A copy of the error (a new
68
+ `Error` with the same message) is a new event, unless it arrives right
69
+ after an identical one (same type, message, frames, fingerprint, user and
70
+ session, and on a server the same request).
71
+
72
+ ## 4. Events missing when the page closes
73
+
74
+ When the page is hidden or closed, the SDK sends its queue with `keepalive`
75
+ so the request survives the page. Browsers allow 64 KiB of `keepalive`
76
+ request bodies in flight per page; beyond that the rest is sent without
77
+ `keepalive` and may be cut off. Events captured in the last moment of a
78
+ page (in an `unload` handler) may not be sent at all. A very large `extra`
79
+ or many breadcrumbs make each event bigger: keep them small.
80
+
81
+ ## 5. Events missing when a process or function ends
82
+
83
+ - `process.exit()` ends the process before anything can be sent. Call
84
+ `await Starko.flush(2000)` first.
85
+ - Serverless functions may be frozen as soon as the handler returns. Wrap
86
+ the handler in `wrapHandler`, or `await Starko.flush(2000)` before
87
+ returning. See [node.md](./node.md#other-frameworks-and-serverless-wraphandler).
88
+ - `next start` exits on `SIGTERM` without waiting; see
89
+ [nextjs.md](./nextjs.md#vercel-and-long-lived-servers).
90
+
91
+ ## 6. The process does not exit, or exits later than before
92
+
93
+ The SDK never keeps a Node process alive on its own. It holds it open only
94
+ to send what is queued, for a bounded time:
95
+
96
+ - when the event loop empties: at most `shutdownTimeout` (2 s), only if
97
+ events are queued;
98
+ - on `SIGTERM` / `SIGINT` without an app handler: at most `shutdownTimeout`;
99
+ - after a crash: at most `fatalFlushTimeout` (1 s);
100
+ - with the `fetch` option (a proxy): a request in flight, at most 10 s.
101
+
102
+ A process that stays up longer is held by something else (an open server,
103
+ a database pool, a timer).
104
+
105
+ ## 7. `401`, `403` and `429`: what each reason means
106
+
107
+ Seen in the browser's network tab, or in the console with `debug: true`.
108
+
109
+ | Status | Reason | Meaning | What the SDK does | What to do |
110
+ | --- | --- | --- | --- | --- |
111
+ | 401 | `unknown_workspace` | The workspace key is not known. | Stops sending for this page load or process. | Fix `workspaceKey`. |
112
+ | 401 | `invalid` | The secret key (`apiKey`, servers only) is not valid. | Drops the batch without retrying and prints `secret key refused` once; later batches are still sent. | Fix or remove `apiKey`. |
113
+ | 401 / 403 | none, or not JSON | Not from Starko: a proxy, a firewall, a captive portal. | Retries with back-off; never switches off. | Check what sits between your app and Starko. |
114
+ | 403 | `disabled` | Error tracking is off for the workspace. | Stops sending. | Enable it in Starko. |
115
+ | 403 | `origin_not_allowed` | The page's origin is not on the workspace's allow-list. | Stops sending for this page load. | Add the origin in Starko, or ignore it for preview hosts. |
116
+ | 429 | `rate_limit` | Too many requests right now. | Waits `Retry-After`, then retries. | Usually nothing. If constant, lower `sampleRate` or fix the error loop. |
117
+ | 429 | `quota` | The workspace's allowance is used up. | Drops the batch and sends nothing until `Retry-After` has passed. | Check the workspace's usage in Starko. |
118
+
119
+ Other answers: `413` (batch too large: halved and retried once), `400`
120
+ (malformed: dropped), and `503` (busy). The ingest API answers `503` with
121
+ `Retry-After: 30` while its queue store is unavailable; the SDK waits at
122
+ least that long before it tries the batch again. Each batch gets at most
123
+ three attempts (network failures and 5xx included), so events can arrive a
124
+ minute or more late, or not at all during a longer outage. The back-off
125
+ and the number of attempts cannot be changed from `init`. The full table
126
+ is in [wire-format.md](./wire-format.md#responses).
127
+
128
+ ## 8. `host answered 3xx … not followed`
129
+
130
+ Your `host` redirects (`http://` to `https://`, an apex domain to `www.`).
131
+ The SDK never follows redirects (the event would be lost and a secret key
132
+ could go to another host), so those events were dropped. Set `host` to the
133
+ final address.
134
+
135
+ ## 9. The error arrives, but is not linked to the customer
136
+
137
+ A user is linked only when verified:
138
+
139
+ - browser: send a user hash with `identify(user, userHash)`
140
+ ([browser.md](./browser.md#identify-the-user)), or have the Starko widget
141
+ on the page;
142
+ - server: set `apiKey` (then `user.id` is trusted), or send a user hash;
143
+ - through the widget's token: verified when that customer's profile is
144
+ anonymous or identity-verified; a customer identified in the widget
145
+ without verification is linked too, labelled "unverified" in Starko;
146
+ - events sent through the PostHog-compatible route are never linked.
147
+
148
+ On a server, a user set outside a request never reaches a request's
149
+ errors: requests start from the `user` passed to `init` (see
150
+ [node.md](./node.md#code-outside-a-request)). Set the user inside the
151
+ request. On the Edge runtime a `setUser` outside a request scope is
152
+ refused, with a warning; set it inside `wrapHandler`.
153
+
154
+ ## 10. `events dropped: …` in the console
155
+
156
+ A limit dropped events. For the three rate limits the line is printed at
157
+ most once a minute per limit, with the number dropped since the previous
158
+ line:
159
+
160
+ - `events dropped by rate limit per error (10, then 1 per 10 s): N …,
161
+ latest "TypeError: Order <n> not found"`: one error was reported more
162
+ than 10 times at once. An error is its type and message with numbers and
163
+ ids masked (`<n>`, `<id>`), as the line shows;
164
+ - `events dropped by maxEventsPerLifetime`: 100 per page load in the
165
+ browser;
166
+ - `events dropped by maxEventsPerMinute`: 300 a minute on servers.
167
+
168
+ Printed once: the queue size (`maxQueueSize`), more than 30 events before
169
+ the remote config arrived, and an async `beforeSend` that did not settle in
170
+ time. A page or server that hits these is usually throwing the same error
171
+ in a loop: fix the loop, or raise the limit if the volume is expected.
172
+
173
+ ## 11. Source-map upload: storage, expired URLs, the allowance
174
+
175
+ These come from the build plugins, `withStarko` and `starko sourcemaps
176
+ upload`, not from the runtime SDK. With the bulk upload (the default when
177
+ the server offers it) every map is sent from the build machine straight to
178
+ Starko's storage through a short-lived signed URL, so the build needs to
179
+ reach two hosts: the Starko host and the storage host the server names.
180
+ The first line of the upload says which protocol is used:
181
+ `source map upload: using the bulk upload: …` or
182
+ `source map upload: using the v1 upload through <host>: …`.
183
+
184
+ **`uploads to Starko's storage at <origin> fail (3 in a row, last: …)`.**
185
+ The build machine cannot reach the storage host: a proxy, a firewall or an
186
+ allow-list that lets only the Starko host through. With the default
187
+ `uploadProtocol: "auto"` the upload goes on through the Starko host (v1)
188
+ for every map storage does not hold, and the warning says so. That
189
+ includes the few maps reserved before the failure was detected (until a
190
+ first upload to storage succeeds, maps are reserved 4 at a time): the
191
+ server lets v1 take those reservations over at once, since nothing was
192
+ stored under them. Fix it either way, so later builds use the faster bulk
193
+ upload:
194
+
195
+ - allow the storage host named in the warning (only its host is printed;
196
+ the signed URL never is), or
197
+ - set `uploadProtocol: "v1"` (CLI: `--protocol v1`): every map goes through
198
+ the Starko host, and the storage host is never contacted.
199
+
200
+ With `uploadProtocol: "bulk"` there is no fallback: the upload stops with
201
+ the same message.
202
+
203
+ Behind a proxy: the build tools send with Node's global `fetch`, to the
204
+ Starko host and to storage alike. It uses `HTTPS_PROXY` / `HTTP_PROXY` and
205
+ `NO_PROXY` only when Node runs with `NODE_USE_ENV_PROXY=1` (checked on Node
206
+ 24), or when your build installs a global dispatcher with a proxy
207
+ (undici's `setGlobalDispatcher`). The storage host must not be in
208
+ `NO_PROXY` if it is only reachable through the proxy.
209
+
210
+ **An expired URL.** A signed URL is valid for 10 minutes. The tools time
211
+ it from the server's "seconds left" (`expires_in_s`) on the build
212
+ machine's own monotonic clock, so a build machine whose clock is wrong
213
+ still renews it in time: a new `bulk/start` for the map (the server signs
214
+ the same object again) when it has less than a minute left before its
215
+ upload starts. An upload storage refuses (an expired URL included) is
216
+ never repeated to the same URL: it is confirmed with the server (an
217
+ earlier attempt may have landed) and, when it did not, started again for a
218
+ fresh URL. Nothing to do. When a map reports `not uploaded after 4
219
+ bulk/start requests`, check the build machine's connection to storage.
220
+
221
+ **`no answer within 135 s` (or 45 s, 75 s).** Each request waits for its
222
+ route's longest run on the server plus 15 s (`bulk/finish`, which
223
+ verifies maps, up to 2 minutes): a slow answer is waited for. Three
224
+ requests in a row without an answer stop the upload with `cannot reach
225
+ <host>`: check the build machine's connection to the Starko host.
226
+
227
+ **`the server refused the uploaded map (failed: Verification failed: …);
228
+ it is not sent again by this build`.** Starko read the map back and it was
229
+ not what the build declared: its sha256, its `debugId`, its size or its
230
+ gzip. The same bytes would fail again, and every failed map counts against
231
+ the key's daily upload budget, so the tools do not retry it. Check that
232
+ nothing changes the bundle or the map after the upload starts (another
233
+ plugin, a minifier run afterwards; see [One tool per
234
+ build](./source-maps.md#one-tool-per-build)); a later build with the fixed
235
+ map sends it again.
236
+
237
+ **`… storage allowance … (over_allowance); the upload stops here`.** The
238
+ workspace's source-map storage is full. The maps already reserved are
239
+ finished, nothing more is sent, and the build log says how far it got.
240
+ Delete maps you no longer need in Starko, then build again. v1
241
+ reports the same as `413: Source-map storage allowance reached`.
242
+
243
+ **`the server asks to wait 10 h before the next request (429: … daily
244
+ source-map upload budget …)`.** The API key's daily upload budget is
245
+ spent. The upload stops at once; the next day's build continues.
246
+
247
+ **`earlier uploads of this debug id may still be under way on the server
248
+ … (busy)`.** Rare: the map's debug id was restarted more than three times
249
+ within about 20 minutes (builds of other content for the same id, or maps
250
+ that failed verification), and the server waits for one of those uploads
251
+ to be over. The tools wait out a `busy` of up to a minute; a longer one
252
+ fails that map, and a later build sends it. v1 reports a map whose bulk
253
+ upload already put an object in Starko's storage less than about 20
254
+ minutes ago as `Starko is receiving this map through a direct upload to
255
+ its storage that may still be under way` (a reservation with nothing in
256
+ storage is taken over by v1 at once).
257
+
258
+ **`Starko has disabled source-map uploads (423: …)`.** The server found an
259
+ uploaded map readable without a signature and switched source-map uploads
260
+ off, for every build, until an operator fixes its storage (this can take
261
+ hours). Nothing more is sent and nothing is retried; the build goes on
262
+ (unless `failOnError` is set). This is a problem on Starko's side: contact
263
+ Starko. Maps that were not uploaded are sent by a build after it is fixed.
package/docs/widget.md ADDED
@@ -0,0 +1,84 @@
1
+ # Using the SDK with the Starko widget
2
+
3
+ The Starko widget (chat, help center, session recording) can report page
4
+ errors on its own. When the SDK is on the same page, the SDK takes over
5
+ error capture and the two share what links an error to a customer and to a
6
+ recording. Install both as usual; there is nothing to configure, and they
7
+ may load in either order.
8
+
9
+ ```ts
10
+ import * as Starko from "@starko-one/sdk/browser";
11
+
12
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>" });
13
+ // The widget's own snippet stays as it is.
14
+ ```
15
+
16
+ ## Who captures errors
17
+
18
+ The two meet through one global object, `window.__STARKO_BRIDGE__`. The SDK
19
+ announces on it whether it is capturing page errors (`capturesErrors`), and
20
+ announces every change with a `starko:bridge` event on `window`.
21
+
22
+ - While `capturesErrors` is true, the widget does not install its own error
23
+ hooks: each error is reported once, by the SDK.
24
+ - `capturesErrors` is true only while the SDK is running **and** its global
25
+ error handlers are installed. It becomes false after `close()`, when the
26
+ workspace's error tracking is switched off, or when you remove the
27
+ `GlobalHandlers` integration. The widget then reports page errors itself
28
+ again.
29
+ - The widget also reports errors a page passes to `console.error` (for
30
+ example from a framework's error boundary) and stops doing so when the SDK
31
+ is there. So, while the widget is on the page, the SDK captures them
32
+ instead: an `Error` object passed to `console.error` is reported as a
33
+ handled error. Remove the `ConsoleErrorCapture` integration to stop that;
34
+ add `consoleErrorCaptureIntegration()` yourself to capture them without the
35
+ widget too.
36
+
37
+ ## The session: errors linked to recordings
38
+
39
+ With the widget on the page and recording, the SDK stamps the recorder's
40
+ session id on every error, so the error links to the recording of the
41
+ session it happened in. Without the widget, the SDK creates its own session
42
+ id, kept per tab in `sessionStorage` under `starko:errors:session`, the same
43
+ key the widget uses, so both agree whichever loads first.
44
+
45
+ ## The customer: verified through the widget
46
+
47
+ When the widget is on the page, the SDK sends the widget's client token
48
+ with every error. Starko verifies it and links the error to the widget's
49
+ customer, with no user hash needed. The link is verified when that
50
+ customer's profile is anonymous or identity-verified. A customer who was
51
+ identified in the widget without verification (an email typed into it, or
52
+ `identify` without a hash) is linked too, and Starko labels that link
53
+ "unverified" on the error, in the affected customers list and in a ticket
54
+ filed from it. Starko also checks the user hash you sent with `identify`:
55
+ a valid hash links your user as verified and replaces the unverified link.
56
+ The token is a credential: the SDK
57
+ sends it with the event and nowhere else (never in logs, breadcrumbs or
58
+ extra data), and Starko does not store it.
59
+
60
+ Without the widget, identify users with `identify(user, userHash)`; see
61
+ [browser.md](./browser.md#identify-the-user).
62
+
63
+ ## Load order and lifecycle
64
+
65
+ | Situation | What happens |
66
+ | --- | --- |
67
+ | SDK first, widget later | The widget finds the SDK on the bridge and leaves error capture to it. The SDK reads the widget's session and token on every event, so events after the widget arrived carry them. |
68
+ | Widget first, SDK later | The SDK registers on the bridge and announces it; the widget stands its error capture down. |
69
+ | `Starko.close()` | `capturesErrors` becomes false and is announced; the widget reports errors itself again. |
70
+ | Error tracking switched off for the workspace | Same as `close()`. |
71
+ | `init` called again, or a second copy of the SDK (script tag and npm package) | One bridge entry, always routed to the current SDK client. |
72
+ | The page sets `__STARKO_BRIDGE__` to something that is not an object | The SDK leaves it alone and runs without the bridge. |
73
+
74
+ ## Duplicate reports
75
+
76
+ Each error should arrive once. If you see the same error twice, once from
77
+ the widget and once from the SDK:
78
+
79
+ - check that `Starko.init` actually ran and is enabled (with `debug: true`
80
+ the console shows `[starko] started`);
81
+ - check that `GlobalHandlers` was not removed (then `capturesErrors` is false
82
+ and the widget reports instead, which is expected);
83
+ - check that the widget build on the page reads the bridge. A widget that
84
+ does not know `__STARKO_BRIDGE__` keeps capturing next to the SDK.