@realuptime/errors 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RealUptime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @realuptime/errors
+
+Zero-dependency error tracking SDK for JavaScript and Node: part of
+[RealUptime Errors](https://realuptime.io/error-tracking).
+
+This is a **mirror**. It is published from `packages/errors-js` in the
+[realuptime monorepo](https://github.com/RealUptimeHQ/realuptime) by
+`scripts/publish-sdk-mirrors.mjs` and is not edited directly; open issues
+and PRs against this repo, but expect source changes to land here after
+they merge upstream.
+
+## Install
+
+Installable from the package registry (primary) or straight from this mirror's git history (e.g. to pin an exact commit).
+
+```bash
+npm install @realuptime/errors
+```
+
+```bash
+# or, straight from this mirror
+npm install github:RealUptimeHQ/realuptime-errors-js
+```
+
+## Usage
+
+```js
+import * as realuptimeErrors from "@realuptime/errors";
+
+realuptimeErrors.init({
+  dsn: "https://realuptime.io/api/errors/v1/ingest/rue_...", // from your project's dashboard
+  release: "v2.4.1",
+  environment: "production",
+});
+
+realuptimeErrors.captureException(someError);
+```
+
+WSGI/ASGI equivalents live in the Python SDK,
+[realuptime-errors-py](https://github.com/RealUptimeHQ/realuptime-errors-py).
+
+## Source maps (Vite / webpack plugins)
+
+Upload the `.map` files a production build writes, for the release your
+app reports at runtime, so minified JS frames symbolicate on the issue page.
+Both plugins read the maps the bundler already wrote and POST them to your
+project's source-map endpoint (authenticated by the DSN, the one secret CI
+already has). They change nothing in the build output.
+
+```js
+// vite.config.js
+import { realuptimeSourcemaps } from "@realuptime/errors/vite";
+export default {
+  build: { sourcemap: true },
+  plugins: [realuptimeSourcemaps({ release: process.env.GITHUB_SHA, dsn: process.env.REALUPTIME_ERRORS_DSN })],
+};
+
+// webpack.config.js
+const { RealuptimeSourcemapsPlugin } = require("@realuptime/errors/webpack");
+module.exports = { devtool: "source-map", plugins: [new RealuptimeSourcemapsPlugin({ release: process.env.GITHUB_SHA })] };
+```
+
+An upload failure is logged with the server's own message and the build
+still succeeds; pass `failOnError: true` to fail the build instead. With no
+DSN set (local builds) the plugin logs one line and uploads nothing. Limits:
+2MB per map, 50 maps per release, 10 files per request (batched for you).
+
+## What this SDK actually does
+
+- **Never crashes your app.** Every public function catches everything;
+  a broken SDK logs once (prefixed `[realuptime-errors]`) and goes quiet.
+  An error tracker that crashes the app it watches is worse than none.
+- **Scrubs PII by default, client-side**, before anything serializes:
+  `Authorization`/`Proxy-Authorization`/`Cookie`/`Set-Cookie` headers are
+  replaced whole; card-shaped digit runs (Luhn-checked), JWTs, prefixed API
+  keys, and long hex/base64 runs are pattern-scrubbed anywhere they appear
+  in the message, request context, breadcrumbs, or captured source lines.
+  Opt one field back in with `allowFields: ["x-request-id"]`; there is no
+  global "disable scrubbing" switch, by design, and an allowed field's value
+  still passes the pattern rules.
+- **Never silently drops.** The in-memory buffer (200 events) evicts the
+  oldest event when full, counts every eviction, and reports the count on
+  the next successful batch, so drops show up on your dashboard instead of
+  disappearing.
+- **Zero runtime dependencies.** `dependencies` in `package.json` is
+  always `{}`, enforced by `wire-contract.test.ts` in this repo, not just
+  claimed in prose.
+
+## Config (`init`)
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `dsn` | `string` | required | Your project's ingest URL, shown once at creation. Safe in client-side code: it can only submit events to that one project. |
+| `release` | `string?` | none | e.g. a git SHA or version tag. |
+| `environment` | `string?` | none | e.g. `"production"`. |
+| `allowFields` | `string[]?` | `[]` | Lower-cased header/field names to opt back into capture. |
+| `captureUnhandled` | `boolean` | `true` | Installs process/window handlers for uncaught exceptions and rejections. |
+
+## Source and build
+
+`index.ts`, `client.ts`, `buffer.ts`, `scrub.ts`, `custom-scrub.ts`, and
+`types.ts` are the real, tested source (see the `.test.ts` files beside them). `dist/` is a
+plain compile of that source (TypeScript's own compiler, no bundler, ES2022
+modules, declarations included) and is what `package.json` actually points
+`import`/`types` at, so a plain `npm install` plus `import` works with no
+extra build step or type-stripping flag on the consumer's side.
+
+## Version
+
+This mirror tracks SDK_VERSION `0.4.0` in `index.ts`, the string every
+event actually carries on the wire.
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

package/buffer.ts

@@ -0,0 +1,52 @@
+import type { WireEvent } from "./types.ts";
+
+/**
+ * Bounded in-memory event buffer, modelled on apps/agent/buffer.ts: oldest
+ * dropped when full, every drop counted, and the count is reported in the
+ * next successful batch (`droppedClient` on the wire) so even client-side
+ * drops reach the product's visible drop counters. In-memory only; an error
+ * SDK that writes to the customer's filesystem is over the line.
+ */
+
+export const BUFFER_MAX = 200;
+
+export class EventBuffer {
+  private events: WireEvent[] = [];
+  private droppedSinceReport = 0;
+
+  push(event: WireEvent): void {
+    if (this.events.length >= BUFFER_MAX) {
+      this.events.shift();
+      this.droppedSinceReport += 1;
+    }
+    this.events.push(event);
+  }
+
+  get length(): number {
+    return this.events.length;
+  }
+
+  /** Reads up to `n` events without removing them; `commit(n)` removes them
+   * only after the server acknowledged the batch, so a failed delivery
+   * retries the same events instead of losing them. */
+  peekBatch(n: number): WireEvent[] {
+    return this.events.slice(0, n);
+  }
+
+  commit(n: number): void {
+    this.events.splice(0, n);
+  }
+
+  /** The drop count to carry on the NEXT batch. Taken (reset to zero) only
+   * when the caller is about to put it on the wire; if that delivery fails
+   * the caller must give it back via `restoreDropped`. */
+  takeDropped(): number {
+    const n = this.droppedSinceReport;
+    this.droppedSinceReport = 0;
+    return n;
+  }
+
+  restoreDropped(n: number): void {
+    this.droppedSinceReport += n;
+  }
+}

package/client.ts

@@ -0,0 +1,181 @@
+import { EventBuffer } from "./buffer.ts";
+import { MAX_EVENTS_PER_BATCH, type WireBatch, type WireEvent, type WireIngestResult } from "./types.ts";
+
+/**
+ * Delivery: batched, buffered, backed off, and incapable of crashing the
+ * host app (docs/errors-plan.md, "The SDKs"). Disciplines inherited from
+ * apps/agent/api.ts and runtime.ts:
+ *
+ *   - Failures never throw out of the SDK. Everything is caught; the first
+ *     failure of each kind logs ONCE and further ones are silent, because
+ *     an error tracker that floods the console is nearly as bad as one that
+ *     throws.
+ *   - Transient failures (network, 5xx, unparseable body) back off
+ *     exponentially and the events stay buffered.
+ *   - `over_quota` responses stop delivery until the reset instant the
+ *     server names. Retrying into a hard cap burns the customer's cycles
+ *     and our ingest budget for nothing; the drop already happened and is
+ *     already counted server-side.
+ *   - `key_revoked` (403) disables the SDK for the process lifetime after
+ *     one log line naming the fix. A revoked key never becomes an event
+ *     black hole or a retry storm.
+ *   - `rate_limited` (429) is transient: back off and keep the events.
+ */
+
+export const SEND_TIMEOUT_MS = 10_000;
+export const BACKOFF_START_MS = 5_000;
+export const BACKOFF_MAX_MS = 300_000;
+
+export interface TransportOptions {
+  endpoint: string;
+  sdk: string;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  log?: (message: string) => void;
+}
+
+interface RefusalBody {
+  error?: string;
+  reason?: string;
+  resetsAt?: string;
+}
+
+export class Transport {
+  private readonly buffer = new EventBuffer();
+  private readonly fetchImpl: typeof fetch;
+  private readonly now: () => number;
+  private readonly log: (message: string) => void;
+  private backoffMs = 0;
+  private nextAttemptAt = 0;
+  private pausedUntil = 0;
+  private disabled = false;
+  private loggedKinds = new Set<string>();
+  private inFlight: Promise<void> | null = null;
+
+  constructor(private readonly options: TransportOptions) {
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.now = options.now ?? Date.now;
+    this.log = options.log ?? ((message) => console.error(message));
+  }
+
+  enqueue(event: WireEvent): void {
+    if (this.disabled) return;
+    this.buffer.push(event);
+    void this.flush();
+  }
+
+  /** Sends what is due. Serialized: one delivery in flight at a time, so a
+   * burst of captures becomes one batch, not a request per event. */
+  flush(): Promise<void> {
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.deliver().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+
+  private logOnce(kind: string, message: string): void {
+    if (this.loggedKinds.has(kind)) return;
+    this.loggedKinds.add(kind);
+    this.log(`[realuptime-errors] ${message}`);
+  }
+
+  private async deliver(): Promise<void> {
+    while (this.buffer.length > 0) {
+      const now = this.now();
+      if (this.disabled || now < this.nextAttemptAt || now < this.pausedUntil) return;
+
+      const events = this.buffer.peekBatch(MAX_EVENTS_PER_BATCH);
+      const droppedClient = this.buffer.takeDropped();
+      const batch: WireBatch = { sdk: this.options.sdk, droppedClient, events };
+
+      let response: Response;
+      try {
+        response = await this.fetchImpl(this.options.endpoint, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(batch),
+          signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+        });
+      } catch {
+        this.buffer.restoreDropped(droppedClient);
+        this.backOff("network", "cannot reach the ingest endpoint; buffering and retrying");
+        return;
+      }
+
+      if (response.ok) {
+        this.buffer.commit(events.length);
+        this.backoffMs = 0;
+        this.nextAttemptAt = 0;
+        let body: WireIngestResult | null = null;
+        try {
+          body = (await response.json()) as WireIngestResult;
+        } catch {
+          body = null;
+        }
+        if (body?.overQuota) {
+          this.pauseUntil(body.quota?.resetsAt);
+          this.logOnce(
+            "over-quota",
+            `monthly event quota reached (${body.quota?.limit ?? "?"}); pausing until ${body.quota?.resetsAt ?? "the window resets"}. Dropped events are counted and shown on your realuptime Errors dashboard.`,
+          );
+          return;
+        }
+        continue;
+      }
+
+      let refusal: RefusalBody = {};
+      try {
+        refusal = (await response.json()) as RefusalBody;
+      } catch {
+        refusal = {};
+      }
+
+      if (response.status === 403 && refusal.reason === "key_revoked") {
+        this.disabled = true;
+        this.logOnce(
+          "revoked",
+          "this project's ingest key was revoked; error reporting is disabled for this process. Rotate the key in realuptime Errors settings and redeploy with the new DSN.",
+        );
+        return;
+      }
+      if (response.status === 429 && refusal.reason === "over_quota") {
+        // The whole batch was refused at the cap: nothing was written, and
+        // holding the events would only re-refuse them all window long.
+        this.buffer.commit(events.length);
+        this.pauseUntil(refusal.resetsAt);
+        this.logOnce(
+          "over-quota",
+          `monthly event quota reached; pausing until ${refusal.resetsAt ?? "the window resets"}. Dropped events are counted and shown on your realuptime Errors dashboard.`,
+        );
+        return;
+      }
+      if (response.status === 400) {
+        // A malformed batch will never become well-formed by retrying; drop
+        // it rather than wedging the buffer, and say so once.
+        this.buffer.commit(events.length);
+        this.buffer.restoreDropped(droppedClient);
+        this.logOnce("malformed", `the server refused a batch as malformed: ${refusal.error ?? "no detail"}. This is an SDK bug worth reporting.`);
+        continue;
+      }
+
+      this.buffer.restoreDropped(droppedClient);
+      this.backOff("transient", `ingest endpoint answered ${response.status}; buffering and retrying`);
+      return;
+    }
+  }
+
+  private pauseUntil(resetsAt: string | undefined): void {
+    const parsed = resetsAt ? Date.parse(resetsAt) : Number.NaN;
+    // A missing or unparseable reset instant still pauses meaningfully: an
+    // hour is long enough to stop the burn, short enough to recover early
+    // in a new window.
+    this.pausedUntil = Number.isFinite(parsed) ? parsed : this.now() + 60 * 60_000;
+  }
+
+  private backOff(kind: string, message: string): void {
+    this.backoffMs = this.backoffMs <= 0 ? BACKOFF_START_MS : Math.min(this.backoffMs * 2, BACKOFF_MAX_MS);
+    this.nextAttemptAt = this.now() + this.backoffMs;
+    this.logOnce(kind, `${message} (backing off).`);
+  }
+}

package/custom-scrub.ts

@@ -0,0 +1,271 @@
+import { SCRUBBED } from "./scrub.ts";
+import type { WireEvent } from "./types.ts";
+
+/**
+ * Customer-defined ADDITIONAL scrub rules, client side (REA-264). The rules
+ * a project's owner set in the realuptime Errors settings are fetched once
+ * at init (see index.ts, `fetchScrubRules`) and applied here AFTER the
+ * default scrub (scrub.ts), never instead of it. There is nothing in this
+ * file that can relax a default: a rule can only add a field name, a key
+ * glob, or a value regex that turns more into `[scrubbed]`.
+ *
+ * DUPLICATED from packages/db/error-scrub-rules.ts, the scrub.ts
+ * convention: this package must stay import-free. custom-scrub-vectors.json
+ * pins the two (and the Python SDK) to byte-identical output; a semantic
+ * change is a three-implementation change.
+ *
+ * The validator is carried here too, even though rules only ever arrive
+ * from our own endpoint, because "only ever" is not a guarantee the host
+ * app should depend on: a rule that fails the same safe-subset check the
+ * server applies is skipped, so no network response can hand this process
+ * a catastrophic-backtracking pattern.
+ */
+
+export type CustomScrubRuleKind = "field_name" | "key_glob" | "value_regex";
+export interface CustomScrubRule {
+  kind: CustomScrubRuleKind;
+  pattern: string;
+}
+
+const KINDS: readonly string[] = ["field_name", "key_glob", "value_regex"];
+const MAX_PATTERN_LENGTH = 200;
+const MAX_QUANTIFIERS = 10;
+const MAX_REPEAT = 100;
+/** Most rules a response may carry; matches the server's per-project cap. */
+export const MAX_CUSTOM_SCRUB_RULES = 50;
+
+export function validateCustomScrubRule(input: { kind: unknown; pattern: unknown }): boolean {
+  if (typeof input?.kind !== "string" || !KINDS.includes(input.kind)) return false;
+  if (typeof input.pattern !== "string") return false;
+  const pattern = input.pattern;
+  if (pattern.trim().length === 0 || pattern.length > MAX_PATTERN_LENGTH) return false;
+  if (/[\r\n]/.test(pattern)) return false;
+  if (input.kind === "field_name" || input.kind === "key_glob") {
+    if (pattern !== pattern.trim()) return false;
+    const hasWildcard = /[*?]/.test(pattern);
+    return input.kind === "key_glob" ? hasWildcard : !hasWildcard;
+  }
+  return safeRegex(pattern);
+}
+
+function safeRegex(pattern: string): boolean {
+  const groupHasQuantifier: boolean[] = [];
+  let quantifiers = 0;
+  let inClass = false;
+  let lastClosedGroupHadQuantifier = false;
+  let lastWasQuantifier = false;
+  let lastWasAtom = false;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "\\") {
+      const next = pattern[i + 1];
+      if (next === undefined) return false;
+      if (/[1-9]/.test(next) || next === "k") return false;
+      if (next === "p" || next === "P" || next === "u" || next === "c") return false;
+      i += 1;
+      if (!inClass) {
+        lastWasAtom = true;
+        lastWasQuantifier = false;
+        lastClosedGroupHadQuantifier = false;
+      }
+      continue;
+    }
+    if (inClass) {
+      if (ch === "]") inClass = false;
+      continue;
+    }
+    if (ch === "[") {
+      inClass = true;
+      if (pattern[i + 1] === "^") i += 1;
+      if (pattern[i + 1] === "]") i += 1;
+      lastWasAtom = true;
+      lastWasQuantifier = false;
+      lastClosedGroupHadQuantifier = false;
+      continue;
+    }
+    if (ch === "(") {
+      if (pattern[i + 1] === "?") {
+        if (pattern[i + 2] !== ":") return false;
+        i += 2;
+      }
+      groupHasQuantifier.push(false);
+      lastWasAtom = false;
+      lastWasQuantifier = false;
+      lastClosedGroupHadQuantifier = false;
+      continue;
+    }
+    if (ch === ")") {
+      const had = groupHasQuantifier.pop();
+      if (had === undefined) return false;
+      lastClosedGroupHadQuantifier = had;
+      if (had && groupHasQuantifier.length > 0) groupHasQuantifier[groupHasQuantifier.length - 1] = true;
+      lastWasAtom = true;
+      lastWasQuantifier = false;
+      continue;
+    }
+    const isBrace = ch === "{";
+    if (ch === "*" || ch === "+" || ch === "?" || isBrace) {
+      if (isBrace) {
+        const close = pattern.indexOf("}", i);
+        const body = close === -1 ? null : pattern.slice(i + 1, close);
+        const m = body === null ? null : /^(\d+)(?:,(\d*))?$/.exec(body);
+        if (!m) {
+          lastWasAtom = true;
+          lastWasQuantifier = false;
+          lastClosedGroupHadQuantifier = false;
+          continue;
+        }
+        const lo = Number(m[1]);
+        const hi = m[2] === undefined ? lo : m[2] === "" ? Number.POSITIVE_INFINITY : Number(m[2]);
+        if (lo > MAX_REPEAT || (Number.isFinite(hi) && hi > MAX_REPEAT)) return false;
+        if (Number.isFinite(hi) && hi < lo) return false;
+        i = close;
+      }
+      if (ch === "?" && lastWasQuantifier) {
+        lastWasQuantifier = false;
+        continue;
+      }
+      if (!lastWasAtom) return false;
+      if (lastClosedGroupHadQuantifier) return false;
+      quantifiers += 1;
+      if (quantifiers > MAX_QUANTIFIERS) return false;
+      if (groupHasQuantifier.length > 0) groupHasQuantifier[groupHasQuantifier.length - 1] = true;
+      lastWasAtom = false;
+      lastWasQuantifier = true;
+      lastClosedGroupHadQuantifier = false;
+      continue;
+    }
+    if (ch === "|") {
+      lastWasAtom = false;
+      lastWasQuantifier = false;
+      lastClosedGroupHadQuantifier = false;
+      continue;
+    }
+    lastWasAtom = true;
+    lastWasQuantifier = false;
+    lastClosedGroupHadQuantifier = false;
+  }
+  if (inClass || groupHasQuantifier.length > 0) return false;
+  let compiled: RegExp;
+  try {
+    compiled = new RegExp(pattern, "g");
+  } catch {
+    return false;
+  }
+  return !new RegExp(compiled.source).test("");
+}
+
+export interface CompiledCustomScrubRules {
+  matchesKey: (name: string) => boolean;
+  valueRegexes: RegExp[];
+  count: number;
+}
+
+function globToRegExp(glob: string): RegExp {
+  let out = "^";
+  for (const ch of glob) {
+    if (ch === "*") out += ".*";
+    else if (ch === "?") out += ".";
+    else out += ch.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  }
+  return new RegExp(`${out}$`, "i");
+}
+
+/** Compiles rules, skipping any that fail validation. Never throws. */
+export function compileCustomScrubRules(rules: readonly unknown[]): CompiledCustomScrubRules {
+  const names = new Set<string>();
+  const globs: RegExp[] = [];
+  const valueRegexes: RegExp[] = [];
+  let count = 0;
+  for (const raw of rules.slice(0, MAX_CUSTOM_SCRUB_RULES)) {
+    const rule = raw as { kind?: unknown; pattern?: unknown };
+    if (!rule || typeof rule !== "object" || !validateCustomScrubRule({ kind: rule.kind, pattern: rule.pattern })) continue;
+    count += 1;
+    const pattern = rule.pattern as string;
+    if (rule.kind === "field_name") names.add(pattern.toLowerCase());
+    else if (rule.kind === "key_glob") globs.push(globToRegExp(pattern));
+    else valueRegexes.push(new RegExp(pattern, "g"));
+  }
+  return {
+    matchesKey: (name) => {
+      const lower = name.toLowerCase();
+      if (names.has(lower)) return true;
+      for (const glob of globs) if (glob.test(lower)) return true;
+      return false;
+    },
+    valueRegexes,
+    count,
+  };
+}
+
+export const NO_CUSTOM_SCRUB_RULES: CompiledCustomScrubRules = { matchesKey: () => false, valueRegexes: [], count: 0 };
+
+function applyValue(value: string, compiled: CompiledCustomScrubRules): string {
+  let out = value;
+  for (const re of compiled.valueRegexes) {
+    re.lastIndex = 0;
+    out = out.replace(re, SCRUBBED);
+  }
+  return out;
+}
+
+/** Applies compiled rules to an event that has ALREADY been through
+ * scrubEvent. Returns a new object; never mutates the input. */
+export function applyCustomScrubRules(event: WireEvent, compiled: CompiledCustomScrubRules): WireEvent {
+  if (compiled.count === 0) return event;
+  const value = (input: string): string => applyValue(input, compiled);
+  const entry = (name: string, input: string): string => (compiled.matchesKey(name) ? SCRUBBED : value(input));
+  const map = <M extends object>(input: M, prefix = ""): M => {
+    const out: Record<string, unknown> = {};
+    for (const [name, v] of Object.entries(input)) out[name] = typeof v === "string" ? entry(prefix + name, v) : v;
+    return out as M;
+  };
+  return {
+    ...event,
+    message: value(event.message),
+    request: event.request
+      ? {
+          ...event.request,
+          ...(typeof event.request.path === "string" ? { path: value(event.request.path) } : {}),
+          ...(typeof event.request.route === "string" ? { route: value(event.request.route) } : {}),
+          ...(event.request.headers ? { headers: map(event.request.headers) } : {}),
+        }
+      : event.request,
+    breadcrumbs: event.breadcrumbs
+      ? event.breadcrumbs.map((crumb) => ({
+          ...crumb,
+          message: value(crumb.message),
+          ...(crumb.data ? { data: map(crumb.data) } : {}),
+        }))
+      : event.breadcrumbs,
+    frames: event.frames
+      ? event.frames.map((frame) =>
+          frame.contextLine != null || frame.preContext?.length || frame.postContext?.length || frame.vars
+            ? {
+                ...frame,
+                ...(frame.contextLine != null ? { contextLine: value(frame.contextLine) } : {}),
+                ...(frame.preContext ? { preContext: frame.preContext.map(value) } : {}),
+                ...(frame.postContext ? { postContext: frame.postContext.map(value) } : {}),
+                ...(frame.vars ? { vars: map(frame.vars) } : {}),
+              }
+            : frame,
+        )
+      : event.frames,
+    ...(event.user ? { user: map(event.user, "user.") } : {}),
+    ...(event.tags ? { tags: map(event.tags) } : {}),
+    ...(event.context ? { context: map(event.context) } : {}),
+    ...(event.device ? { device: map(event.device) } : {}),
+  };
+}
+
+/**
+ * The rules endpoint for a DSN: the ingest URL with `/ingest/` swapped for
+ * `/scrub-rules/`. Returns null for a DSN that is not ingest-shaped, in
+ * which case no fetch is attempted and the defaults run alone.
+ */
+export function scrubRulesUrlFor(dsn: string): string | null {
+  const marker = "/api/errors/v1/ingest/";
+  const at = dsn.indexOf(marker);
+  if (at === -1) return null;
+  return `${dsn.slice(0, at)}/api/errors/v1/scrub-rules/${dsn.slice(at + marker.length)}`;
+}

package/dist/buffer.d.ts

@@ -0,0 +1,25 @@
+import type { WireEvent } from "./types.ts";
+/**
+ * Bounded in-memory event buffer, modelled on apps/agent/buffer.ts: oldest
+ * dropped when full, every drop counted, and the count is reported in the
+ * next successful batch (`droppedClient` on the wire) so even client-side
+ * drops reach the product's visible drop counters. In-memory only; an error
+ * SDK that writes to the customer's filesystem is over the line.
+ */
+export declare const BUFFER_MAX = 200;
+export declare class EventBuffer {
+    private events;
+    private droppedSinceReport;
+    push(event: WireEvent): void;
+    get length(): number;
+    /** Reads up to `n` events without removing them; `commit(n)` removes them
+     * only after the server acknowledged the batch, so a failed delivery
+     * retries the same events instead of losing them. */
+    peekBatch(n: number): WireEvent[];
+    commit(n: number): void;
+    /** The drop count to carry on the NEXT batch. Taken (reset to zero) only
+     * when the caller is about to put it on the wire; if that delivery fails
+     * the caller must give it back via `restoreDropped`. */
+    takeDropped(): number;
+    restoreDropped(n: number): void;
+}