@loxel.dev/pharos-browser 0.6.0

package/README.md

@@ -0,0 +1,360 @@
+# @loxel.dev/pharos-browser
+
+A thin browser client for [Pharos](https://pharos-ops.app):
+server-evaluated feature flags, error reporting, and session replay.
+
+Bootstraps a context against the Pharos client API, then keeps flag values
+current over a Server-Sent Events stream. Uncaught errors and unhandled
+rejections are reported automatically. Session replay is opt-in, and its one
+dependency (`rrweb`) is loaded on demand so you do not pay for it unless you
+record — see [Bundle size](#bundle-size).
+
+Built and tested with [Bun](https://bun.sh).
+
+Internals — the wire format, the local rest, the degradation ladder, and
+the full export reference — are in `TECHNICAL-DETAILS.md`, shipped alongside
+this file.
+
+## The server-evaluated model
+
+This client never evaluates flags itself. Every value `flag()` returns was
+computed **server-side** — rules, percentage rollouts, targeting attributes,
+and bucketing all happen behind `POST /api/v1/client/bootstrap`, which
+returns a flat `{key: value}` map for the given context.
+
+The client's only job is to hold that map, keep it fresh via `GET /api/v1/client/stream`, and
+hand values back synchronously. This keeps rule logic and segment membership
+off the client (nothing to reverse-engineer from a bundle) and means a
+targeting change takes effect for every open tab without a redeploy.
+
+## Install
+
+```sh
+bun add @loxel.dev/pharos-browser        # or: npm install @loxel.dev/pharos-browser
+```
+
+The published tarball ships **built output only** (`dist/`, plus `.d.ts`
+files), not TypeScript source: the `exports` map is what lets a bundler
+resolve the bare specifier.
+
+## Before you start
+
+**Pharos is a hosted service, and access is by invitation.** There is one
+instance, at `https://pharos-ops.app`.
+
+`init()` needs three values, and they all come from your console there:
+
+| value | where it comes from |
+|---|---|
+| `baseUrl` | always `https://pharos-ops.app` |
+| `clientKey` | ORGANIZATION → API keys → new key, kind **client**. Starts `phc_`. |
+| `context.application` | the application that client key was minted for |
+
+Register your browser origins on that application (ORGANIZATION →
+Applications) before the first request. An origin that is not on the list is
+refused by CORS, which surfaces as a network error rather than a permissions
+one — the most common first-run failure.
+
+Use the `phc_` **client** key, never the `phs_` server key. The client key is
+meant to ship in your bundle: it only authorises bootstrap, error ingest and
+replay upload, for one application. The server key does much more and must
+stay on a backend.
+
+## Bundle size
+
+**Importing this package does not cost you `rrweb`.** The session recorder is
+the only thing that needs it, and the recorder is not on the root entry:
+
+| you import | you get |
+|---|---|
+| `@loxel.dev/pharos-browser` | flags, error reporting, the privacy policy, the replay buffer/encoder/store — **no rrweb** |
+| `@loxel.dev/pharos-browser/replay` | the recorder, and therefore rrweb |
+| `await client.startReplay()` | the recorder, fetched on demand as a separate chunk |
+
+Measured on a real application (a React + Vite app, replay switched off):
+importing the client used to add **204 kB raw / 63 kB gzip** to its main
+chunk, essentially all of it rrweb, paid whether or not anything ever
+recorded. It now adds **8.5 kB raw / 2.9 kB gzip**.
+
+`startReplay()` reaches the recorder through a dynamic `import()`. The chunk
+still ships with your deployment, so turning replay on stays a configuration
+change — it just stops being downloaded by visitors who never record.
+
+`rrweb` (2.1.1) is an ordinary runtime dependency — **not a CDN script**.
+Installing this package installs rrweb into your own `node_modules`; your
+bundler compiles it into your own output, served from your own origin.
+
+This package's build never inlines it. The published tarball contains no rrweb
+files at all — only a single unresolved `import { record } from "rrweb"` for
+your bundler to resolve. That is what lets a project already using rrweb end
+up with one shared copy rather than two.
+
+## Usage
+
+### Set up
+
+```typescript
+import { PharosBrowserClient } from "@loxel.dev/pharos-browser";
+
+const client = await PharosBrowserClient.init({
+  baseUrl: "https://pharos-ops.app",   // required
+  clientKey: "phc_...",                // required
+  context: {
+    contextKey: "user-42",             // required — who is asking; buckets rollouts
+    application: "tax-graph",          // recommended — see below
+    release: "1.4.0",                  // recommended — see below
+    sessionId: "sess-abc",             // optional — joins errors to replay windows
+    attributes: { plan: "enterprise", country: "US" },  // optional — flag targeting
+  },
+});
+```
+
+`contextKey` is the only context field the server enforces — a bootstrap
+without one is a `400`.
+
+**`application` and `release` are optional to the type, and you want both
+anyway.** `application` is hashed into the error fingerprint, so omitting it
+collapses every browser application in your organization into one fingerprint
+namespace and stops the console's `application=` filter from returning your
+rows. `release` drives release attribution and the `release=` filter.
+
+`sessionId` matters only if you want an error and the replay window captured
+around it to be joinable; `client.startReplay()` gives you one id across both
+without passing anything. `attributes` is free-form data for your flag
+targeting rules — send nothing if no rule reads it.
+
+### Read a flag
+
+```typescript
+// Synchronous, no network call — the value was computed server-side and is
+// already here. Your default is returned until the bootstrap lands, and for
+// any key Pharos does not know.
+if (client.flag("new-nav", false)) {
+  renderNewNav();
+}
+
+// Values stay current over the stream, so a targeting change takes effect in
+// every open tab without a redeploy. Re-read on change; do not trust the
+// payload's shape.
+const off = client.on("change", () => rerender());
+
+// Stream and bootstrap failures surface here rather than throwing.
+client.on("error", (err) => console.warn("pharos stream error", err));
+```
+
+### Identify a user
+
+```typescript
+// After login. This is a full HTTP round trip, not a local re-key — call it
+// on real identity changes, not per render.
+await client.identify({
+  contextKey: user.id,
+  application: "tax-graph",  // identify REPLACES the stored context, so
+  release: "1.4.0",          // resend these or errors lose them
+});
+```
+
+### Shut down
+
+```typescript
+off();          // unsubscribe the change listener
+client.close(); // close the stream, unregister the error listeners
+```
+
+## Error reporting
+
+`init()` reports errors to `POST /api/v1/errors` two ways:
+
+- **Auto-capture** (on by default) — registers `window.addEventListener("error", ...)`
+  and `window.addEventListener("unhandledrejection", ...)` and reports every
+  uncaught exception / rejected promise automatically. Opt out with
+  `init({ ..., errors: false })` to only report via explicit
+  `captureException()` calls. `close()` unregisters both listeners.
+- **`captureException(err, opts?)`** — call this yourself from a `catch`
+  block for errors your own code already handled. `err` can be an `Error`,
+  a string, or anything else (`String(err)` is used as a fallback message);
+  `opts.site` labels where it was caught (e.g. a route name) and
+  `opts.attributes` attaches extra scalar (or array-of-scalar) context to
+  this occurrence only.
+
+```typescript
+// Uncaught errors and unhandled rejections are reported for you. Report a
+// handled one yourself, with whatever context makes it diagnosable:
+try {
+  await checkout(cart);
+} catch (err) {
+  client.captureException(err, {
+    site: "checkout",
+    attributes: { step: "payment", itemCount: cart.length },
+  });
+}
+```
+
+**If you use an error boundary, report from it explicitly.** React hands a
+render error to the nearest boundary instead of letting it reach the window,
+so auto-capture never sees the one class of error that takes your whole UI
+down:
+
+```typescript
+componentDidCatch(error, info) {
+  client.captureException(error, {
+    site: "ErrorBoundary",
+    attributes: { componentStack: info.componentStack ?? "" },
+  });
+}
+```
+
+Every report is a **single-entry** batch: `message` (from `err.message`,
+falling back to `String(err)`, never sent empty — `"(no message)"` is used
+instead), `kind` (from `err.name`), `stack` (parsed from `err.stack` when
+it's a string — V8 and Firefox stack-trace shapes are both recognized, via
+the exported `parseStack`), the client's current flag map, and the same
+reserved context fields `init()`'s bootstrap sends (`contextKey`,
+`application`, `release`, `sessionId` — whichever are set on the current
+context).
+
+`application`/`release` matter here beyond bookkeeping: the
+server hashes them into the error fingerprint and release-tracking, so
+omitting them would silently merge every browser app's errors into one
+fingerprint namespace and break the admin issues API's `release=` filter.
+
+**Every field is sanitized/truncated client-side** to the server's
+validation caps before sending, because the server rejects the *whole*
+batch if any single field violates them (an empty flag map or `attrs` map
+is simply omitted rather than sent empty) — this matters most for
+auto-capture, which forwards whatever an uncaught exception happened to
+contain.
+
+Sending is fire-and-forget: a failed POST never throws, it emits
+`on("error")` like the SSE stream's own failures do.
+
+`captureException` after `close()` is a no-op (no fetch), matching `identify()`'s
+documented behavior.
+
+## Session replay
+
+Recording is **opt-in**. Importing this package records nothing.
+
+One call starts a recorder, wires it to this client's errors, and uploads
+windows under the same session id your errors already carry:
+
+```typescript
+const recorder = await client.startReplay();
+
+// Consent withdrawn: stops recording, discards the buffer, and deletes
+// anything already persisted locally.
+client.detachReplay();
+recorder.stop();
+```
+
+It is **async** because it loads the recorder on demand — that is what keeps
+`rrweb` out of your bundle until you actually record.
+
+**How it records.** The recorder runs as a *dashcam*: it is always capturing
+into a bounded local buffer and sends nothing until something goes wrong. A
+trigger — anything reaching `captureException`, including `window.onerror` and
+unhandled promise rejections — flushes a window covering `preRollMs` before
+the error and `postRollMs` after it. A burst of errors from one broken render
+produces **one** window, not fifty: triggers inside an existing post-roll
+extend that window.
+
+**When to call it.** Call `startRecording()` after the document is parsed if
+you can. rrweb defers its first snapshot while `document.readyState` is
+`"loading"`; the recorder pins `recordAfter: "DOMContentLoaded"` rather than
+rrweb's `"load"` default, which shrinks that gap from "until every subresource
+has loaded" to "until the document is parsed" — but **it does not close it**.
+A recorder started from a `<head>` script captures nothing (and `stats()`
+reports `snapshots: 0`) until `DOMContentLoaded` fires.
+
+**What it captures.** DOM structure and mutations, clicks, focus, input events
+and scroll (via [rrweb](https://www.rrweb.io/)), plus one Pharos-specific
+addition: an **activation mode** (`pointer`, `keyboard` or `programmatic`)
+emitted as an rrweb custom event tagged `pharos-activation`.
+
+**What it never captures: key identity.** The keyboard listener records a
+single enum — *that* the last input was a key — and never reads, stores or
+transmits which key was pressed. A `keydown` listener sees passwords, and this
+one cannot leak one.
+
+**Privacy.** Every node is routed through this package's privacy policy
+(`decide`, `masksValue`, `maskText`, `scrubAttribute`); the recorder
+re-implements no rule of its own. **Rendered text is recorded by default** and
+markers hide (`pharos-exclude`) or obfuscate (`pharos-mask`) it — a deliberate
+posture, not an omission. See
+[the Pharos README](../../README.md#session-replay-privacy-contract) for what
+is and is not masked — including what it does **not** catch.
+
+**Retention is not yours to choose.** Stored windows expire under a
+per-application **TTL**, and each application also has a **session cap**: when
+it is exceeded the oldest sessions are deleted along with their windows and
+their stored bytes. Both are per-application configuration delivered over
+`/api/v1/client/bootstrap`; a value in an upload body is read by nothing. The
+TTL is the user-facing promise, and **the cap is what protects the disk** —
+one busy application would otherwise consume the whole retention window.
+
+Wiring your own transport (`startRecording`, `startReplayUpload`), the wire
+format, the local IndexedDB rest and its 24-hour expiry, what
+`droppedWindows` counts, and the degradation ladder are all in
+`TECHNICAL-DETAILS.md`, shipped in this package.
+
+## API at a glance
+
+Full reference — every export, every option — is in `TECHNICAL-DETAILS.md`.
+
+| | |
+|---|---|
+| `PharosBrowserClient.init(config)` | bootstrap and open the live stream |
+| `flag(key, default)` | synchronous lookup; no network call, no evaluation |
+| `on("change" \| "error", cb)` | subscribe; returns an unsubscribe function |
+| `identify(context)` | re-bootstrap as a new context (a full round trip — call it on login, not per render) |
+| `captureException(err, opts?)` | report a caught error; never throws |
+| `startReplay(options?)` | start a recorder wired to this client, and attach it |
+| `attachReplay` / `detachReplay` | route this client's errors into a recorder you started yourself |
+| `close()` | stop the stream and unregister the error listeners |
+
+The privacy policy (`decide`, `maskText`, `scrubAttribute`,
+`collectRecordedStrings`, the marker constants) is exported from the root so
+you can verify what a recorder would send before turning one on.
+
+## Version history
+
+- `0.6.0` — **first npm release, as `@loxel.dev/pharos-browser`.** Ships built
+  output with an `exports` map, so it resolves as an ordinary package.
+
+  **Breaking:** the recorder moved to the `@loxel.dev/pharos-browser/replay`
+  subpath (`startRecording`, `startReplayUpload`, `resolveSessionId`,
+  `SESSION_STORAGE_KEY`, `SESSION_DROPS_KEY`), and `client.startReplay()` now
+  returns a promise. Everything else is unchanged on the root.
+
+  Why: `rrweb` was reachable from the root entry, so it landed in every
+  bundle whether or not anything recorded — **+204 kB raw / +63 kB gzip** on a
+  real application with replay switched off. It is now loaded on demand,
+  costing **8.5 kB raw / 2.9 kB gzip**.
+
+- `0.5.2` — stops shipping most checkpoint segments twice. A segment flushed
+  by the unload path while still open was shipped again when it closed,
+  roughly doubling ingest for always-on recording. No API change.
+
+- `0.5.1` — replay-upload correctness. `droppedWindows` is now cumulative
+  across page loads. A window persisted by a tab switch is uploaded when the
+  tab becomes visible again rather than waiting for a full page load. Adds
+  `startReplay()`, and a warning when replay and errors would be reported
+  under different session ids.
+
+- `0.5.0` — session-replay upload: `startReplayUpload()`, gzip + JSON envelope
+  to `POST /api/v1/client/replay`, IndexedDB rest for windows triggered during
+  unload, a durable per-tab session id, and `droppedWindows`.
+
+- `0.4.0` — session-replay recorder: `startRecording()` with a pluggable sink,
+  a checkpoint-segmented ring buffer, activation-mode capture that never reads
+  key identity, error-driven windows, and self-degradation under load.
+
+- `0.3.0` — session-replay privacy contract: `pharos-exclude` / `pharos-mask`
+  markers, field-sensitivity detection, attribute/URL/style scrubbing, and
+  `collectRecordedStrings` for verifying what a recorder would send.
+
+- `0.2.0` — error reporting: `captureException`, auto-capture of uncaught
+  errors and unhandled rejections, and `parseStack`.
+
+- `0.1.0` — initial release: bootstrap + SSE stream, `flag` / `on` /
+  `identify` / `close`.