@starko-one/sdk 0.0.0-stage → 0.1.0-beta.0

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 +124 -0
  2. package/LICENSE +17 -0
  3. package/NOTICE +58 -0
  4. package/README.md +81 -2
  5. package/dist/api-B5IHeINe.d.ts +558 -0
  6. package/dist/api-DR4HazCu.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-7HYGODU6.cjs +583 -0
  24. package/dist/chunk-A5M4NOVT.js +413 -0
  25. package/dist/chunk-A7MYYWMP.cjs +15 -0
  26. package/dist/chunk-BAQA47FM.js +1113 -0
  27. package/dist/chunk-CM7HM6CC.js +563 -0
  28. package/dist/chunk-DFYNIWUN.js +608 -0
  29. package/dist/chunk-DMVVCGKO.cjs +96 -0
  30. package/dist/chunk-FARGXYJ4.cjs +56 -0
  31. package/dist/chunk-G3MYIAX2.js +1226 -0
  32. package/dist/chunk-G4NAVZQ4.js +249 -0
  33. package/dist/chunk-GH7RYPKS.js +96 -0
  34. package/dist/chunk-HADYYQNL.cjs +134 -0
  35. package/dist/chunk-HOQPAB4X.js +178 -0
  36. package/dist/chunk-J5RU73SW.js +214 -0
  37. package/dist/chunk-JNAJ3YZB.cjs +223 -0
  38. package/dist/chunk-KN7H22EQ.cjs +659 -0
  39. package/dist/chunk-LDQ4I7FZ.cjs +1151 -0
  40. package/dist/chunk-NPGESRVQ.js +1212 -0
  41. package/dist/chunk-OPWM5V7A.cjs +258 -0
  42. package/dist/chunk-PYYWPIFL.cjs +1230 -0
  43. package/dist/chunk-R7JLZ4WO.cjs +115 -0
  44. package/dist/chunk-SC6VQSES.js +213 -0
  45. package/dist/chunk-TPSJGLR3.cjs +220 -0
  46. package/dist/chunk-UKBY6HPC.js +131 -0
  47. package/dist/chunk-VRSEHRBX.cjs +185 -0
  48. package/dist/chunk-X74AONZA.js +90 -0
  49. package/dist/chunk-XW3I5CJN.js +12 -0
  50. package/dist/chunk-XW56FKKJ.js +53 -0
  51. package/dist/chunk-Z3G5SW7R.cjs +1251 -0
  52. package/dist/chunk-ZVMAN7OO.cjs +431 -0
  53. package/dist/cli/index.cjs +1487 -0
  54. package/dist/common-ARWXbeS3.d.ts +36 -0
  55. package/dist/common-CwIFh2hK.d.cts +36 -0
  56. package/dist/dedupe-eHBIfUUD.d.cts +13 -0
  57. package/dist/dedupe-fw8aNtt4.d.ts +13 -0
  58. package/dist/handler-DTZ4Rzcf.d.ts +82 -0
  59. package/dist/handler-_00lctTI.d.cts +82 -0
  60. package/dist/index.cjs +277 -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 +275 -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 +261 -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-0BhybO54.d.cts +47 -0
  81. package/dist/options-0BhybO54.d.ts +47 -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-Bvh45bOf.d.cts +404 -0
  87. package/dist/scope-Bvh45bOf.d.ts +404 -0
  88. package/dist/server-edge-BPOGA3GH.cjs +51 -0
  89. package/dist/server-edge-GYKAJREU.js +48 -0
  90. package/dist/server-node-HYK2OB2J.js +24 -0
  91. package/dist/server-node-J2DBAHDV.cjs +27 -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-B7REA7uy.d.cts +30 -0
  95. package/dist/session-propagation-BnJjKJbR.d.ts +30 -0
  96. package/dist/starko.min.js +6 -0
  97. package/docs/browser.md +381 -0
  98. package/docs/configuration.md +269 -0
  99. package/docs/nextjs.md +312 -0
  100. package/docs/node.md +376 -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 +332 -0
  105. package/docs/troubleshooting.md +171 -0
  106. package/docs/widget.md +84 -0
  107. package/docs/wire-format.md +367 -0
  108. package/package.json +98 -4
