@beignet/provider-error-reporting-sentry 0.0.14

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @beignet/provider-error-reporting-sentry
+
+## 0.0.14
+
+### Patch Changes
+
+- 0b106c3: Add first-class error reporting primitives and a Sentry-backed error reporting
+  provider.
+
+## 0.0.13
+
+### Patch Changes
+
+- Initial Sentry-backed error reporting provider.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taylor Bryant
+
+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,76 @@
+# @beignet/provider-error-reporting-sentry
+
+Sentry-backed `ErrorReporterPort` provider for Beignet applications.
+
+The provider installs `ctx.ports.errorReporter` using `@sentry/node` while
+keeping Sentry imports out of contracts, use cases, routes, and domain code.
+
+## Install
+
+```bash
+bun add @beignet/provider-error-reporting-sentry @sentry/node
+```
+
+## Register
+
+```typescript
+// server/providers.ts
+import { createSentryErrorReportingProvider } from "@beignet/provider-error-reporting-sentry";
+
+export const providers = [
+  createSentryErrorReportingProvider({
+    dsn: process.env.SENTRY_DSN,
+    init: {
+      environment: process.env.NODE_ENV,
+    },
+  }),
+];
+```
+
+With no `dsn` or `SENTRY_DSN`, the provider still contributes the Beignet port
+but does not initialize Sentry. This is useful for examples and local apps that
+want stable wiring before production secrets exist.
+
+## Use
+
+```typescript
+await ctx.ports.errorReporter.captureException(error, {
+  level: "error",
+  requestId: ctx.requestId,
+  traceId: ctx.traceId,
+  tags: {
+    feature: "billing",
+  },
+  contexts: {
+    tenant: { id: ctx.tenant.id },
+  },
+});
+```
+
+The provider also contributes `ctx.ports.sentry` as an escape hatch with the raw
+Sentry SDK and configured client.
+
+## Devtools
+
+Captured exceptions and messages are recorded as Beignet error instrumentation
+under the `errors` watcher when devtools or another instrumentation sink is
+installed before the provider.
+
+## API
+
+### `createSentryErrorReporter(options)`
+
+Creates an `ErrorReporterPort` from a Sentry-compatible client. Use this for
+tests or custom provider composition.
+
+### `createSentryErrorReportingProvider(options)`
+
+Creates a Beignet lifecycle provider that contributes:
+
+- `ctx.ports.errorReporter`, the standard Beignet `ErrorReporterPort`
+- `ctx.ports.sentry`, an escape hatch with the raw Sentry client and SDK
+
+### `sentryErrorReportingProvider`
+
+Ready-to-register provider using the default Sentry singleton and
+`process.env.SENTRY_DSN` when present.

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @beignet/provider-error-reporting-sentry
+ *
+ * Sentry-backed error reporting provider for Beignet.
+ */
+import type { ErrorReportContext, ErrorReporterFlushOptions, ErrorReporterPort, ErrorReportJsonValue, ErrorReportLevel, ErrorReportOptions, ErrorReportResult, ErrorReportTags, ErrorReportUser } from "@beignet/core/error-reporting";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import type { NodeOptions, Scope } from "@sentry/node";
+import * as Sentry from "@sentry/node";
+/**
+ * Sentry SDK surface used by the provider. Supplying this in tests avoids the
+ * process-wide singleton.
+ */
+export interface SentryErrorReportingClient {
+    captureException(error: unknown): string | undefined;
+    captureMessage(message: string): string | undefined;
+    setUser(user: SentryErrorReportingUser | null): void;
+    setTags(tags: Record<string, string>): void;
+    setContext(name: string, context: ErrorReportContext | null): void;
+    flush(timeout?: number): PromiseLike<boolean> | boolean;
+    close?(timeout?: number): PromiseLike<boolean> | boolean;
+    withScope<T>(callback: (scope: Scope) => T): T;
+    init?(options?: NodeOptions): void;
+}
+/**
+ * Escape hatch for apps that need the raw Sentry SDK.
+ */
+export interface SentryErrorReportingEscapeHatch {
+    client: SentryErrorReportingClient;
+    sdk: typeof Sentry;
+}
+export type SentryErrorReportingUser = Record<string, ErrorReportJsonValue | undefined>;
+/**
+ * Ports contributed by the Sentry provider.
+ */
+export interface SentryErrorReportingProviderPorts {
+    errorReporter: ErrorReporterPort;
+    sentry: SentryErrorReportingEscapeHatch;
+}
+/**
+ * Options for the direct Sentry reporter factory.
+ */
+export interface CreateSentryErrorReporterOptions {
+    client?: SentryErrorReportingClient;
+    instrumentation?: ProviderInstrumentationTarget;
+}
+/**
+ * Options for the Sentry lifecycle provider.
+ */
+export interface CreateSentryErrorReportingProviderOptions {
+    client?: SentryErrorReportingClient;
+    /**
+     * Sentry DSN. When omitted, the provider checks `process.env.SENTRY_DSN`.
+     * With no DSN, the SDK is not initialized and captures are effectively no-op
+     * until the app initializes Sentry elsewhere.
+     */
+    dsn?: string;
+    /**
+     * Additional Sentry initialization options.
+     */
+    init?: Omit<NodeOptions, "dsn">;
+    /**
+     * Close the Sentry client on server stop.
+     *
+     * @default false
+     */
+    closeOnStop?: boolean;
+    /**
+     * Flush/close timeout in milliseconds.
+     *
+     * @default 2000
+     */
+    flushTimeoutMs?: number;
+}
+/**
+ * Create a Beignet error reporter backed by Sentry.
+ */
+export declare function createSentryErrorReporter(options?: CreateSentryErrorReporterOptions): ErrorReporterPort;
+/**
+ * Create a Beignet provider that contributes `ports.errorReporter`.
+ */
+export declare function createSentryErrorReportingProvider(options?: CreateSentryErrorReportingProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    errorReporter: ErrorReporterPort;
+    sentry: {
+        client: typeof Sentry | SentryErrorReportingClient;
+        sdk: typeof Sentry;
+    };
+}, unknown, void>;
+/**
+ * Ready-to-register Sentry error reporting provider using the default Sentry
+ * singleton.
+ */
+export declare const sentryErrorReportingProvider: import("@beignet/core/providers").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    errorReporter: ErrorReporterPort;
+    sentry: {
+        client: typeof Sentry | SentryErrorReportingClient;
+        sdk: typeof Sentry;
+    };
+}, unknown, void>;
+export type { ErrorReportContext, ErrorReporterFlushOptions, ErrorReporterPort, ErrorReportJsonValue, ErrorReportLevel, ErrorReportOptions, ErrorReportResult, ErrorReportTags, ErrorReportUser, };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,eAAe,EAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAiB,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpD,OAAO,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,GAAG,IAAI,CAAC;IACrD,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAAC;IACnE,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxD,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACzD,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,0BAA0B,CAAC;IACnC,GAAG,EAAE,OAAO,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAC3C,MAAM,EACN,oBAAoB,GAAG,SAAS,CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD,aAAa,EAAE,iBAAiB,CAAC;IACjC,MAAM,EAAE,+BAA+B,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,yCAAyC;IACxD,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,gCAAqC,GAC7C,iBAAiB,CAmFnB;AAED;;GAEG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,GAAE,yCAA8C;;;;;;kBAgCxD;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;iBACH,CAAC;AAmGvC,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,CAAC"}

