@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/observability/telemetry.ts

@@ -0,0 +1,546 @@
+import type {
+  ConnectionMode,
+  WalletError,
+  WalletFlowType,
+  Platform,
+  LogLevel,
+  Namespace,
+  NetworkId,
+  FailureKind,
+  ErrorSource,
+  LifecycleUnavailableReason,
+  Session
+} from '@meshconnect/uwc-types'
+import type { UWCEventName, UWCEventMap, UWCOperation } from '../events'
+import { UWC_CORE_VERSION } from '../version'
+import { scrubMessage } from './scrub'
+
+/**
+ * Telemetry record schema version. Bump on any breaking change to the
+ * `UWCTelemetryEvent` shape so a downstream consumer can branch on it.
+ */
+export const TELEMETRY_SCHEMA_VERSION = 1
+
+/**
+ * Egress bounds for `networkMismatch`. `walletNetworkIds` comes from catalog
+ * wallet metadata (`provider.supportedNetworkIds`), not live wallet input — but
+ * it is unbounded upstream, so cap cardinality and element length here as
+ * defense-in-depth. Elements are NOT scrubbed: a legitimate
+ * `solana:<32-char-base58-ref>` CAIP-2 id would be eaten by the base58 rule.
+ */
+const MAX_NETWORK_MISMATCH_IDS = 20
+const MAX_NETWORK_ID_LENGTH = 64
+
+function capNetworkMismatch(
+  mismatch:
+    | { walletNetworkIds: string[]; configuredNetworkIds: string[] }
+    | undefined
+): { walletNetworkIds: string[]; configuredNetworkIds: string[] } | undefined {
+  if (!mismatch) return undefined
+  const cap = (ids: string[]) =>
+    ids
+      .slice(0, MAX_NETWORK_MISMATCH_IDS)
+      .map(id => id.slice(0, MAX_NETWORK_ID_LENGTH))
+  return {
+    walletNetworkIds: cap(mismatch.walletNetworkIds),
+    configuredNetworkIds: cap(mismatch.configuredNetworkIds)
+  }
+}
+
+/**
+ * A normalized, PII-safe telemetry record derived from a `UWCEventMap` event.
+ *
+ * This is the ONLY shape that reaches `observer.onEvent`. It is the PII boundary:
+ * it has no field for a signing payload, signature, raw transaction, or wallet
+ * address — leaking those is structurally impossible, not merely discouraged.
+ */
+export interface UWCTelemetryEvent {
+  /**
+   * Record schema version — the literal type IS the version this package
+   * emits, so a consumer can branch exhaustively (`event.schemaVersion === 1`)
+   * and gets a compile break when a bump lands. Import the runtime value as
+   * `TELEMETRY_SCHEMA_VERSION`.
+   */
+  schemaVersion: typeof TELEMETRY_SCHEMA_VERSION
+  /**
+   * The `@meshconnect/uwc-core` version that produced the record (generated
+   * from package.json at build time) — aggregate failures per released
+   * version to spot version-specific regressions.
+   */
+  uwcVersion: string
+  /** The originating event name. */
+  name: UWCEventName
+  /** Per-connector-instance id (stamped on every event). */
+  sdkSessionId: string
+  /**
+   * Consumer-supplied correlation id (e.g. their `link_sess_id`), present only
+   * when supplied — never aliased to `sdkSessionId`. Lets UWC events join the
+   * consumer's existing telemetry without a separate mapping.
+   */
+  correlationId?: string | undefined
+  /** ms since epoch when the record was produced. */
+  timestamp: number
+  /** Wallet-boundary op, when the event relates to one. */
+  operation?: UWCOperation | undefined
+  connectionMode?: ConnectionMode | undefined
+  /** CAIP namespace (eip155 | solana | tron | tvm …) — never an address. */
+  namespace?: Namespace | undefined
+  /** CAIP chain id (e.g. `eip155:1`) — never an address. */
+  chainId?: NetworkId | undefined
+  /** Catalog wallet id — never an address. */
+  walletId?: string | undefined
+  /** Correlates a handoff start with its terminal. */
+  handoffId?: string | undefined
+  durationMs?: number | undefined
+  walletFlowType?: WalletFlowType | undefined
+  platform?: Platform | undefined
+  /** A `walletTimedOut` marker fired before the terminal (late completion). */
+  timedOut?: boolean | undefined
+  /** Marker deadline — present on `walletTimedOut` and on a late terminal. */
+  timeoutMs?: number | undefined
+  /** switchNetwork only: target chain was already the active one (no-op switch). */
+  targetAlreadyActive?: boolean | undefined
+  /** Non-success outcomes: stringified error code when reliably known. */
+  errorCode?: string | undefined
+  /** Non-success outcomes: coarse cause bucket. `unknown` when not classifiable. */
+  failureKind?: FailureKind | undefined
+  /** Non-success outcomes: where the error originated, when inferable. */
+  source?: ErrorSource | undefined
+  /**
+   * Connect `no_common_network` failures only: the wallet's advertised vs the
+   * configured CAIP-2 id lists (non-PII). Lets a dashboard show "wallet offered
+   * X, token configured Y" — the diagnosis for the #1 prod connection error.
+   */
+  networkMismatch?:
+    | { walletNetworkIds: string[]; configuredNetworkIds: string[] }
+    | undefined
+  /** Present on failure events. `message` is scrubbed before egress. */
+  error?: WalletError | undefined
+  /** Log level, present only for `name === 'log'`. */
+  level?: LogLevel | undefined
+  /**
+   * Per-chain supported capability names (e.g. `{ 'eip155:8453': ['atomic'] }`),
+   * present only for `capabilitiesUpdated`. Feature flags + chain ids — not PII.
+   */
+  capabilities?: Record<string, string[]> | undefined
+  /**
+   * Per-namespace requested-vs-matched discovery summary, present only on
+   * `walletsDetected`. Counts only — never a wallet id or address.
+   */
+  discovery?: Record<string, { requested: number; matched: number }> | undefined
+  /**
+   * Per-namespace count of the session's available addresses, present on
+   * `connected` / `sessionChanged`. Counts only — never an address.
+   */
+  addressNamespaces?: Record<string, number> | undefined
+  /**
+   * Namespaces the connected wallet supports for this session's configured
+   * networks but returned NO address for — present on `connected` /
+   * `sessionChanged` only when non-empty. A RAW FACT (supported-but-absent), not
+   * an asserted bug: it's the observable symptom of a silently dropped
+   * secondary-namespace gather — e.g. injected-connector's framed-embed skip,
+   * where the wallet supports Solana but the session has zero Solana addresses.
+   * The consumer interprets it (link-v2 deposit ⇒ lost holdings; a single-
+   * namespace deposit ⇒ intended). Pairs with `discovery` for the full picture.
+   */
+  missingNamespaces?: string[] | undefined
+  /** `lifecycleTelemetryUnavailable` only: why lifecycle telemetry couldn't attach. */
+  reason?: LifecycleUnavailableReason | undefined
+  /** `lifecycleTelemetryUnavailable` only: direct page vs production iframe. */
+  runtime?: 'direct' | 'iframe' | undefined
+  /**
+   * `error` only: a handoff terminal already reported this failure — this
+   * record is the back-compat duplicate. Count terminals + `error` where NOT
+   * handoffCovered to avoid double-counting.
+   */
+  handoffCovered?: boolean | undefined
+}
+
+/**
+ * Vendor-agnostic telemetry sink. Consumers implement; UWC ships no vendor SDK.
+ * Both methods are optional and called best-effort (throws are swallowed upstream).
+ *
+ * CONTRACT — both methods are invoked **synchronously on the wallet-operation
+ * path**. A terminal event (e.g. `walletSucceeded`) fires between the wallet
+ * returning a result and that result reaching the caller, so a slow handler adds
+ * latency to connect / sign / sendTransaction. Keep handlers **non-blocking**:
+ * hand off to a queue-backed sink (Datadog `addAction`, Segment `track`, etc. are
+ * already non-blocking) or defer heavy work yourself — e.g.
+ * `onEvent: e => queueMicrotask(() => doHeavyWork(e))`. Do not perform synchronous
+ * network/IO or expensive serialization inline.
+ */
+export interface UWCObserver {
+  /** A normalized, PII-safe event. Forward to Datadog / Amplitude / Segment / … (non-blocking). */
+  onEvent?(event: UWCTelemetryEvent): void
+  /** A log line (all levels). `args` is already scrubbed. Keep non-blocking. */
+  onLog?(level: LogLevel, message: string, args: unknown[]): void
+}
+
+/**
+ * Best-effort coarse runtime surface. HEURISTIC — user agents lie and in-app
+ * browsers are hard to detect; treat `webview` as a hint, not a guarantee.
+ * Never returns the raw UA (PII / high-cardinality).
+ */
+export function derivePlatform(): Platform {
+  if (typeof navigator === 'undefined' || !navigator.userAgent) return 'unknown'
+  const ua = navigator.userAgent
+  const isIOS = /iPhone|iPad|iPod/i.test(ua)
+  const isAndroid = /Android/i.test(ua)
+  // Android in-app browsers tag the UA with `; wv`; iOS WKWebViews lack `Safari`.
+  const isWebview =
+    (isAndroid && /; wv\)/i.test(ua)) || (isIOS && !/Safari/i.test(ua))
+  if (isWebview) return 'webview'
+  if (isIOS || isAndroid) return 'mobile'
+  return 'desktop'
+}
+
+/**
+ * Derive the flow taxonomy from connection mode + surface. HEURISTIC — UWC does
+ * not always know whether a WalletConnect handoff used a deeplink vs a QR scan;
+ * we infer from the platform (mobile ⇒ deeplink, desktop ⇒ QR), matching link-v2's
+ * historical intent. Consumers with better context may override downstream.
+ */
+export function deriveWalletFlowType(
+  connectionMode: ConnectionMode,
+  platform: Platform
+): WalletFlowType {
+  const isDesktop = platform === 'desktop'
+  switch (connectionMode) {
+    case 'injected':
+      // Injected on a phone almost always means we're inside a wallet's browser.
+      return isDesktop ? 'browser_extension_flow' : 'in_wallet_browser_flow'
+    case 'walletConnect':
+      return isDesktop
+        ? 'wallet_connect_qr_flow'
+        : 'wallet_connect_deep_link_flow'
+    case 'tonConnect':
+      return isDesktop ? 'ton_connect_qr_flow' : 'ton_connect_deep_link_flow'
+    default:
+      return 'unknown'
+  }
+}
+
+/**
+ * Per-namespace address coverage for a session — telemetry-only, non-PII
+ * (namespace names + counts, never an address). Derived purely from the session:
+ * `availableNetworks` is the connected wallet's supported networks already
+ * filtered to the session's configured set, and `availableAddresses` is what the
+ * connect actually gathered, so `missing` is precise per-connect (no cross-wallet
+ * discovery join that could false-positive on a different installed wallet).
+ *
+ * `missing` is the observable symptom of a dropped secondary-namespace gather:
+ * the wallet supports the namespace for a configured network, but no address for
+ * it came back.
+ */
+function summarizeAddressCoverage(session: Session): {
+  addressNamespaces: Record<string, number>
+  missing: string[]
+} {
+  // Defensive `?? []`: this runs on the wallet path, so a partial/malformed
+  // session must never throw here (a real session always has both arrays).
+  const addressNamespaces: Record<string, number> = {}
+  const present = new Set<string>()
+  for (const { networkId } of session.availableAddresses ?? []) {
+    const namespace = networkId.split(':')[0]
+    if (!namespace) continue
+    present.add(namespace)
+    addressNamespaces[namespace] = (addressNamespaces[namespace] ?? 0) + 1
+  }
+  const supported = new Set(
+    (session.availableNetworks ?? []).map(n => n.namespace)
+  )
+  const missing = [...supported].filter(namespace => !present.has(namespace))
+  return { addressNamespaces, missing }
+}
+
+/**
+ * Map a raw `UWCEventMap` event to its PII-safe `UWCTelemetryEvent`.
+ *
+ * Per-event allow-listing: only known-safe fields are copied. Payloads carrying a
+ * `Session`/`Network` (which include the wallet address) are reduced to
+ * `namespace` + `chainId` + `walletId`. Unknown/noisy payloads collapse to just
+ * the name. `error.message` is scrubbed.
+ */
+function buildTelemetryEvent<K extends UWCEventName>(
+  name: K,
+  data: UWCEventMap[K],
+  sdkSessionId: string,
+  now: number,
+  correlationId?: string
+): UWCTelemetryEvent {
+  // `correlationId` is added to the key only when supplied — never aliased to
+  // `sdkSessionId`, so a consumer can tell "I gave no id" from "id == session".
+  const base: UWCTelemetryEvent = {
+    schemaVersion: TELEMETRY_SCHEMA_VERSION,
+    uwcVersion: UWC_CORE_VERSION,
+    name,
+    sdkSessionId,
+    timestamp: now,
+    ...(correlationId !== undefined ? { correlationId } : {})
+  }
+
+  switch (name) {
+    case 'connecting': {
+      const d = data as UWCEventMap['connecting']
+      return {
+        ...base,
+        operation: 'connect',
+        connectionMode: d.connectionMode,
+        walletId: d.walletId
+      }
+    }
+    case 'connected':
+    case 'sessionChanged': {
+      const d = data as UWCEventMap['connected']
+      const session = d.session
+      const { addressNamespaces, missing } = summarizeAddressCoverage(session)
+      return {
+        ...base,
+        connectionMode: session.connectionMode ?? undefined,
+        namespace: session.activeNetwork?.namespace,
+        chainId: session.activeNetwork?.id,
+        walletId: session.activeWallet?.id,
+        addressNamespaces,
+        ...(missing.length > 0 && { missingNamespaces: missing })
+      }
+    }
+    case 'networkSwitched': {
+      const d = data as UWCEventMap['networkSwitched']
+      return {
+        ...base,
+        operation: 'switchNetwork',
+        namespace: d.network.namespace,
+        chainId: d.network.id
+      }
+    }
+    case 'connectionUri': {
+      // Carry the mode but NEVER the URI itself (a relay/pairing string).
+      const d = data as UWCEventMap['connectionUri']
+      return { ...base, connectionMode: d.connectionMode }
+    }
+    case 'error': {
+      const d = data as UWCEventMap['error']
+      return {
+        ...base,
+        operation: d.operation,
+        error: { type: d.error.type, message: scrubMessage(d.error.message) },
+        // Telemetry-only classification — undefined for ordinary errors, set for
+        // pre-wallet validation failures (e.g. no_common_network) that never
+        // reach the handoff funnel.
+        errorCode: d.errorCode,
+        failureKind: d.failureKind,
+        source: d.source,
+        networkMismatch: capNetworkMismatch(d.networkMismatch),
+        handoffCovered: d.handoffCovered
+      }
+    }
+    case 'awaitingWallet': {
+      const d = data as UWCEventMap['awaitingWallet']
+      return {
+        ...base,
+        operation: d.operation,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId,
+        handoffId: d.handoffId,
+        walletFlowType: d.walletFlowType,
+        platform: d.platform,
+        targetAlreadyActive: d.targetAlreadyActive
+      }
+    }
+    case 'walletSucceeded': {
+      const d = data as UWCEventMap['walletSucceeded']
+      return {
+        ...base,
+        operation: d.operation,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId,
+        handoffId: d.handoffId,
+        durationMs: d.durationMs,
+        timedOut: d.timedOut,
+        timeoutMs: d.timeoutMs,
+        targetAlreadyActive: d.targetAlreadyActive
+      }
+    }
+    case 'walletRejected': {
+      const d = data as UWCEventMap['walletRejected']
+      return {
+        ...base,
+        operation: d.operation,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId,
+        handoffId: d.handoffId,
+        durationMs: d.durationMs,
+        timedOut: d.timedOut,
+        timeoutMs: d.timeoutMs,
+        targetAlreadyActive: d.targetAlreadyActive,
+        errorCode: d.errorCode,
+        failureKind: d.failureKind,
+        source: d.source
+      }
+    }
+    case 'walletTimedOut': {
+      const d = data as UWCEventMap['walletTimedOut']
+      return {
+        ...base,
+        operation: d.operation,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId,
+        handoffId: d.handoffId,
+        durationMs: d.durationMs,
+        timeoutMs: d.timeoutMs,
+        targetAlreadyActive: d.targetAlreadyActive
+      }
+    }
+    case 'walletFailed': {
+      const d = data as UWCEventMap['walletFailed']
+      return {
+        ...base,
+        operation: d.operation,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId,
+        handoffId: d.handoffId,
+        durationMs: d.durationMs,
+        timedOut: d.timedOut,
+        timeoutMs: d.timeoutMs,
+        targetAlreadyActive: d.targetAlreadyActive,
+        errorCode: d.errorCode,
+        failureKind: d.failureKind,
+        source: d.source,
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+      }
+    }
+    case 'capabilitiesUpdated': {
+      const d = data as UWCEventMap['capabilitiesUpdated']
+      // Summarize to per-chain lists of the capability names that are not
+      // 'unsupported'. Compact + non-PII (chain ids + bounded feature names).
+      const capabilities: Record<string, string[]> = {}
+      for (const [chainId, caps] of Object.entries(d.capabilities)) {
+        const enabled = Object.entries(caps)
+          .filter(([, cap]) => cap && cap.status !== 'unsupported')
+          .map(([feature]) => feature)
+        if (enabled.length > 0) capabilities[chainId] = enabled
+      }
+      return { ...base, capabilities }
+    }
+    case 'walletsDetected': {
+      const d = data as UWCEventMap['walletsDetected']
+      // Carry only the compact requested-vs-matched summary; never the wallet list.
+      return { ...base, ...(d.discovery ? { discovery: d.discovery } : {}) }
+    }
+    case 'walletDiscoveryFailed': {
+      const d = data as UWCEventMap['walletDiscoveryFailed']
+      return {
+        ...base,
+        connectionMode: d.connectionMode,
+        namespace: d.namespace,
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+      }
+    }
+    case 'pageHiddenDuringHandoff':
+    case 'pageVisibleDuringHandoff': {
+      const d = data as UWCEventMap['pageHiddenDuringHandoff']
+      return { ...base, handoffId: d.handoffId, platform: d.platform }
+    }
+    case 'bridgeError': {
+      const d = data as UWCEventMap['bridgeError']
+      return {
+        ...base,
+        namespace: d.namespace,
+        source: 'bridge',
+        failureKind: 'bridge_error',
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+      }
+    }
+    case 'relayError': {
+      const d = data as UWCEventMap['relayError']
+      // A relay-socket transport failure (WalletConnect only). The scrubbed message
+      // carries the diagnostic detail (e.g. "code: 3000 (JWT ... not yet valid)").
+      return {
+        ...base,
+        connectionMode: 'walletConnect',
+        source: 'provider',
+        failureKind: 'network_error',
+        error: { type: d.error.type, message: scrubMessage(d.error.message) }
+      }
+    }
+    case 'walletAccountChanged':
+    case 'walletDisconnected':
+    case 'walletSessionExpired': {
+      const d = data as UWCEventMap['walletAccountChanged']
+      return {
+        ...base,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace
+      }
+    }
+    case 'walletChainChanged': {
+      const d = data as UWCEventMap['walletChainChanged']
+      return {
+        ...base,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        chainId: d.chainId
+      }
+    }
+    case 'lifecycleTelemetryUnavailable': {
+      const d = data as UWCEventMap['lifecycleTelemetryUnavailable']
+      return {
+        ...base,
+        connectionMode: d.connectionMode,
+        walletId: d.walletId,
+        namespace: d.namespace,
+        reason: d.reason,
+        runtime: d.runtime
+      }
+    }
+    default:
+      // ready / disconnected / networkSwitching / change / log — name only
+      // (log goes via onLog).
+      return base
+  }
+}
+
+/**
+ * Drop keys whose value is `undefined` so a record never carries a
+ * present-but-undefined optional (e.g. `errorCode: undefined` on a non-error
+ * event), which would make `'errorCode' in event` misleading. Shallow by design:
+ * nested objects (`error`, `networkMismatch`, `discovery`, `capabilities`,
+ * `addressNamespaces`) are only ever built with defined values.
+ */
+function compactUndefined(event: UWCTelemetryEvent): UWCTelemetryEvent {
+  const record = event as unknown as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(record)) {
+    const value = record[key]
+    if (value !== undefined) out[key] = value
+  }
+  return out as unknown as UWCTelemetryEvent
+}
+
+/**
+ * Normalize a bus event into a PII-safe `UWCTelemetryEvent`, dropping undefined
+ * optionals so the emitted shape is consistent across event kinds.
+ */
+export function normalizeEvent<K extends UWCEventName>(
+  name: K,
+  data: UWCEventMap[K],
+  sdkSessionId: string,
+  now: number,
+  correlationId?: string
+): UWCTelemetryEvent {
+  return compactUndefined(
+    buildTelemetryEvent(name, data, sdkSessionId, now, correlationId)
+  )
+}