@voltro/plugin-sentry 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { Cause } from 'effect';
+import { LogRecord } from '@voltro/logger';
+import { Subject } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+
+export declare interface Breadcrumb {
+    /** Unix SECONDS (Sentry breadcrumb convention). */
+    readonly timestamp: number;
+    readonly level: 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+    readonly category?: string;
+    readonly message: string;
+    readonly data?: Record<string, unknown>;
+}
+
+declare interface BreadcrumbRing {
+    /** Record a log line under its trace. */
+    readonly add: (traceId: string, record: LogRecord) => void;
+    /** Return + REMOVE a trace's breadcrumbs (chronological). */
+    readonly take: (traceId: string) => ReadonlyArray<Breadcrumb>;
+    readonly drop: (traceId: string) => void;
+    readonly size: () => number;
+}
+
+declare interface BreadcrumbRingOptions {
+    readonly maxPerTrace?: number;
+    readonly maxTraces?: number;
+    readonly ttlMs?: number;
+}
+
+declare interface CaptureContext {
+    readonly tag: string;
+    readonly kind: string;
+    readonly subject: Subject;
+    readonly traceId: string;
+    readonly spanId?: string;
+}
+
+export declare const captureToSentry: (sentry: SentryLike, cause: Cause.Cause<unknown>, ctx: CaptureContext, breadcrumbs: ReadonlyArray<Breadcrumb>) => void;
+
+/** Unwrap an Effect `Cause` to the underlying error value (Error | tagged
+ *  error | defect). `Cause.squash` returns the most informative throwable. */
+export declare const causeToError: (cause: Cause.Cause<unknown>) => unknown;
+
+export declare const makeBreadcrumbRing: (opts?: BreadcrumbRingOptions, now?: () => number) => BreadcrumbRing;
+
+export declare const parseDsn: (dsn: string | undefined) => SentryDsn | null;
+
+declare interface SentryDsn {
+    readonly protocol: string;
+    readonly publicKey: string;
+    readonly host: string;
+    readonly projectId: string;
+}
+
+/** Extra `Sentry.init` options passed through verbatim — the escape hatch for
+ *  everything the first-class options don't cover: `beforeSend` /
+ *  `beforeBreadcrumb` (PII/event scrubbing), `ignoreErrors`, error
+ *  `sampleRate`, `maxValueLength`, … Structural (not `NodeOptions`) so
+ *  `@sentry/node` stays an optional dependency.
+ *
+ *  Merge contract: the bag is spread FIRST, then the plugin's own keys — so
+ *  the plugin stays authoritative for everything it manages (`dsn`,
+ *  `skipOpenTelemetrySetup`, `tracesSampleRate`, and `environment` /
+ *  `release` / `profilesSampleRate` when set). `integrations` is the one
+ *  exception: user integrations are APPENDED to the plugin's own, never
+ *  replacing them. */
+export declare interface SentryInitOverrides {
+    /** Extra Sentry integrations, appended AFTER the plugin's own. */
+    readonly integrations?: ReadonlyArray<unknown>;
+    readonly [key: string]: unknown;
+}
+
+export declare interface SentryLike {
+    withScope(callback: (scope: SentryScopeLike) => void): unknown;
+    captureException(exception: unknown): unknown;
+}
+
+export declare const sentryPlugin: (options?: SentryPluginOptions) => VoltroPlugin;
+
+export declare interface SentryPluginOptions {
+    /** Sentry DSN. Default `SENTRY_DSN` env. Without a valid DSN the plugin is a no-op. */
+    readonly dsn?: string;
+    /** `environment` tag (Sentry env). Default `SENTRY_ENVIRONMENT` env. */
+    readonly environment?: string;
+    /** Release identifier (Sentry release health + source maps). Default `SENTRY_RELEASE` env. */
+    readonly release?: string;
+    /** Performance-trace sample rate (0..1). Default 1.0. Only relevant with `traces`. */
+    readonly tracesSampleRate?: number;
+    /** Route the framework's OTel spans to Sentry as transactions. Default false
+     *  (errors + breadcrumbs only — no performance traces). */
+    readonly traces?: boolean;
+    /** Continuous CPU profiling via @sentry/profiling-node. Default false. */
+    readonly profiling?: boolean;
+    /** Profile sample rate (0..1) when `profiling`. Default 1.0. */
+    readonly profilesSampleRate?: number;
+    /** Max breadcrumbs retained per trace. Default 50. */
+    readonly maxBreadcrumbs?: number;
+    /** Disambiguates multiple instances. */
+    readonly name?: string;
+    /** Escape hatch: extra `Sentry.init` options (`beforeSend`, `ignoreErrors`,
+     *  `sampleRate`, extra `integrations`, …). Plugin-managed keys win; user
+     *  `integrations` are appended. See {@link SentryInitOverrides}. */
+    readonly init?: SentryInitOverrides;
+}
+
+declare interface SentryScopeLike {
+    setContext(key: string, context: Record<string, unknown> | null): unknown;
+    setTag(key: string, value: string): unknown;
+    addBreadcrumb(breadcrumb: Breadcrumb): unknown;
+}
+
+export declare const toBreadcrumb: (r: LogRecord) => Breadcrumb;
+
+export { }