@@ -0,0 +1,171 @@
1
+ # Troubleshooting
2
+
3
+ Start every investigation with `debug: true` in `init` (script tag:
4
+ `data-debug`). The SDK then logs to the console, every line starting with
5
+ `[starko]`: `started` once it runs, `dropped <why>` for each event it drops,
6
+ and the status of each request it sends. Remove `debug` again in production.
7
+
8
+ Some messages are printed even without `debug`: events dropped by a rate
9
+ limit (`events dropped by …`, at most once a minute per limit), and, once
10
+ each, other dropped events (`events dropped: …`), a host that redirects, a
11
+ secret key the ingest API refused, and, on the Edge runtime, a server user
12
+ set outside a request.
13
+
14
+ ## 1. Nothing arrives
15
+
16
+ Work down this list:
17
+
18
+ 1. **Did the SDK start?** With `debug: true`, look for `[starko] started`.
19
+ `[starko] no workspaceKey` means the key is missing. `init` must run
20
+ before the error happens: errors thrown before it are not captured.
21
+ 2. **Is the workspace key right?** It is the workspace id shown in Starko
22
+ under Settings. A wrong key gets `401` with reason `unknown_workspace`;
23
+ the SDK then stops sending for the rest of the page load or process
24
+ (`[starko] 401 unknown_workspace: off`).
25
+ 3. **Is the secret key right?** (servers with `apiKey`) A wrong, revoked or
26
+ malformed `apiKey` gets `401` with reason `invalid`. The SDK drops each
27
+ batch it was refused for, without retrying, and prints
28
+ ``[starko] 401: secret key refused, events dropped. Check `apiKey`.``
29
+ once, even without `debug`. Later batches are sent and refused the same
30
+ way. Fix `apiKey`, or remove it: without it, events are accepted like a
31
+ browser's.
32
+ 4. **Is error tracking enabled for the workspace?** If not, the remote
33
+ config says so (`[starko] config: disabled`) or the ingest API answers
34
+ `403` with reason `disabled`, and the SDK switches itself off.
35
+ 5. **Is the page's origin allowed?** If the workspace restricts which
36
+ origins may send errors, a page on another origin (a preview deployment,
37
+ `localhost`) gets `403` with reason `origin_not_allowed`, and the SDK
38
+ stops for that page load.
39
+ 6. **Is the request blocked before it leaves?** Ad blockers and privacy
40
+ extensions may block requests to error-tracking endpoints. In the
41
+ browser's network tab, look for the `POST …/api/v1/ingest/errors`
42
+ request: blocked, or never sent. Errors from those visitors do not
43
+ arrive.
44
+ 7. **Was the event dropped on purpose?** With `debug: true` each drop says
45
+ why: `InboundFilters` (noise, see [browser.md](./browser.md#filter-noise)),
46
+ `ignoreErrors`, `allowUrls` / `denyUrls`, `suppress` (a rule set for the
47
+ workspace), `sample`, `beforeSend`, or a rate limit.
48
+ 8. **Did it have time to leave?** Events are sent a second after capture.
49
+ A script or serverless function that ends at once loses them unless it
50
+ flushes; see [5](#5-events-missing-when-a-process-or-function-ends).
51
+
52
+ ## 2. Stack traces are minified
53
+
54
+ Upload source maps at build time: [source-maps.md](./source-maps.md), and its
55
+ [troubleshooting](./source-maps.md#troubleshooting-unresolved-frames) for
56
+ frames that stay unresolved.
57
+
58
+ ## 3. The same error is reported twice
59
+
60
+ - **With the Starko widget on the page:** see
61
+ [widget.md](./widget.md#duplicate-reports).
62
+ - **Two copies of `init`** in different bundles: one client replaces the
63
+ other, which is fine; but two different Starko SDK versions of different
64
+ compatibility lines (`0.1.x` next to `1.x`, for example) keep separate
65
+ state and both report. Use one version.
66
+ - **Your own handler and the SDK:** the SDK reports the same error object
67
+ once, however many times it is captured. A copy of the error (a new
68
+ `Error` with the same message) is a new event, unless it arrives right
69
+ after an identical one (same type, message, frames, fingerprint, user and
70
+ session, and on a server the same request).
71
+
72
+ ## 4. Events missing when the page closes
73
+
74
+ When the page is hidden or closed, the SDK sends its queue with `keepalive`
75
+ so the request survives the page. Browsers allow 64 KiB of `keepalive`
76
+ request bodies in flight per page; beyond that the rest is sent without
77
+ `keepalive` and may be cut off. Events captured in the last moment of a
78
+ page (in an `unload` handler) may not be sent at all. A very large `extra`
79
+ or many breadcrumbs make each event bigger: keep them small.
80
+
81
+ ## 5. Events missing when a process or function ends
82
+
83
+ - `process.exit()` ends the process before anything can be sent. Call
84
+ `await Starko.flush(2000)` first.
85
+ - Serverless functions may be frozen as soon as the handler returns. Wrap
86
+ the handler in `wrapHandler`, or `await Starko.flush(2000)` before
87
+ returning. See [node.md](./node.md#other-frameworks-and-serverless-wraphandler).
88
+ - `next start` exits on `SIGTERM` without waiting; see
89
+ [nextjs.md](./nextjs.md#vercel-and-long-lived-servers).
90
+
91
+ ## 6. The process does not exit, or exits later than before
92
+
93
+ The SDK never keeps a Node process alive on its own. It holds it open only
94
+ to send what is queued, for a bounded time:
95
+
96
+ - when the event loop empties: at most `shutdownTimeout` (2 s), only if
97
+ events are queued;
98
+ - on `SIGTERM` / `SIGINT` without an app handler: at most `shutdownTimeout`;
99
+ - after a crash: at most `fatalFlushTimeout` (1 s);
100
+ - with the `fetch` option (a proxy): a request in flight, at most 10 s.
101
+
102
+ A process that stays up longer is held by something else (an open server,
103
+ a database pool, a timer).
104
+
105
+ ## 7. `401`, `403` and `429`: what each reason means
106
+
107
+ Seen in the browser's network tab, or in the console with `debug: true`.
108
+
109
+ | Status | Reason | Meaning | What the SDK does | What to do |
110
+ | --- | --- | --- | --- | --- |
111
+ | 401 | `unknown_workspace` | The workspace key is not known. | Stops sending for this page load or process. | Fix `workspaceKey`. |
112
+ | 401 | `invalid` | The secret key (`apiKey`, servers only) is not valid. | Drops the batch without retrying and prints `secret key refused` once; later batches are still sent. | Fix or remove `apiKey`. |
113
+ | 401 / 403 | none, or not JSON | Not from Starko: a proxy, a firewall, a captive portal. | Retries with back-off; never switches off. | Check what sits between your app and Starko. |
114
+ | 403 | `disabled` | Error tracking is off for the workspace. | Stops sending. | Enable it in Starko. |
115
+ | 403 | `origin_not_allowed` | The page's origin is not on the workspace's allow-list. | Stops sending for this page load. | Add the origin in Starko, or ignore it for preview hosts. |
116
+ | 429 | `rate_limit` | Too many requests right now. | Waits `Retry-After`, then retries. | Usually nothing. If constant, lower `sampleRate` or fix the error loop. |
117
+ | 429 | `quota` | The workspace's allowance is used up. | Drops the batch and sends nothing until `Retry-After` has passed. | Check the workspace's usage in Starko. |
118
+
119
+ Other answers: `413` (batch too large: halved and retried once), `400`
120
+ (malformed: dropped), and `503` (busy). The ingest API answers `503` with
121
+ `Retry-After: 30` while its queue store is unavailable; the SDK waits at
122
+ least that long before it tries the batch again. Each batch gets at most
123
+ three attempts (network failures and 5xx included), so events can arrive a
124
+ minute or more late, or not at all during a longer outage. The back-off
125
+ and the number of attempts cannot be changed from `init`. The full table
126
+ is in [wire-format.md](./wire-format.md#responses).
127
+
128
+ ## 8. `host answered 3xx … not followed`
129
+
130
+ Your `host` redirects (`http://` to `https://`, an apex domain to `www.`).
131
+ The SDK never follows redirects (the event would be lost and a secret key
132
+ could go to another host), so those events were dropped. Set `host` to the
133
+ final address.
134
+
135
+ ## 9. The error arrives, but is not linked to the customer
136
+
137
+ A user is linked only when verified:
138
+
139
+ - browser: send a user hash with `identify(user, userHash)`
140
+ ([browser.md](./browser.md#identify-the-user)), or have the Starko widget
141
+ on the page;
142
+ - server: set `apiKey` (then `user.id` is trusted), or send a user hash;
143
+ - through the widget's token: verified when that customer's profile is
144
+ anonymous or identity-verified; a customer identified in the widget
145
+ without verification is linked too, labelled "unverified" in Starko;
146
+ - events sent through the PostHog-compatible route are never linked.
147
+
148
+ On a server, a user set outside a request never reaches a request's
149
+ errors: requests start from the `user` passed to `init` (see
150
+ [node.md](./node.md#code-outside-a-request)). Set the user inside the
151
+ request. On the Edge runtime a `setUser` outside a request scope is
152
+ refused, with a warning; set it inside `wrapHandler`.
153
+
154
+ ## 10. `events dropped: …` in the console
155
+
156
+ A limit dropped events. For the three rate limits the line is printed at
157
+ most once a minute per limit, with the number dropped since the previous
158
+ line:
159
+
160
+ - `events dropped by rate limit per error (10, then 1 per 10 s): N …,
161
+ latest "TypeError: Order <n> not found"`: one error was reported more
162
+ than 10 times at once. An error is its type and message with numbers and
163
+ ids masked (`<n>`, `<id>`), as the line shows;
164
+ - `events dropped by maxEventsPerLifetime`: 100 per page load in the
165
+ browser;
166
+ - `events dropped by maxEventsPerMinute`: 300 a minute on servers.
167
+
168
+ Printed once: the queue size (`maxQueueSize`), more than 30 events before
169
+ the remote config arrived, and an async `beforeSend` that did not settle in
170
+ time. A page or server that hits these is usually throwing the same error
171
+ in a loop: fix the loop, or raise the limit if the volume is expected.
package/docs/widget.md ADDED
@@ -0,0 +1,84 @@
1
+ # Using the SDK with the Starko widget
2
+
3
+ The Starko widget (chat, help center, session recording) can report page
4
+ errors on its own. When the SDK is on the same page, the SDK takes over
5
+ error capture and the two share what links an error to a customer and to a
6
+ recording. Install both as usual; there is nothing to configure, and they
7
+ may load in either order.
8
+
9
+ ```ts
10
+ import * as Starko from "@starko-one/sdk/browser";
11
+
12
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>" });
13
+ // The widget's own snippet stays as it is.
14
+ ```
15
+
16
+ ## Who captures errors
17
+
18
+ The two meet through one global object, `window.__STARKO_BRIDGE__`. The SDK
19
+ announces on it whether it is capturing page errors (`capturesErrors`), and
20
+ announces every change with a `starko:bridge` event on `window`.
21
+
22
+ - While `capturesErrors` is true, the widget does not install its own error
23
+ hooks: each error is reported once, by the SDK.
24
+ - `capturesErrors` is true only while the SDK is running **and** its global
25
+ error handlers are installed. It becomes false after `close()`, when the
26
+ workspace's error tracking is switched off, or when you remove the
27
+ `GlobalHandlers` integration. The widget then reports page errors itself
28
+ again.
29
+ - The widget also reports errors a page passes to `console.error` (for
30
+ example from a framework's error boundary) and stops doing so when the SDK
31
+ is there. So, while the widget is on the page, the SDK captures them
32
+ instead: an `Error` object passed to `console.error` is reported as a
33
+ handled error. Remove the `ConsoleErrorCapture` integration to stop that;
34
+ add `consoleErrorCaptureIntegration()` yourself to capture them without the
35
+ widget too.
36
+
37
+ ## The session: errors linked to recordings
38
+
39
+ With the widget on the page and recording, the SDK stamps the recorder's
40
+ session id on every error, so the error links to the recording of the
41
+ session it happened in. Without the widget, the SDK creates its own session
42
+ id, kept per tab in `sessionStorage` under `starko:errors:session`, the same
43
+ key the widget uses, so both agree whichever loads first.
44
+
45
+ ## The customer: verified through the widget
46
+
47
+ When the widget is on the page, the SDK sends the widget's client token
48
+ with every error. Starko verifies it and links the error to the widget's
49
+ customer, with no user hash needed. The link is verified when that
50
+ customer's profile is anonymous or identity-verified. A customer who was
51
+ identified in the widget without verification (an email typed into it, or
52
+ `identify` without a hash) is linked too, and Starko labels that link
53
+ "unverified" on the error, in the affected customers list and in a ticket
54
+ filed from it. Starko also checks the user hash you sent with `identify`:
55
+ a valid hash links your user as verified and replaces the unverified link.
56
+ The token is a credential: the SDK
57
+ sends it with the event and nowhere else (never in logs, breadcrumbs or
58
+ extra data), and Starko does not store it.
59
+
60
+ Without the widget, identify users with `identify(user, userHash)`; see
61
+ [browser.md](./browser.md#identify-the-user).
62
+
63
+ ## Load order and lifecycle
64
+
65
+ | Situation | What happens |
66
+ | --- | --- |
67
+ | SDK first, widget later | The widget finds the SDK on the bridge and leaves error capture to it. The SDK reads the widget's session and token on every event, so events after the widget arrived carry them. |
68
+ | Widget first, SDK later | The SDK registers on the bridge and announces it; the widget stands its error capture down. |
69
+ | `Starko.close()` | `capturesErrors` becomes false and is announced; the widget reports errors itself again. |
70
+ | Error tracking switched off for the workspace | Same as `close()`. |
71
+ | `init` called again, or a second copy of the SDK (script tag and npm package) | One bridge entry, always routed to the current SDK client. |
72
+ | The page sets `__STARKO_BRIDGE__` to something that is not an object | The SDK leaves it alone and runs without the bridge. |
73
+
74
+ ## Duplicate reports
75
+
76
+ Each error should arrive once. If you see the same error twice, once from
77
+ the widget and once from the SDK:
78
+
79
+ - check that `Starko.init` actually ran and is enabled (with `debug: true`
80
+ the console shows `[starko] started`);
81
+ - check that `GlobalHandlers` was not removed (then `capturesErrors` is false
82
+ and the widget reports instead, which is expected);
83
+ - check that the widget build on the page reads the bridge. A widget that
84
+ does not know `__STARKO_BRIDGE__` keeps capturing next to the SDK.
@@ -0,0 +1,367 @@
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.0" },
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.
301
+
302
+ 1. `POST /api/v1/sourcemaps/check` with `{ release?, chunks: [{ chunk_id, content_hash }] }`
303
+ (at most 500 chunks) returns `{ missing: [chunk_id] }`: the maps the server
304
+ still needs.
305
+ 2. For each missing map: gzip it, cut it into parts of at most 3 MiB (at most
306
+ 32 parts), and send each with
307
+ `POST /api/v1/sourcemaps/upload?chunk_id=…&part=<n>&parts=<total>&content_hash=…`
308
+ (`application/octet-stream`). `part` is 0-based. Parts can be retried and
309
+ sent in any order.
310
+ 3. `POST /api/v1/sourcemaps/complete` with `{ chunk_id, parts, content_hash, size_bytes, file_name?, release? }`.
311
+
312
+ `content_hash` is the sha256 (hex) of the uncompressed source map.
313
+ `chunk_id` is the debug id the build injected into the bundle: a
314
+ `//# debugId=<uuid>` comment at the end of the file, the same id in the source
315
+ map's `debugId` field, and a snippet that registers it at runtime in
316
+ `globalThis._starkoDebugIds`.
317
+
318
+ Rules the server applies:
319
+
320
+ - **A chunk id is write-once.** The first map that completes for a chunk id
321
+ is the one used. `check` never reports a chunk that has a completed map as
322
+ missing, and an upload or `complete` with a different `content_hash` for it
323
+ is refused with 409. Replacing a map means deleting it in Starko first.
324
+ (The debug id is derived from the bundle's bytes, so the same id always
325
+ means the same bundle and the same map.)
326
+ - At `complete`, the map's own `debugId` must equal `chunk_id` and its sha256
327
+ must equal `content_hash`; otherwise the upload is discarded.
328
+ - A map larger than 64 MiB uncompressed is refused, and a workspace has a
329
+ total storage allowance.
330
+ - Uploads that never complete are removed after a day.
331
+
332
+ ## PostHog-compatible ingest
333
+
334
+ Clients whose **servers** run on a stack without a Starko SDK can point one
335
+ of PostHog's **server** SDKs at Starko. Set the SDK's host to
336
+ `{host}/api/ingest/ph` and its project token to the workspace key. In
337
+ browsers, use `@starko-one/sdk`.
338
+
339
+ - Verified: Python (`posthog` 8 and later), .NET (PostHog 2.x; its
340
+ `HostUrl` must end with a slash, `…/api/ingest/ph/`, or it posts to the
341
+ wrong path), Node (`posthog-node` 6).
342
+ - Not supported yet: PHP and Ruby. Their SDKs post to a path ending in a
343
+ slash, which the Starko host answers with a redirect they do not follow;
344
+ Ruby's SDK also drops the path from the host. Use the native route above.
345
+ - Go: not verified.
346
+
347
+ - `POST /batch`, `/capture`, `/e` and `/i/v0/e` accept PostHog's capture
348
+ format (`api_key` + `batch`, or a single event), plain or gzip.
349
+ - Only `$exception` events are kept. Every other event (page views,
350
+ autocapture, identify, …) is discarded when the request is parsed: it is
351
+ never queued, stored or logged.
352
+ - `/flags`, `/decide` and the remote-config paths answer with no flags and
353
+ every optional PostHog feature switched off.
354
+ - The same on/off switch, limits and privacy rules apply as for the native route.
355
+
356
+ Field mapping: `uuid` → `event_id`, `$exception_list` → `exception_list`
357
+ (frame order normalised per SDK and version to most recent call first), `$exception_fingerprint` →
358
+ `fingerprint`, `$exception_level` → `level`, `distinct_id` → `user.id`
359
+ (as text only, see Identity), `$session_id` → `session_id`,
360
+ `$release_id`/`$app_version` → `release`, `$current_url` → `request.url`,
361
+ `$lib` / `$lib_version` → `sdk`. `$ip` and everything else is dropped.
362
+
363
+ ## Versions
364
+
365
+ A request with a `v` the server does not support is answered with 400,
366
+ `reason: "unsupported_version"` and `data.supported_versions`. Additions to
367
+ v1 are always optional fields; anything a v1 receiver would reject is v2.