@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,112 @@
1
+ # Privacy
2
+
3
+ What the SDK collects by default, what it never collects, and how to collect
4
+ less. This page describes the software; it is not legal advice.
5
+
6
+ ## Browser (`/browser`, `/next/client`, script tag)
7
+
8
+ Collected by default with every error:
9
+
10
+ | What | Details |
11
+ | --- | --- |
12
+ | The error | Type, message, stack frames (script URL, function, line, column), the chain of `cause`s. |
13
+ | Page | The page URL (`location.href`) and the referrer, with the URL rules below. |
14
+ | Breadcrumbs | Up to 50: clicks (a short CSS-like selector of the element, never its text or an input's value), navigation (from and to; path only when same-origin), `fetch`/XHR (method, URL, status code), and `console.warn` / `console.error` text cut to 200 characters. |
15
+ | Session | A random session id kept in `sessionStorage` (`starko:errors:session`), or the Starko widget's recorder session id when the widget is on the page. |
16
+ | Widget token | When the Starko widget is on the page: its client token, which links the error to the widget's customer. Verified by Starko and then discarded, not stored. |
17
+ | What you set | The user (`setUser`, `identify`), tags, extra data and contexts. Nothing about the user unless you set it. |
18
+
19
+ The SDK itself adds no user agent and no IP address to the event; Starko
20
+ receives the request like any other HTTP request.
21
+
22
+ Never collected: request or response bodies, cookies, request headers, the
23
+ text of the page, input values, `localStorage`.
24
+
25
+ Clicks inside an element with the `starko-mask` or `starko-no-capture`
26
+ class, or the `data-starko-mask` or `data-starko-no-capture` attribute (the
27
+ same markers the Starko session recorder honours), are not recorded at all.
28
+
29
+ ## Servers (`/node`, `/next`)
30
+
31
+ | What | Details |
32
+ | --- | --- |
33
+ | The error | Type, message, stack frames (file path, function, line, column), the chain of `cause`s. |
34
+ | Request | Method, URL (with the URL rules below) and route pattern of the request the error happened in, and the browser's session id from the `x-starko-session-id` header. |
35
+ | Breadcrumbs | `console.warn` / `console.error` text cut to 200 characters, per request. No HTTP client breadcrumbs. |
36
+ | Host | `server_name` (the host name, or `serverName`), the Node version, OS name, version and architecture. |
37
+ | Source lines | Up to 7 lines before and after each in-app frame, from your own source files only. See [node.md](./node.md#source-lines) for exactly which files may be read; `.env` files and other dotfiles never are. |
38
+ | Next.js | Route path, router kind, route type, render source and the error's `digest`. |
39
+ | What you set | The user, tags, extra data and contexts. |
40
+
41
+ Never collected: request or response bodies, cookies, request headers other
42
+ than `x-starko-session-id`, environment variables, the process's arguments.
43
+
44
+ ## URL rules (every platform)
45
+
46
+ Applied to every URL the SDK sends: page URL, referrer, request URL,
47
+ breadcrumb URLs, stack-frame file names that are URLs, and `http(s)://` URLs
48
+ inside error messages and breadcrumb messages.
49
+
50
+ - The `#fragment` is removed.
51
+ - The `user:password@` part is removed.
52
+ - The **values** of sensitive query parameters become `[redacted]`. A
53
+ parameter is sensitive when its name, or any part of it (split on `_`, `-`
54
+ and camelCase), is one of: `token`, `access_token`, `id_token`,
55
+ `refresh_token`, `code`, `key`, `api_key`, `apikey`, `secret`, `password`,
56
+ `passwd`, `pwd`, `auth`, `authorization`, `session`, `sessionid`, `sid`,
57
+ `sig`, `signature`, `jwt`, `otp`, `pin`, `email`, `phone`, `ssn`,
58
+ `x-amz-signature`, `x-amz-credential`, `x-amz-security-token`. So
59
+ `accessToken`, `clientSecret`, `apiKey`, `sessionId` and `X-Amz-Signature`
60
+ all match.
61
+
62
+ Every other query parameter **is** sent. If your URLs carry personal data
63
+ under other names (`?customer=…`), remove it in `beforeSend`. The rules run
64
+ after `beforeSend`, on whatever it returns.
65
+
66
+ ## Collect less
67
+
68
+ | To stop collecting | Do this |
69
+ | --- | --- |
70
+ | Everything, for some users or pages | `enabled: false`, or `beforeSend` returning `null`. |
71
+ | Any field of an event | Change or delete it in `beforeSend`. |
72
+ | Breadcrumbs of one kind | `breadcrumbsIntegration({ console: false })` (also `dom`, `fetch`, `xhr`, `history`); see [browser.md](./browser.md#breadcrumbs). |
73
+ | One breadcrumb | `beforeBreadcrumb` returning `null`. |
74
+ | All breadcrumbs | `maxBreadcrumbs: 0`. |
75
+ | Clicks in part of the page | Mark it with `starko-mask` / `starko-no-capture`. |
76
+ | The page URL and referrer | Remove the `HttpContext` integration, or edit `event.request` in `beforeSend`. |
77
+ | The session header on your API requests | Remove the `SessionPropagation` integration. Server errors then no longer link to the browser session. |
78
+ | Console errors captured while the widget is on the page | Remove the `ConsoleErrorCapture` integration. |
79
+ | Server console breadcrumbs | Remove the `ConsoleBreadcrumbs` integration. |
80
+ | Source lines | Remove the `ContextLines` integration. |
81
+ | Host name | Set `serverName` to a neutral value, or remove the `NodeContext` integration. |
82
+ | A share of events | `sampleRate`. |
83
+
84
+ How to remove an integration: [configuration.md](./configuration.md#adding-and-removing-integrations).
85
+
86
+ ## What Starko does on its side
87
+
88
+ - It applies the same URL rules again when an event arrives.
89
+ - It removes well-known secret formats (card numbers, bearer tokens, cloud
90
+ and API keys, JWTs) from messages, source lines, extra data, tags and
91
+ breadcrumbs before storing them.
92
+ - It never fetches your scripts or source maps from the internet; it uses
93
+ only the maps you upload.
94
+ - The user hash and the widget's client token are checked when the request
95
+ arrives and are not stored.
96
+ - How long errors are kept is a setting of your Starko workspace, not of
97
+ this SDK.
98
+
99
+ ## What to tell your users
100
+
101
+ In plain terms, a statement along these lines is accurate for the defaults:
102
+
103
+ > When something goes wrong in our app, we send a technical error report to
104
+ > Starko, our customer-support provider. It contains the error, the page or
105
+ > request where it happened, a short record of the clicks, page changes,
106
+ > network requests and console warnings just before it, and, when you are
107
+ > signed in, your account id and email address. It does not contain what you
108
+ > type into forms, passwords, or the content of our network requests.
109
+
110
+ Adjust it to what you actually send: drop the account part if you never set
111
+ a user, and add anything you put in tags, extra data or contexts. If you
112
+ use the Starko widget's session recording, describe that too.
package/docs/react.md ADDED
@@ -0,0 +1,187 @@
1
+ # React
2
+
3
+ `@starko-one/sdk/react` adds an error boundary and handlers for React 19's
4
+ root error options. It needs React 18 or later (the root handlers need 19).
5
+ It does not start the SDK: start it first with `@starko-one/sdk/browser` (or
6
+ `@starko-one/sdk/next/client` in Next.js). Before the SDK is started, these
7
+ components capture nothing.
8
+
9
+ ## Shortest setup
10
+
11
+ ```tsx
12
+ import { createRoot } from "react-dom/client";
13
+ import * as Starko from "@starko-one/sdk/browser";
14
+ import { StarkoErrorBoundary, reactErrorHandler } from "@starko-one/sdk/react";
15
+
16
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>" });
17
+
18
+ function App() {
19
+ return <h1>Shop</h1>;
20
+ }
21
+
22
+ createRoot(document.getElementById("root")!, reactErrorHandler()).render(
23
+ <StarkoErrorBoundary fallback={<p>Something went wrong.</p>}>
24
+ <App />
25
+ </StarkoErrorBoundary>,
26
+ );
27
+ ```
28
+
29
+ On React 18, leave out `reactErrorHandler()`: uncaught render errors still
30
+ reach the page's global error handler, which the browser SDK listens to.
31
+
32
+ ## `StarkoErrorBoundary`
33
+
34
+ ```tsx
35
+ import type { ReactNode } from "react";
36
+ import * as Starko from "@starko-one/sdk/browser";
37
+ import { StarkoErrorBoundary } from "@starko-one/sdk/react";
38
+
39
+ export function CheckoutSection({ children }: { children: ReactNode }) {
40
+ return (
41
+ <StarkoErrorBoundary
42
+ fallback={({ error, eventId, resetError }) => (
43
+ <div role="alert">
44
+ <p>Checkout failed to load ({error instanceof Error ? error.message : "unknown error"}).</p>
45
+ <p>Reference: {eventId}</p>
46
+ <button onClick={resetError}>Try again</button>
47
+ </div>
48
+ )}
49
+ beforeCapture={(scope) => {
50
+ scope.setTag("section", "checkout");
51
+ }}
52
+ onError={(error, componentStack, eventId) => {
53
+ console.info("checkout error reported", eventId);
54
+ }}
55
+ onReset={() => {
56
+ Starko.addBreadcrumb({ category: "ui", message: "checkout boundary reset" });
57
+ }}
58
+ >
59
+ {children}
60
+ </StarkoErrorBoundary>
61
+ );
62
+ }
63
+ ```
64
+
65
+ <!-- options: StarkoErrorBoundaryProps -->
66
+ | Prop | Meaning |
67
+ | --- | --- |
68
+ | `children` | What the boundary renders until an error. |
69
+ | `fallback` | Rendered instead of the children after an error: a React node, or a function receiving `{ error, componentStack, eventId, resetError }`. Without a fallback the boundary renders nothing after an error. |
70
+ | `onError(error, componentStack, eventId)` | Called after the error is captured. |
71
+ | `beforeCapture(scope, error, componentStack)` | Called before capturing, with a scope that applies to this error only: set tags, extra, context or the user on it. If it throws, the error is still captured. |
72
+ | `onReset(error, componentStack, eventId)` | Called when `resetError` clears the error and the children render again. |
73
+
74
+ What is sent: the error with the component stack in `contexts.react`, and
75
+ `mechanism.type: "react.error-boundary"`. `eventId` is `""` when the SDK is
76
+ not started.
77
+
78
+ During server rendering React does not call error boundaries: the boundary
79
+ renders its children and captures nothing.
80
+
81
+ ### In the Next.js App Router
82
+
83
+ `@starko-one/sdk/react` is a client module (its entry starts with
84
+ `"use client"`), so a Server Component (a layout or a page) can import it
85
+ and render `StarkoErrorBoundary` directly, as long as every prop it passes
86
+ can cross from the server to the client: `children` and a `fallback` that
87
+ is a React node.
88
+
89
+ ```tsx
90
+ import type { ReactNode } from "react";
91
+ import { StarkoErrorBoundary } from "@starko-one/sdk/react";
92
+
93
+ export default function DashboardLayout({ children }: { children: ReactNode }) {
94
+ return <StarkoErrorBoundary fallback={<p>This section failed to load.</p>}>{children}</StarkoErrorBoundary>;
95
+ }
96
+ ```
97
+
98
+ Functions cannot be passed from a Server Component to a client one, so a
99
+ `fallback` function, `onError`, `beforeCapture` and `onReset` (and
100
+ `withErrorBoundary` and `reactErrorHandler`, which are called rather than
101
+ rendered) only work in a file of your own that starts with `"use client"`:
102
+
103
+ ```tsx
104
+ "use client";
105
+ import type { ReactNode } from "react";
106
+ import { StarkoErrorBoundary } from "@starko-one/sdk/react";
107
+
108
+ export function ClientBoundary({ children }: { children: ReactNode }) {
109
+ return (
110
+ <StarkoErrorBoundary
111
+ fallback={({ resetError }) => <button onClick={resetError}>Something went wrong. Try again</button>}
112
+ beforeCapture={(scope) => scope.setTag("section", "dashboard")}
113
+ >
114
+ {children}
115
+ </StarkoErrorBoundary>
116
+ );
117
+ }
118
+ ```
119
+
120
+ Render `ClientBoundary` from the Server Component instead.
121
+
122
+ For route segments, Next's own `error.tsx` and `global-error.tsx` are the
123
+ usual boundaries; see [nextjs.md](./nextjs.md#errors-shown-by-global-errortsx-and-errortsx).
124
+
125
+ ## `withErrorBoundary`
126
+
127
+ Wraps a component in a `StarkoErrorBoundary`; the second argument takes the
128
+ same props as the boundary (without `children`).
129
+
130
+ ```tsx
131
+ import { withErrorBoundary } from "@starko-one/sdk/react";
132
+
133
+ function OrderHistory({ customerId }: { customerId: string }) {
134
+ return <section>Orders of {customerId}</section>;
135
+ }
136
+
137
+ export const SafeOrderHistory = withErrorBoundary(OrderHistory, {
138
+ fallback: <p>Order history is unavailable.</p>,
139
+ });
140
+ ```
141
+
142
+ ## React 19 root handlers: `reactErrorHandler`
143
+
144
+ React 19's `createRoot` and `hydrateRoot` take `onUncaughtError`,
145
+ `onCaughtError` and `onRecoverableError`. `reactErrorHandler()` returns all
146
+ three:
147
+
148
+ ```tsx
149
+ import { hydrateRoot } from "react-dom/client";
150
+ import { reactErrorHandler } from "@starko-one/sdk/react";
151
+
152
+ function App() {
153
+ return <h1>Shop</h1>;
154
+ }
155
+
156
+ hydrateRoot(document.getElementById("root")!, <App />, {
157
+ ...reactErrorHandler({
158
+ onCaughtError(error, errorInfo) {
159
+ console.warn("caught by a boundary", error, errorInfo.componentStack);
160
+ },
161
+ }),
162
+ identifierPrefix: "shop",
163
+ });
164
+ ```
165
+
166
+ | Hook | Captured as | Then, without your callback |
167
+ | --- | --- | --- |
168
+ | `onUncaughtError` | `react.onUncaughtError`, unhandled | What React does by default: the error is reported to the page (`reportError`). |
169
+ | `onCaughtError` | `react.onCaughtError`, handled | `console.error(error)`, as React does. |
170
+ | `onRecoverableError` | `react.onRecoverableError`, handled | Reported to the page, as React does. |
171
+
172
+ Each event carries the component stack in `contexts.react`. A callback you
173
+ pass for a hook runs instead of React's default for that hook, as when you
174
+ pass it to React directly. An error caught by a `StarkoErrorBoundary` is
175
+ left to the boundary, so it is one event, not two. An error reported once is
176
+ not reported again when it reaches the page's global error handler.
177
+
178
+ ## What `handled` means
179
+
180
+ Every event records `mechanism.handled`:
181
+
182
+ - `false`: the error reached the user without your code dealing with it. Uncaught
183
+ errors, `onUncaughtError`, and a `StarkoErrorBoundary` **without** a
184
+ `fallback` (the subtree simply disappears).
185
+ - `true`: your code caught it. `captureException`, `onCaughtError`,
186
+ `onRecoverableError`, and a `StarkoErrorBoundary` **with** a `fallback`
187
+ (the user saw your fallback).