package/dist/index.js

@@ -0,0 +1,193 @@
+import { Cause as e, Effect as t } from "effect";
+import { pluginEnv as n } from "@voltro/env";
+import { addSink as r } from "@voltro/logger";
+import { definePlugin as i, subscribeServerErrors as a } from "@voltro/protocol";
+//#region src/dsn.ts
+var o = (e) => {
+	if (!e) return null;
+	try {
+		let t = new URL(e), n = t.username, r = t.pathname.split("/").filter(Boolean), i = r[r.length - 1];
+		return !n || !i ? null : {
+			protocol: t.protocol.replace(/:$/, ""),
+			publicKey: n,
+			host: t.host,
+			projectId: i
+		};
+	} catch {
+		return null;
+	}
+}, s = {
+	trace: "debug",
+	debug: "debug",
+	info: "info",
+	warn: "warning",
+	error: "error",
+	fatal: "fatal"
+}, c = (e) => ({
+	timestamp: e.ts.getTime() / 1e3,
+	level: s[e.level] ?? "info",
+	...e.scope ? { category: e.scope } : {},
+	message: e.message,
+	...Object.keys(e.fields).length > 0 ? { data: { ...e.fields } } : {}
+}), l = (e = {}, t = () => Date.now()) => {
+	let n = e.maxPerTrace ?? 50, r = e.maxTraces ?? 1e3, i = e.ttlMs ?? 5 * 6e4, a = /* @__PURE__ */ new Map(), o = () => {
+		let e = t() - i;
+		for (let [t, n] of a) if (n.at < e) a.delete(t);
+		else break;
+	};
+	return {
+		add(e, i) {
+			o();
+			let s = a.get(e), l = s ?? {
+				at: t(),
+				crumbs: []
+			};
+			for (s && a.delete(e), l.at = t(), l.crumbs.push(c(i)), l.crumbs.length > n && l.crumbs.shift(), a.set(e, l); a.size > r;) {
+				let e = a.keys().next().value;
+				if (e === void 0) break;
+				a.delete(e);
+			}
+		},
+		take(e) {
+			let t = a.get(e);
+			return a.delete(e), t ? t.crumbs : [];
+		},
+		drop(e) {
+			a.delete(e);
+		},
+		size() {
+			return a.size;
+		}
+	};
+}, u = (t) => e.squash(t), d = (e, t, n = []) => {
+	e.withScope((r) => {
+		r.setTag("voltro.errorSource", t.source), t.name !== void 0 && r.setTag("voltro.name", t.name), t.traceId !== void 0 && r.setContext("trace", { trace_id: t.traceId }), t.fields !== void 0 && r.setContext("voltro", t.fields);
+		for (let e of n) r.addBreadcrumb(e);
+		e.captureException(t.error);
+	});
+}, f = (t, n, r, i) => {
+	if (e.isInterruptedOnly(n)) return;
+	let a = u(n);
+	t.withScope((e) => {
+		e.setContext("trace", {
+			trace_id: r.traceId,
+			...r.spanId === void 0 ? {} : { span_id: r.spanId }
+		}), e.setTag("rpc.tag", r.tag), e.setTag("rpc.kind", r.kind), e.setTag("subject.type", r.subject.type), r.subject.tenantId !== void 0 && r.subject.tenantId !== null && e.setTag("tenant.id", r.subject.tenantId);
+		for (let t of i) e.addBreadcrumb(t);
+		t.captureException(a);
+	});
+}, p = n([
+	{
+		name: "SENTRY_DSN",
+		required: !1,
+		secret: !0,
+		description: "Sentry DSN (carries a project key). Without a valid DSN the plugin is inert."
+	},
+	{
+		name: "SENTRY_ENVIRONMENT",
+		required: !1,
+		secret: !1,
+		description: "Sentry `environment` tag (e.g. production, staging)."
+	},
+	{
+		name: "SENTRY_RELEASE",
+		required: !1,
+		secret: !1,
+		description: "Release identifier for Sentry release health + source maps."
+	}
+]), m = (e = {}) => {
+	let n = p.read("SENTRY_DSN", e.dsn), s = o(n), c = e.name ? `@voltro/plugin-sentry#${e.name}` : "@voltro/plugin-sentry";
+	if (!s) return i({
+		name: c,
+		description: "Sentry error tracking (inactive — no valid SENTRY_DSN).",
+		onActivate: (e) => t.sync(() => e.logger.warn("sentry inactive — no valid DSN (set `dsn` or SENTRY_DSN)")),
+		onDeactivate: () => t.void
+	});
+	let u = p.read("SENTRY_ENVIRONMENT", e.environment), m = p.read("SENTRY_RELEASE", e.release), h = e.tracesSampleRate ?? 1, g = l({ maxPerTrace: e.maxBreadcrumbs ?? 50 }), _, v = (e, t) => {
+		if (_) try {
+			f(_, e, t, g.take(t.traceId));
+		} catch {}
+	}, y = (e, n) => e.pipe(t.tapErrorCause((e) => t.sync(() => v(e, {
+		tag: n.tag,
+		kind: n.kind,
+		subject: n.subject,
+		traceId: n.traceId,
+		...n.spanId === void 0 ? {} : { spanId: n.spanId }
+	})))), b = [
+		"rpc:intercept:mutation",
+		"rpc:intercept:query",
+		"rpc:intercept:action",
+		`network:outbound:${s.host}`
+	], x, S;
+	return i({
+		name: c,
+		description: "Deep Sentry integration — trace-correlated errors + breadcrumbs + (opt-in) performance traces.",
+		permissions: b,
+		declaredEnv: p.declared,
+		interceptMutation: y,
+		interceptQuery: y,
+		interceptAction: y,
+		contributeObservability: async (t) => {
+			let r;
+			try {
+				r = await import("@sentry/node");
+			} catch {
+				t.logger.warn("sentry requested but @sentry/node is not installed — inactive");
+				return;
+			}
+			let i = [];
+			if (e.profiling) try {
+				let { nodeProfilingIntegration: e } = await import("@sentry/profiling-node");
+				i.push(e());
+			} catch {
+				t.logger.warn("sentry profiling requested but @sentry/profiling-node is not installed");
+			}
+			let { integrations: a, ...o } = e.init ?? {};
+			if (a && i.push(...a), r.init({
+				...o,
+				dsn: n,
+				skipOpenTelemetrySetup: !0,
+				tracesSampleRate: h,
+				...u ? { environment: u } : {},
+				...m ? { release: m } : {},
+				...e.profiling ? { profilesSampleRate: e.profilesSampleRate ?? 1 } : {},
+				...i.length > 0 ? { integrations: i } : {}
+			}), _ = r, t.logger.info("sentry active", {
+				environment: u,
+				release: m,
+				traces: !!e.traces,
+				profiling: !!e.profiling
+			}), e.traces) try {
+				let { SentrySpanProcessor: e } = await import("@sentry/opentelemetry");
+				return {
+					spanProcessors: [new e()],
+					resourceAttributes: {
+						...m ? { "service.version": m } : {},
+						...u ? { "deployment.environment": u } : {}
+					}
+				};
+			} catch {
+				t.logger.warn("sentry traces requested but @sentry/opentelemetry is not installed — skipping span export");
+				return;
+			}
+		},
+		onActivate: () => t.sync(() => {
+			x = r((e) => {
+				let t = e.fields.traceId;
+				typeof t == "string" && t.length > 0 && g.add(t, e);
+			}), S = a((e) => {
+				if (_) try {
+					d(_, e, e.traceId ? g.take(e.traceId) : []);
+				} catch {}
+			});
+		}),
+		onDeactivate: () => t.promise(async () => {
+			x?.(), x = void 0, S?.(), S = void 0;
+			try {
+				await (await import("@sentry/node")).close(2e3);
+			} catch {}
+		})
+	});
+};
+//#endregion
+export { f as captureToSentry, u as causeToError, l as makeBreadcrumbRing, o as parseDsn, m as sentryPlugin, c as toBreadcrumb };

