@nevermined-io/payments 1.5.0 → 1.6.0

package/dist/x402/langsmith/spans.d.ts

@@ -0,0 +1,163 @@
+/**
+ * LangSmith span helpers for Nevermined payment events (TypeScript).
+ *
+ * TS parity port of `payments_py/langsmith/spans.py`. Emits the cross-SDK
+ * `nvm:verify` / `nvm:settlement` spans defined by the
+ * **observability-spans-v1** contract
+ * (`docs/specs/observability-spans-v1.md` in nvm-monorepo), so a single
+ * LangSmith trace can be correlated across the TypeScript and Python SDKs
+ * (e.g. filtered on `nvm.tx_hash`).
+ *
+ * All helpers in this module silently no-op when:
+ *   - the optional `langsmith` JS SDK is not installed; or
+ *   - no LangSmith run tree is active in the current context (e.g.
+ *     `LANGSMITH_TRACING` is unset, or the call is not inside a traced run).
+ *
+ * Failures inside this module never propagate out — observability is
+ * best-effort and must not interfere with the payment flow.
+ *
+ * `langsmith` is imported **lazily** (dynamic `import()`), so users who only
+ * use the `requiresPayment` wrapper without tracing are not forced to install
+ * it. Install it yourself (`pnpm add langsmith`) and set `LANGSMITH_TRACING=true`
+ * to surface these spans.
+ */
+import type { RunTree } from 'langsmith';
+import type { VerifyPermissionsResult, SettlePermissionsResult } from '../facilitator-api.js';
+/** Plain JSON-ish metadata bag attached to a span / run tree. */
+export type SpanMetadata = Record<string, unknown>;
+/** Span names — must match observability-spans-v1 exactly (case-sensitive). */
+export declare const NVM_VERIFY_SPAN = "nvm:verify";
+export declare const NVM_SETTLEMENT_SPAN = "nvm:settlement";
+/**
+ * Return the current LangSmith `RunTree`, or `undefined` if none is active or
+ * `langsmith` is not installed. Safe to call unconditionally.
+ */
+export declare function activeRunTree(): Promise<RunTree | undefined>;
+/**
+ * Merge `metadata` into `runTree`, swallowing any error. No-op if `runTree` is
+ * absent or `metadata` is empty. Matches Python's `run_tree.add_metadata`.
+ *
+ * The merge is performed on THIS side of the boundary — we read the existing
+ * `extra.metadata`, spread the new keys over it, then assign — rather than
+ * relying on the langsmith `RunTree.metadata` setter to merge. In `langsmith@0.7`
+ * the setter does merge (`extra.metadata = { ...existing, ...new }`), but that is
+ * an implementation detail of `run_trees.js`, not a documented contract: a future
+ * release that flips it to plain assignment would silently drop the static
+ * `nvm.*` keys attached on the pre-verify pass once the post-verify pass runs.
+ * Reading+merging here keeps the double-pass accumulation correct regardless, and
+ * mirrors how {@link redactMetadataKeys} already reaches into `extra.metadata`.
+ */
+export declare function addMetadata(runTree: RunTree | undefined, metadata: SpanMetadata): void;
+/**
+ * Remove `keys` from `runTree`'s metadata in place.
+ *
+ * LangSmith inherits a parent run's metadata into child runs created via
+ * `createChild`, so call this on the PARENT run BEFORE opening any child span
+ * whose metadata should not carry the keys. The most common use is stripping
+ * the full `payment_token` from the parent tool span's metadata, since the raw
+ * access token grants access to the protected tool until it expires.
+ *
+ * No-op when `runTree` is absent or no keys are provided. Errors are swallowed
+ * so observability never disrupts the payment flow — but, unlike the other
+ * swallow paths, a failure here is **security-sensitive**: if the parent run
+ * tree still holds the raw `payment_token`, that credential rides into the
+ * parent tree and the inherited verify/settle child spans. So this path warns
+ * (not just debug) to keep the leak diagnosable.
+ */
+export declare function redactMetadataKeys(runTree: RunTree | undefined, ...keys: string[]): void;
+/**
+ * Return a short, non-functional reference to a payment token for span
+ * metadata. Mirrors `payments_py/langsmith/spans.py::abbreviate_token` and the
+ * redaction contract in nvm-monorepo#1746 §4 (short-token hardening from
+ * nvm-monorepo#1747, tracked in payments-py PR #217).
+ *
+ * - `undefined`/empty input → `undefined` (and silent — no token at all is not
+ *   a "wrong token" mistake).
+ * - Already-redacted input (a genuine `<prefix>…(short)` marker) → returned
+ *   unchanged and silent, so the helper stays idempotent (the decorator path
+ *   abbreviates the same token more than once). A raw value that merely *ends*
+ *   in the marker is NOT treated as redacted (see {@link isRedactedMarker}).
+ * - A token of length ≤ 20 is almost always a misconfiguration (a plan id, an
+ *   opaque handle, etc. passed where the JWT was expected). Because this helper
+ *   exists to keep credentials out of a durable trace store, such tokens are
+ *   **redacted, not exported**: at most the first 4 chars are revealed (to aid
+ *   debugging the misconfig), followed by the `…(short)` marker — and for a
+ *   token of 4 chars or fewer **nothing** is revealed (the whole value would
+ *   otherwise be the "prefix"), so it collapses to just `…(short)`. A warning
+ *   is emitted. The full short value never leaves this function.
+ * - Otherwise (a normal JWT, more than 20 chars) → `<first 16>…<last 4>`.
+ */
+export declare function abbreviateToken(token: string | undefined | null): string | undefined;
+/** Inputs accepted by {@link buildVerifyMetadata}. */
+export interface VerifyMetadataInput {
+    planIds: string[];
+    scheme?: string;
+    network?: string;
+    agentId?: string;
+    verification?: VerifyPermissionsResult;
+    durationMs?: number;
+    token?: string;
+}
+/**
+ * Build the `nvm.*` metadata for a verify span. Drops absent values (a key is
+ * omitted, never set to null/undefined). Matches observability-spans-v1 §2.
+ *
+ * `token` is abbreviated/redacted via {@link abbreviateToken} before being
+ * surfaced as `nvm.payment_token` so the full credential never lands in
+ * metadata we control.
+ */
+export declare function buildVerifyMetadata(input: VerifyMetadataInput): SpanMetadata;
+/** Inputs accepted by {@link buildSettleMetadata}. */
+export interface SettleMetadataInput {
+    settlement: SettlePermissionsResult;
+    planIds: string[];
+    agentId?: string;
+    durationMs?: number;
+    token?: string;
+}
+/**
+ * Build the `nvm.*` metadata for a settlement span. Drops absent values.
+ * Matches observability-spans-v1 §3.
+ *
+ * Note the types preserved exactly per the spec: `nvm.credits_redeemed`
+ * (←`creditsRedeemed`) and `nvm.balance.after` (←`remainingBalance`) are
+ * STRINGS — they are not coerced to numbers. `nvm.tx_hash` ← `transaction`.
+ */
+export declare function buildSettleMetadata(input: SettleMetadataInput): SpanMetadata;
+/**
+ * An opened Nevermined span. `end()` records `outputs`/`error` and flushes the
+ * child run to LangSmith. Always safe to call (no-op when `runTree` is absent).
+ */
+export interface NvmSpan {
+    /** The underlying child `RunTree`, or `undefined` when tracing is inactive. */
+    readonly runTree: RunTree | undefined;
+    /** Attach `nvm.*` metadata to this span. */
+    addMetadata(metadata: SpanMetadata): void;
+    /** Close the span, flushing it to LangSmith. Optionally record an error. */
+    end(error?: unknown): Promise<void>;
+}
+/** Inputs accepted by {@link verifySpan}. */
+export interface VerifySpanInput {
+    planIds: string[];
+    scheme?: string;
+    network?: string;
+    agentId?: string;
+}
+/**
+ * Open an `nvm:verify` child span around a verify call. Returns an
+ * {@link NvmSpan} whose `end()` must be called once the verify completes (or
+ * throws). Always safe — a no-op span is returned when tracing is inactive or
+ * `langsmith` is not installed.
+ */
+export declare function verifySpan(input: VerifySpanInput): Promise<NvmSpan>;
+/** Inputs accepted by {@link settlementSpan}. */
+export interface SettlementSpanInput {
+    planIds: string[];
+    agentId?: string;
+}
+/**
+ * Open an `nvm:settlement` child span around a settle call. Same semantics as
+ * {@link verifySpan}.
+ */
+export declare function settlementSpan(input: SettlementSpanInput): Promise<NvmSpan>;
+//# sourceMappingURL=spans.d.ts.map

