@newtalaria/browser 0.1.16 → 0.1.18

package/README.md

@@ -2,6 +2,8 @@
 
 Browser SDK for [Talaria](https://github.com/) — error capture and **session replay** (rrweb event streams, not video).
 
+Network calls (`fetch` / XHR) are instrumented as replay breadcrumbs; **only first-party (same-origin) or allowlisted origins** promote failed requests to error events — see [Failed HTTP / network requests](#failed-http--network-requests--events).
+
 ## Install
 
 ```bash
@@ -187,27 +189,68 @@ Set `inlineStylesheet: true` so same-origin stylesheet rules are embedded while
 
 ### Failed HTTP / network requests → events
 
-By default, completed `fetch` / XHR responses with status **500–599** are sent as Talaria events (message like `HTTP 500: GET /api/...`).
+All instrumented `fetch` / XHR calls are recorded as replay breadcrumbs (`talaria-network`). **Error events are promoted only for first-party (same-origin) or explicitly allowlisted origins.**
+
+| Request | HTTP 5xx | Transport failure / timeout | Abort |
+| --- | --- | --- | --- |
+| Same-origin | Error event | Error event | Breadcrumb only |
+| Allowlisted third-party (`networkErrorOrigins`) | Error event | Error event | Breadcrumb only |
+| Other third-party (analytics, ads, widgets, …) | Breadcrumb only | Breadcrumb only | Breadcrumb only |
+
+This avoids Issue spam from Google Analytics, ad pixels, privacy blockers, and similar third-party noise—without a hardcoded domain denylist. Add origins you intentionally depend on (payments, CMS APIs, widgets):
+
+```ts
+networkErrorOrigins: ['https://api.stripe.com', 'https://widget.yonder.example'],
+// Escape hatch (not recommended): networkErrorOrigins: ['*']
+```
+
+**URL privacy:** network telemetry stores `origin + pathname` only (plus `hostname` / `pathname`). Query strings and fragments are stripped by default. Set `captureRequestQueryParameters: true` to keep query params after redaction of secrets **and** common tracking keys (`token`, `api_key`, `gclid`, `fbclid`, `_ga`, `cid`, `sid`, …). Bodies and auth headers are never captured.
+
+Both **`fetch`** and **`XMLHttpRequest`** are instrumented (`network.transport`: `fetch` | `xhr`). Failure kinds are only claimed when detectable:
 
-Transport failures (CORS, offline, DNS — browser `TypeError: Failed to fetch`) are also promoted by default as:
+| `failure.kind` | Meaning |
+| --- | --- |
+| `http` | Completed response with a real status (e.g. 500) |
+| `network` | No usable HTTP response (status 0 / Failed to fetch) — CORS, block, DNS, offline, etc. |
+| `timeout` | `TimeoutError` or XHR `timeout` event |
+| `abort` | `AbortError` / XHR abort — recorded in breadcrumbs, **not** promoted as events |
+
+We **do not** classify status 0 as `cors` — browsers do not expose that reliably. Tags include `network.party` (`first_party` \| `third_party`).
 
-`Network error: POST https://www.google-analytics.com/g/collect — TypeError: Failed to fetch`
+Promoted events use structured `extra` (server groups on method + host + path + kind + status):
 
-**URL privacy:** network telemetry stores `origin + pathname` only (plus `hostname` / `pathname` fields). Query strings and fragments are stripped by default — analytics/ads URLs often carry `cid`, `sid`, `dl`, etc. Set `includeNetworkUrlQuery: true` to keep query params after sensitive-key redaction (`token`, `api_key`, …).
+```json
+{
+  "http": {
+    "method": "POST",
+    "url": "https://app.example.com/api/orders",
+    "origin": "https://app.example.com",
+    "hostname": "app.example.com",
+    "pathname": "/api/orders",
+    "transport": "fetch"
+  },
+  "failure": { "kind": "network", "name": "TypeError", "message": "Failed to fetch" },
+  "network": { "party": "first_party", "durationMs": 842, "aborted": false, "ok": false },
+  "exception_class": "NetworkError",
+  "status_code": null
+}
+```
 
-Replay `talaria-network` breadcrumbs include method, sanitized URL, status (when an HTTP response exists), duration, and on failures `errorName` / `errorMessage` / `aborted` / `failureKind`. Request/response bodies and auth headers are never captured.
+Crawler UAs are tagged (`bot=true`, `bot.name=Baiduspider`) without inventing a browser name.
 
 ```ts
 Talaria.init({
   dsn: 'https://api.example.com',
   apiKey: 'tal_live_…',
   environment: 'production',
-  // Default true — HTTP status promotion
+  // Default true — HTTP status promotion (first-party / allowlisted only)
   captureFailedRequests: true,
-  // Default true — CORS/offline/DNS fetch failures
+  // Default true — transport failures (first-party / allowlisted only)
   captureNetworkErrors: true,
+  // Extra origins to treat like first-party for promotion
+  networkErrorOrigins: ['https://api.stripe.com'],
   // Default false — do not store ?query on network URLs
-  includeNetworkUrlQuery: false,
+  captureRequestQueryParameters: false,
   // Default [[500, 599]]. CMS admin often wants 4xx too:
   failedRequestStatusCodes: [[400, 599]],
   // Extra URL substrings to skip (Talaria /events and /replays are always skipped)
@@ -215,7 +258,24 @@ Talaria.init({
 });
 ```
 
-`AbortError` is never promoted and is ignored by the global `unhandledrejection` handler. If a fetch failure is left unhandled after network-error promotion, the duplicate bare `TypeError` event is suppressed; if promotion is off, the exception is kept and correlated with the recent request URL/method/duration.
+`AbortError` is never promoted and is ignored by the global `unhandledrejection` handler. Bare `TypeError: Failed to fetch` / `TimeoutError` rejections are correlated with recent network breadcrumbs: promoted failures and third-party noise are suppressed; first-party failures with promotion off keep the exception and merge request context.
+
+#### Network event tags (low cardinality)
+
+| Tag | Values | Notes |
+| --- | --- | --- |
+| `http.method` | `GET`, `POST`, … | |
+| `http.status_code` | e.g. `500` | Present on HTTP promotions only |
+| `network.failure_kind` | `http` \| `network` \| `timeout` | |
+| `network.transport` | `fetch` \| `xhr` | |
+| `network.party` | `first_party` \| `third_party` | Same-origin vs cross-origin (allowlist does not change this tag) |
+| `network.error_name` | e.g. `TypeError`, `TimeoutError` | When available |
+
+Hostname, pathname, full sanitized URL, and duration live in `extra` — not tags — to avoid high-cardinality facets.
+
+#### Issue grouping (server)
+
+Promoted network events set `extra.exception_class` (`HttpError` \| `NetworkError` \| `TimeoutError`) and `extra.status_code`. The server fingerprints them on **method + hostname + pathname + failure kind + status** (not the human message), so query strings and volatile error text do not fragment Issues. See [`planning/fingerprints.md`](../../../planning/fingerprints.md) §6.4.
 
 ### Event timestamps
 
@@ -226,11 +286,35 @@ Talaria.init({
 
 If replay upload runs before event ingest, `extra.sdk.queuedMs` records how long capture waited (ms). A large `createdAt - timestamp` gap is usually flush/queue delay or clock skew — not a wrong failure classification.
 
+## Init options reference
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `dsn` / `baseUrl` | *(required)* | Serverpod host, e.g. `https://api.example.com` |
+| `apiKey` | *(required)* | Project API key (`tal_live_…`) |
+| `environment` | *(required)* | `production` \| `staging` \| `development` (aliases accepted) |
+| `release` | — | Optional release string on every event |
+| `userId` | — | Optional app user id |
+| `tags` | — | Tags merged into every event |
+| `replaysSessionSampleRate` | `0` | Fraction of sessions that upload continuously |
+| `replaysOnErrorSampleRate` | `1` | Fraction of errors that promote the ring buffer |
+| `replaysErrorAfterMs` | `15000` | Post-error upload window; `0` = continue to 5 min cap |
+| `maskAllInputs` | `true` | rrweb input masking |
+| `inlineStylesheet` | `false` | Embed same-origin CSS (CMS/admin) |
+| `blockSelector` | — | Extra CSS selectors blocked from the DOM snapshot |
+| `disableDefaultIntegrations` | `false` | Skip `window.onerror` / `unhandledrejection` |
+| `captureFailedRequests` | `true` | Promote HTTP status failures (**first-party / allowlisted only**) |
+| `captureNetworkErrors` | `true` | Promote transport/timeout failures (**first-party / allowlisted only**) |
+| `networkErrorOrigins` | `[]` | Extra origins eligible for promotion; same-origin always eligible; `['*']` = all (not recommended) |
+| `failedRequestStatusCodes` | `[[500, 599]]` | Status codes/ranges to promote when origin is eligible |
+| `failedRequestIgnoreUrls` | `[]` | URL substrings never promoted (Talaria `/events` + `/replays` always ignored) |
+| `captureRequestQueryParameters` | `false` | Keep `?query` on network URLs after redaction (`includeNetworkUrlQuery` alias) |
+
 ## Public API
 
 | API | Description |
 | --- | --- |
-| `Talaria.init(options)` | Configure + start recording |
+| `Talaria.init(options)` | Configure + start recording + install network/console hooks |
 | `Talaria.captureException(error)` | Ingest error (+ replay link when sampled) |
 | `Talaria.captureMessage(message, level?)` | Ingest message |
 | `Talaria.getReplayId()` | Active upload replay id, or `null` |

package/dist/client.d.ts

@@ -107,7 +107,7 @@ export declare class TalariaClient {
     private pruneRecentNetworkFailures;
     private rememberNetworkFailure;
     /**
-     * Find a recent transport failure for a bare fetch TypeError.
+     * Find a recent transport failure for a bare fetch TypeError / TimeoutError.
      * Consumes the entry so a later duplicate path cannot reuse it.
      */
     private consumeCorrelatedNetworkFailure;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}