@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,386 @@
1
+ # Browser
2
+
3
+ Error tracking for any web page, with or without a framework. For React see
4
+ also [react.md](./react.md); for Next.js use [nextjs.md](./nextjs.md) instead
5
+ of this page.
6
+
7
+ ## Install with npm
8
+
9
+ ```sh
10
+ npm install @starko-one/sdk
11
+ ```
12
+
13
+ ```ts
14
+ import * as Starko from "@starko-one/sdk/browser";
15
+
16
+ Starko.init({
17
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
18
+ release: "shop@4.12.0",
19
+ environment: "production",
20
+ });
21
+ ```
22
+
23
+ Set `environment` per deployment. If your build tool sets it from
24
+ `NODE_ENV`, mind that hosts with preview deployments build those in
25
+ production mode too: use the host's own variable where it has one (see
26
+ [nextjs.md](./nextjs.md#environment-production-or-preview)).
27
+
28
+ Call `init` once, in your entry file, before the rest of your app runs:
29
+ errors thrown before `init` are not captured. Calling `init` again replaces
30
+ the previous client. `init` never throws; it returns the client, or
31
+ `undefined` when it could not start.
32
+
33
+ The workspace key is the workspace id shown in Starko under Settings. It is
34
+ public: it only lets a page send errors. Never put a secret key
35
+ (`sk_starko_…`) in browser code.
36
+
37
+ Use as `release` the release your source maps were uploaded for. If you
38
+ use one of the build plugins, you can leave it out: the plugin writes the
39
+ release it uploaded for into your bundles and `init` uses it (it is read
40
+ for each event, so `init` may run before those bundles load). See
41
+ [source-maps.md](./source-maps.md).
42
+
43
+ ## Install with a script tag
44
+
45
+ ```html
46
+ <script
47
+ src="https://cdn.jsdelivr.net/npm/@starko-one/sdk@0.1.0-beta.1/dist/starko.min.js"
48
+ data-workspace-key="<STARKO_WORKSPACE_KEY>"
49
+ data-release="shop@4.12.0"
50
+ data-environment="production"
51
+ ></script>
52
+ ```
53
+
54
+ Always pin the exact version in the URL. An unpinned URL changes under you
55
+ when a new version is published. The bundle is 53 kB minified, 19.04 kB
56
+ gzipped.
57
+
58
+ The tag works as a classic script, with `defer` or `async`, and as
59
+ `<script type="module">`; in a module the bundle finds its tag by the
60
+ `data-workspace-key` attribute. A classic script defines `window.Starko`;
61
+ a module sets it unless the page already has a `Starko` global. With
62
+ `defer`, `async` or `type="module"`, the bundle runs after inline scripts
63
+ that follow the tag, so start it with the attributes, or call `init` from a
64
+ script of the same kind placed after the tag (`defer` and module scripts
65
+ run in document order; `async` ones do not).
66
+
67
+ With `data-workspace-key` on the tag, the bundle starts itself. The other
68
+ attributes it reads:
69
+
70
+ | Attribute | Option |
71
+ | --- | --- |
72
+ | `data-workspace-key` | `workspaceKey`. Without it the bundle does not start; call `Starko.init` yourself. |
73
+ | `data-release` | `release` |
74
+ | `data-environment` | `environment` |
75
+ | `data-host` | `host` (default `https://v2.starko.one`) |
76
+ | `data-debug` | `debug: true` when the attribute is present |
77
+
78
+ For any other option, leave `data-workspace-key` off and call `init` from your
79
+ own script after the tag:
80
+
81
+ ```html
82
+ <script src="https://cdn.jsdelivr.net/npm/@starko-one/sdk@0.1.0-beta.1/dist/starko.min.js"></script>
83
+ <script>
84
+ window.Starko.init({
85
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
86
+ release: "shop@4.12.0",
87
+ sampleRate: 0.5,
88
+ });
89
+ </script>
90
+ ```
91
+
92
+ The bundle exposes `window.Starko` with `init`, `captureException`,
93
+ `captureMessage`, `setUser`, `identify`, `setTag`, `setTags`, `setExtra`,
94
+ `setExtras`, `setContext`, `addBreadcrumb`, `withScope`, `flush`, `close`,
95
+ `getClient`, `SDK_VERSION` and `consoleErrorCaptureIntegration`. The other
96
+ integration factories are only in the npm package. Errors raised entirely
97
+ inside the bundle itself are never reported.
98
+
99
+ ## Identify the user
100
+
101
+ An error is linked to a customer in Starko only when the link is verified.
102
+ Send the user with a **user hash**: an HMAC-SHA256, in hex, of the user's id
103
+ (or of their email when you have no id), computed on **your backend** with
104
+ your workspace's identity secret. It is the same hash the Starko widget's
105
+ `identify` takes.
106
+
107
+ On your server (Node shown; any language with HMAC-SHA256 works):
108
+
109
+ ```js
110
+ import { createHmac } from "node:crypto";
111
+
112
+ // Never run this in the browser: the identity secret must stay on your server.
113
+ // STARKO_IDENTITY_SECRET is an environment variable of your own holding it.
114
+ export function starkoUserHash(userId) {
115
+ return createHmac("sha256", process.env.STARKO_IDENTITY_SECRET).update(userId).digest("hex");
116
+ }
117
+ ```
118
+
119
+ Hand the hash to the page with the signed-in user (in your session payload,
120
+ say), then:
121
+
122
+ ```ts
123
+ import * as Starko from "@starko-one/sdk/browser";
124
+
125
+ export function onSignIn(user: { id: string; email: string; name: string }, starkoUserHash: string) {
126
+ Starko.identify({ id: user.id, email: user.email, name: user.name }, starkoUserHash);
127
+ }
128
+
129
+ export function onSignOut() {
130
+ Starko.setUser(null);
131
+ }
132
+ ```
133
+
134
+ - `identify(user, userHash)` sets the user and the hash. `identify("user_123", hash)` takes the id alone.
135
+ - `setUser({ id, email, name })` sets a user without a hash.
136
+ - `init({ user, userHash })` sets them at start.
137
+ - A user without a valid hash is kept on the error as text (the id and email
138
+ you sent) and is never linked to a customer, never counted as an affected
139
+ customer and never attached to a ticket: anyone can put any id in a
140
+ browser request, so an unverified id cannot be trusted.
141
+ - When the Starko widget is on the page, the SDK also sends the widget's own
142
+ token, which links the error to the widget's customer without a hash.
143
+ The token is checked first. When the widget's customer was identified
144
+ without verification (an email typed into the widget, for example), the
145
+ error is still linked to them and Starko labels the link "unverified"; a
146
+ valid hash you sent with `identify` links your user as verified instead.
147
+ See [widget.md](./widget.md).
148
+ - The hash is a credential. The SDK never logs it and the server does not store it.
149
+
150
+ ## Capture errors yourself
151
+
152
+ ```ts
153
+ import * as Starko from "@starko-one/sdk/browser";
154
+
155
+ async function checkout(cartId: string) {
156
+ try {
157
+ await fetch(`/api/checkout/${cartId}`, { method: "POST" });
158
+ } catch (error) {
159
+ const eventId = Starko.captureException(error, {
160
+ tags: { area: "checkout" },
161
+ extra: { cartId },
162
+ });
163
+ console.log("reported as", eventId);
164
+ }
165
+ }
166
+
167
+ Starko.captureMessage("Payment provider fell back to redirect flow", "warning");
168
+ ```
169
+
170
+ - `captureException(value, hint?)` takes anything thrown (an `Error`, a
171
+ string, an object) and returns the event id (`""` before `init`). The hint
172
+ may set `tags`, `extra`, `contexts`, `fingerprint` (events with the same
173
+ fingerprint become one issue) and `level`. Captured errors are recorded as
174
+ handled.
175
+ - `captureMessage(message, level?)` reports a message with the caller's
176
+ stack. The level defaults to `"info"`. Only `error` and `fatal` events can
177
+ file a ticket.
178
+ - The same error object is reported once, even if it is captured again or
179
+ later reaches the global handler.
180
+
181
+ Data for every later event:
182
+
183
+ ```ts
184
+ import * as Starko from "@starko-one/sdk/browser";
185
+
186
+ Starko.setTag("plan", "pro");
187
+ Starko.setTags({ region: "eu", tenant: "acme" });
188
+ Starko.setExtra("featureFlags", { newCheckout: true });
189
+ Starko.setContext("cart", { items: 3, currency: "EUR" });
190
+ ```
191
+
192
+ Data for one capture only:
193
+
194
+ ```ts
195
+ import * as Starko from "@starko-one/sdk/browser";
196
+
197
+ function reportImportFailure(error: unknown, fileName: string) {
198
+ Starko.withScope((scope) => {
199
+ scope.setTag("feature", "import");
200
+ scope.setExtra("fileName", fileName);
201
+ Starko.captureException(error);
202
+ });
203
+ }
204
+ ```
205
+
206
+ ## Breadcrumbs
207
+
208
+ Breadcrumbs are what happened before the error. Recorded automatically:
209
+
210
+ | Kind | What is recorded |
211
+ | --- | --- |
212
+ | Clicks | A short CSS-like path of the element (`form#login > button.primary`), never its text or an input's value. Nothing inside elements with `starko-mask` / `starko-no-capture` classes or `data-starko-mask` / `data-starko-no-capture` attributes. |
213
+ | Navigation | `pushState`, `replaceState` and back/forward: from and to (path only when same-origin). |
214
+ | `fetch` and XHR | Method, URL and status code. Never bodies, cookies or headers. Requests to Starko are not recorded. |
215
+ | Console | `console.warn` and `console.error` only, as text cut to 200 characters. |
216
+
217
+ At most 50 breadcrumbs are kept (`maxBreadcrumbs`), and at most 32 KiB of
218
+ them are sent with an event.
219
+
220
+ Add your own, edit or drop any of them:
221
+
222
+ ```ts
223
+ import * as Starko from "@starko-one/sdk/browser";
224
+
225
+ Starko.init({
226
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
227
+ beforeBreadcrumb(breadcrumb) {
228
+ if (breadcrumb.category === "console" && breadcrumb.message?.includes("[analytics]")) return null;
229
+ return breadcrumb;
230
+ },
231
+ });
232
+
233
+ Starko.addBreadcrumb({ category: "cart", message: "Coupon applied", data: { code: "SPRING" } });
234
+ ```
235
+
236
+ To turn off one kind, replace the default `Breadcrumbs` integration (an
237
+ integration with the same name as a default replaces it):
238
+
239
+ ```ts
240
+ import * as Starko from "@starko-one/sdk/browser";
241
+ import { breadcrumbsIntegration } from "@starko-one/sdk/browser";
242
+
243
+ Starko.init({
244
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
245
+ integrations: [breadcrumbsIntegration({ console: false, dom: true, fetch: true, xhr: true, history: true })],
246
+ });
247
+ ```
248
+
249
+ ## `beforeSend`
250
+
251
+ The last step before an event is queued. Return the event (changed or not),
252
+ or `null` to drop it. It may be `async`.
253
+
254
+ ```ts
255
+ import * as Starko from "@starko-one/sdk/browser";
256
+
257
+ Starko.init({
258
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
259
+ beforeSend(event) {
260
+ if (event.request?.url?.includes("/admin/")) return null;
261
+ if (event.user) delete event.user.email;
262
+ return event;
263
+ },
264
+ });
265
+ ```
266
+
267
+ - It runs after filtering, sampling and the rate limits, so it is not called
268
+ for events that would be dropped anyway.
269
+ - If it throws, the event is dropped (it may have been the step that removes
270
+ personal data). An async `beforeSend` that has not settled after
271
+ `beforeSendTimeoutMs` (default 5000 ms) is abandoned and its event dropped.
272
+ - The URL redaction described in [privacy.md](./privacy.md) runs after
273
+ `beforeSend`, so the event you see still has the raw URLs.
274
+
275
+ ## Filter noise
276
+
277
+ Dropped before anything is sent, with no setting needed:
278
+
279
+ - an error with no message and no stack;
280
+ - a cross-origin `Script error.` without a stack (an error in a script from
281
+ another origin loaded without `crossorigin`; the browser hides its details);
282
+ - an error with a browser extension in its top three frames;
283
+ - `ResizeObserver loop …` errors;
284
+ - aborted requests (`AbortError`, "The operation was aborted", …);
285
+ - plain network failures (`Failed to fetch`, `Load failed`, `NetworkError …`
286
+ without a stack);
287
+ - errors raised entirely inside Starko's own scripts (widget, recorder, this SDK);
288
+ - the same error twice in a row (same type, message, frames, fingerprint,
289
+ user and session).
290
+
291
+ Your own rules:
292
+
293
+ ```ts
294
+ import * as Starko from "@starko-one/sdk/browser";
295
+
296
+ Starko.init({
297
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
298
+ ignoreErrors: ["Non-critical widget timeout", /^ChunkLoadError/],
299
+ allowUrls: [/^https:\/\/shop\.example\.com\//],
300
+ denyUrls: [/\/vendor\/legacy-chat\.js/],
301
+ });
302
+ ```
303
+
304
+ - `ignoreErrors` matches `Type: message` and `message`: a string matches
305
+ anywhere in it, a `RegExp` is tested against it.
306
+ - `allowUrls` / `denyUrls` match the file of the most recent stack frame that
307
+ has a file. An event without such a frame passes both.
308
+ - Rules set for the workspace in Starko (the remote config, below) drop
309
+ matching events too.
310
+
311
+ The built-in filters are the `InboundFilters` integration; removing it (see
312
+ [configuration.md](./configuration.md#adding-and-removing-integrations))
313
+ turns all of them off.
314
+
315
+ ## Sampling and limits
316
+
317
+ ```ts
318
+ import * as Starko from "@starko-one/sdk/browser";
319
+
320
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>", sampleRate: 0.25 });
321
+ ```
322
+
323
+ `sampleRate` (0 to 1, default 1) is the share of events sent. The workspace's
324
+ remote sample rate multiplies it. Limits that always apply in a browser:
325
+
326
+ - per error: 10 at once, then 1 every 10 seconds. An error here is its
327
+ type and the first 120 characters of its message, with numbers, UUIDs
328
+ and long hex ids masked (`Order 1234 not found` and `Order 98 not found`
329
+ count as one); without a message, its type and the file and line it was
330
+ thrown from;
331
+ - 100 events per page load (`maxEventsPerLifetime`);
332
+ - 100 events waiting in memory (`maxQueueSize`); the oldest are dropped first.
333
+
334
+ Drops by the first two limits are logged to the console even without
335
+ `debug`, at most once a minute per limit, with the number dropped since the
336
+ previous line; a full queue is logged once.
337
+
338
+ ## Remote config
339
+
340
+ At `init` the SDK reads the workspace's settings from Starko
341
+ (`GET /api/v1/ingest/config`): whether error tracking is on, a sample rate
342
+ and suppression rules. Until the answer arrives (at most 10 seconds), up to
343
+ 30 events are held; they are then sent or dropped by what it says. If error
344
+ tracking is off for the workspace, the SDK removes its hooks and sends
345
+ nothing. If the request fails, the SDK runs with the defaults (on, sample
346
+ rate 1, no rules).
347
+
348
+ `remoteConfig: false` skips the request; the workspace's on/off switch is
349
+ then only learned from the ingest API's answer to the first batch.
350
+
351
+ ## Offline, and when the page is hidden
352
+
353
+ - Events are sent in batches of up to 20, one second after the first one
354
+ (`flushInterval`).
355
+ - A request that has not answered after 12 seconds (`requestTimeoutMs`) is
356
+ aborted and counts as a network failure.
357
+ - A failed batch is retried with back-off (waiting at least `Retry-After`
358
+ when the answer has one), at most three attempts. After
359
+ three batches in a row are given up, sending pauses for five minutes, and
360
+ resumes earlier when the browser fires `online`. Events captured while
361
+ offline wait in the queue (at most 100).
362
+ - When the page is hidden or unloaded (`visibilitychange` to hidden,
363
+ `pagehide`), the queue is sent at once with `keepalive`, so it can outlive
364
+ the page. Browsers allow 64 KiB of `keepalive` bodies in flight; a request
365
+ beyond that is sent without `keepalive` and may be cut off if the page is
366
+ really closing.
367
+ - Redirects are never followed. If your `host` redirects (`http://` to
368
+ `https://`, an apex domain), the batch is dropped and the console names the
369
+ redirect target, even without `debug`. Set `host` to the final address.
370
+
371
+ ## Stop or flush
372
+
373
+ ```ts
374
+ import * as Starko from "@starko-one/sdk/browser";
375
+
376
+ async function signOutEverywhere() {
377
+ await Starko.flush(2000); // true when everything queued went out within 2 s
378
+ await Starko.close(); // flush, then remove every hook; nothing is sent afterwards
379
+ }
380
+ ```
381
+
382
+ ## See also
383
+
384
+ - [configuration.md](./configuration.md): every option and its default.
385
+ - [privacy.md](./privacy.md): what is collected and how to collect less.
386
+ - [troubleshooting.md](./troubleshooting.md).