package/dist/index.js

@@ -0,0 +1,200 @@
+/**
+ * @beignet/provider-error-reporting-sentry
+ *
+ * Sentry-backed error reporting provider for Beignet.
+ */
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import * as Sentry from "@sentry/node";
+/**
+ * Create a Beignet error reporter backed by Sentry.
+ */
+export function createSentryErrorReporter(options = {}) {
+    const client = options.client ?? Sentry;
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "error-reporting-sentry",
+        watcher: "errors",
+    });
+    return {
+        async captureException(error, reportOptions) {
+            const startedAt = Date.now();
+            const id = withConfiguredScope(client, reportOptions, () => client.captureException(error));
+            instrumentation.record({
+                type: "error",
+                watcher: "errors",
+                owner: "provider",
+                message: errorMessage(error),
+                stack: errorStack(error),
+                requestId: reportOptions?.requestId,
+                traceId: reportOptions?.traceId,
+                spanId: reportOptions?.spanId,
+                parentSpanId: reportOptions?.parentSpanId,
+                traceparent: reportOptions?.traceparent,
+                details: {
+                    provider: "sentry",
+                    eventId: id,
+                    level: reportOptions?.level ?? "error",
+                    durationMs: Date.now() - startedAt,
+                    tags: reportOptions?.tags,
+                    contexts: reportOptions?.contexts,
+                    extra: reportOptions?.extra,
+                    mechanism: reportOptions?.mechanism,
+                    handled: reportOptions?.handled,
+                },
+            });
+            return result(id);
+        },
+        async captureMessage(message, reportOptions) {
+            const startedAt = Date.now();
+            const id = withConfiguredScope(client, reportOptions, () => client.captureMessage(message));
+            instrumentation.record({
+                type: "error",
+                watcher: "errors",
+                owner: "provider",
+                message,
+                requestId: reportOptions?.requestId,
+                traceId: reportOptions?.traceId,
+                spanId: reportOptions?.spanId,
+                parentSpanId: reportOptions?.parentSpanId,
+                traceparent: reportOptions?.traceparent,
+                details: {
+                    provider: "sentry",
+                    eventId: id,
+                    level: reportOptions?.level ?? "error",
+                    durationMs: Date.now() - startedAt,
+                    tags: reportOptions?.tags,
+                    contexts: reportOptions?.contexts,
+                    extra: reportOptions?.extra,
+                    mechanism: reportOptions?.mechanism,
+                    handled: reportOptions?.handled,
+                },
+            });
+            return result(id);
+        },
+        setUser(user) {
+            client.setUser(toSentryUser(user));
+        },
+        setTags(tags) {
+            client.setTags(normalizeTags(tags));
+        },
+        setContext(name, context) {
+            client.setContext(name, context);
+        },
+        async flush(flushOptions) {
+            return Boolean(await client.flush(flushOptions?.timeoutMs));
+        },
+    };
+}
+/**
+ * Create a Beignet provider that contributes `ports.errorReporter`.
+ */
+export function createSentryErrorReportingProvider(options = {}) {
+    return createProvider({
+        name: "error-reporting-sentry",
+        metadata: {
+            packageName: "@beignet/provider-error-reporting-sentry",
+            ports: ["errorReporter", "sentry"],
+            watchers: ["errors"],
+        },
+        setup({ ports }) {
+            const client = options.client ?? Sentry;
+            initializeSentry(client, options);
+            return {
+                ports: {
+                    errorReporter: createSentryErrorReporter({
+                        client,
+                        instrumentation: ports,
+                    }),
+                    sentry: {
+                        client,
+                        sdk: Sentry,
+                    },
+                },
+                async stop() {
+                    if (options.closeOnStop && client.close) {
+                        await client.close(options.flushTimeoutMs ?? 2000);
+                    }
+                },
+            };
+        },
+    });
+}
+/**
+ * Ready-to-register Sentry error reporting provider using the default Sentry
+ * singleton.
+ */
+export const sentryErrorReportingProvider = createSentryErrorReportingProvider();
+function initializeSentry(client, options) {
+    if (!client.init)
+        return;
+    const dsn = options.dsn ?? process.env.SENTRY_DSN;
+    if (!dsn && !options.init)
+        return;
+    client.init({
+        ...options.init,
+        dsn,
+    });
+}
+function withConfiguredScope(client, options, capture) {
+    return client.withScope((scope) => {
+        applyScope(scope, options);
+        return capture();
+    });
+}
+function applyScope(scope, options) {
+    if (!options)
+        return;
+    if (options.level)
+        scope.setLevel(toSentryLevel(options.level));
+    if (options.user !== undefined)
+        scope.setUser(toSentryUser(options.user));
+    if (options.tags)
+        scope.setTags(normalizeTags(options.tags));
+    if (options.extra)
+        scope.setExtras(stripUndefined(options.extra));
+    if (options.fingerprint)
+        scope.setFingerprint([...options.fingerprint]);
+    for (const [name, context] of Object.entries(options.contexts ?? {})) {
+        if (context !== undefined) {
+            scope.setContext(name, stripUndefined(context));
+        }
+    }
+    scope.setContext("beignet", stripUndefined({
+        requestId: options.requestId,
+        traceId: options.traceId,
+        spanId: options.spanId,
+        parentSpanId: options.parentSpanId,
+        traceparent: options.traceparent,
+        mechanism: options.mechanism,
+        handled: options.handled,
+    }));
+}
+function toSentryLevel(level) {
+    return level === "warning" ? "warning" : level;
+}
+function normalizeTags(tags) {
+    return Object.fromEntries(Object.entries(tags)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, String(value)]));
+}
+function toSentryUser(user) {
+    if (user === null)
+        return null;
+    const { ipAddress, ...rest } = user;
+    return stripUndefined({
+        ...rest,
+        ip_address: ipAddress,
+    });
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function errorStack(error) {
+    return error instanceof Error ? error.stack : undefined;
+}
+function result(id) {
+    return id ? { id } : {};
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@beignet/provider-error-reporting-sentry",
+  "version": "0.0.14",
+  "type": "module",
+  "description": "Sentry error reporting provider for Beignet",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "sentry",
+    "error-reporting",
+    "provider",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-error-reporting-sentry"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@beignet/core": ">=0.0.3 <1.0.0",
+    "@sentry/node": "^10.58.0"
+  },
+  "devDependencies": {
+    "@beignet/core": "*",
+    "@beignet/devtools": "*",
+    "@sentry/node": "^10.58.0",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "beignet": {
+    "provider": {
+      "displayName": "Sentry error reporting provider",
+      "ports": [
+        "errorReporter",
+        "sentry"
+      ],
+      "appPorts": [
+        {
+          "name": "errorReporter",
+          "type": "ErrorReporterPort"
+        }
+      ],
+      "env": [
+        "SENTRY_DSN"
+      ],
+      "requiredEnv": [],
+      "watchers": [
+        "errors"
+      ],
+      "registration": {
+        "required": true,
+        "tokens": [
+          "sentryErrorReportingProvider",
+          "createSentryErrorReportingProvider"
+        ]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,342 @@
+/**
+ * @beignet/provider-error-reporting-sentry
+ *
+ * Sentry-backed error reporting provider for Beignet.
+ */
+
+import type {
+  ErrorReportContext,
+  ErrorReporterFlushOptions,
+  ErrorReporterPort,
+  ErrorReportJsonValue,
+  ErrorReportLevel,
+  ErrorReportOptions,
+  ErrorReportResult,
+  ErrorReportTags,
+  ErrorReportUser,
+} from "@beignet/core/error-reporting";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import type { NodeOptions, Scope, SeverityLevel } from "@sentry/node";
+import * as Sentry from "@sentry/node";
+
+/**
+ * Sentry SDK surface used by the provider. Supplying this in tests avoids the
+ * process-wide singleton.
+ */
+export interface SentryErrorReportingClient {
+  captureException(error: unknown): string | undefined;
+  captureMessage(message: string): string | undefined;
+  setUser(user: SentryErrorReportingUser | null): void;
+  setTags(tags: Record<string, string>): void;
+  setContext(name: string, context: ErrorReportContext | null): void;
+  flush(timeout?: number): PromiseLike<boolean> | boolean;
+  close?(timeout?: number): PromiseLike<boolean> | boolean;
+  withScope<T>(callback: (scope: Scope) => T): T;
+  init?(options?: NodeOptions): void;
+}
+
+/**
+ * Escape hatch for apps that need the raw Sentry SDK.
+ */
+export interface SentryErrorReportingEscapeHatch {
+  client: SentryErrorReportingClient;
+  sdk: typeof Sentry;
+}
+
+export type SentryErrorReportingUser = Record<
+  string,
+  ErrorReportJsonValue | undefined
+>;
+
+/**
+ * Ports contributed by the Sentry provider.
+ */
+export interface SentryErrorReportingProviderPorts {
+  errorReporter: ErrorReporterPort;
+  sentry: SentryErrorReportingEscapeHatch;
+}
+
+/**
+ * Options for the direct Sentry reporter factory.
+ */
+export interface CreateSentryErrorReporterOptions {
+  client?: SentryErrorReportingClient;
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+/**
+ * Options for the Sentry lifecycle provider.
+ */
+export interface CreateSentryErrorReportingProviderOptions {
+  client?: SentryErrorReportingClient;
+  /**
+   * Sentry DSN. When omitted, the provider checks `process.env.SENTRY_DSN`.
+   * With no DSN, the SDK is not initialized and captures are effectively no-op
+   * until the app initializes Sentry elsewhere.
+   */
+  dsn?: string;
+  /**
+   * Additional Sentry initialization options.
+   */
+  init?: Omit<NodeOptions, "dsn">;
+  /**
+   * Close the Sentry client on server stop.
+   *
+   * @default false
+   */
+  closeOnStop?: boolean;
+  /**
+   * Flush/close timeout in milliseconds.
+   *
+   * @default 2000
+   */
+  flushTimeoutMs?: number;
+}
+
+/**
+ * Create a Beignet error reporter backed by Sentry.
+ */
+export function createSentryErrorReporter(
+  options: CreateSentryErrorReporterOptions = {},
+): ErrorReporterPort {
+  const client = options.client ?? Sentry;
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "error-reporting-sentry",
+      watcher: "errors",
+    },
+  );
+
+  return {
+    async captureException(error, reportOptions) {
+      const startedAt = Date.now();
+      const id = withConfiguredScope(client, reportOptions, () =>
+        client.captureException(error),
+      );
+      instrumentation.record({
+        type: "error",
+        watcher: "errors",
+        owner: "provider",
+        message: errorMessage(error),
+        stack: errorStack(error),
+        requestId: reportOptions?.requestId,
+        traceId: reportOptions?.traceId,
+        spanId: reportOptions?.spanId,
+        parentSpanId: reportOptions?.parentSpanId,
+        traceparent: reportOptions?.traceparent,
+        details: {
+          provider: "sentry",
+          eventId: id,
+          level: reportOptions?.level ?? "error",
+          durationMs: Date.now() - startedAt,
+          tags: reportOptions?.tags,
+          contexts: reportOptions?.contexts,
+          extra: reportOptions?.extra,
+          mechanism: reportOptions?.mechanism,
+          handled: reportOptions?.handled,
+        },
+      });
+      return result(id);
+    },
+    async captureMessage(message, reportOptions) {
+      const startedAt = Date.now();
+      const id = withConfiguredScope(client, reportOptions, () =>
+        client.captureMessage(message),
+      );
+      instrumentation.record({
+        type: "error",
+        watcher: "errors",
+        owner: "provider",
+        message,
+        requestId: reportOptions?.requestId,
+        traceId: reportOptions?.traceId,
+        spanId: reportOptions?.spanId,
+        parentSpanId: reportOptions?.parentSpanId,
+        traceparent: reportOptions?.traceparent,
+        details: {
+          provider: "sentry",
+          eventId: id,
+          level: reportOptions?.level ?? "error",
+          durationMs: Date.now() - startedAt,
+          tags: reportOptions?.tags,
+          contexts: reportOptions?.contexts,
+          extra: reportOptions?.extra,
+          mechanism: reportOptions?.mechanism,
+          handled: reportOptions?.handled,
+        },
+      });
+      return result(id);
+    },
+    setUser(user) {
+      client.setUser(toSentryUser(user));
+    },
+    setTags(tags) {
+      client.setTags(normalizeTags(tags));
+    },
+    setContext(name, context) {
+      client.setContext(name, context);
+    },
+    async flush(flushOptions) {
+      return Boolean(await client.flush(flushOptions?.timeoutMs));
+    },
+  };
+}
+
+/**
+ * Create a Beignet provider that contributes `ports.errorReporter`.
+ */
+export function createSentryErrorReportingProvider(
+  options: CreateSentryErrorReportingProviderOptions = {},
+) {
+  return createProvider({
+    name: "error-reporting-sentry",
+    metadata: {
+      packageName: "@beignet/provider-error-reporting-sentry",
+      ports: ["errorReporter", "sentry"],
+      watchers: ["errors"],
+    },
+    setup({ ports }) {
+      const client = options.client ?? Sentry;
+      initializeSentry(client, options);
+
+      return {
+        ports: {
+          errorReporter: createSentryErrorReporter({
+            client,
+            instrumentation: ports,
+          }),
+          sentry: {
+            client,
+            sdk: Sentry,
+          },
+        } satisfies SentryErrorReportingProviderPorts,
+        async stop() {
+          if (options.closeOnStop && client.close) {
+            await client.close(options.flushTimeoutMs ?? 2000);
+          }
+        },
+      };
+    },
+  });
+}
+
+/**
+ * Ready-to-register Sentry error reporting provider using the default Sentry
+ * singleton.
+ */
+export const sentryErrorReportingProvider =
+  createSentryErrorReportingProvider();
+
+function initializeSentry(
+  client: SentryErrorReportingClient,
+  options: CreateSentryErrorReportingProviderOptions,
+) {
+  if (!client.init) return;
+  const dsn = options.dsn ?? process.env.SENTRY_DSN;
+  if (!dsn && !options.init) return;
+
+  client.init({
+    ...options.init,
+    dsn,
+  });
+}
+
+function withConfiguredScope<T>(
+  client: SentryErrorReportingClient,
+  options: ErrorReportOptions | undefined,
+  capture: () => T,
+): T {
+  return client.withScope((scope) => {
+    applyScope(scope, options);
+    return capture();
+  });
+}
+
+function applyScope(scope: Scope, options: ErrorReportOptions | undefined) {
+  if (!options) return;
+  if (options.level) scope.setLevel(toSentryLevel(options.level));
+  if (options.user !== undefined) scope.setUser(toSentryUser(options.user));
+  if (options.tags) scope.setTags(normalizeTags(options.tags));
+  if (options.extra) scope.setExtras(stripUndefined(options.extra));
+  if (options.fingerprint) scope.setFingerprint([...options.fingerprint]);
+
+  for (const [name, context] of Object.entries(options.contexts ?? {})) {
+    if (context !== undefined) {
+      scope.setContext(name, stripUndefined(context));
+    }
+  }
+
+  scope.setContext(
+    "beignet",
+    stripUndefined({
+      requestId: options.requestId,
+      traceId: options.traceId,
+      spanId: options.spanId,
+      parentSpanId: options.parentSpanId,
+      traceparent: options.traceparent,
+      mechanism: options.mechanism,
+      handled: options.handled,
+    }),
+  );
+}
+
+function toSentryLevel(level: ErrorReportLevel): SeverityLevel {
+  return level === "warning" ? "warning" : level;
+}
+
+function normalizeTags(tags: ErrorReportTags): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(tags)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => [key, String(value)]),
+  );
+}
+
+function toSentryUser(
+  user: ErrorReportUser | null,
+): SentryErrorReportingUser | null {
+  if (user === null) return null;
+  const { ipAddress, ...rest } = user;
+
+  return stripUndefined({
+    ...rest,
+    ip_address: ipAddress,
+  }) as SentryErrorReportingUser;
+}
+
+function stripUndefined(
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function errorStack(error: unknown): string | undefined {
+  return error instanceof Error ? error.stack : undefined;
+}
+
+function result(id: string | undefined): ErrorReportResult {
+  return id ? { id } : {};
+}
+
+export type {
+  ErrorReportContext,
+  ErrorReporterFlushOptions,
+  ErrorReporterPort,
+  ErrorReportJsonValue,
+  ErrorReportLevel,
+  ErrorReportOptions,
+  ErrorReportResult,
+  ErrorReportTags,
+  ErrorReportUser,
+};