@weatherboard/errors 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weatherboard
+
+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

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @weatherboard/errors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Products never import `@sentry/*` directly.
+
+Entry points:
+- `./next`: `withErrors(nextConfig, opts)` wraps Next config, exposes `$SENTRY_BUILD_ENVIRONMENT` and `$SENTRY_BUILD_RELEASE`, and uploads source maps only with all three upload variables. Maps are deleted after upload; budget builds can set `PERF_BUDGET_SOURCE_MAPS=keep`.
+- `./next/server`: `register` and `onRequestError` for server instrumentation.
+- `./next/client`: deferred browser initialization and `onRouterTransitionStart`. Buffers early errors and rejections, loading immediately on the first error; otherwise waits for load and idle. Breadcrumbs before SDK initialization are unavailable.
+- `./next/global-error`: `GlobalError` reports render failures and renders its required `children`; the product supplies the fallback document and design.
+- `./client`: `reportHandled(error, { where, extra })` for catches that show a banner or toast. Fingerprints use `where` and message. Never throws; before the deferred browser SDK loads, queues the error and its context and requests the SDK immediately. With no configured loader or a disabled SDK, it is a no-op. The `where` tag identifies the catch site.
+- `./http`: `refuse(status, message, { kind, where, context?, body?, headers? })` returns `{ error: message, ...body }`. Expected refusals add a breadcrumb; invariant refusals capture a grouped warning. `fail(message, cause, { where, status = 500, context?, body?, headers? })` captures the original exception and returns only the supplied public message/body. Both tolerate reporting failures and skip telemetry before SDK initialization. Context redacts sensitive keys, bearer strings, known token formats and email addresses.
+- `./noise`: shared patterns with their justifying issue ids.
+- `./worker`: `withWorkerErrors`, `withDurableObjectErrors` and Worker `reportHandled`.
+- `./verify`: `verifyErrors(appDirectory)` or `verifyWorkerWiring(workerDirectory)` registers the product wiring test.
+
+The five configuration variables are `SENTRY_DSN` (server), `PUBLIC_SENTRY_DSN` (browser), `SENTRY_ORG`, `SENTRY_PROJECT`, and `SENTRY_AUTH_TOKEN` (secret, build only). The wrapper inlines only the public DSN. Reporting requires a DSN and `VERCEL_ENV=production` or `preview`; development and unset environments do not initialize. Release comes from `VERCEL_GIT_COMMIT_SHA`, never `NODE_ENV`. Tracing is off and default PII is disabled.
+
+Wire a Next app in four files:
+
+1. In `next.config.mjs`: import `{ withErrors }` from `@weatherboard/errors/next` and export `withErrors(nextConfig)`.
+2. In `instrumentation.ts`: export `{ register, onRequestError }` from `@weatherboard/errors/next/server`.
+3. In `instrumentation-client.ts`: export `{ onRouterTransitionStart }` from `@weatherboard/errors/next/client`.
+4. In the app's global error boundary, mark it `"use client"`, import `{ GlobalError }` from `@weatherboard/errors/next/global-error`, and render `<GlobalError error={error}><html><body>your fallback</body></html></GlobalError>`.
+
+Add a node:test file calling `verifyErrors` with the app directory. React Native is outside this version. Never pass a private cause message as the public HTTP message. Extra body fields retain their existing wire shape; they are not telemetry context.
+
+## Cloudflare Workers
+
+Import from `@weatherboard/errors/worker`. Wrap the default handler with
+`withWorkerErrors(handler)`. Export each Durable Object as
+`const MyObject = withDurableObjectErrors(MyObjectImplementation)` and an instance
+type alias when bindings reference that type. Built-in handlers, alarms, WebSocket
+handlers and prototype RPC methods are instrumented by `@sentry/cloudflare`.
+`verifyWorkerWiring(dir)` checks the defaults, DO classes and direct SDK imports.
+
+Optional environment fields (extend `WorkerErrorEnv` in the Worker's typed Env):
+
+| Field | Purpose |
+| --- | --- |
+| `SENTRY_DSN` | Worker secret; absent means the original invocation/construction path runs without Sentry |
+| `SENTRY_ENVIRONMENT` | Explicit reporting environment |
+| `ENVIRONMENT` | Existing per-environment Worker var, used when the explicit field is absent |
+| `SENTRY_RELEASE` | Git SHA recorded by the deploy; takes precedence over version metadata |
+| `CF_VERSION_METADATA` | Cloudflare `version_metadata` binding; when `SENTRY_RELEASE` is absent, release uses `tag`, then `id` if untagged (a platform version ID, not a git SHA) |
+
+A Worker deployed per environment reads its own environment var. A Worker shared
+by every environment must take the decision from its caller through a trusted
+mapping, or treat absence as non-production; never infer production from the
+shared Worker's deployment. Unset environment becomes `development`. Reporting is
+enabled by a DSN; development is not promoted to production or silently discarded.
+No DSN leaves the handler's arguments, receiver, result and thrown errors unchanged.
+The wrapper selects the original handler at invocation time because Worker secrets
+are unavailable at module evaluation. DO construction similarly bypasses the SDK.
+
+Tracing is disabled (`tracesSampleRate: 0`), default PII is disabled
+(`sendDefaultPii: false`), and the SDK flushes via `waitUntil`; responses do not wait
+for reporting. In catches that recover, keep the existing log and call
+`reportHandled(error, { where, extra })` inside the instrumented invocation. It
+fingerprints by `where` and message and never throws. Only send scrubbed errors and
+safe extras: default PII settings do not scrub application-supplied exception text.

package/after-load.d.ts

@@ -0,0 +1,15 @@
+export type LoadWindow = {
+    readonly document: {
+        readonly readyState: string;
+    };
+    addEventListener(type: "load", listener: () => void, options: {
+        once: true;
+    }): void;
+    setTimeout(handler: () => void, timeout: number): unknown;
+    readonly requestIdleCallback?: (callback: () => void, options: {
+        timeout: number;
+    }) => unknown;
+};
+export declare const IDLE_TIMEOUT_MS = 2000;
+export declare const IDLE_FALLBACK_MS = 200;
+export declare function afterLoadAndIdle(win: LoadWindow, run: () => void): void;

package/after-load.js

@@ -0,0 +1,18 @@
+const IDLE_TIMEOUT_MS = 2e3;
+const IDLE_FALLBACK_MS = 200;
+function afterLoadAndIdle(win, run) {
+  const whenIdle = () => {
+    if (typeof win.requestIdleCallback === "function") {
+      win.requestIdleCallback(run, { timeout: IDLE_TIMEOUT_MS });
+    } else {
+      win.setTimeout(run, IDLE_FALLBACK_MS);
+    }
+  };
+  if (win.document.readyState === "complete") whenIdle();
+  else win.addEventListener("load", whenIdle, { once: true });
+}
+export {
+  IDLE_FALLBACK_MS,
+  IDLE_TIMEOUT_MS,
+  afterLoadAndIdle
+};

package/browser-sdk.d.ts

@@ -0,0 +1,3 @@
+import * as Sentry from "@sentry/nextjs";
+export declare const captureException: typeof Sentry.captureException;
+export declare const captureRouterTransitionStart: typeof Sentry.captureRouterTransitionStart;

package/browser-sdk.js

@@ -0,0 +1,27 @@
+import * as Sentry from "@sentry/nextjs";
+import { attachReporter } from "./client.js";
+import { SENTRY_IGNORE_ERRORS } from "./noise.js";
+Sentry.init({
+  dsn: process.env.PUBLIC_SENTRY_DSN,
+  environment: $SENTRY_BUILD_ENVIRONMENT,
+  release: $SENTRY_BUILD_RELEASE || void 0,
+  tracesSampleRate: 0,
+  sendDefaultPii: false,
+  defaultIntegrations: false,
+  integrations: [
+    Sentry.globalHandlersIntegration(),
+    Sentry.dedupeIntegration(),
+    Sentry.breadcrumbsIntegration(),
+    Sentry.linkedErrorsIntegration(),
+    Sentry.functionToStringIntegration(),
+    Sentry.browserSessionIntegration()
+  ],
+  ignoreErrors: SENTRY_IGNORE_ERRORS
+});
+attachReporter(Sentry);
+const captureException = Sentry.captureException;
+const captureRouterTransitionStart = Sentry.captureRouterTransitionStart;
+export {
+  captureException,
+  captureRouterTransitionStart
+};

package/client.d.ts

@@ -0,0 +1,14 @@
+import { type CaptureContext } from "./sentry-deferred.js";
+export type HandledContext = {
+    where: string;
+    extra?: Record<string, unknown>;
+};
+type Reporter = {
+    isEnabled(): boolean;
+    captureException(error: unknown, context: CaptureContext): unknown;
+};
+/** Internal SDK registration shared by server and browser entry points. */
+export declare function attachReporter(reporter: Reporter): void;
+/** UI catch sites must never fail while reporting the original error. No SDK import on this path. */
+export declare function reportHandled(error: unknown, context: HandledContext): void;
+export {};

package/client.js

@@ -0,0 +1,21 @@
+import { captureException } from "./sentry-deferred.js";
+const KEY = /* @__PURE__ */ Symbol.for("weatherboard.errors.reporter");
+const holder = globalThis;
+function attachReporter(reporter) {
+  holder[KEY] = reporter;
+}
+function reportHandled(error, context) {
+  try {
+    const sdk = holder[KEY];
+    if (sdk && !sdk.isEnabled()) return;
+    const message = error instanceof Error ? error.message : String(error);
+    const captureContext = { fingerprint: [context.where, message], tags: { where: context.where }, extra: context.extra };
+    if (sdk) sdk.captureException(error, captureContext);
+    else captureException(error, captureContext);
+  } catch {
+  }
+}
+export {
+  attachReporter,
+  reportHandled
+};

package/environment.d.ts

@@ -0,0 +1,2 @@
+/** Only deployed Vercel environments report errors; NODE_ENV is deliberately irrelevant. */
+export declare function deployedEnvironment(value: string | undefined): "production" | "preview" | null;

package/environment.js

@@ -0,0 +1,6 @@
+function deployedEnvironment(value) {
+  return value === "production" || value === "preview" ? value : null;
+}
+export {
+  deployedEnvironment
+};

package/global-error.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+/** Reporting only. The product owns its document and fallback design. */
+export declare function GlobalError({ error, children }: {
+    error: Error & {
+        digest?: string;
+    };
+    children: ReactNode;
+}): ReactNode;
+export default GlobalError;

package/global-error.js

@@ -0,0 +1,14 @@
+"use client";
+import { useEffect } from "react";
+import { captureException } from "./sentry-deferred.js";
+function GlobalError({ error, children }) {
+  useEffect(() => {
+    captureException(error);
+  }, [error]);
+  return children;
+}
+var global_error_default = GlobalError;
+export {
+  GlobalError,
+  global_error_default as default
+};

package/http.d.ts

@@ -0,0 +1,15 @@
+type Options = {
+    where: string;
+    context?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    headers?: HeadersInit;
+};
+/** A valid refusal is a breadcrumb; an impossible refusal is a grouped warning. */
+export declare function refuse(status: number, message: string, options: Options & {
+    kind: "expected" | "invariant";
+}): Response;
+/** Report the original cause; only the public message and body are sent to the caller. */
+export declare function fail(message: string, cause: unknown, options: Options & {
+    status?: number;
+}): Response;
+export {};

package/http.js

@@ -0,0 +1,60 @@
+import * as SentryModule from "@sentry/nextjs";
+const Sentry = SentryModule.default ?? SentryModule;
+function scrub(value, seen = /* @__PURE__ */ new WeakSet(), depth = 0) {
+  if (typeof value === "string") return value.replace(/\bBearer\s+\S+/gi, "[redacted]").replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted]").replace(/\b(?:gh[pousr]_[\w]+|github_pat_[\w]+|sk-[\w-]+|eyJ[\w-]+\.[\w-]+\.[\w-]+)\b/g, "[redacted]");
+  if (value === null || typeof value !== "object") return value;
+  if (depth >= 8 || seen.has(value)) return "[redacted]";
+  seen.add(value);
+  if (Array.isArray(value)) return value.map((item) => scrub(item, seen, depth + 1));
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    /token|secret|password|authorization|cookie|email|api.?key|credential/i.test(key) ? "[redacted]" : scrub(item, seen, depth + 1)
+  ]));
+}
+function template(message) {
+  return String(scrub(message)).replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<id>").replace(/\b[a-z]+_[a-z0-9-]+\b/gi, "<id>").replace(/\b[0-9a-f]{8,}\b/gi, "<id>").replace(/\d+/g, "<n>");
+}
+function response(message, status, options) {
+  try {
+    return Response.json({ error: message, ...options.body }, { status, headers: options.headers });
+  } catch {
+    return Response.json({ error: message }, { status: status >= 200 && status <= 599 && ![204, 205, 304].includes(status) ? status : 500 });
+  }
+}
+function refuse(status, message, options) {
+  try {
+    if (Sentry.isInitialized() && Sentry.isEnabled()) {
+      const extra = scrub(options.context);
+      const safeMessage = String(scrub(message));
+      if (options.kind === "expected") Sentry.addBreadcrumb({
+        category: "refuse",
+        level: "info",
+        message: safeMessage,
+        data: { ...extra, where: options.where, status }
+      });
+      else Sentry.captureMessage(safeMessage, {
+        level: "warning",
+        tags: { where: options.where },
+        extra,
+        fingerprint: ["refuse", options.where, template(message)]
+      });
+    }
+  } catch {
+  }
+  return response(message, status, options);
+}
+function fail(message, cause, options) {
+  try {
+    if (Sentry.isInitialized() && Sentry.isEnabled()) Sentry.captureException(cause, {
+      level: "error",
+      tags: { where: options.where },
+      extra: scrub(options.context)
+    });
+  } catch {
+  }
+  return response(message, options.status ?? 500, options);
+}
+export {
+  fail,
+  refuse
+};

