@dvmkit/sdk 0.6.0-rc.1 → 0.7.0-rc.2

package/README.md

@@ -98,6 +98,8 @@ The public [SDK guide](https://dvmkit.com/docs/sdk) covers signed requests, cust
 
 ## Diagnostic retention
 
+[Payment diagnostics](./docs/DIAGNOSTICS.md) documents the closed failure categories, stages, and top-up causes retained by safe logging sinks.
+
 The SDK advertises 730 days of retention for sanitized diagnostics in every existing span dataset: `platform`, `cashu`, `lightning`, `stripe`, `x402`, `tempo`, `isolate`, `audit`, and `cron`. Dataset names, producer permissions, and query semantics remain unchanged; only operator services may write to `audit`.
 
 This metadata describes the retention schedule. The SDK does not automatically delete diagnostics or override platform destruction or case controls. The platform must enforce the schedule and those controls.

package/dist/{chunk-PLG4XER6.js → chunk-26W6GPCD.js}

@@ -1,9 +1,34 @@
 import {
   X402_DEFAULT_FACILITATOR
-} from "./chunk-IWQHUSMO.js";
+} from "./chunk-62FI3NJF.js";
 import {
   callerLoggers
-} from "./chunk-66HGCPBU.js";
+} from "./chunk-KXWROQGK.js";
+import {
+  diagnosticConsole
+} from "./chunk-LAKP6FUI.js";
+
+// src/observability/payment-diagnostics.ts
+import { AsyncLocalStorage } from "async_hooks";
+var scopes = new AsyncLocalStorage();
+function withPaymentDiagnostics(fn) {
+  return scopes.run({}, fn);
+}
+async function withPaymentStage(stage, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    const scope = scopes.getStore();
+    if (scope && (!scope.failure || !Object.is(scope.failure.error, error))) {
+      scope.failure = { error, stage };
+    }
+    throw error;
+  }
+}
+function paymentFailureStage(error) {
+  const failure = scopes.getStore()?.failure;
+  return failure && Object.is(failure.error, error) ? failure.stage : "unknown";
+}
 
 // src/lib/x402/facilitator.ts
 import { createPrivateKey, randomBytes } from "crypto";
