@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,547 @@
1
+ # Wire format v1
2
+
3
+ The contract between every Starko SDK and the Starko ingest API. The typed
4
+ version is [`src/types/wire.ts`](../src/types/wire.ts); valid examples are in
5
+ [`fixtures/wire/`](../fixtures/wire). The SDKs are thin producers of this
6
+ format: anything that can send this JSON can report errors to Starko.
7
+
8
+ ## Send errors
9
+
10
+ ```
11
+ POST {host}/api/v1/ingest/errors
12
+ ```
13
+
14
+ - `host` defaults to `https://v2.starko.one`.
15
+ - The body is JSON, optionally gzip-compressed (`Content-Encoding: gzip`, or
16
+ detected by the gzip magic bytes). Any `Content-Type` is accepted; browsers
17
+ send `text/plain` so the request needs no CORS preflight.
18
+ - The **workspace key** goes in the body (`workspace`). It is the workspace id
19
+ shown in Starko under Settings. It is public: it only lets a caller send
20
+ errors, never read anything.
21
+ - A server may also send a **secret key** (`Authorization: Bearer sk_starko_…`
22
+ with the `errors:write` scope, created in Starko under Settings). It is
23
+ optional. With it, the events are trusted: the `user.id` they name is linked
24
+ without a hash, and the per-IP limits do not apply. Never ship a secret key
25
+ to a browser.
26
+
27
+ ```json
28
+ {
29
+ "v": 1,
30
+ "workspace": "3ba57953-699d-4385-bc68-08fd6e7d9226",
31
+ "sdk": { "name": "starko.browser", "version": "0.1.0-beta.1" },
32
+ "sent_at": 1795000000500,
33
+ "events": [
34
+ {
35
+ "event_id": "0b0e7a52-5c1f-4c58-9a57-6f1d2f0c9a11",
36
+ "timestamp": 1795000000000,
37
+ "platform": "browser",
38
+ "level": "error",
39
+ "exception_list": [
40
+ {
41
+ "type": "TypeError",
42
+ "value": "Cannot read properties of undefined (reading 'total')",
43
+ "mechanism": { "type": "onerror", "handled": false },
44
+ "stacktrace": {
45
+ "type": "raw",
46
+ "frames": [
47
+ {
48
+ "platform": "web:javascript",
49
+ "filename": "https://shop.example.com/assets/checkout-4f9a2c.js",
50
+ "function": "renderTotals",
51
+ "lineno": 1,
52
+ "colno": 48213,
53
+ "in_app": true,
54
+ "chunk_id": "5b1f6c0e-7a55-5d0e-9d0c-2f4f8b7a9e10"
55
+ }
56
+ ]
57
+ }
58
+ }
59
+ ],
60
+ "release": "shop@4.12.0",
61
+ "environment": "production",
62
+ "session_id": "b2f7c1de-1c7c-4a1c-9d3f-9f5d7f0e6a55",
63
+ "user": { "id": "user_123", "email": "ana@example.com" },
64
+ "request": { "url": "https://shop.example.com/checkout?step=2" },
65
+ "tags": { "plan": "pro" },
66
+ "breadcrumbs": [
67
+ { "timestamp": 1794999998000, "type": "ui", "category": "click", "message": "button#pay" }
68
+ ]
69
+ }
70
+ ]
71
+ }
72
+ ```
73
+
74
+ ### Envelope
75
+
76
+ | Field | Required | Meaning |
77
+ | --- | --- | --- |
78
+ | `v` | yes | Always `1`. |
79
+ | `workspace` | yes | Workspace key. |
80
+ | `sdk` | yes | `name` and `version` of the sender. |
81
+ | `sent_at` | yes | Sender's clock (epoch ms) when this request left. Set it again on every retry. |
82
+ | `events` | yes | 1 to 20 events. |
83
+
84
+ ### Event
85
+
86
+ | Field | Required | Meaning |
87
+ | --- | --- | --- |
88
+ | `event_id` | yes | UUID minted by the sender. An event id is counted once per workspace, so a retry never double-counts. |
89
+ | `timestamp` | yes | Epoch ms when the error happened, on the sender's clock. |
90
+ | `platform` | yes | `browser`, `node`, `dotnet`, `php`, `python`, `ruby`, `go`, `java` or `other`. |
91
+ | `level` | yes | `fatal`, `error`, `warning`, `info` or `debug`. Only `error` and `fatal` can file a ticket. |
92
+ | `exception_list` | yes | The thrown error first, then its causes. At least one. |
93
+ | `fingerprint` | no | Custom grouping key: events with the same value become one issue. |
94
+ | `release` | no | App version. Frames are resolved by `chunk_id`, not by release; send the release the source maps were uploaded for. |
95
+ | `environment` | no | `production`, `staging`, … |
96
+ | `session_id` | no | Session shared with the Starko widget and session replay. |
97
+ | `user` | no | `id` (your own user id), `email`, `name`, `hash`. See identity below. |
98
+ | `client_token` | no | The Starko widget's client token when the widget is on the page. |
99
+ | `request` | no | `url`, `method`, `route`, `referrer`. |
100
+ | `user_agent` | no | For server SDKs forwarding a browser's user agent. |
101
+ | `server_name` | no | Host that captured the event. |
102
+ | `tags` | no | String key/value pairs you can filter on. |
103
+ | `extra` | no | Free-form JSON shown on the occurrence. |
104
+ | `contexts` | no | Named blocks such as `runtime`, `os`, `browser`. |
105
+ | `breadcrumbs` | no | What happened before the error, oldest first. |
106
+ | `trace` | no | `trace_id`, `span_id`. |
107
+
108
+ **Time.** The server corrects `timestamp` by the clock skew it sees
109
+ (receipt time minus `sent_at`, applied when larger than 5 minutes), then
110
+ replaces it with the receipt time when it is still more than 24 hours off.
111
+
112
+ ### Exception
113
+
114
+ | Field | Required | Meaning |
115
+ | --- | --- | --- |
116
+ | `type` | yes | Error class name. |
117
+ | `value` | yes | Message. |
118
+ | `module` | no | Namespace or module of the error class. |
119
+ | `mechanism` | no | `type` (what caught it), `handled` (false for unhandled), `synthetic`, and `source` / `exception_id` / `parent_id` for chains. |
120
+ | `stacktrace` | no | `{ "type": "raw", "frames": [...] }`. |
121
+
122
+ **Frames are ordered most recent call first**: `frames[0]` is where the error
123
+ was thrown. Some other SDKs (Sentry's, for one) send the opposite order; code
124
+ adapted from their parsers must not reverse.
125
+
126
+ ### Frame
127
+
128
+ | Field | Required | Meaning |
129
+ | --- | --- | --- |
130
+ | `platform` | yes | `web:javascript`, `node:javascript` or `custom`. |
131
+ | `lang` | for `custom` | Lowercase language name: `dotnet`, `php`, `python`, … |
132
+ | `filename` | no | Script URL or file path. |
133
+ | `abs_path` | no | Absolute path when `filename` is relative. |
134
+ | `function` | no | Function or method name. |
135
+ | `module` | no | Module, namespace or class. |
136
+ | `lineno`, `colno` | no | 1-based. |
137
+ | `in_app` | no | `false` for dependencies and runtime internals. When absent, the server decides. |
138
+ | `chunk_id` | no | Debug id of the bundle; the server finds the source map by it. |
139
+ | `context_line`, `pre_context`, `post_context` | no | Source lines around the frame, when the sender can read source. |
140
+ | `resolved` | no | `true` when the frame already shows original source. Honoured on `custom` frames only. |
141
+
142
+ JavaScript frames from a minified bundle are resolved on the server with the
143
+ uploaded source map, whatever `resolved` says. `custom` frames are stored as
144
+ sent: languages that run their source directly (PHP, Python) or carry debug
145
+ info (.NET) need no upload.
146
+
147
+ The server only ever uses source maps that were uploaded to it. It never
148
+ fetches a script or a source map from a URL found in an event.
149
+
150
+ ### Responses
151
+
152
+ Every response is JSON: `{ "ok": boolean, "message": string, "data": … }`.
153
+ When a request is not accepted, `data.reason` says why.
154
+
155
+ | Status | `data.reason` | Meaning | What a sender does |
156
+ | --- | --- | --- | --- |
157
+ | 200 | | `data: { accepted, rejected }`. Rejected events failed validation; the rest were taken. | Nothing. |
158
+ | 3xx | | A proxy or a misconfigured `host` (`http://`, an apex domain). The ingest API never redirects. | Do NOT follow it (the POST would become a GET and the key would go to another host): drop the batch and tell the user, naming the `Location`. |
159
+ | 400 | `invalid`, `unsupported_version` | Malformed envelope, or a `v` the server does not speak (`data.supported_versions`). | Drop the batch. |
160
+ | 401 | `invalid` | A secret key was presented (`Authorization: Bearer …`) and is not valid. | A configuration error: drop the batch without retrying and tell the user once (the Starko SDKs print `secret key refused`); fix or remove the key. |
161
+ | 401 | `unknown_workspace` | Unknown workspace key. | Stop sending for this page load or process. |
162
+ | 403 | `disabled` | Error tracking is off for the workspace (`data.enabled` is `false`). | Stop sending for this page load or process. |
163
+ | 403 | `origin_not_allowed` | The page's origin is not on the workspace's allow-list. | Stop sending for this page load. |
164
+ | 413 | `too_large` | Body too large. | Halve the batch and retry once. |
165
+ | 429 | `rate_limit` | Too many requests. `Retry-After` in seconds. | Wait, then retry. |
166
+ | 429 | `quota` | The workspace's allowance is used up. `Retry-After` is long. | Drop the batch; do not retry until `Retry-After` has passed. |
167
+ | 503 | `busy` | The server is shedding load or its queue store is unavailable. `Retry-After` in seconds (30 for an unavailable store). | Wait at least `Retry-After`, then retry. |
168
+
169
+ Rules for every sender:
170
+
171
+ - **Switch off only on an explicit answer.** A sender disables itself only
172
+ when the body is JSON of the shape above with `reason` `unknown_workspace`,
173
+ `disabled` or `origin_not_allowed`. A 401 or 403 with any other body (a
174
+ proxy, a firewall, a captive portal) is a temporary failure.
175
+ - **At most three attempts** per batch, with backoff and jitter, honouring
176
+ `Retry-After`. A request that gets no answer within a deadline (10 to 15
177
+ seconds in a browser) is aborted and counts as a network failure. After
178
+ repeated failures a sender pauses for a few minutes (never for the rest of
179
+ a page load: a long-lived single-page app must not go quiet after a short
180
+ offline period), resumes earlier when the browser reports it is back
181
+ `online`, and keeps only a bounded queue.
182
+ - **Never follow a redirect**, on the ingest or the config request.
183
+ - **Unknown things are ignored**: fields a receiver does not know, an unknown
184
+ `platform` (treated as `other`), an unknown `level` (treated as `error`).
185
+
186
+ ### Limits
187
+
188
+ Lengths are JavaScript string lengths.
189
+
190
+ | What | Limit |
191
+ | --- | --- |
192
+ | Events per request | 20 |
193
+ | Body | 512 KiB as sent, 2 MiB decompressed |
194
+ | JSON nesting depth | 20 |
195
+ | Exceptions per event | 10 (the first 10 are kept) |
196
+ | Frames per exception | 50 (the 25 most recent and the 25 oldest are kept) |
197
+ | Distinct `chunk_id`s resolved per event | 8 |
198
+ | `type` / `value` | 200 / 2000 |
199
+ | `filename`, `abs_path` / `function`, `module` | 1000 / 300 |
200
+ | Context lines | 7 before, 7 after, 300 each |
201
+ | Breadcrumbs | 50, 32 KiB in total |
202
+ | Tags | 50, key 64 and value 256 |
203
+ | `extra`, `contexts` | 16 KiB each |
204
+ | `fingerprint` / `release` / `environment` | 128 / 128 / 64 |
205
+ | URLs | 2048 |
206
+ | `session_id` | 8 to 70 of `A-Z a-z 0-9 -` |
207
+
208
+ The server truncates strings and arrays beyond these and rejects an event or
209
+ request beyond the size and depth limits.
210
+
211
+ The server also protects a workspace from floods: requests per IP and per
212
+ workspace per minute, a monthly allowance spent at most a share per day and
213
+ per IP, a cap on new issues per hour, and one daily cap on tickets filed
214
+ automatically. The exact numbers are server policy, not part of this format.
215
+
216
+ ### Identity
217
+
218
+ An event is linked to a customer in Starko by a credential. The credentials
219
+ an event carries are checked in this order, and the first one that gives a
220
+ verified link wins; the next one is checked only when the one before it
221
+ gave none:
222
+
223
+ 1. `client_token`: the widget's own token. The link is verified when the
224
+ token's customer is in this workspace and their profile is anonymous or
225
+ identity-verified. For a customer who was identified in the widget
226
+ without verification (an email typed into it, `identify` without a
227
+ hash) the event is still linked, and Starko labels the link
228
+ "unverified" wherever it shows it; a verified link from 2 or 3 replaces
229
+ it. A token that does not verify links nobody.
230
+ 2. `user.id` or `user.email` with a valid `user.hash`. The hash is the one the
231
+ widget's `identify` uses: an HMAC-SHA256 (hex) computed by your backend
232
+ with the workspace identity secret, over `user.id` when `user.id` is set,
233
+ otherwise over `user.email`.
234
+ 3. `user.id` in a request authenticated with a secret key (server SDKs),
235
+ matched to an existing customer's own id. A hash over `user.id` likewise
236
+ matches by id only, never by email.
237
+
238
+ A `user` without any of these is kept on the occurrence as text (the id and
239
+ email the sender claimed) and is never linked to a customer, never shown as
240
+ an affected customer and never attached to a ticket. Error events never
241
+ create customers.
242
+
243
+ `client_token` and `user.hash` are credentials. The server verifies them when
244
+ the request arrives and keeps only the resulting customer id: they are not
245
+ stored, queued or logged. SDKs must not log them either.
246
+
247
+ ### Privacy
248
+
249
+ What the SDKs do by default, and the server enforces again:
250
+
251
+ - These URL rules apply to every URL a sender sends: the page URL and
252
+ referrer, request and breadcrumb URLs, frame file names (`filename`,
253
+ `abs_path`; a script loaded from a signed URL), and `http(s)` URLs found
254
+ inside exception messages and breadcrumb messages (the rest of the text is
255
+ left alone).
256
+ - The `#fragment` and the userinfo (`user:pass@`) of every URL are dropped.
257
+ - Query-string values of sensitive parameters (`token`, `code`, `key`,
258
+ `secret`, `password`, `signature`, `session`, `email`, … the list is
259
+ `SENSITIVE_QUERY_PARAMS` in `wire.ts`) are replaced with `[redacted]`. A
260
+ name matches when the whole name or any part of it is on the list, compared
261
+ case-insensitively, with names split on `_`, `-` and camelCase boundaries:
262
+ `access_token`, `accessToken`, `clientSecret`, `apiKey`, `sessionId` and
263
+ `X-Amz-Signature` all match.
264
+ - Click breadcrumbs carry a short selector, never an element's text or an
265
+ input's value, and skip elements the Starko recorder is told to mask
266
+ (`starko-mask`, `starko-no-capture`).
267
+ - Console breadcrumbs cover warnings and errors only, as text cut to 200
268
+ characters.
269
+ - Request and response bodies, cookies and headers are never collected.
270
+ - Server SDKs read source lines (`context_line`, …) only from source files
271
+ (`.js .mjs .cjs .jsx .ts .tsx .mts .cts`) whose real path is inside the
272
+ application's root, never from dotfiles: a stack can name any path.
273
+ - The server scrubs well-known secret formats (card numbers, bearer tokens,
274
+ cloud and API keys, JWTs) from messages, source lines, `extra`, tags and
275
+ breadcrumbs before storing them.
276
+
277
+ ## Read the remote config
278
+
279
+ ```
280
+ GET {host}/api/v1/ingest/config?workspace=<workspace key>
281
+ ```
282
+
283
+ ```json
284
+ { "ok": true, "message": "Ok", "data": { "enabled": true, "sample_rate": 1, "suppress": [{ "value_contains": "ResizeObserver loop" }] } }
285
+ ```
286
+
287
+ An SDK reads it once: a browser SDK at start (holding events until it
288
+ arrives), a server SDK just before its first request (so an idle process
289
+ makes no request; events captured before it apply what it says once it
290
+ arrives). `enabled: false` means install nothing and send nothing (and
291
+ drop what is unsent); an unknown workspace gets the same answer. A failed request is
292
+ treated as `enabled: true` with defaults. The response is cacheable for a
293
+ minute. `sample_rate` and `suppress` reduce noise in well-behaved SDKs; they
294
+ are not a protection.
295
+
296
+ ## Upload source maps
297
+
298
+ Authenticated with a secret key that has the `sourcemaps:write` scope
299
+ (`Authorization: Bearer sk_starko_…`), created in Starko under Settings.
300
+ The key identifies the workspace. Every answer is JSON,
301
+ `{ "ok": boolean, "message": string, "data": … }`, and a status other than
302
+ 200 means the whole request failed (`data` is `null`).
303
+
304
+ `content_hash` is the sha256 (hex) of the **uncompressed** source map.
305
+ `chunk_id` is the debug id the build injected into the bundle: a
306
+ `//# debugId=<uuid>` comment at the end of the file, the same id in the source
307
+ map's `debugId` field, and a snippet that registers it at runtime in
308
+ `globalThis._starkoDebugIds`. The server accepts a UUID in any case, with or
309
+ without hyphens, and answers with the id as it was sent.
310
+
311
+ There are two protocols. The **bulk upload** sends each map straight from
312
+ the build to Starko's storage through a short-lived signed URL; nothing but
313
+ small JSON requests goes through the Starko host. **v1** sends every map
314
+ through the Starko host in parts. The Starko tools use the bulk upload when
315
+ the server has it and v1 otherwise (`uploadProtocol`, `--protocol`).
316
+
317
+ ### Bulk upload
318
+
319
+ ```
320
+ POST /api/v1/sourcemaps/bulk/check 1,000 chunks a request → the chunks the server lacks
321
+ POST /api/v1/sourcemaps/bulk/start 200 maps a request → per map: a signed upload target, or a status
322
+ PUT <target url> one gzipped map → straight to storage
323
+ POST /api/v1/sourcemaps/bulk/finish 200 maps a request → per map: stored, or what to do next
324
+ ```
325
+
326
+ The server suggests 2 `bulk/start` or `bulk/finish` requests and 16 PUTs in
327
+ flight (`SOURCEMAP_BULK_REQUEST_CONCURRENCY`, `SOURCEMAP_BULK_UPLOAD_CONCURRENCY`
328
+ in `wire.ts`). More finishes gain nothing: the server verifies one
329
+ workspace's maps at most 6 at a time, and only one of them over 8 MiB
330
+ gzipped (`SOURCEMAP_BULK_VERIFY_PER_WORKSPACE`), across all of that
331
+ workspace's `bulk/finish` and v1 `complete` requests; one finish keeps that
332
+ busy and a second hides the round trip. **Every request may be repeated
333
+ with the same body** after any failure.
334
+
335
+ **How long a request may take.** No route runs longer than its limit on the
336
+ server (`SOURCEMAP_ROUTE_MAX_SECONDS`): `check`, `bulk/check` and
337
+ `bulk/start` 30 s (a start usually answers well within 15 s), v1 `upload`
338
+ and `complete` 60 s, `bulk/finish` 120 s (it starts no verification after
339
+ 45 s and finishes those under way: about 70 s at worst). A client waits at
340
+ least that long, plus the network, before it treats a request as lost: the
341
+ Starko tools wait the limit plus 15 s.
342
+
343
+ **1. `bulk/check`** with `{ release?, chunks: [{ chunk_id, content_hash }] }`,
344
+ at most 1,000 chunks, returns `data: { missing: [chunk_id] }`: the chunks
345
+ the server still needs, that is without a stored map and without a map
346
+ pending the server's own verification with the same `content_hash` (unlike
347
+ v1's `check`, which reports a pending map missing). `release` is
348
+ `{ version, commit?, branch? }`; it is created when new. A server that
349
+ predates the bulk upload answers this route with 404 (or 405): use v1.
350
+
351
+ **2. `bulk/start`** with `{ release?, maps: [{ chunk_id, content_hash, size_bytes, file_name? }] }`,
352
+ at most 200 maps. `size_bytes` is the length of the **gzipped** map the
353
+ build will PUT (1 to 67,779,953 bytes, `SOURCEMAP_BULK_MAX_OBJECT_BYTES`).
354
+ It is signed into the URL and storage refuses a body of another length, so
355
+ gzip each map once and send exactly those bytes. `file_name` is the
356
+ bundle's path relative to the build output, at most 512 characters
357
+ (`SOURCEMAP_MAX_FILE_NAME`, counted as JavaScript string length; a longer
358
+ one is a 400, so shorten it first: the Starko tools keep the end of the
359
+ path after a `…`). 200 maps with every field at its limit stay inside the
360
+ 1 MiB body limit whatever the characters. A chunk id named twice in one request is answered twice
361
+ when both entries are the same, and refused (400) otherwise. The answer is
362
+ `data: { maps: [...] }`, one entry per map, in request order:
363
+
364
+ | `status` | Meaning | What the build does |
365
+ | --- | --- | --- |
366
+ | `upload` | Reserved; `upload` holds the target (below). Also the answer after a failed map or a PUT that stored nothing: a new object (or a fresh URL for the same one) at once. | PUT the map to it, then name it in `bulk/finish`. |
367
+ | `uploaded` | Already reserved, and storage already holds its object (an earlier PUT landed). No target. | Do not PUT it: name it in `bulk/finish`. |
368
+ | `present` | A stored map with this `content_hash` exists. | Nothing. |
369
+ | `pending` | The same map was uploaded and waits for the server's own verification. | Nothing. |
370
+ | `conflict` | The chunk id has a stored map with another `content_hash` (write-once). | Report it; not retryable. Delete the stored map in Starko to replace it. |
371
+ | `busy` | Only after this chunk id was restarted (new content, failed maps) more than 3 times within about 20 minutes while the earlier URLs may still be used; `retry_after_s` says when one is over (at most about 20 minutes). A normal build never sees it. | Start this map again after `retry_after_s`, or leave it to the next build. |
372
+ | `over_allowance` | The workspace's source-map storage allowance is reached. | Stop: every further map would be refused the same way. Not retryable until maps are deleted. |
373
+
374
+ An entry may carry a `message`. The reservation counts against the
375
+ allowance from this moment. The key's daily byte budget (8 GiB of gzipped
376
+ maps a UTC day) is checked here (what the key stored today plus the
377
+ request's new reservations; a 429 when it would pass) and charged by
378
+ `bulk/finish` for each map it stores, and for each map that fails
379
+ verification (the larger of its size and what it inflated to). A start
380
+ for a map that already has a reservation with the same `content_hash` and
381
+ `size_bytes`, made less than 3 hours ago, re-signs the **same** object (no
382
+ second reservation): that is how an expired URL is renewed, and the answer
383
+ is `uploaded` when storage already holds that object. Anything else (no
384
+ reservation, other content or size, an older reservation, a failed upload)
385
+ reserves a new object at once.
386
+
387
+ The target:
388
+
389
+ ```json
390
+ {
391
+ "url": "https://<region>.ingest.uploadthing.com/<key>?expires=…&x-ut-file-size=…&x-ut-acl=private&…&signature=…",
392
+ "method": "PUT",
393
+ "headers": { "Range": "bytes=0-", "x-uploadthing-version": "7.7.4" },
394
+ "form_field": "file",
395
+ "file_name": "sm-5b1f6c0e.bin",
396
+ "content_type": "application/octet-stream",
397
+ "size_bytes": 48213,
398
+ "expires_at": "2026-11-21T10:10:00.000Z",
399
+ "expires_in_s": 599
400
+ }
401
+ ```
402
+
403
+ `expires_in_s` is the time the URL has left when the server answered, on
404
+ the server's clock; `expires_at` is the same instant as a date. Time the
405
+ expiry from `expires_in_s` and when the answer arrived (a monotonic clock),
406
+ not by comparing `expires_at` with the build machine's clock, which may be
407
+ off. Renew a target that has less than a minute left before its PUT.
408
+
409
+ **3. The PUT.** `PUT <url>` with every header in `headers` and a
410
+ `multipart/form-data` body with exactly one part: name `form_field`,
411
+ filename `file_name`, `Content-Type: content_type`, content the gzipped map
412
+ (exactly `size_bytes` bytes). Nothing else: no `Authorization` (the secret
413
+ key never goes to storage). Any 2xx is success; the answer's body is not
414
+ needed. A PUT that got **no answer** (a network error, a timeout) may be
415
+ repeated to the same target while it is valid. After a **2xx**, never PUT
416
+ that target again: name the map in `bulk/finish`. After a **4xx**, whatever
417
+ it is (an expired URL included), do not PUT that target again either: name
418
+ the map in `bulk/finish`, since an earlier attempt may have stored it;
419
+ `not_uploaded` then means `bulk/start` it again and PUT what that answers.
420
+ Storage is expected to refuse
421
+ a body of another length than `size_bytes` (the server has not verified
422
+ that against its storage provider); `bulk/finish` fails an object of
423
+ another size either way. **The URL is a credential** for that one object:
424
+ never log it or show it, not even on failure. It cannot be revoked: it
425
+ works until `expires_at` (10 minutes after the start, on the server's
426
+ clock), also after the key that got it is revoked. After that, call
427
+ `bulk/start` again for the map. Do not follow a redirect.
428
+
429
+ **A build that cannot reach the storage host** (a proxy or a firewall in
430
+ front of it) sends its maps through v1 instead, the ones it already
431
+ reserved included: v1 takes a reservation over at once when storage holds
432
+ no object for it (see v1 below).
433
+
434
+ **4. `bulk/finish`** with `{ maps: [{ chunk_id, content_hash }] }`, at most
435
+ 200 maps: the maps whose PUT succeeded (or may have: finishing a map that
436
+ was not uploaded is harmless). The server reads each object back, checks
437
+ its size, gunzips it, compares its sha256 with `content_hash` and its own
438
+ `debugId` with the chunk id; nothing the build declares is trusted. The
439
+ answer is one entry per map, in request order:
440
+
441
+ | `status` | Meaning | What the build does |
442
+ | --- | --- | --- |
443
+ | `stored` | Verified and stored (also when it already was). | Done. |
444
+ | `pending` | Stored; too large to verify inside the request, the server verifies it in the background. | Done. |
445
+ | `not_uploaded` | Storage has no complete object for the reservation. | `bulk/start` it again (never PUT a target again after a 2xx): it answers `uploaded` once storage shows the object, or a target to PUT. |
446
+ | `not_reserved` | No reservation for this chunk id and `content_hash` (or it was removed). | `bulk/start` again, PUT, finish. |
447
+ | `conflict` | As in `bulk/start`. | Report it; not retryable. |
448
+ | `failed` | The stored object is wrong (size, gzip, sha256, `debugId`, not a source map; `message` says which). Charged to the key's daily budget. | Report it; do not send it again in this build (the same bytes fail again, and each failure costs budget). A fixed build's `bulk/start` reserves a new object at once. |
449
+ | `retry` | Not checked this time (storage did not answer, or the request ran out of time or of its turn at the workspace's verification). | `bulk/finish` again for it. |
450
+
451
+ **423** on any of the three routes (and on v1's `upload`) means the server
452
+ has switched source-map uploads off: its storage served a map without a
453
+ signature. It is not retryable and lasts until a Starko operator fixes
454
+ storage (hours or more): stop uploading and report the message. A
455
+ `bulk/finish` answered 423 deleted the maps it named.
456
+
457
+ Whole-request answers of the three routes:
458
+
459
+ | Status | Meaning | What the build does |
460
+ | --- | --- | --- |
461
+ | 400 | Invalid body (too many entries, a chunk id that is not a UUID, a size out of range, one chunk id with two contents). | Fix the request. |
462
+ | 401 | Missing or invalid key (also one revoked meanwhile). | Stop. |
463
+ | 404, 405 | `bulk/check` on a server without the bulk upload. | Use v1. |
464
+ | 413 | Body over 512 KiB (`bulk/check`) or 1 MiB (`bulk/start`, `bulk/finish`). | Send fewer entries. |
465
+ | 423 | Source-map uploads are disabled, see above. | Stop; do not retry. |
466
+ | 429 | Rate limited (`Retry-After`, at most a minute), too many failed key checks from the address, or (`bulk/start`) the key's daily byte budget (`Retry-After` until the next UTC day). | Wait `Retry-After`; stop when it is hours. |
467
+ | 500 | Unexpected. | Repeat a few times with back-off, then give up. |
468
+ | 503 | `bulk/start`: another start of the workspace is reserving, or the database did not answer. Always with `Retry-After`. | Repeat after `Retry-After` (the Starko tools wait at least that long, five tries). |
469
+
470
+ ### v1
471
+
472
+ 1. `POST /api/v1/sourcemaps/check` with `{ release?, chunks: [{ chunk_id, content_hash }] }`
473
+ (at most 500 chunks) returns `{ missing: [chunk_id] }`: the maps the server
474
+ still needs.
475
+ 2. For each missing map: gzip it, cut it into parts of at most 3 MiB (at most
476
+ 32 parts), and send each with
477
+ `POST /api/v1/sourcemaps/upload?chunk_id=…&part=<n>&parts=<total>&content_hash=…`
478
+ (`application/octet-stream`). `part` is 0-based. Parts can be retried and
479
+ sent in any order.
480
+ 3. `POST /api/v1/sourcemaps/complete` with `{ chunk_id, parts, content_hash, size_bytes, file_name?, release? }`.
481
+
482
+ A part for a chunk id with an unfinished bulk reservation **takes it over
483
+ at once** when storage holds no object for it (a build that could not reach
484
+ storage falls back to v1); the server keeps the reservation's object key
485
+ until its URL is over, so a PUT that still arrives through it is never lost
486
+ or counted twice. When storage does hold an object for it, or does not
487
+ answer, the part is refused with 409 and a `Retry-After` (up to about 20
488
+ minutes): that upload may still be finished through `bulk/finish`.
489
+ `complete` answers 503 with `Retry-After` while the server is busy verifying
490
+ or storage did not answer: repeat it after that. While the server has
491
+ source-map uploads switched off, `upload` answers 423 (not retryable).
492
+ `file_name` on `complete`: the server keeps the first 512 characters.
493
+
494
+ ### Rules the server applies
495
+
496
+ - **A chunk id is write-once.** The first map that completes for a chunk id
497
+ is the one used. A check never reports a chunk that has a completed map as
498
+ missing, and an upload, `complete` or `bulk/start` with a different
499
+ `content_hash` for it is refused (409, or `conflict`). Replacing a map
500
+ means deleting it in Starko first. (The debug id is derived from the
501
+ bundle's bytes, so the same id always means the same bundle and the same
502
+ map.)
503
+ - Before a map is stored, its own `debugId` must equal `chunk_id` and its
504
+ sha256 must equal `content_hash`; otherwise the upload is discarded.
505
+ - A map larger than 64 MiB uncompressed is refused, and a workspace has a
506
+ total storage allowance.
507
+ - Both protocols share the per-key request limit (2,000 requests a minute)
508
+ and the key's daily byte budget (8 GiB a UTC day; maps that fail
509
+ verification count). PUTs to storage are not Starko requests.
510
+ - Uploads and reservations that never complete are removed after a day.
511
+
512
+ ## PostHog-compatible ingest
513
+
514
+ Clients whose **servers** run on a stack without a Starko SDK can point one
515
+ of PostHog's **server** SDKs at Starko. Set the SDK's host to
516
+ `{host}/api/ingest/ph` and its project token to the workspace key. In
517
+ browsers, use `@starko-one/sdk`.
518
+
519
+ - Verified: Python (`posthog` 8 and later), .NET (PostHog 2.x; its
520
+ `HostUrl` must end with a slash, `…/api/ingest/ph/`, or it posts to the
521
+ wrong path), Node (`posthog-node` 6).
522
+ - Not supported yet: PHP and Ruby. Their SDKs post to a path ending in a
523
+ slash, which the Starko host answers with a redirect they do not follow;
524
+ Ruby's SDK also drops the path from the host. Use the native route above.
525
+ - Go: not verified.
526
+
527
+ - `POST /batch`, `/capture`, `/e` and `/i/v0/e` accept PostHog's capture
528
+ format (`api_key` + `batch`, or a single event), plain or gzip.
529
+ - Only `$exception` events are kept. Every other event (page views,
530
+ autocapture, identify, …) is discarded when the request is parsed: it is
531
+ never queued, stored or logged.
532
+ - `/flags`, `/decide` and the remote-config paths answer with no flags and
533
+ every optional PostHog feature switched off.
534
+ - The same on/off switch, limits and privacy rules apply as for the native route.
535
+
536
+ Field mapping: `uuid` → `event_id`, `$exception_list` → `exception_list`
537
+ (frame order normalised per SDK and version to most recent call first), `$exception_fingerprint` →
538
+ `fingerprint`, `$exception_level` → `level`, `distinct_id` → `user.id`
539
+ (as text only, see Identity), `$session_id` → `session_id`,
540
+ `$release_id`/`$app_version` → `release`, `$current_url` → `request.url`,
541
+ `$lib` / `$lib_version` → `sdk`. `$ip` and everything else is dropped.
542
+
543
+ ## Versions
544
+
545
+ A request with a `v` the server does not support is answered with 400,
546
+ `reason: "unsupported_version"` and `data.supported_versions`. Additions to
547
+ v1 are always optional fields; anything a v1 receiver would reject is v2.