@reopt-ai/data-sdk-client 0.1.6 → 0.2.0

package/README.md

@@ -104,9 +104,11 @@ init({
     scrollDepth: true,
     exceptions: false, // $exception for uncaught errors and unhandled rejections; loads as its own chunk when on
   },
+  release: undefined, // build id stamped on every event as $release_id; see below
   tracingHeaders: false, // opt-in: add reopt-device-id to same-origin fetch/XHR (true) or to listed hosts; loads as its own chunk
   normalizePath: (pathname) => pathname, // see below; applied to every path the SDK stamps itself
   fetch: undefined, // transport override for tests
+  observe: undefined, // local lifecycle observer for devtools; never sent over the network
   consent: { categories: ["analytics", "marketing"], defaultConsent: true },
   batch: { size: 100, intervalMs: 1000, maxBytes: 400_000 },
   retry: { maxRetries: 3, baseDelay: 1000, maxDelay: 30000, jitter: 0.1 },
@@ -115,6 +117,42 @@ init({
 });
 ```
 
+## Release tracking
+
+`release` stamps every event with `$release_id`. Error tracking reads it to say
+which build an issue first and last appeared in, and — once you resolve an issue
+"in" a release — to tell a plain reopen from a **regression**, where the fix you
+declared did not hold.
+
+```ts
+init({ writeKey: "wk_…", release: "1.4.0" });
+```
+
+Most apps do not know their version at the call site. The SDK falls back to
+`globalThis.__REOPT_RELEASE__`, which is where a build step writes it:
+
+```js
+// vite.config.js
+export default { define: { __REOPT_RELEASE__: JSON.stringify(process.env.GIT_SHA) } };
+
+// next.config.js
+module.exports = {
+  webpack: (config, { webpack }) => {
+    config.plugins.push(
+      new webpack.DefinePlugin({ __REOPT_RELEASE__: JSON.stringify(process.env.VERCEL_GIT_COMMIT_SHA) })
+    );
+    return config;
+  },
+};
+```
+
+An explicit `release` wins over the global. With neither, the property is
+omitted entirely — not sent as an empty string, which would create a release
+named `""` and label every issue with it.
+
+The label is yours: a version, a commit sha, a build id. The server never issues
+one and never rejects an event for carrying an unfamiliar release.
+
 ## Runtime-resolved keys, manual page views, external consent
 
 The three things a multi-tenant host needs, in the shape it needs them:
@@ -134,6 +172,7 @@ const writeKey = await resolveBrandWriteKey(brandId);
 - **`register(properties)`** attaches properties to every event from then on — including the automatic ones. This is how a host puts its own breakdown axis (`page_id`, a tenant) on `$web_vitals` and `$pageleave`, which the SDK otherwise stamps with only a path. An event's own properties win; `reset()` clears them.
 - **Fail-open.** A missing `writeKey` or `baseUrl` logs a warning and yields a disabled client whose every call is a no-op; nothing throws. Analytics must never be why a page fails.
 - **`fetch`** injects the transport. A test can hand in a recording function and assert on the exact payload the SDK built, instead of intercepting the network.
+- **`observe`** receives local configuration, enqueue/drop, identity, consent, and pause/resume facts in lifecycle order. Its implementation loads as an opt-in chunk, buffers facts while that chunk arrives, ignores callback errors, and never receives the write key or event properties. Use it for diagnostics such as `@reopt-ai/data-sdk-devtool`, not application behavior.
 
 ## Bootstrap and caching (Next.js)
 
@@ -145,7 +184,102 @@ const writeKey = await resolveBrandWriteKey(brandId);
 
 ## Size
 
-The production bundle is checked on every build (`scripts/check-size.mjs`): each entry is bundled as a consumer would (minified, `NODE_ENV=production`, framework externals) and must stay under **10.4 KB gzip** for the vanilla entry (10.65 / 10.9 KB for `./react` / `./next`) and carry no zod. Opt-in features (tracing headers, exception capture) are separate chunks. Event validation in production is a hand-written mirror of the contract; the zod schema runs in development only and is dropped by the consumer's bundler.
+### `$exception_list` — the structured form
+
+Alongside the flat keys, an exception carries the parsed cause chain. The flat
+keys still describe the outermost error and are unchanged, so anything written
+against them keeps working; `$exception_list` is what the issue page renders and
+what fingerprinting groups on.
+
+| Field                 | Meaning                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `type` / `value`      | `TypeError` / the message. For a non-`Error` throw the SDK derives both.              |
+| `mechanism.handled`   | `false` when nothing caught it. Causes are `true` — they were caught and re-thrown.   |
+| `mechanism.type`      | `onerror` \| `unhandledrejection` \| `manual` \| `console` \| `nextjs_onRequestError` |
+| `mechanism.synthetic` | The SDK invented the type because what was thrown was not an `Error`.                 |
+| `stacktrace.frames[]` | `filename`, `function`, `lineno`, `colno`, `in_app` — innermost first.                |
+
+```json
+{
+  "$exception_type": "TypeError",
+  "$exception_message": "cart.items is not a function",
+  "$exception_list": [
+    {
+      "type": "TypeError",
+      "value": "cart.items is not a function",
+      "mechanism": { "handled": false, "type": "onerror" },
+      "stacktrace": {
+        "type": "raw",
+        "frames": [
+          {
+            "filename": "https://shop.example.com/main.a1b2c3d4.js",
+            "function": "handleCheckout",
+            "lineno": 412,
+            "colno": 19,
+            "in_app": true
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+#### Throttling
+
+Automatic capture is throttled per exception `type` — a token bucket of 10 with
+one token back every 10s. One component stuck in a rejection loop can fire
+thousands of identical events a second; unthrottled that fills the visitor's
+network and the customer's quota with a single bug, and buries every other error
+in the issue list.
+
+```ts
+capture: {
+  exceptions: true,
+  exceptionRateLimit: { bucketSize: 20, refillSeconds: 5 }, // or `false` for no limit
+}
+```
+
+Per type, so a runaway `TypeError` cannot silence a `RangeError` that starts
+later. Never applied to `captureException()` — a report you asked for explicitly
+is not noise the SDK gets to drop. When throttling kicks in, `debug: true` logs
+it once per type.
+
+#### Breadcrumbs
+
+`$exception_steps` carries what happened just before the error — up to 20 steps,
+each with a 200-character message and at most 1 KB of serialized `data`.
+
+```ts
+client.addExceptionStep({ category: "fetch", message: "POST /orders", data: { status: 500 } });
+// …later, any exception carries the trail
+```
+
+`capture.exceptionSteps: true` also records a `navigation` step on every page
+view. Off by default: navigation history on every error is a privacy decision
+the host makes, not the SDK. `addExceptionStep()` works either way.
+
+The trail is copied onto an exception, not moved — a second error in the same
+session sees the same history rather than an empty one. One buffer per page, not
+per client.
+
+A cause chain is carried outermost first, up to four links. A stack made
+entirely of `chrome-extension://` frames is **not reported** — it is a bug in a
+visitor's extension, which the site cannot reproduce or fix.
+
+`captureException(error, options?)` takes `{ fingerprint?, level?, properties? }`.
+`fingerprint` is a _suggestion_ — the server bounds it and decides — and is how
+you say "group these two apart" or "group these together". The pre-options shape
+`captureException(error, { myProperty: 1 })` still works: an object carrying none
+of the three option keys is read as properties.
+
+`captureException()` is the one place the list can be absent. The parsers live
+in the exception chunk, and a manual capture made before that chunk has loaded
+reports the flat keys only; the server falls back to fingerprinting those, so
+the event still groups. Turning on `capture.exceptions` loads the chunk at init,
+which is the usual case.
+
+The production bundle is checked on every build (`scripts/check-size.mjs`): each entry is bundled as a consumer would (minified, `NODE_ENV=production`, framework externals) and must stay under **10.65 KB gzip** for the vanilla entry (10.9 / 11.15 KB for `./react` / `./next`) and carry no zod. Opt-in features (observer formatting, tracing headers, exception capture) are separate chunks. Event validation in production is a hand-written mirror of the contract; the zod schema runs in development only and is dropped by the consumer's bundler.
 
 ## What it does that you would otherwise have to remember
 
@@ -161,9 +295,9 @@ The production bundle is checked on every build (`scripts/check-size.mjs`): each
 
 Names and property keys are exported from `@reopt-ai/data-contract/events` (`AUTO_EVENT_NAMES`, `AUTO_EVENT_PROPERTIES`); the low-cardinality subset suitable as rollup dimensions is `AUTO_EVENT_ROLLUP_KEYS`. Derive catalogue entries from those rather than retyping them.
 
-| Event         | Properties                                                                                                         |
-| ------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `$pageview`   | `path`, `origin`, `title`, `referrer`, `utm_*`, `search` (Next, when present), plus anything `normalizePath` lifts |
-| `$pageleave`  | `path`, `origin`, `duration` (s), `scroll_depth` (0–100)                                                           |
-| `$web_vitals` | `metric_name`, `metric_id`, `value`, `delta`, `rating`, `navigation_type`, `path`                                  |
-| `$exception`  | `$exception_type`, `$exception_message`, `$exception_stack`, `$exception_source`, `$exception_handled`, `path`     |
+| Event         | Properties                                                                                                                        |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `$pageview`   | `path`, `origin`, `title`, `referrer`, `utm_*`, `search` (Next, when present), plus anything `normalizePath` lifts                |
+| `$pageleave`  | `path`, `origin`, `duration` (s), `scroll_depth` (0–100)                                                                          |
+| `$web_vitals` | `metric_name`, `metric_id`, `value`, `delta`, `rating`, `navigation_type`, `path`                                                 |
+| `$exception`  | `$exception_type`, `$exception_message`, `$exception_stack`, `$exception_source`, `$exception_handled`, `$exception_list`, `path` |