package/dist/x402/langsmith/spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.d.ts","sourceRoot":"","sources":["../../../src/x402/langsmith/spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE7F,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAElD,+EAA+E;AAC/E,eAAO,MAAM,eAAe,eAAe,CAAA;AAC3C,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AA4EnD;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAYlE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAUtF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAexF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAoBpF;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,uBAAuB,CAAA;IACtC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CAe5E;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,uBAAuB,CAAA;IACnC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CAa5E;AAOD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,4CAA4C;IAC5C,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IACzC,4EAA4E;IAC5E,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC;AA6CD,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzE;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjF"}

package/dist/x402/langsmith/spans.js

@@ -0,0 +1,341 @@
+/**
+ * LangSmith span helpers for Nevermined payment events (TypeScript).
+ *
+ * TS parity port of `payments_py/langsmith/spans.py`. Emits the cross-SDK
+ * `nvm:verify` / `nvm:settlement` spans defined by the
+ * **observability-spans-v1** contract
+ * (`docs/specs/observability-spans-v1.md` in nvm-monorepo), so a single
+ * LangSmith trace can be correlated across the TypeScript and Python SDKs
+ * (e.g. filtered on `nvm.tx_hash`).
+ *
+ * All helpers in this module silently no-op when:
+ *   - the optional `langsmith` JS SDK is not installed; or
+ *   - no LangSmith run tree is active in the current context (e.g.
+ *     `LANGSMITH_TRACING` is unset, or the call is not inside a traced run).
+ *
+ * Failures inside this module never propagate out — observability is
+ * best-effort and must not interfere with the payment flow.
+ *
+ * `langsmith` is imported **lazily** (dynamic `import()`), so users who only
+ * use the `requiresPayment` wrapper without tracing are not forced to install
+ * it. Install it yourself (`pnpm add langsmith`) and set `LANGSMITH_TRACING=true`
+ * to surface these spans.
+ */
+/** Span names — must match observability-spans-v1 exactly (case-sensitive). */
+export const NVM_VERIFY_SPAN = 'nvm:verify';
+export const NVM_SETTLEMENT_SPAN = 'nvm:settlement';
+/**
+ * Marker appended to a redacted short token. The joining character is the
+ * single Unicode ellipsis `…` (U+2026), matching the Python implementation
+ * and the spec, NOT three ASCII dots. (`…` is one UTF-16 code unit, so this
+ * string has length 8.)
+ */
+const SHORT_TOKEN_MARKER = '…(short)';
+/**
+ * A redacted short token is exactly `<prefix><marker>` where `prefix` is either
+ * empty (raw length 4 or fewer) or the first 4 chars (raw length over 4) — so a genuine
+ * marker only ever has one of these two lengths. Recognising it by both suffix
+ * AND an exact length stops a raw ≤20-char value that merely *ends* in the
+ * marker (e.g. `"x…(short)"`) from slipping through verbatim.
+ */
+const REDACTED_MARKER_LENGTHS = new Set([SHORT_TOKEN_MARKER.length, 4 + SHORT_TOKEN_MARKER.length]);
+/** True if `token` is already a value produced by the short-token branch. */
+function isRedactedMarker(token) {
+    return token.endsWith(SHORT_TOKEN_MARKER) && REDACTED_MARKER_LENGTHS.has(token.length);
+}
+let cachedLangsmith;
+/** True when the dynamic-import error means the package is simply not installed. */
+function isModuleNotFound(err) {
+    const code = err?.code;
+    return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
+}
+async function loadLangsmith() {
+    if (cachedLangsmith !== undefined)
+        return cachedLangsmith;
+    try {
+        // `getCurrentRunTree` is NOT exported from the `langsmith` root entry point —
+        // it lives exclusively at the `langsmith/singletons/traceable` sub-path (true
+        // across every published 0.x). Importing the root and reading
+        // `mod.getCurrentRunTree` always yields `undefined`, which would disable
+        // every span in production while the mocked unit tests stay green. Import the
+        // sub-path directly. (See the un-mocked smoke test in
+        // `langsmith-real-sdk.test.ts`, which fails loudly if this ever moves again.)
+        const mod = (await import('langsmith/singletons/traceable'));
+        if (typeof mod?.getCurrentRunTree === 'function') {
+            cachedLangsmith = mod;
+        }
+        else {
+            // Installed but missing the API we rely on — a real, diagnosable problem,
+            // distinct from "not installed". Warn once (cached null prevents repeats).
+            cachedLangsmith = null;
+            console.warn('nvm-langsmith: `langsmith` is installed but `langsmith/singletons/traceable` ' +
+                'does not export getCurrentRunTree; Nevermined spans are disabled.');
+        }
+    }
+    catch (err) {
+        cachedLangsmith = null;
+        // "Not installed" is the expected optional-peer path → stay silent. Any
+        // other failure (a broken install, a transitive load error) disables all
+        // spans with no other signal, so surface it once.
+        if (!isModuleNotFound(err)) {
+            console.warn('nvm-langsmith: failed to load `langsmith`; spans disabled', err);
+        }
+    }
+    return cachedLangsmith;
+}
+/**
+ * Return the current LangSmith `RunTree`, or `undefined` if none is active or
+ * `langsmith` is not installed. Safe to call unconditionally.
+ */
+export async function activeRunTree() {
+    const ls = await loadLangsmith();
+    if (ls === null)
+        return undefined;
+    try {
+        // `permitAbsentRunTree: true` returns undefined instead of throwing when
+        // there is no active run, mirroring Python's `get_current_run_tree()` used
+        // behind a try/except.
+        return ls.getCurrentRunTree(true);
+    }
+    catch (err) {
+        console.debug('nvm-langsmith: getCurrentRunTree failed (ignored)', err);
+        return undefined;
+    }
+}
+/**
+ * Merge `metadata` into `runTree`, swallowing any error. No-op if `runTree` is
+ * absent or `metadata` is empty. Matches Python's `run_tree.add_metadata`.
+ *
+ * The merge is performed on THIS side of the boundary — we read the existing
+ * `extra.metadata`, spread the new keys over it, then assign — rather than
+ * relying on the langsmith `RunTree.metadata` setter to merge. In `langsmith@0.7`
+ * the setter does merge (`extra.metadata = { ...existing, ...new }`), but that is
+ * an implementation detail of `run_trees.js`, not a documented contract: a future
+ * release that flips it to plain assignment would silently drop the static
+ * `nvm.*` keys attached on the pre-verify pass once the post-verify pass runs.
+ * Reading+merging here keeps the double-pass accumulation correct regardless, and
+ * mirrors how {@link redactMetadataKeys} already reaches into `extra.metadata`.
+ */
+export function addMetadata(runTree, metadata) {
+    if (!runTree || !metadata || Object.keys(metadata).length === 0)
+        return;
+    try {
+        const rt = runTree;
+        const existing = rt.extra?.metadata ?? {};
+        runTree.metadata = { ...existing, ...metadata };
+    }
+    catch (err) {
+        // observability hygiene must never disrupt the payment flow
+        console.debug('nvm-langsmith: addMetadata failed (ignored)', err);
+    }
+}
+/**
+ * Remove `keys` from `runTree`'s metadata in place.
+ *
+ * LangSmith inherits a parent run's metadata into child runs created via
+ * `createChild`, so call this on the PARENT run BEFORE opening any child span
+ * whose metadata should not carry the keys. The most common use is stripping
+ * the full `payment_token` from the parent tool span's metadata, since the raw
+ * access token grants access to the protected tool until it expires.
+ *
+ * No-op when `runTree` is absent or no keys are provided. Errors are swallowed
+ * so observability never disrupts the payment flow — but, unlike the other
+ * swallow paths, a failure here is **security-sensitive**: if the parent run
+ * tree still holds the raw `payment_token`, that credential rides into the
+ * parent tree and the inherited verify/settle child spans. So this path warns
+ * (not just debug) to keep the leak diagnosable.
+ */
+export function redactMetadataKeys(runTree, ...keys) {
+    if (!runTree || keys.length === 0)
+        return;
+    try {
+        const extra = runTree.extra;
+        const metadata = extra?.metadata;
+        if (metadata && typeof metadata === 'object') {
+            for (const key of keys)
+                delete metadata[key];
+        }
+    }
+    catch (err) {
+        console.warn(`nvm-langsmith: failed to redact metadata keys [${keys.join(', ')}] from ` +
+            'the parent run tree — a raw credential may remain in the trace', err);
+    }
+}
+/**
+ * Return a short, non-functional reference to a payment token for span
+ * metadata. Mirrors `payments_py/langsmith/spans.py::abbreviate_token` and the
+ * redaction contract in nvm-monorepo#1746 §4 (short-token hardening from
+ * nvm-monorepo#1747, tracked in payments-py PR #217).
+ *
+ * - `undefined`/empty input → `undefined` (and silent — no token at all is not
+ *   a "wrong token" mistake).
+ * - Already-redacted input (a genuine `<prefix>…(short)` marker) → returned
+ *   unchanged and silent, so the helper stays idempotent (the decorator path
+ *   abbreviates the same token more than once). A raw value that merely *ends*
+ *   in the marker is NOT treated as redacted (see {@link isRedactedMarker}).
+ * - A token of length ≤ 20 is almost always a misconfiguration (a plan id, an
+ *   opaque handle, etc. passed where the JWT was expected). Because this helper
+ *   exists to keep credentials out of a durable trace store, such tokens are
+ *   **redacted, not exported**: at most the first 4 chars are revealed (to aid
+ *   debugging the misconfig), followed by the `…(short)` marker — and for a
+ *   token of 4 chars or fewer **nothing** is revealed (the whole value would
+ *   otherwise be the "prefix"), so it collapses to just `…(short)`. A warning
+ *   is emitted. The full short value never leaves this function.
+ * - Otherwise (a normal JWT, more than 20 chars) → `<first 16>…<last 4>`.
+ */
+export function abbreviateToken(token) {
+    if (!token)
+        return undefined;
+    if (isRedactedMarker(token)) {
+        // Already redacted (re-applied on the decorator path); re-slicing would let
+        // the marker drift, so return unchanged and stay silent — the original
+        // short value already triggered the warning.
+        return token;
+    }
+    if (token.length <= 20) {
+        console.warn('abbreviateToken: token is 20 characters or fewer — was the right x402 ' +
+            'access token passed? Short/non-JWT tokens are almost always a ' +
+            'misconfiguration and are redacted (not exported).');
+        // Reveal at most 4 chars; for a ≤4-char token reveal nothing, since
+        // token.slice(0, 4) would be the entire value — defeating the redaction.
+        const prefix = token.length > 4 ? token.slice(0, 4) : '';
+        return `${prefix}${SHORT_TOKEN_MARKER}`;
+    }
+    return `${token.slice(0, 16)}…${token.slice(-4)}`;
+}
+/**
+ * Build the `nvm.*` metadata for a verify span. Drops absent values (a key is
+ * omitted, never set to null/undefined). Matches observability-spans-v1 §2.
+ *
+ * `token` is abbreviated/redacted via {@link abbreviateToken} before being
+ * surfaced as `nvm.payment_token` so the full credential never lands in
+ * metadata we control.
+ */
+export function buildVerifyMetadata(input) {
+    const { planIds, scheme, network, agentId, verification, durationMs, token } = input;
+    const md = { 'nvm.plan_ids': [...planIds] };
+    if (scheme)
+        md['nvm.scheme'] = scheme;
+    if (network)
+        md['nvm.network'] = network;
+    if (agentId)
+        md['nvm.agent_id'] = agentId;
+    if (durationMs !== undefined)
+        md['nvm.verify.duration_ms'] = round2(durationMs);
+    const abbreviated = abbreviateToken(token);
+    if (abbreviated)
+        md['nvm.payment_token'] = abbreviated;
+    if (verification) {
+        if (verification.payer)
+            md['nvm.payer'] = verification.payer;
+        if (verification.network && !('nvm.network' in md))
+            md['nvm.network'] = verification.network;
+        if (verification.agentRequestId)
+            md['nvm.agent_request_id'] = verification.agentRequestId;
+    }
+    return md;
+}
+/**
+ * Build the `nvm.*` metadata for a settlement span. Drops absent values.
+ * Matches observability-spans-v1 §3.
+ *
+ * Note the types preserved exactly per the spec: `nvm.credits_redeemed`
+ * (←`creditsRedeemed`) and `nvm.balance.after` (←`remainingBalance`) are
+ * STRINGS — they are not coerced to numbers. `nvm.tx_hash` ← `transaction`.
+ */
+export function buildSettleMetadata(input) {
+    const { settlement, planIds, agentId, durationMs, token } = input;
+    const md = { 'nvm.plan_ids': [...planIds] };
+    if (agentId)
+        md['nvm.agent_id'] = agentId;
+    if (durationMs !== undefined)
+        md['nvm.settle.duration_ms'] = round2(durationMs);
+    const abbreviated = abbreviateToken(token);
+    if (abbreviated)
+        md['nvm.payment_token'] = abbreviated;
+    if (settlement.creditsRedeemed != null)
+        md['nvm.credits_redeemed'] = settlement.creditsRedeemed;
+    if (settlement.remainingBalance != null)
+        md['nvm.balance.after'] = settlement.remainingBalance;
+    if (settlement.transaction)
+        md['nvm.tx_hash'] = settlement.transaction;
+    if (settlement.network)
+        md['nvm.network'] = settlement.network;
+    if (settlement.payer)
+        md['nvm.payer'] = settlement.payer;
+    return md;
+}
+/** Round to 2 decimals, matching Python's `round(value, 2)`. */
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+async function openNvmSpan(name, inputs) {
+    const parent = await activeRunTree();
+    if (!parent)
+        return inactiveSpan();
+    let child;
+    try {
+        child = parent.createChild({ name, run_type: 'tool', inputs });
+    }
+    catch (err) {
+        // span setup is pure observability — never let it disrupt the payment flow
+        console.debug(`nvm-langsmith: createChild(${name}) failed (ignored)`, err);
+        return inactiveSpan();
+    }
+    return {
+        runTree: child,
+        addMetadata(metadata) {
+            addMetadata(child, metadata);
+        },
+        async end(error) {
+            try {
+                await child.end(undefined, error === undefined ? undefined : error instanceof Error ? error.message : String(error));
+                await child.postRun();
+            }
+            catch (err) {
+                // best-effort flush
+                console.debug(`nvm-langsmith: ${name} span flush failed (ignored)`, err);
+            }
+        },
+    };
+}
+function inactiveSpan() {
+    return {
+        runTree: undefined,
+        addMetadata() {
+            /* no-op */
+        },
+        async end() {
+            /* no-op */
+        },
+    };
+}
+/**
+ * Open an `nvm:verify` child span around a verify call. Returns an
+ * {@link NvmSpan} whose `end()` must be called once the verify completes (or
+ * throws). Always safe — a no-op span is returned when tracing is inactive or
+ * `langsmith` is not installed.
+ */
+export async function verifySpan(input) {
+    const { planIds, scheme, network, agentId } = input;
+    const inputs = { plan_ids: [...planIds] };
+    if (scheme)
+        inputs.scheme = scheme;
+    if (network)
+        inputs.network = network;
+    if (agentId)
+        inputs.agent_id = agentId;
+    return openNvmSpan(NVM_VERIFY_SPAN, inputs);
+}
+/**
+ * Open an `nvm:settlement` child span around a settle call. Same semantics as
+ * {@link verifySpan}.
+ */
+export async function settlementSpan(input) {
+    const { planIds, agentId } = input;
+    const inputs = { plan_ids: [...planIds] };
+    if (agentId)
+        inputs.agent_id = agentId;
+    return openNvmSpan(NVM_SETTLEMENT_SPAN, inputs);
+}
+//# sourceMappingURL=spans.js.map

