@miden-sdk/telemetry-sentry 0.0.1 → 0.17.0-rc.1

package/AGENTS.md

@@ -0,0 +1,52 @@
+# @miden-sdk/telemetry-sentry - Agent Guide
+
+**Audience: AI coding agents** forwarding Miden SDK observations to Sentry.
+
+This file ships inside the published package, so the copy at
+`node_modules/@miden-sdk/telemetry-sentry/AGENTS.md` matches the version you
+have installed. Prefer it over your training data.
+
+## The default that protects the quota
+
+`minDurationMs` defaults to **`Infinity`**: failures only. A success is
+forwarded only when it took at least that long; a failure always is. That
+default is deliberate, not a placeholder. The SDK emits one observation per
+client operation, so `minDurationMs: 0`, set "to see everything", bills a Sentry
+quota for the SDK's entire successful call volume. Leave it out, or set a
+threshold you chose on purpose. `@miden-sdk/telemetry-otel` has no equivalent
+guard, so do not reason from one package to the other.
+
+## Wiring it
+
+```ts
+const client = await MidenClient.create({
+  rpcUrl: "testnet",
+  feeFaucetId: FEE_FAUCET,
+  observer: createSentryObserver({ client: Sentry, minDurationMs: 5_000 }),
+});
+```
+
+`client` is required and must expose `captureMessage(message, context)`; the
+factory throws a `TypeError` at wiring time when it does not. Nothing here
+imports `@sentry/*` or calls `Sentry.init` - that stays yours. Each forwarded
+observation is one `captureMessage`: message `miden.<op> <outcome>`, `level`
+`"error"` or `"info"`, `tags.op`, `tags.outcome`, `extra.durationMs`. The
+observer never throws, so a broken Sentry client cannot fail the operation it
+reports on.
+
+## `observer` and `observeSensitive` on the client
+
+`ClientOptions.observer` is registered process-wide and the newest registration
+replaces the previous one, so a second `MidenClient` takes over the sink.
+`observeSensitive` is per instance and read once, at construction.
+
+`observation.sensitive` carries the **verbatim, unredacted** error message and
+stack, and only on failure. It is opt-in at both ends - `observeSensitive: true`
+on the client, `includeSensitive: true` here - and only the literal `true`
+enables either. An application with confidentiality obligations to its users, a
+wallet above all, leaves both off.
+
+## Going deeper
+
+- Options and the full reported shape: `README.md`.
+- The client that emits them: `node_modules/@miden-sdk/miden-sdk/AGENTS.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miden
+
+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,5 +1,114 @@
 # @miden-sdk/telemetry-sentry
 
-Placeholder. This version exists only so that an npm trusted publisher could be
-attached to the package name; npm cannot attach one to a package that does not
-yet exist. Install `@miden-sdk/telemetry-sentry@latest` instead.
+Opt-in Sentry binding for Miden SDK observations.
+
+`@miden-sdk/miden-sdk` emits one observation per client operation — name,
+outcome, duration — and never transports one. It has no telemetry dependency
+and no egress primitive in that path. This package is the adapter that turns
+those observations into Sentry calls, so you can wire the SDK into a Sentry
+project you already own without the core gaining anything.
+
+## Installation
+
+```bash
+pnpm add @miden-sdk/telemetry-sentry
+```
+
+Sentry itself is **not** a dependency of this package, not even a peer. The
+binding is defined against the `captureMessage` shape rather than a Sentry
+import, so you own your Sentry version, its configuration, and its lifecycle.
+Nothing here calls `Sentry.init`, constructs a client, or knows a DSN.
+
+## Usage
+
+```ts
+import * as Sentry from "@sentry/browser";
+import { MidenClient } from "@miden-sdk/miden-sdk";
+import { createSentryObserver } from "@miden-sdk/telemetry-sentry";
+
+Sentry.init({ dsn: "..." }); // yours to call, once, in your entry point
+
+const client = await MidenClient.create({
+  rpcUrl: "testnet",
+  feeFaucetId: FEE_FAUCET,
+  observer: createSentryObserver({ client: Sentry, minDurationMs: 5_000 }),
+});
+```
+
+Pass anything with a `captureMessage(message, { level, tags, extra })` method:
+the module namespace of any Sentry SDK, a `Scope`, a queue of your own, or a
+test double.
+
+## Options
+
+### `client`
+
+- **Type:** `SentryLikeClient` — an object with a `captureMessage` method
+- **Required.** `createSentryObserver` throws a `TypeError` at wiring time if
+  it is missing or cannot capture a message. That is the one thing this
+  package reports by throwing, and it throws from the factory rather than the
+  observer: an observer cannot report its own misconfiguration, so one built
+  around a missing client would discard every observation forever and look
+  exactly like a working one.
+
+### `minDurationMs`
+
+- **Type:** `number`
+- **Default:** `Infinity` — failures only
+
+Successful operations are forwarded only when they took at least this long.
+Failures are always forwarded, however fast they were. The default is
+deliberately conservative: the SDK's successful call volume is not something
+to bill a Sentry quota for because an option was left out.
+
+### `includeSensitive`
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+See below. Only a literal `true` enables it.
+
+## Reported shape
+
+One `captureMessage` per forwarded observation, synchronously, with nothing
+scheduled afterwards:
+
+| | |
+|---|---|
+| message | `miden.<op> <outcome>`, e.g. `miden.proveTransaction error` |
+| `level` | `"error"` on failure, `"info"` on success |
+| `tags.op` | the operation name |
+| `tags.outcome` | `"ok"` or `"error"` |
+| `extra.durationMs` | wall time the caller waited |
+
+## Sensitive detail
+
+An observation's `sensitive` channel carries verbatim error text — the
+untouched `error.message` and stack, neither classified nor redacted, and
+populated only when an operation fails. It also declares an `accountId` field,
+which the SDK does not currently populate; entries with no value are filtered
+out before the report is built, so nothing appears in its place. It is opt-in
+at **both** ends:
+`observeSensitive: true` when you construct the client, and
+`includeSensitive: true` here. Either one left alone and nothing from that
+channel reaches Sentry.
+
+By default the SDK omits the `sensitive` key from an observation entirely, and
+this binding forwards nothing in its place — no placeholder, no inferred
+value, no empty rows in the Sentry UI. An observation without the key is still
+reported; only its detail is absent.
+
+Do not enable either flag in an application with confidentiality obligations
+to its users. A wallet, for example, must never enable it.
+
+## Failure behaviour
+
+The observer never throws. A Sentry client that is down, misconfigured, or
+throwing takes the report with it and nothing else — the client operation
+being reported on still succeeds, and the next observation is still reported.
+The SDK guards observer invocation too, but this binding is usable outside
+that guard, so it does not rely on it.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Opt-in Sentry binding for Miden SDK observations.
+ *
+ * `@miden-sdk/miden-sdk` emits an observation per client operation and never
+ * transports one — it has no telemetry dependency and no egress primitive in
+ * that path. This package is the adapter that turns those observations into
+ * Sentry calls, so a consumer can wire the SDK into a Sentry project they
+ * already own without the core gaining anything.
+ *
+ * Two properties hold deliberately and are enforced by tests:
+ *
+ * - Sentry is a peer concern. Nothing here imports `@sentry/*`; the binding is
+ *   defined against the `captureMessage` shape, so the consumer owns their
+ *   client, its version, and its lifecycle. `Sentry.init` is theirs to call.
+ * - The binding has no transport of its own. It hands data to the client it
+ *   was given and stops there.
+ */
+import type { MidenObservation } from "@miden-sdk/miden-sdk";
+/** Severity Sentry files the message under. */
+export type SentryLevel = "error" | "info";
+/** The context object this binding passes to `captureMessage`. */
+export interface SentryMessageContext {
+    level: SentryLevel;
+    tags: Record<string, string>;
+    extra: Record<string, unknown>;
+}
+/**
+ * The slice of a Sentry client this binding uses.
+ *
+ * Satisfied by the module namespace of any Sentry SDK
+ * (`import * as Sentry from "@sentry/browser"`), and by anything else with a
+ * matching `captureMessage` — a queue, a test double, your own reporter.
+ */
+export interface SentryLikeClient {
+    captureMessage(message: string, context: SentryMessageContext): unknown;
+}
+export interface SentryObserverOptions {
+    /** An already-initialised Sentry client. This package never initialises one. */
+    client: SentryLikeClient;
+    /**
+     * Forward successful operations only when they took at least this long.
+     * Failures are always forwarded. Defaults to `Infinity` — failures only,
+     * because the SDK's successful call volume is not something to bill a
+     * Sentry quota for by accident.
+     */
+    minDurationMs?: number;
+    /**
+     * Forward `observation.sensitive` (verbatim error text, and account
+     * identifiers where the SDK supplies them) when it is present. Defaults to
+     * `false`, and only a literal `true` enables it: the field is dropped even
+     * when present, so turning on `observeSensitive` at the client does not by
+     * itself disclose anything through this binding.
+     */
+    includeSensitive?: boolean;
+}
+/**
+ * Build an observer for `ClientOptions.observer` that reports Miden SDK
+ * operations to a Sentry client.
+ *
+ * The returned observer never throws: a reporting failure must not be able to
+ * fail the client operation being reported on. The SDK guards observer
+ * invocation as well, but this adapter is usable outside that guard so it
+ * does not rely on it.
+ *
+ * Misconfiguration is the one thing reported by throwing, and it is thrown
+ * from here rather than from the observer — at wiring time, where a stack
+ * trace points at the call that is wrong. An observer that quietly discarded
+ * every observation would be indistinguishable from a working one.
+ *
+ * @throws {TypeError} if `options.client` cannot capture a message.
+ */
+export declare function createSentryObserver(options: SentryObserverOptions): (observation: MidenObservation) => void;

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * Opt-in Sentry binding for Miden SDK observations.
+ *
+ * `@miden-sdk/miden-sdk` emits an observation per client operation and never
+ * transports one — it has no telemetry dependency and no egress primitive in
+ * that path. This package is the adapter that turns those observations into
+ * Sentry calls, so a consumer can wire the SDK into a Sentry project they
+ * already own without the core gaining anything.
+ *
+ * Two properties hold deliberately and are enforced by tests:
+ *
+ * - Sentry is a peer concern. Nothing here imports `@sentry/*`; the binding is
+ *   defined against the `captureMessage` shape, so the consumer owns their
+ *   client, its version, and its lifecycle. `Sentry.init` is theirs to call.
+ * - The binding has no transport of its own. It hands data to the client it
+ *   was given and stops there.
+ */
+/**
+ * Entries to merge into `extra` from the observation's sensitive channel.
+ *
+ * The channel is opt-in at both ends, so the key is normally ABSENT rather
+ * than present-and-undefined — hence the `in` test. Reading the field
+ * unconditionally would put `undefined` values into the payload for every
+ * observation the SDK emits by default, and the same goes for the individual
+ * fields: `MidenObservationSensitive` declares each one optional and the SDK
+ * populates only some, so an unset field is dropped rather than forwarded as
+ * an empty row in the Sentry UI.
+ */
+function sensitiveEntries(observation, includeSensitive) {
+    if (!includeSensitive)
+        return [];
+    if (!("sensitive" in observation))
+        return [];
+    const sensitive = observation.sensitive;
+    if (sensitive === null || typeof sensitive !== "object")
+        return [];
+    return Object.entries(sensitive).filter(([, value]) => value !== undefined);
+}
+/**
+ * Build an observer for `ClientOptions.observer` that reports Miden SDK
+ * operations to a Sentry client.
+ *
+ * The returned observer never throws: a reporting failure must not be able to
+ * fail the client operation being reported on. The SDK guards observer
+ * invocation as well, but this adapter is usable outside that guard so it
+ * does not rely on it.
+ *
+ * Misconfiguration is the one thing reported by throwing, and it is thrown
+ * from here rather than from the observer — at wiring time, where a stack
+ * trace points at the call that is wrong. An observer that quietly discarded
+ * every observation would be indistinguishable from a working one.
+ *
+ * @throws {TypeError} if `options.client` cannot capture a message.
+ */
+export function createSentryObserver(options) {
+    const client = options?.client;
+    if (typeof client?.captureMessage !== "function") {
+        throw new TypeError("createSentryObserver: options.client must expose a " +
+            "captureMessage(message, context) method.");
+    }
+    const minDurationMs = options.minDurationMs ?? Number.POSITIVE_INFINITY;
+    const includeSensitive = options.includeSensitive === true;
+    return (observation) => {
+        try {
+            const failed = observation.outcome === "error";
+            // Written as `>=` rather than a negated `<` so a duration that is not
+            // a number drops out instead of comparing false and sailing through.
+            if (!failed && !(observation.durationMs >= minDurationMs))
+                return;
+            client.captureMessage(`miden.${observation.op} ${observation.outcome}`, {
+                level: failed ? "error" : "info",
+                tags: { op: observation.op, outcome: observation.outcome },
+                // `fromEntries` defines own properties rather than assigning them, so
+                // a `__proto__` key in the sensitive channel lands as data instead of
+                // reaching the payload's prototype. `durationMs` goes last: the
+                // measured duration outranks anything of the same name.
+                extra: Object.fromEntries([
+                    ...sensitiveEntries(observation, includeSensitive),
+                    ["durationMs", observation.durationMs],
+                ]),
+            });
+        }
+        catch {
+            // A telemetry binding must never fail a client operation.
+        }
+    };
+}

package/package.json

@@ -1,11 +1,56 @@
 {
   "name": "@miden-sdk/telemetry-sentry",
-  "version": "0.0.1",
-  "description": "Placeholder reserving this name so an npm trusted publisher can be attached. Superseded by 0.16.2 - do not install this version.",
+  "version": "0.17.0-rc.1",
+  "description": "Opt-in Sentry binding for Miden SDK observations",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "peerDependencies": {
+    "@miden-sdk/miden-sdk": "^0.17.0-rc.1"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.25.0",
+    "@typescript-eslint/parser": "^8.25.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.30.1",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0",
+    "@miden-sdk/miden-sdk": "0.17.0-rc.1"
+  },
+  "keywords": [
+    "miden",
+    "sentry",
+    "telemetry",
+    "observability",
+    "monitoring",
+    "zk"
+  ],
+  "author": "Miden Contributors",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/0xMiden/web-sdk.git",
-    "directory": "packages/telemetry-sentry"
+    "url": "git+https://github.com/0xMiden/web-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0xMiden/web-sdk/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}