@terrapi/phoebe-browser

@terrapi/phoebe-browser

Phoebe Errors browser SDK. A thin, brand-clean wrapper around the official MIT-licensed @sentry/browser SDK. Phoebe's ingest endpoint is Sentry-wire-compatible, so the upstream SDK handles all transport and serialization — this package only owns Phoebe defaults, two custom capture integrations, and a stable public API.

Install

npm install @terrapi/phoebe-browser
# web-vitals is an optional dependency, installed automatically; remove with --no-optional

Quick start

import * as Phoebe from "@terrapi/phoebe-browser";

Phoebe.init({
  dsn: "https://abc123@errors.phoebe.io/42", // public key is WRITE-ONLY
  environment: "production",
  release: "web@1.4.2",
  tracesSampleRate: 0.1, // Web Vitals + performance; 0 disables
  sampleRate: 1.0,       // fraction of errors to send
});

// Use the re-exported API anywhere — never import @sentry/* directly.
Phoebe.setUser({ id: "user_123" });
Phoebe.captureException(new Error("boom"));
Phoebe.addBreadcrumb({ category: "checkout", message: "clicked pay" });

What init() turns on

Capability	Backed by
Global JS errors + unhandledrejection	globalHandlersIntegration
fetch/XHR failures (network, 4xx/5xx)	httpClientIntegration (see note)
Failed subresource loads (script/img/css)	phoebeResourceErrorsIntegration (custom)
Breadcrumbs (clicks, navigation, console, fetch)	breadcrumbsIntegration
Async-callback errors	browserApiErrorsIntegration
Web Vitals (LCP/CLS/INP/FCP/TTFB)	browserTracingIntegration
cause chaining + de-duplication	linkedErrors + dedupe

Options

See PhoebeBrowserOptions in src/types.ts. Notable Phoebe-specific flags:

• captureResourceErrors (default true) — failed subresource capture.
• useWebVitalsPackage (default false) — also report Web Vitals via the standalone web-vitals package (browserTracing already records them).
• failedRequestStatusCodes (default [[400, 599]]) — which HTTP statuses become error events. Defaults to all 4xx + 5xx (maximum visibility).
• failedRequestTargets (default: all URLs) — allowlist of request URLs whose failures are captured.

Tuning HTTP capture per app

By default every failing request (4xx + 5xx, any URL) becomes an issue. To cut noise from expected failures — e.g. 404s for missing map tiles — narrow it:

Phoebe.init({
  dsn: "...",
  // Only treat server errors + rate limits as issues (skip 401/404/422 etc.):
  failedRequestStatusCodes: [[500, 599], 429],
  // ...or keep all statuses but only for your own API hosts:
  failedRequestTargets: [/api\.myapp\.com/],
});

Honest caveats

• CORS detection is heuristic. A genuine CORS/offline/DNS failure yields a TypeError: Failed to fetch with no HTTP response, so there is no status code to match. httpClientIntegration captures 4xx/5xx where a response exists; true CORS failures show up as unhandled exceptions + fetch breadcrumbs. We cannot reliably distinguish CORS from a network drop in the browser.
• Resource errors have no status. Browsers hide why a subresource failed (cross-origin privacy), so these are reported as warnings with element + URL.
• Protocol coupling is version-pinned. This package targets the Sentry JavaScript v9 wire format and API. The dependency is pinned accordingly.

Build

npm run build           # tsup -> ESM + CJS + d.ts + minified IIFE (CDN)
npm run typecheck       # against installed @sentry/browser
npm run typecheck:verify # offline, against ../../types ambient shims

The IIFE output (dist/index.global.js) exposes window.Phoebe and is the file the loader snippet async-loads from the CDN.