package/dist/web.d.ts

@@ -0,0 +1,73 @@
+import { ClientTraceEvent } from '@voltro/client';
+import { reportClientError } from '@voltro/client';
+
+/** Report a client error (route render/loader failure OR a manual capture) to
+ *  Sentry, tagged with its source + route + React component stack. Pure given
+ *  a `SentryBrowserLike` — unit-testable with a fake. */
+export declare const captureClientError: (sentry: SentryBrowserLike, event: {
+    readonly error: unknown;
+    readonly source: string;
+    readonly componentStack?: string;
+    readonly pathname?: string;
+    readonly context?: Record<string, unknown>;
+}) => void;
+
+/** Tear down the trace + error bridges (tests / hot-reload). */
+export declare const closeSentryBrowser: () => void;
+
+/** Initialise browser-side Sentry + wire the rpc trace bridge. Idempotent-ish:
+ *  a second call re-subscribes the bridge (disposing the first). No-op on the
+ *  server (SSR) and without a DSN. */
+export declare const initSentryBrowser: (options?: SentryBrowserOptions) => Promise<void>;
+
+/** Emit a browser-side Sentry span into the SAME trace as the server
+ *  transaction the call will produce. */
+export declare const recordClientTraceSpan: (sentry: SentryBrowserLike, event: ClientTraceEvent) => void;
+
+export { reportClientError }
+
+export declare interface SentryBrowserLike {
+    continueTrace<T>(context: {
+        sentryTrace: string;
+        baggage?: string;
+    }, callback: () => T): T;
+    startInactiveSpan(options: {
+        name: string;
+        op?: string;
+        attributes?: Record<string, unknown>;
+    }): SentrySpanLike;
+    withScope(callback: (scope: SentryBrowserScopeLike) => void): unknown;
+    captureException(exception: unknown): unknown;
+}
+
+export declare interface SentryBrowserOptions {
+    /** Sentry DSN (public — safe in the browser bundle). Without it → no-op. */
+    readonly dsn?: string;
+    /** `environment` tag. */
+    readonly environment?: string;
+    /** Release identifier (must match the server's `release` for unified
+     *  release health + source maps). */
+    readonly release?: string;
+    /** Performance-trace sample rate (0..1). Default 1.0. */
+    readonly tracesSampleRate?: number;
+    /** Instrument page loads + client navigations via `browserTracingIntegration`.
+     *  Default true. */
+    readonly browserTracing?: boolean;
+}
+
+declare interface SentryBrowserScopeLike {
+    setTag(key: string, value: string): unknown;
+    setContext(key: string, context: Record<string, unknown> | null): unknown;
+}
+
+/** Minimal structural slice of `@sentry/react` we use — keeps this testable
+ *  with a fake; the real module satisfies it structurally. */
+declare interface SentrySpanLike {
+    end(): void;
+}
+
+/** Build the `sentry-trace` header for a client trace event (sampled=1 — the
+ *  framework records always-on; Sentry's client applies its own sample rate). */
+export declare const sentryTraceHeader: (event: ClientTraceEvent) => string;
+
+export { }