@@ -82,7 +107,7 @@ async function verifyWithFacilitator(payload, requirements, config = {}, createA
   return callerLoggers.x402.span(
     "x402.verify_with_facilitator",
     { facilitator_url: url },
-    async () => {
+    () => withPaymentStage("verifier", async () => {
       const authHeaders = (await createAuthHeaders?.())?.verify ?? {};
       const res = await fetch(url, {
         method: "POST",
@@ -96,14 +121,17 @@ async function verifyWithFacilitator(payload, requirements, config = {}, createA
       if (!res.ok) {
         const rejection = await readFacilitatorRejection(res);
         if (rejection?.isValid === false && typeof rejection.invalidReason === "string" && rejection.invalidReason.length > 0) {
+          logRejected("verifier");
           return rejection;
         }
+        logRejected("verifier");
         return { isValid: false, invalidReason: `facilitator_status_${res.status}` };
       }
       const data = await res.json();
+      if (!data.isValid) logRejected("verifier");
       callerLoggers.x402.info("x402.verify_with_facilitator.result", { is_valid: data.isValid });
       return data;
-    }
+    })
   );
 }
 async function settleWithFacilitator(payload, requirements, config = {}, createAuthHeaders = createX402FacilitatorAuthHeaders(config)) {
@@ -112,7 +140,7 @@ async function settleWithFacilitator(payload, requirements, config = {}, createA
   return callerLoggers.x402.span(
     "x402.settle_with_facilitator",
     { facilitator_url: url },
-    async () => {
+    () => withPaymentStage("broadcast", async () => {
       const authHeaders = (await createAuthHeaders?.())?.settle ?? {};
       const res = await fetch(url, {
         method: "POST",
@@ -126,17 +154,20 @@ async function settleWithFacilitator(payload, requirements, config = {}, createA
       if (!res.ok) {
         const rejection = await readFacilitatorRejection(res);
         if (rejection?.success === false && typeof rejection.errorReason === "string" && rejection.errorReason.length > 0) {
+          logRejected("broadcast");
           return rejection;
         }
+        logRejected("broadcast");
         return { success: false, errorReason: `facilitator_status_${res.status}` };
       }
       const data = await res.json();
+      if (!data.success) logRejected("broadcast");
       callerLoggers.x402.info("x402.settle_with_facilitator.result", {
         success: data.success,
         tx_hash: data.transaction
       });
       return data;
-    }
+    })
   );
 }
 async function readFacilitatorRejection(res) {
@@ -151,8 +182,19 @@ async function readFacilitatorRejection(res) {
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function logRejected(stage) {
+  diagnosticConsole.warn({
+    event: "x402_credential_rejected",
+    rail: "x402",
+    failure_category: stage === "verifier" ? "verification_failed" : "settlement_failed",
+    failure_stage: stage
+  });
+}
 
 export {
+  withPaymentDiagnostics,
+  withPaymentStage,
+  paymentFailureStage,
   createX402FacilitatorAuthHeaders,
   createX402FacilitatorClient,
   verifyWithFacilitator,

package/dist/{chunk-FI4CST2D.js → chunk-2OM2QPBE.js}

@@ -1,10 +1,10 @@
 import {
   callerLoggers
-} from "./chunk-66HGCPBU.js";
+} from "./chunk-KXWROQGK.js";
 import {
   diagnosticConsole,
   projectSpanRow
-} from "./chunk-ETXDTUJO.js";
+} from "./chunk-LAKP6FUI.js";
 
 // src/lib/x402/env.ts
 import { isAddress } from "viem";
@@ -388,12 +388,6 @@ var HttpTransport = class {
   }
 };
 
-// src/lib/nwc.ts
-import { decrypt, encrypt } from "nostr-tools/nip04";
-import { SimplePool, useWebSocketImplementation } from "nostr-tools/pool";
-import { finalizeEvent, getPublicKey } from "nostr-tools/pure";
-import WebSocket from "ws";
-
 // src/lib/hash.ts
 import { createHash } from "crypto";
 function sha256hex(input) {
@@ -401,6 +395,10 @@ function sha256hex(input) {
 }
 
 // src/lib/nwc.ts
+import { decrypt, encrypt } from "nostr-tools/nip04";
+import { SimplePool, useWebSocketImplementation } from "nostr-tools/pool";
+import { finalizeEvent, getPublicKey } from "nostr-tools/pure";
+import WebSocket from "ws";
 var webSocketImplementationConfigured = false;
 function ensureWebSocketImplementation() {
   if (webSocketImplementationConfigured) return;

package/dist/{chunk-IWQHUSMO.js → chunk-62FI3NJF.js}

@@ -1,7 +1,7 @@
 import {
   x402NetworkByCaip2,
   x402NetworkBySlug
-} from "./chunk-RLTSCKRI.js";
+} from "./chunk-BPYMEMQX.js";
 
 // src/lib/x402/constants.ts
 var X402_DEFAULT_FACILITATOR = "https://x402.org/facilitator";
@@ -204,6 +204,73 @@ function isOptionalRecord(value) {
   return value === void 0 || value === null || isRecord(value);
 }
 
+// src/lib/payment-amounts.ts
+function msatsToUsd(msats, rate) {
+  return msats / 1e11 * rate;
+}
+function usdToMsats(usd, rate) {
+  return Math.round(usd / rate * 1e11);
+}
+function msatsToUsdCents(msats, btcPriceUsd) {
+  const usd = msatsToUsd(msats, btcPriceUsd);
+  return Math.round(usd * 100);
+}
+function msatsToUsdc(msats, btcUsdRate) {
+  if (!Number.isSafeInteger(msats) || msats < 0) {
+    throw new RangeError("msats must be a non-negative safe integer");
+  }
+  if (!Number.isFinite(btcUsdRate) || btcUsdRate <= 0) {
+    throw new RangeError("BTC/USD rate must be finite and positive");
+  }
+  const [mantissa, exponent = "0"] = btcUsdRate.toString().split("e");
+  const decimalPlaces = mantissa.split(".")[1]?.length ?? 0;
+  const shift = Number(exponent) - decimalPlaces;
+  let numerator = BigInt(msats) * BigInt(mantissa.replace(".", ""));
+  let denominator = 100000n;
+  if (shift > 0) numerator *= 10n ** BigInt(shift);
+  else if (shift < 0) denominator *= 10n ** BigInt(-shift);
+  const micro = (numerator + denominator - 1n) / denominator;
+  if (micro > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError("USDC micro-unit amount exceeds the safe integer range");
+  }
+  return Number(micro);
+}
+function usdcToMsats(usdc, btcUsdRate) {
+  return usdToMsats(usdc, btcUsdRate);
+}
+function msatsToMicro(msats, btcRate) {
+  return Math.round(msatsToUsd(msats, btcRate) * 1e6);
+}
+function microToSats(micro, btcRate) {
+  return Math.ceil(usdToMsats(micro / 1e6, btcRate) / 1e3);
+}
+
+// src/lib/payment-rails/rpc.ts
+function resolveRpcOverride(envValue, bundled) {
+  const override = envValue?.trim() ?? "";
+  return override.length > 0 ? { url: override, source: "override" } : { url: bundled, source: "bundled" };
+}
+function resolveRpcHttpTransportOptions(source, envValue) {
+  if (source !== "override" || !envValue?.trim()) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(envValue);
+  } catch {
+    throw new Error("RPC headers must be a JSON object of non-empty string values.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("RPC headers must be a JSON object of non-empty string values.");
+  const headers = {};
+  for (const [name, value] of Object.entries(parsed)) {
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || typeof value !== "string" || value.length === 0 || /[\r\n]/.test(value))
+      throw new Error("RPC headers must be a JSON object of non-empty string values.");
+    headers[name] = value;
+  }
+  if (Object.keys(headers).length === 0)
+    throw new Error("RPC headers must be a JSON object of non-empty string values.");
+  return { fetchOptions: { headers } };
+}
+
 export {
   X402_DEFAULT_FACILITATOR,
   X402_VERSION,
@@ -226,5 +293,14 @@ export {
   encodePaymentRequiredHeader,
   decodePaymentRequiredHeader,
   exactEvmAuthorization,
-  encodeSettleResponseHeader
+  encodeSettleResponseHeader,
+  msatsToUsd,
+  usdToMsats,
+  msatsToUsdCents,
+  msatsToUsdc,
+  usdcToMsats,
+  msatsToMicro,
+  microToSats,
+  resolveRpcOverride,
+  resolveRpcHttpTransportOptions
 };

package/dist/{chunk-VHNPVGSA.js → chunk-6STC5TCP.js}

@@ -1,9 +1,9 @@
+import {
+  diagnosticConsole
+} from "./chunk-LAKP6FUI.js";
 import {
   withSdkInitLock
 } from "./chunk-COYKJRMM.js";
-import {
-  diagnosticConsole
-} from "./chunk-ETXDTUJO.js";
 
 // src/sdk/server/postgres-replay-store.ts
 var DEFAULT_TABLE_NAME = "signed_request_replays";

package/dist/{chunk-N5RZ5HVB.js → chunk-72V5DTEC.js}

@@ -4,10 +4,10 @@ import {
   signedRequestHeaderMatchesDomain,
   signedRequestStatementHeader,
   testOnlySignedRequestDomain
-} from "./chunk-RCM3P2HE.js";
+} from "./chunk-UKD3R2KU.js";
 import {
   diagnosticConsole
-} from "./chunk-ETXDTUJO.js";
+} from "./chunk-LAKP6FUI.js";
 
 // src/sdk/server/zod-error.ts
 function humanizeZodError(err, opts) {

package/dist/chunk-A262WVYX.js

@@ -0,0 +1,6 @@
+// src/lib/wire-schema.ts
+var CAPABILITY_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export {
+  CAPABILITY_NAME_RE
+};