@voyant-travel/observability-sentry 0.0.0

package/README.md

@@ -0,0 +1,68 @@
+# @voyant-travel/observability-sentry
+
+Sentry adapter for the Voyant observability `Reporter` seam (RFC [voyant#1553](https://github.com/voyant-travel/voyant/issues/1553)).
+
+The framework owns the **mechanism** — a request id minted once and propagated
+(`X-Request-Id` + `getRequestId()`), standard catch points (5xx boundary, auth
+sub-app, module bootstrap, event-bus subscribers, scheduled jobs), and a
+normalized `ErrorEvent` shape. This package is the **opt-in sink**: it forwards
+those events to Sentry, tagging each with the same `requestId` the user sees, so
+a support reference is a one-paste lookup in Sentry issue search.
+
+## Why an adapter and not a Sentry dependency
+
+This package takes **no dependency on a Sentry SDK**. It binds to a structural
+`SentryLike` interface, so you pass your already-initialized Sentry client —
+`@sentry/cloudflare`, `@sentry/node`, `@sentry/bun`, `@sentry/browser`, any
+version. Your deployment owns `init`/DSN/transport/sampling/PII scrubbing; the
+adapter only maps the event and forwards it. The framework drains the buffered
+event via `ctx.waitUntil` using the `flush()` the adapter returns — so you don't
+hand-roll the Workers `flush`/`waitUntil` lifecycle that the RFC found broken in
+three separate copies.
+
+## Usage
+
+```ts
+import * as Sentry from "@sentry/cloudflare"
+import { createApp } from "@voyant-travel/hono"
+import { sentryReporter } from "@voyant-travel/observability-sentry"
+
+const reporter = sentryReporter(Sentry)
+
+const app = createApp({
+  reporter,
+  appName: "operator", // stamped on every event as the `app` tag
+  modules,
+})
+```
+
+That is the entire change — swap `consoleReporter()` (or the no-op default) for
+`sentryReporter(Sentry)`. Every framework catch point now reaches Sentry.
+
+### What lands on the Sentry issue
+
+| `ErrorEvent` field | Sentry mapping |
+| --- | --- |
+| `requestId` | tag `request_id` (omitted when empty, e.g. background jobs) |
+| `app` | tag `app` |
+| `error` | the captured exception (non-`Error` values are wrapped so they still group with a stack) |
+| `context` | nested under the `voyant` context group |
+
+## Options
+
+```ts
+sentryReporter(Sentry, {
+  requestIdTag: "request_id",  // tag key for the correlation id
+  appTag: "app",               // tag key for the logical app name
+  contextKey: "voyant",        // context group the `ErrorEvent.context` nests under
+  flush: true,                 // default: flush when the client exposes flush() (Workers need it)
+  flushTimeoutMs: 2000,        // flush timeout in ms
+})
+```
+
+On long-lived Node/Bun servers you can pass `flush: false` to let Sentry's own
+background transport deliver events instead of flushing per capture.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { ErrorEvent, Reporter } from "@voyant-travel/hono/observability";
+export type { SentryCaptureContext, SentryLike, SentryReporterOptions, } from "./sentry-reporter.js";
+export { sentryReporter } from "./sentry-reporter.js";
+//# 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":"AAEA,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAA;AAC7E,YAAY,EACV,oBAAoB,EACpB,UAAU,EACV,qBAAqB,GACtB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

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

package/dist/sentry-reporter.d.ts

@@ -0,0 +1,71 @@
+import type { Reporter } from "@voyant-travel/hono/observability";
+/**
+ * The slice of a Sentry SDK this adapter calls. Declared structurally so the
+ * adapter binds to ANY Sentry flavour — `@sentry/cloudflare`, `@sentry/node`,
+ * `@sentry/bun`, `@sentry/browser` — and any version whose `captureException`
+ * accepts a capture-context hint, without this package taking a hard dependency
+ * on a specific Sentry SDK. The deployment owns `init`/DSN/transport/sampling;
+ * the adapter only maps the normalized event and forwards it. This is exactly
+ * the split RFC voyant#1553 asked for: the framework owns the catch points and
+ * event shape, the vendor SDK stays a deployment choice.
+ */
+export interface SentryLike {
+    captureException(exception: unknown, hint?: SentryCaptureContext): string;
+    /**
+     * Optional. On Cloudflare Workers, Sentry buffers events and only delivers
+     * them on `flush`; when the client exposes it, the adapter returns
+     * `flush(timeout)` so the framework drains it via `ctx.waitUntil` after the
+     * response. Owning this lifecycle once is the point — the three hand-rolled
+     * `sentry.ts` copies the RFC cites each got the manual `flush`/`waitUntil`
+     * dance subtly wrong, and server-side Worker exceptions never delivered.
+     */
+    flush?(timeout?: number): Promise<boolean>;
+}
+/** The subset of Sentry's capture-context hint this adapter populates. */
+export interface SentryCaptureContext {
+    tags?: Record<string, string>;
+    contexts?: Record<string, Record<string, unknown>>;
+}
+export interface SentryReporterOptions {
+    /**
+     * Tag key carrying the correlation id. Default `"request_id"`. This is the
+     * tag that makes a user-reported reference findable in Sentry — closing the
+     * RFC's root cause, where the id surfaced to the user never reached the event.
+     */
+    requestIdTag?: string;
+    /** Tag key carrying the logical app/worker name. Default `"app"`. */
+    appTag?: string;
+    /**
+     * Sentry context group the normalized `ErrorEvent.context` is nested under
+     * (shows as a labelled section on the issue). Default `"voyant"`.
+     */
+    contextKey?: string;
+    /**
+     * Flush after every capture. Workers must (events are buffered until flush);
+     * long-lived Node/Bun servers need not. Default: flush when the client
+     * exposes a `flush` method.
+     */
+    flush?: boolean;
+    /** Flush timeout in milliseconds. Default `2000` (matches Sentry's own). */
+    flushTimeoutMs?: number;
+}
+/**
+ * Build a {@link Reporter} backed by an already-initialized Sentry client.
+ *
+ * Register it once on `VoyantAppConfig.reporter` and every framework catch
+ * point (5xx boundary, auth sub-app, module bootstrap, event-bus subscribers,
+ * scheduled jobs) routes its {@link ErrorEvent} to Sentry — each tagged with
+ * the same `requestId` the user sees on `X-Request-Id`, so a support reference
+ * is a one-paste lookup in the Sentry issue search.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from "@sentry/cloudflare"
+ * import { sentryReporter } from "@voyant-travel/observability-sentry"
+ *
+ * const reporter = sentryReporter(Sentry)
+ * const app = createApp({ reporter, appName: "operator", modules })
+ * ```
+ */
+export declare function sentryReporter(sentry: SentryLike, options?: SentryReporterOptions): Reporter;
+//# sourceMappingURL=sentry-reporter.d.ts.map

package/dist/sentry-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentry-reporter.d.ts","sourceRoot":"","sources":["../src/sentry-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,mCAAmC,CAAA;AAE7E;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAAA;IACzE;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC3C;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B,GAAG,QAAQ,CA8BhG"}

package/dist/sentry-reporter.js

@@ -0,0 +1,65 @@
+/**
+ * Build a {@link Reporter} backed by an already-initialized Sentry client.
+ *
+ * Register it once on `VoyantAppConfig.reporter` and every framework catch
+ * point (5xx boundary, auth sub-app, module bootstrap, event-bus subscribers,
+ * scheduled jobs) routes its {@link ErrorEvent} to Sentry — each tagged with
+ * the same `requestId` the user sees on `X-Request-Id`, so a support reference
+ * is a one-paste lookup in the Sentry issue search.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from "@sentry/cloudflare"
+ * import { sentryReporter } from "@voyant-travel/observability-sentry"
+ *
+ * const reporter = sentryReporter(Sentry)
+ * const app = createApp({ reporter, appName: "operator", modules })
+ * ```
+ */
+export function sentryReporter(sentry, options = {}) {
+    const requestIdTag = options.requestIdTag ?? "request_id";
+    const appTag = options.appTag ?? "app";
+    const contextKey = options.contextKey ?? "voyant";
+    const flushTimeoutMs = options.flushTimeoutMs ?? 2000;
+    const shouldFlush = options.flush ?? typeof sentry.flush === "function";
+    return {
+        captureException(event) {
+            const { requestId, app, error, context } = event;
+            const tags = { [appTag]: app };
+            // Only tag a non-empty id. Background/scheduled catch points emit an empty
+            // requestId (no request to correlate with), and an empty-string tag is
+            // searchable noise rather than a useful key.
+            if (requestId)
+                tags[requestIdTag] = requestId;
+            sentry.captureException(toError(error), {
+                tags,
+                contexts: context ? { [contextKey]: context } : undefined,
+            });
+            if (shouldFlush && sentry.flush) {
+                // Handed back to the framework, which drains it via `waitUntil` so the
+                // buffered event delivers without blocking the response. `.then`
+                // collapses the boolean to the `void` the Reporter contract expects.
+                return sentry.flush(flushTimeoutMs).then(() => { });
+            }
+        },
+    };
+}
+/**
+ * Sentry produces the richest issue (stack frames, grouping) from a real
+ * `Error`. Pass `Error` instances through untouched; wrap anything else so a
+ * thrown string/object still yields a grouped, stack-bearing issue instead of
+ * Sentry's bare "Non-Error exception captured" placeholder.
+ */
+function toError(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error === "string")
+        return new Error(error);
+    try {
+        return new Error(`Non-Error thrown: ${JSON.stringify(error)}`);
+    }
+    catch {
+        // Circular or otherwise un-serializable value.
+        return new Error(`Non-Error thrown: ${String(error)}`);
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@voyant-travel/observability-sentry",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Sentry adapter for the Voyant observability Reporter seam (RFC voyant#1553).",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@voyant-travel/hono": "workspace:^"
+  },
+  "devDependencies": {
+    "@voyant-travel/hono": "workspace:^",
+    "@voyant-travel/voyant-typescript-config": "workspace:^",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/observability-sentry"
+  }
+}