package/instrumentation-client.d.ts

@@ -0,0 +1 @@
+export { onRouterTransitionStart } from "./sentry-deferred.js";

package/instrumentation-client.js

@@ -0,0 +1,13 @@
+import { afterLoadAndIdle } from "./after-load.js";
+import { bufferEarlyErrors, registerSentryLoader, loadSentryNow } from "./sentry-deferred.js";
+import { onRouterTransitionStart } from "./sentry-deferred.js";
+if (typeof window !== "undefined" && process.env.PUBLIC_SENTRY_DSN && typeof $SENTRY_BUILD_ENVIRONMENT !== "undefined" && ($SENTRY_BUILD_ENVIRONMENT === "production" || $SENTRY_BUILD_ENVIRONMENT === "preview")) {
+  registerSentryLoader(() => import("./browser-sdk.js"));
+  bufferEarlyErrors(window);
+  afterLoadAndIdle(window, () => {
+    void loadSentryNow();
+  });
+}
+export {
+  onRouterTransitionStart
+};

package/next.d.ts

@@ -0,0 +1,6 @@
+/** @param {import('next').NextConfig} nextConfig
+ * @param {{ silent?: boolean }} [opts]
+ * @returns {import('next').NextConfig} */
+export function withErrors(nextConfig: import("next").NextConfig, opts?: {
+    silent?: boolean;
+}): import("next").NextConfig;