package/dist/x402/langsmith/spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.js","sourceRoot":"","sources":["../../../src/x402/langsmith/spans.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * LangSmith span helpers for Nevermined payment events (TypeScript).\n *\n * TS parity port of `payments_py/langsmith/spans.py`. Emits the cross-SDK\n * `nvm:verify` / `nvm:settlement` spans defined by the\n * **observability-spans-v1** contract\n * (`docs/specs/observability-spans-v1.md` in nvm-monorepo), so a single\n * LangSmith trace can be correlated across the TypeScript and Python SDKs\n * (e.g. filtered on `nvm.tx_hash`).\n *\n * All helpers in this module silently no-op when:\n *   - the optional `langsmith` JS SDK is not installed; or\n *   - no LangSmith run tree is active in the current context (e.g.\n *     `LANGSMITH_TRACING` is unset, or the call is not inside a traced run).\n *\n * Failures inside this module never propagate out — observability is\n * best-effort and must not interfere with the payment flow.\n *\n * `langsmith` is imported **lazily** (dynamic `import()`), so users who only\n * use the `requiresPayment` wrapper without tracing are not forced to install\n * it. Install it yourself (`pnpm add langsmith`) and set `LANGSMITH_TRACING=true`\n * to surface these spans.\n */\n\nimport type { RunTree } from 'langsmith'\nimport type { VerifyPermissionsResult, SettlePermissionsResult } from '../facilitator-api.js'\n\n/** Plain JSON-ish metadata bag attached to a span / run tree. */\nexport type SpanMetadata = Record<string, unknown>\n\n/** Span names — must match observability-spans-v1 exactly (case-sensitive). */\nexport const NVM_VERIFY_SPAN = 'nvm:verify'\nexport const NVM_SETTLEMENT_SPAN = 'nvm:settlement'\n\n/**\n * Marker appended to a redacted short token. The joining character is the\n * single Unicode ellipsis `…` (U+2026), matching the Python implementation\n * and the spec, NOT three ASCII dots. (`…` is one UTF-16 code unit, so this\n * string has length 8.)\n */\nconst SHORT_TOKEN_MARKER = '…(short)'\n\n/**\n * A redacted short token is exactly `<prefix><marker>` where `prefix` is either\n * empty (raw length 4 or fewer) or the first 4 chars (raw length over 4) — so a genuine\n * marker only ever has one of these two lengths. Recognising it by both suffix\n * AND an exact length stops a raw ≤20-char value that merely *ends* in the\n * marker (e.g. `\"x…(short)\"`) from slipping through verbatim.\n */\nconst REDACTED_MARKER_LENGTHS = new Set([SHORT_TOKEN_MARKER.length, 4 + SHORT_TOKEN_MARKER.length])\n\n/** True if `token` is already a value produced by the short-token branch. */\nfunction isRedactedMarker(token: string): boolean {\n  return token.endsWith(SHORT_TOKEN_MARKER) && REDACTED_MARKER_LENGTHS.has(token.length)\n}\n\n/**\n * Cached result of the lazy `langsmith` import.\n *\n * `undefined` = not yet attempted; `null` = attempted and unavailable (so we\n * never retry the dynamic import on every call); otherwise the resolved module\n * surface we use (`getCurrentRunTree`).\n */\ntype LangsmithModule = {\n  getCurrentRunTree: (permitAbsentRunTree: boolean) => RunTree | undefined\n}\nlet cachedLangsmith: LangsmithModule | null | undefined\n\n/** True when the dynamic-import error means the package is simply not installed. */\nfunction isModuleNotFound(err: unknown): boolean {\n  const code = (err as { code?: string } | null)?.code\n  return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND'\n}\n\nasync function loadLangsmith(): Promise<LangsmithModule | null> {\n  if (cachedLangsmith !== undefined) return cachedLangsmith\n  try {\n    // `getCurrentRunTree` is NOT exported from the `langsmith` root entry point —\n    // it lives exclusively at the `langsmith/singletons/traceable` sub-path (true\n    // across every published 0.x). Importing the root and reading\n    // `mod.getCurrentRunTree` always yields `undefined`, which would disable\n    // every span in production while the mocked unit tests stay green. Import the\n    // sub-path directly. (See the un-mocked smoke test in\n    // `langsmith-real-sdk.test.ts`, which fails loudly if this ever moves again.)\n    const mod = (await import('langsmith/singletons/traceable')) as unknown as LangsmithModule\n    if (typeof mod?.getCurrentRunTree === 'function') {\n      cachedLangsmith = mod\n    } else {\n      // Installed but missing the API we rely on — a real, diagnosable problem,\n      // distinct from \"not installed\". Warn once (cached null prevents repeats).\n      cachedLangsmith = null\n      console.warn(\n        'nvm-langsmith: `langsmith` is installed but `langsmith/singletons/traceable` ' +\n          'does not export getCurrentRunTree; Nevermined spans are disabled.',\n      )\n    }\n  } catch (err) {\n    cachedLangsmith = null\n    // \"Not installed\" is the expected optional-peer path → stay silent. Any\n    // other failure (a broken install, a transitive load error) disables all\n    // spans with no other signal, so surface it once.\n    if (!isModuleNotFound(err)) {\n      console.warn('nvm-langsmith: failed to load `langsmith`; spans disabled', err)\n    }\n  }\n  return cachedLangsmith\n}\n\n/**\n * Return the current LangSmith `RunTree`, or `undefined` if none is active or\n * `langsmith` is not installed. Safe to call unconditionally.\n */\nexport async function activeRunTree(): Promise<RunTree | undefined> {\n  const ls = await loadLangsmith()\n  if (ls === null) return undefined\n  try {\n    // `permitAbsentRunTree: true` returns undefined instead of throwing when\n    // there is no active run, mirroring Python's `get_current_run_tree()` used\n    // behind a try/except.\n    return ls.getCurrentRunTree(true)\n  } catch (err) {\n    console.debug('nvm-langsmith: getCurrentRunTree failed (ignored)', err)\n    return undefined\n  }\n}\n\n/**\n * Merge `metadata` into `runTree`, swallowing any error. No-op if `runTree` is\n * absent or `metadata` is empty. Matches Python's `run_tree.add_metadata`.\n *\n * The merge is performed on THIS side of the boundary — we read the existing\n * `extra.metadata`, spread the new keys over it, then assign — rather than\n * relying on the langsmith `RunTree.metadata` setter to merge. In `langsmith@0.7`\n * the setter does merge (`extra.metadata = { ...existing, ...new }`), but that is\n * an implementation detail of `run_trees.js`, not a documented contract: a future\n * release that flips it to plain assignment would silently drop the static\n * `nvm.*` keys attached on the pre-verify pass once the post-verify pass runs.\n * Reading+merging here keeps the double-pass accumulation correct regardless, and\n * mirrors how {@link redactMetadataKeys} already reaches into `extra.metadata`.\n */\nexport function addMetadata(runTree: RunTree | undefined, metadata: SpanMetadata): void {\n  if (!runTree || !metadata || Object.keys(metadata).length === 0) return\n  try {\n    const rt = runTree as unknown as { extra?: Record<string, unknown> }\n    const existing = (rt.extra?.metadata as Record<string, unknown> | undefined) ?? {}\n    runTree.metadata = { ...existing, ...metadata }\n  } catch (err) {\n    // observability hygiene must never disrupt the payment flow\n    console.debug('nvm-langsmith: addMetadata failed (ignored)', err)\n  }\n}\n\n/**\n * Remove `keys` from `runTree`'s metadata in place.\n *\n * LangSmith inherits a parent run's metadata into child runs created via\n * `createChild`, so call this on the PARENT run BEFORE opening any child span\n * whose metadata should not carry the keys. The most common use is stripping\n * the full `payment_token` from the parent tool span's metadata, since the raw\n * access token grants access to the protected tool until it expires.\n *\n * No-op when `runTree` is absent or no keys are provided. Errors are swallowed\n * so observability never disrupts the payment flow — but, unlike the other\n * swallow paths, a failure here is **security-sensitive**: if the parent run\n * tree still holds the raw `payment_token`, that credential rides into the\n * parent tree and the inherited verify/settle child spans. So this path warns\n * (not just debug) to keep the leak diagnosable.\n */\nexport function redactMetadataKeys(runTree: RunTree | undefined, ...keys: string[]): void {\n  if (!runTree || keys.length === 0) return\n  try {\n    const extra = (runTree as unknown as { extra?: Record<string, unknown> }).extra\n    const metadata = extra?.metadata as Record<string, unknown> | undefined\n    if (metadata && typeof metadata === 'object') {\n      for (const key of keys) delete metadata[key]\n    }\n  } catch (err) {\n    console.warn(\n      `nvm-langsmith: failed to redact metadata keys [${keys.join(', ')}] from ` +\n        'the parent run tree — a raw credential may remain in the trace',\n      err,\n    )\n  }\n}\n\n/**\n * Return a short, non-functional reference to a payment token for span\n * metadata. Mirrors `payments_py/langsmith/spans.py::abbreviate_token` and the\n * redaction contract in nvm-monorepo#1746 §4 (short-token hardening from\n * nvm-monorepo#1747, tracked in payments-py PR #217).\n *\n * - `undefined`/empty input → `undefined` (and silent — no token at all is not\n *   a \"wrong token\" mistake).\n * - Already-redacted input (a genuine `<prefix>…(short)` marker) → returned\n *   unchanged and silent, so the helper stays idempotent (the decorator path\n *   abbreviates the same token more than once). A raw value that merely *ends*\n *   in the marker is NOT treated as redacted (see {@link isRedactedMarker}).\n * - A token of length ≤ 20 is almost always a misconfiguration (a plan id, an\n *   opaque handle, etc. passed where the JWT was expected). Because this helper\n *   exists to keep credentials out of a durable trace store, such tokens are\n *   **redacted, not exported**: at most the first 4 chars are revealed (to aid\n *   debugging the misconfig), followed by the `…(short)` marker — and for a\n *   token of 4 chars or fewer **nothing** is revealed (the whole value would\n *   otherwise be the \"prefix\"), so it collapses to just `…(short)`. A warning\n *   is emitted. The full short value never leaves this function.\n * - Otherwise (a normal JWT, more than 20 chars) → `<first 16>…<last 4>`.\n */\nexport function abbreviateToken(token: string | undefined | null): string | undefined {\n  if (!token) return undefined\n  if (isRedactedMarker(token)) {\n    // Already redacted (re-applied on the decorator path); re-slicing would let\n    // the marker drift, so return unchanged and stay silent — the original\n    // short value already triggered the warning.\n    return token\n  }\n  if (token.length <= 20) {\n    console.warn(\n      'abbreviateToken: token is 20 characters or fewer — was the right x402 ' +\n        'access token passed? Short/non-JWT tokens are almost always a ' +\n        'misconfiguration and are redacted (not exported).',\n    )\n    // Reveal at most 4 chars; for a ≤4-char token reveal nothing, since\n    // token.slice(0, 4) would be the entire value — defeating the redaction.\n    const prefix = token.length > 4 ? token.slice(0, 4) : ''\n    return `${prefix}${SHORT_TOKEN_MARKER}`\n  }\n  return `${token.slice(0, 16)}…${token.slice(-4)}`\n}\n\n/** Inputs accepted by {@link buildVerifyMetadata}. */\nexport interface VerifyMetadataInput {\n  planIds: string[]\n  scheme?: string\n  network?: string\n  agentId?: string\n  verification?: VerifyPermissionsResult\n  durationMs?: number\n  token?: string\n}\n\n/**\n * Build the `nvm.*` metadata for a verify span. Drops absent values (a key is\n * omitted, never set to null/undefined). Matches observability-spans-v1 §2.\n *\n * `token` is abbreviated/redacted via {@link abbreviateToken} before being\n * surfaced as `nvm.payment_token` so the full credential never lands in\n * metadata we control.\n */\nexport function buildVerifyMetadata(input: VerifyMetadataInput): SpanMetadata {\n  const { planIds, scheme, network, agentId, verification, durationMs, token } = input\n  const md: SpanMetadata = { 'nvm.plan_ids': [...planIds] }\n  if (scheme) md['nvm.scheme'] = scheme\n  if (network) md['nvm.network'] = network\n  if (agentId) md['nvm.agent_id'] = agentId\n  if (durationMs !== undefined) md['nvm.verify.duration_ms'] = round2(durationMs)\n  const abbreviated = abbreviateToken(token)\n  if (abbreviated) md['nvm.payment_token'] = abbreviated\n  if (verification) {\n    if (verification.payer) md['nvm.payer'] = verification.payer\n    if (verification.network && !('nvm.network' in md)) md['nvm.network'] = verification.network\n    if (verification.agentRequestId) md['nvm.agent_request_id'] = verification.agentRequestId\n  }\n  return md\n}\n\n/** Inputs accepted by {@link buildSettleMetadata}. */\nexport interface SettleMetadataInput {\n  settlement: SettlePermissionsResult\n  planIds: string[]\n  agentId?: string\n  durationMs?: number\n  token?: string\n}\n\n/**\n * Build the `nvm.*` metadata for a settlement span. Drops absent values.\n * Matches observability-spans-v1 §3.\n *\n * Note the types preserved exactly per the spec: `nvm.credits_redeemed`\n * (←`creditsRedeemed`) and `nvm.balance.after` (←`remainingBalance`) are\n * STRINGS — they are not coerced to numbers. `nvm.tx_hash` ← `transaction`.\n */\nexport function buildSettleMetadata(input: SettleMetadataInput): SpanMetadata {\n  const { settlement, planIds, agentId, durationMs, token } = input\n  const md: SpanMetadata = { 'nvm.plan_ids': [...planIds] }\n  if (agentId) md['nvm.agent_id'] = agentId\n  if (durationMs !== undefined) md['nvm.settle.duration_ms'] = round2(durationMs)\n  const abbreviated = abbreviateToken(token)\n  if (abbreviated) md['nvm.payment_token'] = abbreviated\n  if (settlement.creditsRedeemed != null) md['nvm.credits_redeemed'] = settlement.creditsRedeemed\n  if (settlement.remainingBalance != null) md['nvm.balance.after'] = settlement.remainingBalance\n  if (settlement.transaction) md['nvm.tx_hash'] = settlement.transaction\n  if (settlement.network) md['nvm.network'] = settlement.network\n  if (settlement.payer) md['nvm.payer'] = settlement.payer\n  return md\n}\n\n/** Round to 2 decimals, matching Python's `round(value, 2)`. */\nfunction round2(value: number): number {\n  return Math.round(value * 100) / 100\n}\n\n/**\n * An opened Nevermined span. `end()` records `outputs`/`error` and flushes the\n * child run to LangSmith. Always safe to call (no-op when `runTree` is absent).\n */\nexport interface NvmSpan {\n  /** The underlying child `RunTree`, or `undefined` when tracing is inactive. */\n  readonly runTree: RunTree | undefined\n  /** Attach `nvm.*` metadata to this span. */\n  addMetadata(metadata: SpanMetadata): void\n  /** Close the span, flushing it to LangSmith. Optionally record an error. */\n  end(error?: unknown): Promise<void>\n}\n\nasync function openNvmSpan(name: string, inputs: SpanMetadata): Promise<NvmSpan> {\n  const parent = await activeRunTree()\n  if (!parent) return inactiveSpan()\n  let child: RunTree\n  try {\n    child = parent.createChild({ name, run_type: 'tool', inputs })\n  } catch (err) {\n    // span setup is pure observability — never let it disrupt the payment flow\n    console.debug(`nvm-langsmith: createChild(${name}) failed (ignored)`, err)\n    return inactiveSpan()\n  }\n  return {\n    runTree: child,\n    addMetadata(metadata: SpanMetadata) {\n      addMetadata(child, metadata)\n    },\n    async end(error?: unknown) {\n      try {\n        await child.end(\n          undefined,\n          error === undefined ? undefined : error instanceof Error ? error.message : String(error),\n        )\n        await child.postRun()\n      } catch (err) {\n        // best-effort flush\n        console.debug(`nvm-langsmith: ${name} span flush failed (ignored)`, err)\n      }\n    },\n  }\n}\n\nfunction inactiveSpan(): NvmSpan {\n  return {\n    runTree: undefined,\n    addMetadata() {\n      /* no-op */\n    },\n    async end() {\n      /* no-op */\n    },\n  }\n}\n\n/** Inputs accepted by {@link verifySpan}. */\nexport interface VerifySpanInput {\n  planIds: string[]\n  scheme?: string\n  network?: string\n  agentId?: string\n}\n\n/**\n * Open an `nvm:verify` child span around a verify call. Returns an\n * {@link NvmSpan} whose `end()` must be called once the verify completes (or\n * throws). Always safe — a no-op span is returned when tracing is inactive or\n * `langsmith` is not installed.\n */\nexport async function verifySpan(input: VerifySpanInput): Promise<NvmSpan> {\n  const { planIds, scheme, network, agentId } = input\n  const inputs: SpanMetadata = { plan_ids: [...planIds] }\n  if (scheme) inputs.scheme = scheme\n  if (network) inputs.network = network\n  if (agentId) inputs.agent_id = agentId\n  return openNvmSpan(NVM_VERIFY_SPAN, inputs)\n}\n\n/** Inputs accepted by {@link settlementSpan}. */\nexport interface SettlementSpanInput {\n  planIds: string[]\n  agentId?: string\n}\n\n/**\n * Open an `nvm:settlement` child span around a settle call. Same semantics as\n * {@link verifySpan}.\n */\nexport async function settlementSpan(input: SettlementSpanInput): Promise<NvmSpan> {\n  const { planIds, agentId } = input\n  const inputs: SpanMetadata = { plan_ids: [...planIds] }\n  if (agentId) inputs.agent_id = agentId\n  return openNvmSpan(NVM_SETTLEMENT_SPAN, inputs)\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/payments",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Typescript SDK to interact with the Nevermined Payments Protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,6 +35,10 @@
     "./langchain": {
       "types": "./dist/x402/langchain/index.d.ts",
       "import": "./dist/x402/langchain/index.js"
+    },
+    "./langsmith": {
+      "types": "./dist/x402/langsmith/index.d.ts",
+      "import": "./dist/x402/langsmith/index.js"
     }
   },
   "scripts": {
@@ -60,6 +64,7 @@
     "@babel/core": "^7.27.4",
     "@babel/preset-env": "^7.27.2",
     "@google-cloud/aiplatform": "^6.1.0",
+    "@langchain/langgraph": "1.2.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@types/express": "4.17.23",
     "@types/jest": "^29.5.13",
@@ -79,6 +84,7 @@
     "eslint-plugin-tsdoc": "^0.5.2",
     "jest": "^29.7.0",
     "langchain": "^0.3.37",
+    "langsmith": "^0.7.4",
     "openai": "^6.2.0",
     "prettier": "^3.2.5",
     "source-map-support": "^0.5.21",
@@ -92,9 +98,11 @@
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "@langchain/langgraph": ">=1.0.0 <2",
     "@modelcontextprotocol/sdk": ">=1.25.0",
     "express": ">=4.0.0",
-    "@langchain/core": ">=0.3.0"
+    "langsmith": ">=0.7.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
@@ -105,6 +113,12 @@
     },
     "@langchain/core": {
       "optional": true
+    },
+    "@langchain/langgraph": {
+      "optional": true
+    },
+    "langsmith": {
+      "optional": true
     }
   },
   "dependencies": {