package/dist/web.js

@@ -0,0 +1,44 @@
+import { reportClientError as e, subscribeClientErrors as t, subscribeClientTraces as n } from "@voltro/client";
+//#region src/webTrace.ts
+var r = (e, t) => {
+	e.withScope((n) => {
+		n.setTag("voltro.errorSource", t.source), t.pathname && n.setTag("route.pathname", t.pathname), t.componentStack && n.setContext("react", { componentStack: t.componentStack }), t.context && n.setContext("voltro", t.context), e.captureException(t.error);
+	});
+}, i = (e) => `${e.traceId}-${e.spanId}-1`, a = (e, t) => {
+	e.continueTrace({ sentryTrace: i(t) }, () => {
+		e.startInactiveSpan({
+			name: `${t.source}.${t.tag}`,
+			op: `rpc.client.${t.source}`,
+			attributes: {
+				"rpc.tag": t.tag,
+				"voltro.source": t.source
+			}
+		}).end();
+	});
+}, o, s, c = async (e = {}) => {
+	if (typeof window > "u") return;
+	let i = e.dsn;
+	if (!i) return;
+	let c = await import("@sentry/react");
+	c.init({
+		dsn: i,
+		tracesSampleRate: e.tracesSampleRate ?? 1,
+		...e.environment ? { environment: e.environment } : {},
+		...e.release ? { release: e.release } : {},
+		integrations: e.browserTracing === !1 ? [] : [c.browserTracingIntegration()]
+	});
+	let l = c;
+	o?.(), o = n((e) => {
+		try {
+			a(l, e);
+		} catch {}
+	}), s?.(), s = t((e) => {
+		try {
+			r(l, e);
+		} catch {}
+	});
+}, l = () => {
+	o?.(), o = void 0, s?.(), s = void 0;
+};
+//#endregion
+export { r as captureClientError, l as closeSentryBrowser, c as initSentryBrowser, a as recordClientTraceSpan, e as reportClientError, i as sentryTraceHeader };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@voltro/plugin-sentry",
+  "version": "0.1.0",
+  "description": "Deep Sentry integration — error tracking correlated to the distributed trace, breadcrumbs from the framework log sink, and (opt-in) performance traces routed from the framework's OTel tracer via @sentry/node in OTel-consumer mode. Errors carry the active trace_id + span_id + the request's recent log lines.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js",
+      "default": "./dist/web.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/logger": "0.1.0",
+    "@voltro/protocol": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@sentry/node": "^10.65.0",
+    "@sentry/opentelemetry": "^10.65.0",
+    "@sentry/profiling-node": "^10.65.0",
+    "@sentry/react": "^10.65.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}