package/next.js

@@ -0,0 +1,47 @@
+import { withSentryConfig } from "@sentry/nextjs/config";
+function withErrors(nextConfig, opts = {}) {
+  const required = ["SENTRY_ORG", "SENTRY_PROJECT", "SENTRY_AUTH_TOKEN"];
+  const missing = required.filter((name) => !process.env[name]);
+  const upload = missing.length === 0;
+  if (!upload) console.info(`[errors] source maps will NOT be uploaded: ${missing.join(", ")} not set.`);
+  const constants = {
+    $SENTRY_BUILD_ENVIRONMENT: process.env.VERCEL_ENV ?? "development",
+    $SENTRY_BUILD_RELEASE: process.env.VERCEL_GIT_COMMIT_SHA ?? "",
+    __SENTRY_DEBUG__: false,
+    __SENTRY_TRACING__: false,
+    __RRWEB_EXCLUDE_SHADOW_DOM__: true,
+    __RRWEB_EXCLUDE_IFRAME__: true,
+    __SENTRY_EXCLUDE_REPLAY_WORKER__: true
+  };
+  return withSentryConfig({
+    ...nextConfig,
+    env: { ...nextConfig.env, PUBLIC_SENTRY_DSN: process.env.PUBLIC_SENTRY_DSN ?? "" },
+    compiler: { ...nextConfig.compiler, define: { ...nextConfig.compiler?.define, ...constants } },
+    productionBrowserSourceMaps: true,
+    webpack(config, context) {
+      const configured = nextConfig.webpack ? nextConfig.webpack(config, context) : config;
+      (configured.plugins ??= []).push(new context.webpack.DefinePlugin(Object.fromEntries(
+        Object.entries(constants).map(([key, value]) => [key, JSON.stringify(value)])
+      )));
+      return configured;
+    }
+  }, {
+    org: upload ? process.env.SENTRY_ORG : void 0,
+    project: upload ? process.env.SENTRY_PROJECT : void 0,
+    authToken: upload ? process.env.SENTRY_AUTH_TOKEN : void 0,
+    sourcemaps: { disable: !upload, deleteSourcemapsAfterUpload: process.env.PERF_BUDGET_SOURCE_MAPS !== "keep" },
+    telemetry: false,
+    silent: opts.silent ?? false,
+    bundleSizeOptimizations: {
+      excludeDebugStatements: true,
+      excludeTracing: true,
+      excludeReplayShadowDom: true,
+      excludeReplayIframe: true,
+      excludeReplayWorker: true
+    },
+    webpack: { treeshake: { removeDebugLogging: true }, automaticVercelMonitors: false }
+  });
+}
+export {
+  withErrors
+};

