@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.
- package/CHANGELOG.md +248 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-BAFm4Lxj.d.ts +558 -0
- package/dist/api-DNrctwJu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-2PM4FRM5.cjs +431 -0
- package/dist/chunk-335HNCOJ.js +249 -0
- package/dist/chunk-3AW5B2WW.js +115 -0
- package/dist/chunk-3R5TQAWD.js +216 -0
- package/dist/chunk-6H5MOPTQ.cjs +1230 -0
- package/dist/chunk-7TKNT3QJ.cjs +2487 -0
- package/dist/chunk-A4WLNFMU.cjs +220 -0
- package/dist/chunk-ALYFFOPR.cjs +134 -0
- package/dist/chunk-BVVFVRMO.js +1113 -0
- package/dist/chunk-CIHNKN62.cjs +15 -0
- package/dist/chunk-CMGCH6HD.js +1212 -0
- package/dist/chunk-D6QAPQ7L.cjs +56 -0
- package/dist/chunk-DUO5V6WZ.js +213 -0
- package/dist/chunk-EC2WZ6PG.js +90 -0
- package/dist/chunk-EFURLFJT.cjs +187 -0
- package/dist/chunk-EROUORMY.js +53 -0
- package/dist/chunk-LXBXFOAP.cjs +96 -0
- package/dist/chunk-MF6SA6DB.js +563 -0
- package/dist/chunk-N5R6ORIB.js +413 -0
- package/dist/chunk-N6R6BWHK.cjs +142 -0
- package/dist/chunk-QAGGN2T7.cjs +225 -0
- package/dist/chunk-QV4HRIDD.cjs +659 -0
- package/dist/chunk-TKNDYQB3.cjs +583 -0
- package/dist/chunk-UI5YC4TH.js +131 -0
- package/dist/chunk-VEHZYLK6.cjs +1151 -0
- package/dist/chunk-VNCWOGTI.js +12 -0
- package/dist/chunk-VWNIOGE6.js +180 -0
- package/dist/chunk-WDKRKGYF.js +608 -0
- package/dist/chunk-XOZIXBUK.js +2462 -0
- package/dist/chunk-ZS3K3SDR.cjs +258 -0
- package/dist/cli/index.cjs +2780 -0
- package/dist/common-DLFAqL2d.d.cts +36 -0
- package/dist/common-DbSXkaw6.d.ts +36 -0
- package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
- package/dist/dedupe-DoYiSx-9.d.ts +13 -0
- package/dist/handler-BcnsnvhF.d.cts +82 -0
- package/dist/handler-qHzilC9T.d.ts +82 -0
- package/dist/index.cjs +309 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +277 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +263 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-BUhWuWJX.d.cts +79 -0
- package/dist/options-BUhWuWJX.d.ts +79 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-D1ouJm2h.d.cts +628 -0
- package/dist/scope-D1ouJm2h.d.ts +628 -0
- package/dist/server-edge-7624N3WF.cjs +51 -0
- package/dist/server-edge-BEEXWL7T.js +48 -0
- package/dist/server-node-ET4LIPEC.cjs +27 -0
- package/dist/server-node-TQUVMZUC.js +24 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
- package/dist/session-propagation-RM5py1bp.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +386 -0
- package/docs/configuration.md +310 -0
- package/docs/nextjs.md +488 -0
- package/docs/node.md +427 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +482 -0
- package/docs/troubleshooting.md +263 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +547 -0
- package/package.json +191 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@starko-one/sdk`. Versions follow
|
|
4
|
+
[semantic versioning](https://semver.org); while the version is below 1.0, a
|
|
5
|
+
minor version may contain breaking changes, and they are listed here.
|
|
6
|
+
|
|
7
|
+
## 0.1.0-beta.1
|
|
8
|
+
|
|
9
|
+
Fixes found by the first install in a large Next.js app (5,226 source maps),
|
|
10
|
+
whose upload stopped at the 3-minute deadline after 45 maps without saying
|
|
11
|
+
how far it had got.
|
|
12
|
+
|
|
13
|
+
### Source-map upload (build plugins, `withStarko`, the CLI)
|
|
14
|
+
|
|
15
|
+
- **The bulk upload.** When the Starko server offers it, each map now goes
|
|
16
|
+
from the build machine straight to Starko's storage through a signed URL
|
|
17
|
+
valid for 10 minutes and for that map only; the Starko host receives
|
|
18
|
+
small requests only (`bulk/check` of 1,000 maps, `bulk/start` and
|
|
19
|
+
`bulk/finish` of 200). A map is gzipped once and those exact bytes are
|
|
20
|
+
declared and sent. 16 maps are sent at the same time by default.
|
|
21
|
+
Measured against a local stand-in for the server, with modelled
|
|
22
|
+
latencies (the server verifying 6 of a workspace's maps at a time, 0.4 s
|
|
23
|
+
each): a 5,226-map first upload in 6.0 min (2,382 maps within the
|
|
24
|
+
3-minute default) where v1 sent 136 in 3 minutes; a later build whose
|
|
25
|
+
maps are all stored in 5.4 s, as with v1.
|
|
26
|
+
- New option `uploadProtocol` (`"auto"`, the default; `"bulk"`; `"v1"`)
|
|
27
|
+
and CLI flag `--protocol <auto|bulk|v1>`. `"auto"` asks the server once,
|
|
28
|
+
at the start of the upload, and uses v1 when the server has no bulk
|
|
29
|
+
upload (a server that predates it answers 404 or 405); the first log line
|
|
30
|
+
says which protocol is used. When uploads to the storage host fail three
|
|
31
|
+
times in a row (a proxy or a firewall that lets only the Starko host
|
|
32
|
+
through), every map storage does not hold goes through v1, the few
|
|
33
|
+
already reserved for storage included (the server lets v1 take over a
|
|
34
|
+
reservation whose object it does not hold), with a warning naming the
|
|
35
|
+
storage host; `"bulk"` stops instead, `"v1"` never contacts storage.
|
|
36
|
+
- Every answer the server gives is handled: an expiring URL is renewed
|
|
37
|
+
before its upload (the server signs the same object again), timed from
|
|
38
|
+
the server's `expires_in_s` on the build machine's monotonic clock, so a
|
|
39
|
+
machine whose clock is off neither PUTs to an expired URL nor renews a
|
|
40
|
+
valid one; `uploaded` is finished without a PUT; a target storage
|
|
41
|
+
answered (2xx or 4xx) is never PUT again, so `not_uploaded` goes back
|
|
42
|
+
through `bulk/start`; an upload storage refused is finished anyway, then
|
|
43
|
+
started once more; `busy` (rare: only after repeated restarts of one
|
|
44
|
+
debug id) is waited out up to a minute; `not_reserved` starts the map
|
|
45
|
+
again; `retry` finishes it again, and only finishes that settled none of
|
|
46
|
+
their maps count towards giving up; `failed` fails that map at once and
|
|
47
|
+
it is not sent again in the build (the same bytes fail again, and a
|
|
48
|
+
failed map counts against the key's daily budget), as does `conflict`;
|
|
49
|
+
`pending` counts as done; `over_allowance` and a spent daily budget stop
|
|
50
|
+
the upload, after finishing the maps already reserved; a `503` with
|
|
51
|
+
`Retry-After` (bulk/start, and v1's complete) is retried after that time;
|
|
52
|
+
a `423` (the server switched source-map uploads off) stops the upload
|
|
53
|
+
without retrying, with v1 too.
|
|
54
|
+
- Each request to the Starko host waits for its route's longest run on the
|
|
55
|
+
server plus 15 s (the contract's `SOURCEMAP_ROUTE_MAX_SECONDS`: 45 s for
|
|
56
|
+
the checks and `bulk/start`, 75 s for v1's upload and complete, 135 s for
|
|
57
|
+
`bulk/finish`), instead of 30 s for all: a `bulk/finish` that verifies
|
|
58
|
+
for a minute is no longer counted as a network error. `bulk/finish` runs
|
|
59
|
+
two at a time: the server verifies a workspace's maps 6 at a time
|
|
60
|
+
whatever the number of requests.
|
|
61
|
+
- `file_name` is at most 512 characters (`SOURCEMAP_MAX_FILE_NAME`); a
|
|
62
|
+
longer path keeps its end after a `…` (was: its first 1,000 characters).
|
|
63
|
+
- Signed storage URLs are credentials: they never appear in a log line or
|
|
64
|
+
an error message, also when an upload fails; only the storage host is
|
|
65
|
+
named. The secret key is never sent to storage, and no redirect
|
|
66
|
+
is followed, from Starko or from storage.
|
|
67
|
+
- v1: a `409` for a map whose bulk upload already put an object in
|
|
68
|
+
Starko's storage now says so (it is accepted again within about 20
|
|
69
|
+
minutes) instead of reporting a different map for the debug id. A
|
|
70
|
+
reservation with nothing in storage is taken over by v1 at once.
|
|
71
|
+
- v1 (servers without the bulk upload, or `uploadProtocol: "v1"`) is
|
|
72
|
+
much faster for thousands of maps too. The steps overlap: checks start
|
|
73
|
+
while maps are still being read, and uploads start as soon as a check is
|
|
74
|
+
answered. Checks carry 500 maps each (was 100) and four run at once (was
|
|
75
|
+
one at a time). 8 maps are sent at the same time (was 4). Measured against
|
|
76
|
+
a local server answering like production did (about 1 s per check, 6 s
|
|
77
|
+
per upload, 4 s per complete): about 140 maps in 3 minutes, about 275 with
|
|
78
|
+
`uploadConcurrency: 16` (was 48). A build whose maps are all on the server
|
|
79
|
+
went from 68 s to 6 s.
|
|
80
|
+
- New option `uploadConcurrency` (default 16 with the bulk upload, 8 with
|
|
81
|
+
v1; at most 16, larger values are clamped) and CLI flag
|
|
82
|
+
`--concurrency <n>` (1 to 16).
|
|
83
|
+
- Requests are paced under the server's limit of 2,000 a minute per API key
|
|
84
|
+
(at most 1,900 a minute). A `429` pauses every request for its
|
|
85
|
+
`Retry-After`, with one warning instead of one per request. A `429`
|
|
86
|
+
asking to wait more than two minutes (the key's daily upload budget is
|
|
87
|
+
spent) or past the deadline stops the upload at once with the server's
|
|
88
|
+
message, instead of retrying it map by map. So does a full storage
|
|
89
|
+
allowance (`413` with v1, `over_allowance` with the bulk upload).
|
|
90
|
+
- At most 256 MiB of map content is held for sending at once (a larger map
|
|
91
|
+
is sent alone), whatever the concurrency.
|
|
92
|
+
- Logging: a progress line every 30 seconds during a long upload; when the
|
|
93
|
+
deadline passes, how many maps were uploaded, how many the server already
|
|
94
|
+
had, how many were not sent (and how many were stopped while being
|
|
95
|
+
sent), and that the next build continues from there. After a fatal error,
|
|
96
|
+
what was uploaded before it. At most 20 per-map failures are printed,
|
|
97
|
+
then a count. The summary line gives the time taken.
|
|
98
|
+
- The inject and collect passes look at 8 files at a time, and leave a
|
|
99
|
+
bundle that already registers its debug id (Turbopack on Next 16) alone
|
|
100
|
+
without parsing its map when the map already names the id: 6.3 s down to
|
|
101
|
+
about 1.3 s for 5,226 bundles.
|
|
102
|
+
- The default deadline stays 3 minutes: later builds send only the chunks
|
|
103
|
+
that changed and finish in seconds; the docs say what to set for a large
|
|
104
|
+
app's first upload.
|
|
105
|
+
|
|
106
|
+
### Docs
|
|
107
|
+
|
|
108
|
+
- The bulk upload, precisely: requests, answers, every per-map status and
|
|
109
|
+
what a sender does with it (wire-format.md); which protocol, proxies and
|
|
110
|
+
the storage host, measurements (source-maps.md); `uploadProtocol`
|
|
111
|
+
(configuration.md); the storage host, expired URLs, the allowance
|
|
112
|
+
(troubleshooting.md, section 11).
|
|
113
|
+
- Large builds: what to expect on the first upload, later builds,
|
|
114
|
+
`uploadTimeoutMs` and `uploadConcurrency` (source-maps.md, nextjs.md,
|
|
115
|
+
configuration.md).
|
|
116
|
+
- Next.js: `environment` from the host's variable (`VERCEL_ENV`,
|
|
117
|
+
`NEXT_PUBLIC_VERCEL_ENV`) with `NODE_ENV` only as the fallback, since
|
|
118
|
+
preview builds have `NODE_ENV=production`; `global-error.tsx` with
|
|
119
|
+
`retry` (Next 16.3) and the earlier props; a setup driven by environment
|
|
120
|
+
variables that starts nothing without a workspace key, with a guarded
|
|
121
|
+
`onRequestError`; config wrappers must keep
|
|
122
|
+
`compiler.runAfterProductionCompile`; the upload key with
|
|
123
|
+
`vercel pull` + `vercel build` on GitHub Actions.
|
|
124
|
+
- Node.js: dropping server events by request path with `beforeSend`
|
|
125
|
+
(`event.request.url`; `denyUrls` matches stack frames), and the argument
|
|
126
|
+
order of `runWithRequestScope(fn, request)`.
|
|
127
|
+
- One table of the environment variables the SDK reads: `STARKO_HOST` is
|
|
128
|
+
read by the build plugins and the CLI only; the runtime `host` option has
|
|
129
|
+
no environment variable.
|
|
130
|
+
|
|
131
|
+
## 0.1.0-beta.0
|
|
132
|
+
|
|
133
|
+
First public beta.
|
|
134
|
+
|
|
135
|
+
### `@starko-one/sdk/browser` (and the script-tag bundle `dist/starko.min.js`)
|
|
136
|
+
|
|
137
|
+
- `init` with uncaught errors and unhandled promise rejections captured,
|
|
138
|
+
stack traces parsed for Chrome, Firefox and Safari, and `cause` chains and
|
|
139
|
+
`AggregateError`s reported as one event.
|
|
140
|
+
- Breadcrumbs: clicks (as a selector, never text or input values),
|
|
141
|
+
navigation, `fetch` and XHR (method, URL, status), console warnings and
|
|
142
|
+
errors.
|
|
143
|
+
- `setUser`, `identify(user, userHash)` for verified customers, tags, extra,
|
|
144
|
+
contexts, `withScope`, `captureException`, `captureMessage`.
|
|
145
|
+
- Noise filters (extensions, `Script error.`, `ResizeObserver`, aborted and
|
|
146
|
+
failed requests), `ignoreErrors`, `allowUrls`, `denyUrls`, `sampleRate`,
|
|
147
|
+
`beforeSend`, `beforeBreadcrumb`, and a duplicate filter that compares
|
|
148
|
+
the error, its fingerprint, the user and the session.
|
|
149
|
+
- Rate limits: per error (its type and message, with numbers and ids
|
|
150
|
+
masked) 10 at once then 1 every 10 seconds, and 100 events per page load.
|
|
151
|
+
Drops are reported in the console at most once a minute per limit, with
|
|
152
|
+
a count.
|
|
153
|
+
- Batching, retries with back-off that honour `Retry-After`, a pause after
|
|
154
|
+
repeated failures, and a `keepalive` send when the page is hidden.
|
|
155
|
+
Redirects are never followed.
|
|
156
|
+
- The workspace's remote config (on/off, sample rate, suppression rules).
|
|
157
|
+
- URL redaction (fragments, credentials, sensitive query values) on every
|
|
158
|
+
URL sent.
|
|
159
|
+
- Works with the Starko widget: one capture, the recorder's session id and
|
|
160
|
+
the widget's verified customer token on every error.
|
|
161
|
+
- Same-origin requests carry the session id, so server errors link to the
|
|
162
|
+
browser session.
|
|
163
|
+
- Script tag: starts itself from `data-workspace-key`, `data-release`,
|
|
164
|
+
`data-environment`, `data-host`, `data-debug`; works as a classic,
|
|
165
|
+
`defer`, `async` or `type="module"` script. 19.04 kB gzipped.
|
|
166
|
+
- `sdk.version` on every event is the package version.
|
|
167
|
+
|
|
168
|
+
### `@starko-one/sdk/node`
|
|
169
|
+
|
|
170
|
+
- `init` for Node.js 18 and later, on Node built-ins only.
|
|
171
|
+
- Every request of an HTTP, HTTPS or HTTP/2 server runs in its own scope
|
|
172
|
+
without middleware: `request`, `checkContinue`, `checkExpectation`,
|
|
173
|
+
`upgrade` and `connect` events, and HTTP/2's compatibility API and raw
|
|
174
|
+
`stream` event, for servers created before or after `init` (tested on
|
|
175
|
+
Node 20, 22, 24 and 26).
|
|
176
|
+
- Request scopes start from a base fixed when the process begins serving:
|
|
177
|
+
`init({ user })` and the tags, extra and contexts set before. Code
|
|
178
|
+
outside any request after that (jobs, timers, pool callbacks) gets a
|
|
179
|
+
scope confined to its own async context, so nothing it sets reaches a
|
|
180
|
+
request or another job. `markServing()` begins serving explicitly.
|
|
181
|
+
- Uncaught exceptions and unhandled rejections captured without changing
|
|
182
|
+
how Node exits; the crash event is sent before the process exits. In a
|
|
183
|
+
worker thread the error is captured, sent, and handed back to Node, so
|
|
184
|
+
the parent's `Worker` still gets `'error'`.
|
|
185
|
+
- Queued events sent when the event loop empties and on `SIGTERM` /
|
|
186
|
+
`SIGINT` (when the app has no handler), without waiting for the remote
|
|
187
|
+
config; the SDK never keeps the process alive otherwise.
|
|
188
|
+
- Source lines around in-app frames, read only from source files inside the
|
|
189
|
+
application root (never a filesystem root).
|
|
190
|
+
- Console breadcrumbs, request data, host and runtime context; duplicates
|
|
191
|
+
are compared per request, user and session.
|
|
192
|
+
- `expressRequestHandler` and `expressErrorHandler` for Express 4 and 5;
|
|
193
|
+
`wrapHandler` for other frameworks and serverless functions;
|
|
194
|
+
`runWithRequestScope`.
|
|
195
|
+
- Optional secret key (`apiKey`) so the server's user ids are trusted. A
|
|
196
|
+
key the ingest API refuses drops the batch without retrying and is
|
|
197
|
+
reported once.
|
|
198
|
+
- Proxies through `NODE_USE_ENV_PROXY` (Node 24.5+) or a `fetch` of your own.
|
|
199
|
+
- Limits for long-running servers: 300 events a minute, no lifetime cap.
|
|
200
|
+
- The release a build plugin wrote into a bundle is read for each event,
|
|
201
|
+
so `init` may run before the bundle loads.
|
|
202
|
+
|
|
203
|
+
### `@starko-one/sdk/next`, `/next/client`, `/next/config`
|
|
204
|
+
|
|
205
|
+
- `register` and `onRequestError` for `instrumentation.ts` on the Node.js
|
|
206
|
+
and Edge runtimes, with route, router kind, route type and render source.
|
|
207
|
+
`register()` begins serving, so a request that arrives while it runs
|
|
208
|
+
keeps what it sets to itself.
|
|
209
|
+
- `init` and `captureGlobalError` for `instrumentation-client.ts` and
|
|
210
|
+
`global-error.tsx`.
|
|
211
|
+
- Next's control flow (`redirect()`, `notFound()`, …) never reported.
|
|
212
|
+
- Flushes that never delay the error response: the platform's `waitUntil`
|
|
213
|
+
on Vercel and Cloudflare, the queue on long-lived servers.
|
|
214
|
+
- `withStarko(nextConfig)`: debug ids and source-map upload for webpack and
|
|
215
|
+
Turbopack builds, maps it switched on deleted from `.next` afterwards.
|
|
216
|
+
On Next 16 it uses Turbopack's native debug ids. It never rewrites a
|
|
217
|
+
client chunk that registers its own debug id, and with
|
|
218
|
+
`experimental.sri` no client chunk at all, so integrity hashes stay valid.
|
|
219
|
+
- The build's release is compiled into the app (`env.STARKO_BUILD_RELEASE`,
|
|
220
|
+
set by `withStarko`), so browser, server and Edge events carry the same
|
|
221
|
+
release as their source maps without a `release` in `init` or `register`.
|
|
222
|
+
- `output: "standalone"` on webpack builds keeps the server source maps that
|
|
223
|
+
Next copies afterwards.
|
|
224
|
+
|
|
225
|
+
### `@starko-one/sdk/react`
|
|
226
|
+
|
|
227
|
+
- `StarkoErrorBoundary`, `withErrorBoundary`, and `reactErrorHandler` for
|
|
228
|
+
React 19's root error options.
|
|
229
|
+
- A client module (`"use client"`): a Server Component can render
|
|
230
|
+
`StarkoErrorBoundary` with a React-node fallback.
|
|
231
|
+
|
|
232
|
+
### `@starko-one/sdk/vite`, `/rollup`, `/webpack` and the `starko` command
|
|
233
|
+
|
|
234
|
+
- Debug ids injected into every bundle, source maps uploaded, maps the
|
|
235
|
+
plugin switched on removed from the output whatever the upload's outcome.
|
|
236
|
+
Rollup decides per output; webpack treats a `SourceMapDevToolPlugin` in
|
|
237
|
+
your config as yours and removes only the maps it added.
|
|
238
|
+
- Bundles that already carry a debug id (Turbopack, Rolldown, Sentry's
|
|
239
|
+
plugins) keep it. Index source maps (`sections`) are supported.
|
|
240
|
+
- Uploads never follow a redirect.
|
|
241
|
+
- `starko sourcemaps inject <dir>` and `starko sourcemaps upload <dir>` for
|
|
242
|
+
other build tools and CI.
|
|
243
|
+
|
|
244
|
+
### Package
|
|
245
|
+
|
|
246
|
+
- ESM and CommonJS builds of every entry, each with its own type
|
|
247
|
+
declarations (`.d.ts` and `.d.cts`), so TypeScript resolves types under
|
|
248
|
+
`node16` / `nodenext` for both `import` and `require`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
Copyright (c) 2026 Starko. All rights reserved.
|
|
2
|
+
|
|
3
|
+
This software is proprietary to Starko. It is not open source.
|
|
4
|
+
|
|
5
|
+
It may be installed and used only by Starko customers, in their own
|
|
6
|
+
applications, to send data to the Starko service, and only under an
|
|
7
|
+
agreement with Starko that covers such use. No other use, copying,
|
|
8
|
+
modification, redistribution or sublicensing is permitted without Starko's
|
|
9
|
+
prior written permission. Making this package available does not by itself
|
|
10
|
+
grant any licence.
|
|
11
|
+
|
|
12
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
13
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
14
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
15
|
+
|
|
16
|
+
Some files adapt code from third-party open-source projects. Those portions
|
|
17
|
+
remain under their original licences; see NOTICE.
|
package/NOTICE
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
@starko-one/sdk
|
|
2
|
+
Copyright (c) 2026 Starko
|
|
3
|
+
|
|
4
|
+
This package is proprietary (see LICENSE). It is original work, structured
|
|
5
|
+
after two open-source SDKs. Where a source file adapts code from one of
|
|
6
|
+
them, that file carries the original copyright notice in its header and is
|
|
7
|
+
listed below; those portions are used under the MIT License, whose text is
|
|
8
|
+
at the end of this file and must stay in every copy of the package. Keep
|
|
9
|
+
the list current: add a line whenever a file is adapted, remove it when the
|
|
10
|
+
adaptation is gone.
|
|
11
|
+
|
|
12
|
+
Upstream projects and licences
|
|
13
|
+
|
|
14
|
+
sentry-javascript MIT Copyright (c) 2012 Functional Software, Inc. dba Sentry
|
|
15
|
+
sentry-javascript-bundler-plugins MIT Copyright (c) 2022 Functional Software, Inc. dba Sentry
|
|
16
|
+
posthog-js (packages/core, packages/node) MIT Copyright (c) 2020 PostHog Inc.
|
|
17
|
+
posthog-js (packages/plugin-utils, rollup-plugin, webpack-plugin) MIT Copyright (c) 2020-2025 PostHog, Inc.
|
|
18
|
+
posthog (cli/, rust/cymbal) MIT Copyright (c) 2020-2026 PostHog Inc.
|
|
19
|
+
|
|
20
|
+
Nothing is taken from posthog-js packages/browser (Apache-2.0) or from the
|
|
21
|
+
posthog repository's ee/ directory.
|
|
22
|
+
|
|
23
|
+
Adapted files
|
|
24
|
+
|
|
25
|
+
src/build/shared/snippet.ts posthog-js packages/plugin-utils/src/chunk-ids.ts (runtime snippet)
|
|
26
|
+
src/build/shared/debug-id.ts posthog-js packages/plugin-utils/src/chunk-ids.ts (UUIDv5 id, comment detection)
|
|
27
|
+
src/build/shared/prologue.ts posthog-js packages/rollup-plugin/src/index.ts, packages/webpack-plugin/src/index.ts (directive prologue)
|
|
28
|
+
src/core/exceptions.ts sentry-javascript (ErrorEvent message pattern, wording for non-Error values); posthog-js packages/core (coercer order)
|
|
29
|
+
src/core/stack-parsers.ts sentry-javascript packages/browser/src/stack-parsers.ts (Firefox eval/Function frame pattern)
|
|
30
|
+
src/core/normalize.ts sentry-javascript packages/core/src/utils/normalize.ts (normalize / normalizeToSize: depth-limited walk, markers, byte budget)
|
|
31
|
+
src/core/debug-ids.ts posthog-js packages/core/src/error-tracking/chunk-ids.ts, itself from sentry-javascript (debug-id map algorithm)
|
|
32
|
+
src/node/integrations/process.ts posthog-js packages/node/src/extensions/error-tracking/autocapture.ts (--unhandled-rejections mode lookup);
|
|
33
|
+
sentry-javascript packages/node/src/integrations/onuncaughtexception.ts, packages/node/src/utils/errorhandling.ts (fatal path: counting the app's listeners, print, bounded flush, exit 1, a second error while exiting)
|
|
34
|
+
src/node/integrations/uncaught-exception.ts sentry-javascript packages/node/src/integrations/onuncaughtexception.ts (exit only without app listeners, an error while shutting down)
|
|
35
|
+
src/node/express.ts sentry-javascript @sentry/node Express error handler (status fields read, 5xx-only default, shouldHandleError, next(err))
|
|
36
|
+
src/react/index.ts sentry-javascript packages/react/src/errorboundary.tsx, packages/react/src/error.ts (error boundary API, reactErrorHandler)
|
|
37
|
+
src/node/integrations/unhandled-rejection.ts posthog-js packages/node/src/extensions/error-tracking/autocapture.ts (listening only next to the app's listeners in throw mode)
|
|
38
|
+
|
|
39
|
+
The MIT License (applies to the adapted portions above, under the upstream
|
|
40
|
+
copyright notices listed in "Upstream projects and licences")
|
|
41
|
+
|
|
42
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
43
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
44
|
+
in the Software without restriction, including without limitation the rights
|
|
45
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
46
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
47
|
+
furnished to do so, subject to the following conditions:
|
|
48
|
+
|
|
49
|
+
The above copyright notice and this permission notice shall be included in all
|
|
50
|
+
copies or substantial portions of the Software.
|
|
51
|
+
|
|
52
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
53
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
54
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
55
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
56
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
57
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
58
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,82 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @starko-one/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Error tracking for browsers, Node.js, Next.js and React that reports to
|
|
4
|
+
[Starko](https://v2.starko.one). Each error arrives linked to the session it
|
|
5
|
+
happened in (and its recording, when the Starko widget records), to the
|
|
6
|
+
customer who hit it once you identify them, and, when you choose, to a bug
|
|
7
|
+
ticket.
|
|
8
|
+
|
|
9
|
+
Status: **beta** (`0.1.0-beta.1`). The public API may still change before 1.0;
|
|
10
|
+
breaking changes are listed in [CHANGELOG.md](./CHANGELOG.md).
|
|
11
|
+
|
|
12
|
+
## Quick start (browser app with a bundler)
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm install @starko-one/sdk
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Call `init` once, as early as possible in your app's entry file:
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
22
|
+
|
|
23
|
+
Starko.init({
|
|
24
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
25
|
+
release: "shop@4.12.0",
|
|
26
|
+
environment: "production",
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The workspace key is public: it lets a page send errors and nothing else.
|
|
31
|
+
Uncaught errors and unhandled promise rejections are now reported. To see what
|
|
32
|
+
the SDK is doing, add `debug: true` and open the browser console.
|
|
33
|
+
|
|
34
|
+
Minified stack traces need source maps uploaded at build time: see
|
|
35
|
+
[source maps](./docs/source-maps.md). Nothing arrives? See
|
|
36
|
+
[troubleshooting](./docs/troubleshooting.md).
|
|
37
|
+
|
|
38
|
+
## Entry points
|
|
39
|
+
|
|
40
|
+
| Import | For |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `@starko-one/sdk/browser` | Browsers (any framework, or none). Also shipped as a script-tag bundle, `dist/starko.min.js` (19.04 kB gzipped). |
|
|
43
|
+
| `@starko-one/sdk/react` | `StarkoErrorBoundary`, `withErrorBoundary`, `reactErrorHandler` (React 18 and 19). A client module, so a Next.js Server Component can render the boundary. Use with `/browser` or `/next/client`. |
|
|
44
|
+
| `@starko-one/sdk/next` | Next.js server side: `register` and `onRequestError` for `instrumentation.ts`. |
|
|
45
|
+
| `@starko-one/sdk/next/client` | Next.js browser side, for `instrumentation-client.ts` and `global-error.tsx`. |
|
|
46
|
+
| `@starko-one/sdk/next/config` | `withStarko(nextConfig)`: source maps for Next.js builds. |
|
|
47
|
+
| `@starko-one/sdk/node` | Node.js 18 and later: servers, workers, scripts, serverless functions. |
|
|
48
|
+
| `@starko-one/sdk/vite`, `/rollup`, `/webpack` | Build plugins that upload source maps. |
|
|
49
|
+
| `@starko-one/sdk` | The environment-free core, for building your own integration or transport. Apps import a platform entry instead. |
|
|
50
|
+
| `starko` (command) | `starko sourcemaps inject` and `starko sourcemaps upload` for other build tools and CI. |
|
|
51
|
+
|
|
52
|
+
## Guides
|
|
53
|
+
|
|
54
|
+
- [Browser](./docs/browser.md): npm or script tag, identifying users, manual capture, filtering, offline behaviour.
|
|
55
|
+
- [React](./docs/react.md): the error boundary and React 19 root error hooks.
|
|
56
|
+
- [Next.js](./docs/nextjs.md): the three files a Next app needs, releases, Vercel and long-lived servers.
|
|
57
|
+
- [Node.js](./docs/node.md): per-request isolation, Express, serverless, crashes and shutdown.
|
|
58
|
+
- [Source maps](./docs/source-maps.md): Vite, Rollup, webpack, Next.js and the CLI.
|
|
59
|
+
- [Configuration reference](./docs/configuration.md): every option with its default, every integration.
|
|
60
|
+
- [Privacy](./docs/privacy.md): what is collected, what is not, and how to collect less.
|
|
61
|
+
- [Using it with the Starko widget](./docs/widget.md).
|
|
62
|
+
- [Other backends](./docs/other-backends.md): the HTTP API, and PostHog server SDKs pointed at Starko.
|
|
63
|
+
- [Troubleshooting](./docs/troubleshooting.md).
|
|
64
|
+
|
|
65
|
+
## What is collected by default
|
|
66
|
+
|
|
67
|
+
- The error: type, message, stack frames, and the chain of `cause`s.
|
|
68
|
+
- The page URL and referrer (browser) or the request's method, URL and route (server), with `#fragments`, `user:pass@` and the values of sensitive query parameters (`token`, `code`, `email`, `password`, …) removed.
|
|
69
|
+
- Breadcrumbs: clicks (as a short CSS selector, never text or input values), navigation, `fetch`/XHR method, URL and status, and `console.warn`/`console.error` text cut to 200 characters (servers: console only).
|
|
70
|
+
- The user only if you set one, and the Starko session id. Never request or response bodies, cookies or headers.
|
|
71
|
+
- On servers: host name, Node and OS versions, and source lines from your own source files.
|
|
72
|
+
|
|
73
|
+
Details and every switch to collect less: [privacy](./docs/privacy.md).
|
|
74
|
+
|
|
75
|
+
## Licence and attribution
|
|
76
|
+
|
|
77
|
+
Proprietary, not open source: see [LICENSE](./LICENSE). Starko customers may
|
|
78
|
+
use it in their own applications under their agreement with Starko. The SDK
|
|
79
|
+
is original work structured after two MIT-licensed open-source SDKs, Sentry's
|
|
80
|
+
JavaScript SDK and PostHog's JavaScript SDK; the files that adapt code from
|
|
81
|
+
them keep the upstream copyright notice, are listed in [NOTICE](./NOTICE)
|
|
82
|
+
and stay under the MIT License, whose text is in that file.
|