package/noise.d.ts

@@ -0,0 +1,57 @@
+export declare const NOISE_ENTRIES: readonly [{
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "AbortError: The operation was aborted.";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "AbortError: Fetch is aborted";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "AbortError: signal is aborted without reason";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "TypeError: Load failed";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "TypeError: Failed to fetch";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "TypeError: NetworkError when attempting to fetch resource.";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "TypeError: cancelled";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "ResizeObserver loop limit exceeded";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: "ResizeObserver loop completed with undelivered notifications";
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}, {
+    readonly issue: "A-806";
+    readonly pattern: RegExp;
+}];
+export declare const SENTRY_IGNORE_ERRORS: (string | RegExp)[];
+export declare function isIgnoredMessage(message: string, patterns?: (string | RegExp)[]): boolean;

package/noise.js

@@ -0,0 +1,29 @@
+const NOISE_ENTRIES = [
+  { issue: "A-806", pattern: /window\.__firefox__/ },
+  { issue: "A-806", pattern: /Can't find variable: __firefox__/ },
+  { issue: "A-806", pattern: /Invalid call to runtime\.sendMessage\(\)\. Tab not found/i },
+  { issue: "A-806", pattern: /Extension context invalidated/i },
+  { issue: "A-806", pattern: /chrome-extension:\/\// },
+  { issue: "A-806", pattern: /moz-extension:\/\// },
+  { issue: "A-806", pattern: /window\.ethereum/i },
+  { issue: "A-806", pattern: "AbortError: The operation was aborted." },
+  { issue: "A-806", pattern: "AbortError: Fetch is aborted" },
+  { issue: "A-806", pattern: "AbortError: signal is aborted without reason" },
+  { issue: "A-806", pattern: "TypeError: Load failed" },
+  { issue: "A-806", pattern: "TypeError: Failed to fetch" },
+  { issue: "A-806", pattern: "TypeError: NetworkError when attempting to fetch resource." },
+  { issue: "A-806", pattern: "TypeError: cancelled" },
+  { issue: "A-806", pattern: "ResizeObserver loop limit exceeded" },
+  { issue: "A-806", pattern: "ResizeObserver loop completed with undelivered notifications" },
+  { issue: "A-806", pattern: /Object Not Found Matching Id:\d+, MethodName:update/ },
+  { issue: "A-806", pattern: /Non-Error promise rejection captured/ }
+];
+const SENTRY_IGNORE_ERRORS = NOISE_ENTRIES.map((entry) => entry.pattern);
+function isIgnoredMessage(message, patterns = SENTRY_IGNORE_ERRORS) {
+  return patterns.some((pattern) => typeof pattern === "string" ? message.includes(pattern) : pattern.test(message));
+}
+export {
+  NOISE_ENTRIES,
+  SENTRY_IGNORE_ERRORS,
+  isIgnoredMessage
+};

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@weatherboard/errors",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Shared Next.js, browser, HTTP and Cloudflare Worker error reporting for Weatherboard products.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Weatherboard-Studio/weatherboard-studio.git",
+    "directory": "packages/errors"
+  },
+  "type": "module",
+  "dependencies": {
+    "@sentry/cloudflare": "10.75.0",
+    "@sentry/nextjs": "10.75.0",
+    "typescript": "~5.7.2"
+  },
+  "peerDependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0"
+  },
+  "sideEffects": [
+    "./instrumentation-client.js",
+    "./browser-sdk.js"
+  ],
+  "exports": {
+    "./next": {
+      "types": "./next.d.ts",
+      "import": "./next.js"
+    },
+    "./next/server": {
+      "types": "./server.d.ts",
+      "import": "./server.js"
+    },
+    "./next/client": {
+      "types": "./instrumentation-client.d.ts",
+      "import": "./instrumentation-client.js"
+    },
+    "./next/global-error": {
+      "types": "./global-error.d.ts",
+      "import": "./global-error.js"
+    },
+    "./client": {
+      "types": "./client.d.ts",
+      "import": "./client.js"
+    },
+    "./http": {
+      "types": "./http.d.ts",
+      "import": "./http.js"
+    },
+    "./noise": {
+      "types": "./noise.d.ts",
+      "import": "./noise.js"
+    },
+    "./verify": {
+      "types": "./verify.d.ts",
+      "import": "./verify.js"
+    },
+    "./worker": {
+      "types": "./worker.d.ts",
+      "import": "./worker.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/sentry-deferred.d.ts

@@ -0,0 +1,32 @@
+export type CaptureContext = {
+    mechanism: {
+        type: string;
+        handled: boolean;
+    };
+} | {
+    fingerprint: string[];
+    tags: Record<string, string>;
+    extra?: Record<string, unknown>;
+};
+export type DeferredSentrySdk = {
+    captureException(error: unknown, hint?: CaptureContext): unknown;
+    captureRouterTransitionStart(href: string, navigationType: string): void;
+};
+export type ErrorTarget = {
+    addEventListener(type: "error" | "unhandledrejection", listener: (event: unknown) => void): void;
+    removeEventListener(type: "error" | "unhandledrejection", listener: (event: unknown) => void): void;
+};
+export declare const ONERROR_MECHANISM: {
+    readonly type: "auto.browser.global_handlers.onerror";
+    readonly handled: false;
+};
+export declare const ONREJECTION_MECHANISM: {
+    readonly type: "auto.browser.global_handlers.onunhandledrejection";
+    readonly handled: false;
+};
+export declare function bufferEarlyErrors(target: ErrorTarget): void;
+export declare function registerSentryLoader(load: () => Promise<DeferredSentrySdk>): void;
+export declare function loadSentryNow(): Promise<DeferredSentrySdk | null>;
+export declare function captureException(error: unknown, context?: CaptureContext): void;
+export declare function onRouterTransitionStart(href: string, navigationType: string): void;
+export declare function resetSentryDeferredForTests(): void;

package/sentry-deferred.js

@@ -0,0 +1,101 @@
+const ONERROR_MECHANISM = { type: "auto.browser.global_handlers.onerror", handled: false };
+const ONREJECTION_MECHANISM = { type: "auto.browser.global_handlers.onunhandledrejection", handled: false };
+const KEY = /* @__PURE__ */ Symbol.for("weatherboard.sentry-deferred");
+function state() {
+  const holder = globalThis;
+  let current = holder[KEY];
+  if (current === void 0) {
+    current = { sdk: null, queue: [], load: null, loading: null, detach: null };
+    holder[KEY] = current;
+  }
+  return current;
+}
+function errorOf(event) {
+  const value = event;
+  if (value !== null && typeof value === "object") {
+    if (value.error !== void 0 && value.error !== null) return value.error;
+    if (typeof value.message === "string") return value.message;
+  }
+  return event;
+}
+function reasonOf(event) {
+  const value = event;
+  return value !== null && typeof value === "object" && "reason" in value ? value.reason : event;
+}
+function bufferEarlyErrors(target) {
+  const current = state();
+  if (current.detach !== null || current.sdk !== null) return;
+  const onError = (event) => record({ error: errorOf(event), context: { mechanism: ONERROR_MECHANISM } });
+  const onRejection = (event) => record({ error: reasonOf(event), context: { mechanism: ONREJECTION_MECHANISM } });
+  target.addEventListener("error", onError);
+  target.addEventListener("unhandledrejection", onRejection);
+  current.detach = () => {
+    target.removeEventListener("error", onError);
+    target.removeEventListener("unhandledrejection", onRejection);
+  };
+}
+function record(pending) {
+  const current = state();
+  if (current.sdk !== null) {
+    current.sdk.captureException(pending.error, pending.context);
+    return;
+  }
+  current.queue.push(pending);
+  void loadSentryNow();
+}
+function registerSentryLoader(load) {
+  state().load = load;
+}
+function loadSentryNow() {
+  const current = state();
+  if (current.loading !== null) return current.loading;
+  if (current.load === null) return Promise.resolve(null);
+  current.loading = current.load().then(
+    (sdk) => {
+      current.sdk = sdk;
+      current.detach?.();
+      current.detach = null;
+      const queued = current.queue.splice(0);
+      for (const pending of queued) {
+        sdk.captureException(pending.error, pending.context);
+      }
+      return sdk;
+    },
+    (error) => {
+      console.info("[sentry] the error-reporting SDK failed to load; errors on this page are not being reported.", error);
+      return null;
+    }
+  );
+  return current.loading;
+}
+function captureException(error, context) {
+  const current = state();
+  if (current.load === null && current.sdk === null) return;
+  if (current.sdk !== null) {
+    current.sdk.captureException(error, context);
+    return;
+  }
+  record({ error, context });
+}
+function onRouterTransitionStart(href, navigationType) {
+  state().sdk?.captureRouterTransitionStart(href, navigationType);
+}
+function resetSentryDeferredForTests() {
+  const current = state();
+  current.detach?.();
+  current.sdk = null;
+  current.queue = [];
+  current.load = null;
+  current.loading = null;
+  current.detach = null;
+}
+export {
+  ONERROR_MECHANISM,
+  ONREJECTION_MECHANISM,
+  bufferEarlyErrors,
+  captureException,
+  loadSentryNow,
+  onRouterTransitionStart,
+  registerSentryLoader,
+  resetSentryDeferredForTests
+};

package/server-sdk.d.ts

@@ -0,0 +1,4 @@
+import * as SentryModule from "@sentry/nextjs";
+declare const Sentry: typeof SentryModule;
+export declare function initialiseServer(overrides?: Pick<Parameters<typeof Sentry.init>[0] & {}, "transport">): void;
+export {};

package/server-sdk.js

@@ -0,0 +1,23 @@
+import * as SentryModule from "@sentry/nextjs";
+const Sentry = SentryModule.default ?? SentryModule;
+import { attachReporter } from "./client.js";
+import { deployedEnvironment } from "./environment.js";
+import { SENTRY_IGNORE_ERRORS } from "./noise.js";
+function initialiseServer(overrides = {}) {
+  const environment = deployedEnvironment(process.env.VERCEL_ENV);
+  const dsn = process.env.SENTRY_DSN;
+  if (!dsn || !environment) return;
+  Sentry.init({
+    dsn,
+    environment,
+    release: process.env.VERCEL_GIT_COMMIT_SHA || void 0,
+    tracesSampleRate: 0,
+    sendDefaultPii: false,
+    ignoreErrors: SENTRY_IGNORE_ERRORS,
+    ...overrides
+  });
+  attachReporter(Sentry);
+}
+export {
+  initialiseServer
+};

package/server.d.ts

@@ -0,0 +1,2 @@
+export { captureRequestError as onRequestError } from "@sentry/nextjs";
+export declare function register(options?: Pick<import("@sentry/nextjs").NodeOptions, "transport">): Promise<void>;

package/server.js

@@ -0,0 +1,12 @@
+import { deployedEnvironment } from "./environment.js";
+import { captureRequestError } from "@sentry/nextjs";
+async function register(options = {}) {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  if (!process.env.SENTRY_DSN || !deployedEnvironment(process.env.VERCEL_ENV)) return;
+  const { initialiseServer } = await import("./server-sdk.js");
+  initialiseServer(options);
+}
+export {
+  captureRequestError as onRequestError,
+  register
+};

package/verify.d.ts

@@ -0,0 +1,5 @@
+/** Assert wiring directly; exported separately so a fixture can prove failure. */
+export declare function assertErrorWiring(appDirectory: string): void;
+/** Call from a product's node:test file with the absolute app directory. */
+export declare function verifyErrors(appDirectory: string): void;
+export { assertWorkerWiring, verifyWorkerWiring } from "./worker-verify.js";

package/verify.js

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { test } from "node:test";
+function sources(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (["node_modules", ".next", ".git", "dist"].includes(entry.name)) return [];
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return sources(path);
+    return /\.[cm]?[jt]sx?$/.test(entry.name) && !/\.(test|spec)\./.test(entry.name) && !entry.name.endsWith(".d.ts") ? [path] : [];
+  });
+}
+function assertErrorWiring(appDirectory) {
+  for (const entry of ["instrumentation.ts", "instrumentation-client.ts"]) {
+    const source = readFileSync(join(appDirectory, entry), "utf8");
+    assert.match(source, /(?:from\s*|import\s*)["']@weatherboard\/errors\//, `${entry} must import @weatherboard/errors`);
+  }
+  assert.ok(["src/app/global-error.tsx", "app/global-error.tsx", "src/app/global-error.jsx", "app/global-error.jsx"].some((path) => existsSync(join(appDirectory, path))), "a global-error boundary must exist");
+  for (const file of sources(appDirectory)) {
+    const source = readFileSync(file, "utf8");
+    const name = relative(appDirectory, file);
+    assert.doesNotMatch(source, /(?:from\s*|import\s*(?:\(\s*)?|require\s*\(\s*|export\s*[^;]*from\s*)["']@sentry\//, `${name}: products never import @sentry/* directly`);
+    assert.doesNotMatch(source, /\bposthog\s*(?:\.\s*captureException|\[\s*["']captureException["']\s*\])/, `${name}: PostHog is analytics only`);
+    assert.doesNotMatch(source, /["']?capture_exceptions["']?\s*:\s*true\b/, `${name}: PostHog exception autocapture must be off`);
+  }
+}
+function verifyErrors(appDirectory) {
+  test("shared error reporting wiring", () => assertErrorWiring(appDirectory));
+}
+import { assertWorkerWiring, verifyWorkerWiring } from "./worker-verify.js";
+export {
+  assertErrorWiring,
+  assertWorkerWiring,
+  verifyErrors,
+  verifyWorkerWiring
+};

package/worker-verify.d.ts

@@ -0,0 +1,4 @@
+/** Inspect actual syntax so a commented-out wrapper cannot satisfy the guard. */
+export declare function assertWorkerWiring(dir: string): void;
+/** Call from each converted Worker's node:test suite. */
+export declare function verifyWorkerWiring(dir: string): void;

package/worker-verify.js

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { test } from "node:test";
+import ts from "typescript";
+function sources(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (["node_modules", ".git", "dist", "test-fixtures"].includes(entry.name)) return [];
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return sources(path);
+    return /\.[cm]?[jt]s$/.test(entry.name) && !/\.(test|spec)\./.test(entry.name) && !entry.name.endsWith(".d.ts") ? [path] : [];
+  });
+}
+function assertWorkerWiring(dir) {
+  let defaults = 0;
+  const classes = [];
+  const wrapped = /* @__PURE__ */ new Set();
+  for (const file of sources(dir)) {
+    const name = relative(dir, file);
+    const source = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    const imports = /* @__PURE__ */ new Map();
+    const visit = (node) => {
+      if (ts.isStringLiteral(node) && node.text.startsWith("@sentry/")) {
+        const parent = node.parent;
+        if (ts.isImportDeclaration(parent) || ts.isExportDeclaration(parent) || ts.isCallExpression(parent)) {
+          assert.fail(`${name}: products never import @sentry/* directly`);
+        }
+      }
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "@weatherboard/errors/worker") {
+        const bindings = node.importClause?.namedBindings;
+        if (bindings && ts.isNamedImports(bindings)) {
+          for (const binding of bindings.elements) imports.set(binding.name.text, binding.propertyName?.text ?? binding.name.text);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+    const isWrapper = (expression, kind) => ts.isCallExpression(expression) && ts.isIdentifier(expression.expression) && imports.get(expression.expression.text) === kind;
+    for (const statement of source.statements) {
+      if (name.startsWith("src/") && ts.isExportAssignment(statement) && !statement.isExportEquals) {
+        defaults++;
+        assert.ok(isWrapper(statement.expression, "withWorkerErrors"), `${name}: default export must be wrapped with withWorkerErrors`);
+      }
+      if (ts.isClassDeclaration(statement) && statement.name) {
+        const base = statement.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)?.types[0]?.expression;
+        if (base && ts.isIdentifier(base)) classes.push({ name: statement.name.text, base: base.text, file: name });
+      }
+      if (ts.isVariableStatement(statement) && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+        for (const declaration of statement.declarationList.declarations) {
+          if (declaration.initializer && isWrapper(declaration.initializer, "withDurableObjectErrors")) {
+            const arg = declaration.initializer.arguments[0];
+            if (arg && ts.isIdentifier(arg)) wrapped.add(`${name}:${arg.text}`);
+          }
+        }
+      }
+    }
+  }
+  assert.ok(defaults > 0, "Worker must have a wrapped default export");
+  const durable = /* @__PURE__ */ new Set(["DurableObject", "Sandbox"]);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const item of classes) if (durable.has(item.base) && !durable.has(item.name)) {
+      durable.add(item.name);
+      changed = true;
+    }
+  }
+  for (const item of classes) if (durable.has(item.base)) {
+    assert.ok(wrapped.has(`${item.file}:${item.name}`), `${item.file}: Durable Object ${item.name} must be instrumented with withDurableObjectErrors`);
+  }
+}
+function verifyWorkerWiring(dir) {
+  test("shared Worker error reporting wiring", () => assertWorkerWiring(dir));
+}
+export {
+  assertWorkerWiring,
+  verifyWorkerWiring
+};

package/worker.d.ts

@@ -0,0 +1,22 @@
+import { type CloudflareOptions } from "@sentry/cloudflare";
+import type { HandledContext } from "./client.js";
+/** Shared Workers must supply caller-derived environment explicitly; unset is development. */
+export interface WorkerErrorEnv {
+    SENTRY_DSN?: string;
+    SENTRY_ENVIRONMENT?: string;
+    ENVIRONMENT?: string;
+    SENTRY_RELEASE?: string;
+    CF_VERSION_METADATA?: {
+        id: string;
+        tag?: string;
+    };
+}
+type Options<E> = (env: E) => CloudflareOptions;
+export declare function workerErrorOptions(env: WorkerErrorEnv): CloudflareOptions;
+/** Select instrumentation per invocation, without modifying the original handler. */
+export declare function withWorkerErrors<H extends object>(handler: H, options?: Options<WorkerErrorEnv>): H;
+/** Preserve the original construction path when a DSN is absent. */
+export declare function withDurableObjectErrors<C extends new (...args: never[]) => object>(object: C, options?: Options<WorkerErrorEnv>): C;
+/** Report inside an instrumented invocation's catch; logging stays at the call site. */
+export declare function reportHandled(error: unknown, context: HandledContext): void;
+export {};

package/worker.js

@@ -0,0 +1,70 @@
+import {
+  captureException,
+  getClient,
+  instrumentDurableObjectWithSentry,
+  withSentry,
+  wrapRequestHandler
+} from "@sentry/cloudflare";
+function workerErrorOptions(env) {
+  return {
+    dsn: env.SENTRY_DSN,
+    environment: env.SENTRY_ENVIRONMENT || env.ENVIRONMENT || "development",
+    release: env.SENTRY_RELEASE || env.CF_VERSION_METADATA?.tag || env.CF_VERSION_METADATA?.id,
+    tracesSampleRate: 0,
+    sendDefaultPii: false,
+    // On SDK 10.75, enableRpcTracePropagation alone captures only calls carrying
+    // SDK metadata. Manager-side callers do not carry it; instrument all methods.
+    instrumentPrototypeMethods: true
+  };
+}
+function withWorkerErrors(handler, options = workerErrorOptions) {
+  let instrumented;
+  const methods = /* @__PURE__ */ new Map();
+  const wrapped = new Proxy(handler, {
+    get(target, key, receiver) {
+      const original = Reflect.get(target, key, receiver);
+      if (typeof original !== "function") return original;
+      if (!methods.has(key)) methods.set(key, new Proxy(original, {
+        apply(method, thisArg, args) {
+          const receiver2 = thisArg === wrapped ? handler : thisArg;
+          const env = args[1];
+          if (!env?.SENTRY_DSN) return Reflect.apply(method, receiver2, args);
+          if (key === "fetch" && args[0] instanceof Request && ["HEAD", "OPTIONS"].includes(args[0].method)) {
+            return wrapRequestHandler({ options: options(env), request: args[0], context: args[2] }, () => Reflect.apply(method, receiver2, args));
+          }
+          instrumented ??= withSentry(options, { ...handler });
+          const captured = Reflect.get(instrumented, key);
+          return Reflect.apply(typeof captured === "function" ? captured : method, receiver2, args);
+        }
+      }));
+      return methods.get(key);
+    }
+  });
+  return wrapped;
+}
+function withDurableObjectErrors(object, options = workerErrorOptions) {
+  let instrumented;
+  return new Proxy(object, {
+    construct(target, args, newTarget) {
+      const env = args[1];
+      if (!env?.SENTRY_DSN) return Reflect.construct(target, args, newTarget);
+      instrumented ??= instrumentDurableObjectWithSentry(options, object);
+      return Reflect.construct(instrumented, args, newTarget);
+    }
+  });
+}
+function reportHandled(error, context) {
+  try {
+    const client = getClient();
+    if (!client?.getOptions().dsn || client.getOptions().enabled === false) return;
+    const message = error instanceof Error ? error.message : String(error);
+    captureException(error, { fingerprint: [context.where, message], extra: context.extra });
+  } catch {
+  }
+}
+export {
+  reportHandled,
+  withDurableObjectErrors,
+  withWorkerErrors,
+  workerErrorOptions
+};