@meshconnect/uwc-core 1.0.3 → 1.1.0

package/dist/observability/lifecycle-bridge.js

@@ -0,0 +1,155 @@
+/**
+ * Hard ceiling on lifecycle emissions per attachment. Every other telemetry
+ * sink this layer added is bounded (relay / bridge / observer-error dedup sets
+ * cap at 100); a provider looping `chainChanged`/`accountsChanged` must not be
+ * the one unbounded path to the observer. A legitimate session stays far below
+ * this; a storming provider goes silent instead of driving egress cost.
+ */
+export const MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT = 100;
+/**
+ * Bridge a connector's PII-safe `WalletLifecycleEvent` stream onto the event bus
+ * as `walletAccountChanged` / `walletChainChanged` / `walletDisconnected` /
+ * `walletSessionExpired`.
+ *
+ * Two correctness concerns are handled here:
+ *  - **Echo suppression.** When UWC drives a `switchNetwork`, the wallet emits its
+ *    own `chainChanged` for the same chain — that's already captured by UWC's
+ *    `networkSwitched` / the switch handoff, so re-emitting it as a wallet-
+ *    initiated `walletChainChanged` would double-count. We watch the bus for
+ *    `networkSwitched` and drop a matching `chainChanged` inside `echoWindowMs`.
+ *  - **Availability is signal.** If the connector can't observe lifecycle, we emit
+ *    `lifecycleTelemetryUnavailable` ONCE so a dashboard can tell "silent" from
+ *    "unwired".
+ *
+ * @returns a teardown that removes the connector subscription AND the bus watcher.
+ */
+export function attachLifecycle(opts) {
+    const { eventManager, subscribe, getRouting } = opts;
+    const runtime = opts.runtime ?? 'direct';
+    const now = opts.now ?? Date.now;
+    const echoWindowMs = opts.echoWindowMs ?? 3000;
+    const emitUnavailable = (reason) => eventManager.emit('lifecycleTelemetryUnavailable', {
+        reason,
+        connectionMode: opts.connectionMode,
+        namespace: opts.namespace,
+        walletId: opts.walletId,
+        runtime
+    });
+    if (!subscribe) {
+        // In the production iframe the injected subscription is deliberately not
+        // attempted (the provider is a Comlink proxy) — the BRIDGE, not the connector,
+        // is why lifecycle is unobservable. On the direct page, a connector with no
+        // `onLifecycleEvent` simply has no lifecycle support for this namespace yet.
+        emitUnavailable(runtime === 'iframe'
+            ? 'bridge_subscription_unavailable'
+            : 'unsupported_namespace');
+        return () => { };
+    }
+    // Record UWC-initiated switches so the wallet's chainChanged echo can be
+    // dropped. Armed from BOTH signals: `awaitingWallet` (operation switchNetwork)
+    // arms at the handoff START, because some providers emit their chainChanged
+    // BEFORE the switch request resolves — i.e. before `networkSwitched` exists —
+    // and `networkSwitched` re-arms at completion for the late-echo case. The
+    // re-arm means one extra suppression window can follow an early echo; the
+    // only event it could swallow is a sub-window user re-switch to the chain
+    // that just became active — accepted over double-counting every early echo.
+    let lastSwitch = opts.initialSwitch;
+    const offAwaiting = eventManager.on('awaitingWallet', data => {
+        if (data.operation === 'switchNetwork' && data.chainId !== undefined) {
+            lastSwitch = { chainId: data.chainId, at: now() };
+        }
+    });
+    const offSwitched = eventManager.on('networkSwitched', data => {
+        lastSwitch = { chainId: data.network.id, at: now() };
+    });
+    const detachBusWatchers = () => {
+        offAwaiting();
+        offSwitched();
+    };
+    // Defense-in-depth: a connector whose subscribe THROWS (e.g. a provider whose
+    // `.on` rejects an un-proxied handler across the iframe bridge) must degrade to
+    // "unavailable", never break the connect path that called us.
+    let unsub;
+    // Emission budget for THIS attachment — suppressed echoes don't spend it.
+    let emitted = 0;
+    let capNotified = false;
+    try {
+        unsub = subscribe(e => {
+            // The whole body is guarded: wallet SDKs dispatch their listeners
+            // unguarded (e.g. TonConnect's bare `forEach`), so a throw here — from
+            // `getRouting()` or any future edit — would abort delivery to the
+            // wallet's OWN later subscribers, including one resolving a pending
+            // connect. Telemetry must never do that.
+            try {
+                if (emitted >= MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT) {
+                    // Mark the trip ONCE — a silent cap would be indistinguishable from a
+                    // provider that simply went quiet.
+                    if (!capNotified) {
+                        capNotified = true;
+                        emitUnavailable('emission_cap');
+                    }
+                    return;
+                }
+                const routing = getRouting();
+                switch (e.type) {
+                    case 'accountChanged':
+                        emitted++;
+                        eventManager.emit('walletAccountChanged', routing);
+                        return;
+                    case 'chainChanged': {
+                        const isEcho = !!lastSwitch &&
+                            e.chainId !== undefined &&
+                            lastSwitch.chainId === e.chainId &&
+                            now() - lastSwitch.at <= echoWindowMs;
+                        if (isEcho) {
+                            // Consume the echo: a UWC switch produces exactly one wallet echo, so
+                            // a LATER chainChanged to the same chain inside the window is a genuine
+                            // user-initiated switch-back and must not be suppressed.
+                            lastSwitch = undefined;
+                            return;
+                        }
+                        emitted++;
+                        eventManager.emit('walletChainChanged', {
+                            ...routing,
+                            ...(e.chainId !== undefined ? { chainId: e.chainId } : {})
+                        });
+                        return;
+                    }
+                    case 'disconnect':
+                        emitted++;
+                        eventManager.emit('walletDisconnected', routing);
+                        return;
+                    case 'sessionExpired':
+                        emitted++;
+                        eventManager.emit('walletSessionExpired', routing);
+                        return;
+                }
+            }
+            catch {
+                // Swallowed: better to drop one lifecycle record than to break the
+                // wallet's event dispatch.
+            }
+        });
+    }
+    catch {
+        unsub = undefined;
+    }
+    // The connector accepted the subscribe call but this session has no observable
+    // surface (returned undefined) or threw — treat as "unavailable" and don't
+    // leave the bus watchers attached.
+    if (!unsub) {
+        detachBusWatchers();
+        // `onLifecycleEvent` ran but exposed no live subscription surface for this
+        // session (returned undefined or threw). Over the bridge, that absence is the
+        // bridge's doing, not the provider's.
+        emitUnavailable(runtime === 'iframe'
+            ? 'bridge_subscription_unavailable'
+            : 'provider_subscription_unavailable');
+        return () => { };
+    }
+    return () => {
+        detachBusWatchers();
+        unsub();
+    };
+}
+//# sourceMappingURL=lifecycle-bridge.js.map

package/dist/observability/lifecycle-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-bridge.js","sourceRoot":"","sources":["../../src/observability/lifecycle-bridge.ts"],"names":[],"mappings":"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"}

package/dist/observability/scrub.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PII / secret scrubber for data leaving UWC through the observer seam.
+ *
+ * Security-first: the normalized `UWCTelemetryEvent` excludes signing payloads
+ * and addresses by construction — its STRUCTURED fields have no slot for them
+ * (§ telemetry.ts). This scrubber is the second line of defence for the two
+ * surfaces that CAN still carry free-form data on the observer path: the
+ * `WalletError.message` forwarded to `observer.onEvent`, and the `args` forwarded
+ * to `observer.onLog`. (The console / custom-logger sink receives raw data — it's
+ * local, not egress.)
+ *
+ * Two detection layers:
+ *  - KEY-based redaction of sensitive object keys — substring match (not regex),
+ *    avoiding the ReDoS class that Wiz flags on user-input regexes.
+ *  - CONTENT-based redaction of secrets embedded in free-form strings (hex blobs,
+ *    secret k/v params, bearer tokens) — via linear regexes with no nested or
+ *    overlapping quantifiers (see SECRET_CONTENT_PATTERNS), so they carry no
+ *    catastrophic-backtracking risk.
+ */
+/**
+ * Recursively copy `value`, redacting sensitive object-keys, capping long
+ * strings, and rendering non-serializable values inert. The returned objects use
+ * a null prototype so a malicious `__proto__`/`constructor` key in attacker-shaped
+ * input can't pollute `Object.prototype` downstream.
+ */
+export declare function scrubValue(value: unknown, depth?: number): unknown;
+/** Scrub a free-form error message (string in → capped string out). */
+export declare function scrubMessage(message: string): string;
+/** Scrub a variadic `args` array before it reaches `observer.onLog`. */
+export declare function scrubArgs(args: unknown[]): unknown[];
+//# sourceMappingURL=scrub.d.ts.map

package/dist/observability/scrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../../src/observability/scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmGH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAwC7D;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAEpD"}

package/dist/observability/scrub.js

@@ -0,0 +1,167 @@
+/**
+ * PII / secret scrubber for data leaving UWC through the observer seam.
+ *
+ * Security-first: the normalized `UWCTelemetryEvent` excludes signing payloads
+ * and addresses by construction — its STRUCTURED fields have no slot for them
+ * (§ telemetry.ts). This scrubber is the second line of defence for the two
+ * surfaces that CAN still carry free-form data on the observer path: the
+ * `WalletError.message` forwarded to `observer.onEvent`, and the `args` forwarded
+ * to `observer.onLog`. (The console / custom-logger sink receives raw data — it's
+ * local, not egress.)
+ *
+ * Two detection layers:
+ *  - KEY-based redaction of sensitive object keys — substring match (not regex),
+ *    avoiding the ReDoS class that Wiz flags on user-input regexes.
+ *  - CONTENT-based redaction of secrets embedded in free-form strings (hex blobs,
+ *    secret k/v params, bearer tokens) — via linear regexes with no nested or
+ *    overlapping quantifiers (see SECRET_CONTENT_PATTERNS), so they carry no
+ *    catastrophic-backtracking risk.
+ */
+/**
+ * Separator-free, lower-cased fragments that mark a value as sensitive. Keys are
+ * normalized (separators stripped) before matching, so `walletPrivateKey`,
+ * `private_key`, `x-api-key`, and `authToken` all hit the same short list. This
+ * over-redacts by design (a `security`-first scrubber prefers a false redaction
+ * to a leak).
+ */
+const SENSITIVE_KEY_FRAGMENTS = [
+    'seed',
+    'mnemonic',
+    'privatekey',
+    'secret',
+    'password',
+    'passphrase',
+    'signature',
+    'message',
+    'payload',
+    'token',
+    'apikey',
+    'authorization',
+    'auth'
+];
+const MAX_STRING_LENGTH = 500;
+const MAX_DEPTH = 4;
+const REDACTED = '[Redacted]';
+function isSensitiveKey(key) {
+    // Strip separators so `private_key` / `x-api-key` normalize to the bare form.
+    const normalized = key.toLowerCase().split('-').join('').split('_').join('');
+    return SENSITIVE_KEY_FRAGMENTS.some(fragment => normalized.includes(fragment));
+}
+// Content patterns for secrets embedded in FREE-FORM strings (error messages,
+// log args) where key-based redaction can't reach. All are linear expressions
+// with no nested/overlapping quantifiers, so they carry no catastrophic-
+// backtracking (ReDoS) risk on attacker-controlled input.
+const SECRET_CONTENT_PATTERNS = [
+    // 0x-prefixed hex blobs: EVM addresses (40 nibbles) and longer
+    // signatures/keys/hashes/calldata (64+). Over-redacts public hashes by design.
+    [/0x[a-fA-F0-9]{40,}/g, '0x[redacted-hex]'],
+    // `secret=…` / `token=…` / `key=…` query-string or k/v fragments.
+    [
+        /\b(token|key|secret|auth|sig|signature|password|passphrase|mnemonic|seed|apikey)=[^\s&"']+/gi,
+        '$1=[redacted]'
+    ],
+    // `Bearer <opaque>` / `Basic <opaque>` authorization values.
+    [/\b(bearer|basic)\s+[A-Za-z0-9._~+/-]+=*/gi, '$1 [redacted]'],
+    // TON user-friendly addresses: `EQ…` / `UQ…` + 46 base64url chars (48 total).
+    // Trailing edge is a negative lookahead, not `\b`: a base64url address can end
+    // in `-`/`_`, where `\b` fails to anchor and the address would slip through.
+    [/\b[EU]Q[A-Za-z0-9_-]{46}(?![A-Za-z0-9_-])/g, '[redacted-ton-address]'],
+    // TON raw-form addresses: `workchain:64-hex` (`0:…`, `-1:…`). Before base58 so
+    // the hex tail gets the specific TON marker, not a generic base58 hit.
+    // Anchor-free like base58 below: digits and `_` are word chars, so a `\b`
+    // never anchors when the address is glued to one (`account_0:…` leaked).
+    // The trailing edge is a hex negative lookahead — a LONGER contiguous hex
+    // run is a different blob, not a 64-hex address.
+    [/-?\d+:[0-9a-fA-F]{64}(?![0-9a-fA-F])/g, '[redacted-ton-address]'],
+    // Solana / generic base58, 32 chars or MORE — bare addresses AND longer blobs
+    // (a signature is ~88 chars, a serialized tx longer still). No upper bound: a
+    // capped quantifier can never match inside a longer contiguous run. No `\b`
+    // anchors either: `0`/`O`/`I`/`l`/`_` are word chars OUTSIDE the base58
+    // alphabet, so they break the class AND defeat a boundary anchor — an address
+    // glued to one (`account_<addr>`) would slip through anchored matching.
+    // Over-redaction inside longer tokens is accepted by design. Placed LAST: it
+    // is the broadest pattern and would otherwise swallow narrower matches above.
+    [/[1-9A-HJ-NP-Za-km-z]{32,}/g, '[redacted-base58]']
+];
+/**
+ * Redact secrets that live INSIDE a free-form string. Best-effort and
+ * deliberately conservative toward over-redaction: a wallet error string can
+ * embed an address, a reverted-tx calldata blob, or a URL with a token, none of
+ * which key-based redaction sees.
+ *
+ * Base58 (Solana) and TON addresses (user-friendly `EQ…`/`UQ…` AND the raw
+ * `workchain:hex` form) are redacted as a security gate: a leaked
+ * recipient/wallet address on the egress path is treated as a defect, so we
+ * accept that any base58-looking token of 32+ chars (some ids, tx hashes,
+ * IPFS CIDs) is over-redacted by design. The narrower TON patterns run before
+ * the broad base58 one so TON addresses get the specific marker.
+ *
+ * One documented gap remains: BARE (non-`0x`) hex blobs — a raw 64-char hex
+ * string is far more often a legitimate id/hash than a secret, so only
+ * `0x`-prefixed hex is redacted. Structured telemetry fields never carry
+ * addresses regardless (see telemetry.ts); this pass only hardens the free-form
+ * `error.message` / log-arg surface.
+ */
+function redactSecretsInString(input) {
+    let out = input;
+    for (const [pattern, replacement] of SECRET_CONTENT_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+/**
+ * Recursively copy `value`, redacting sensitive object-keys, capping long
+ * strings, and rendering non-serializable values inert. The returned objects use
+ * a null prototype so a malicious `__proto__`/`constructor` key in attacker-shaped
+ * input can't pollute `Object.prototype` downstream.
+ */
+export function scrubValue(value, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return '[Truncated: max depth]';
+    if (value === null || value === undefined)
+        return value;
+    const type = typeof value;
+    if (type === 'string') {
+        // Redact embedded secrets BEFORE capping, so the cap can't slice a pattern
+        // in half and leak its tail.
+        const str = redactSecretsInString(value);
+        return str.length > MAX_STRING_LENGTH
+            ? str.slice(0, MAX_STRING_LENGTH) + '…[truncated]'
+            : str;
+    }
+    if (type === 'number' || type === 'boolean')
+        return value;
+    if (type === 'bigint')
+        return value.toString();
+    if (type === 'function' || type === 'symbol')
+        return `[${type}]`;
+    if (Array.isArray(value)) {
+        return value.map(item => scrubValue(item, depth + 1));
+    }
+    if (type === 'object') {
+        // Error instances carry a useful message but also a stack we don't want.
+        // Null prototype here too — the doc above promises it for every returned
+        // object, and an Error-shaped attacker value lands in this branch.
+        if (value instanceof Error) {
+            const out = Object.create(null);
+            out['name'] = value.name;
+            out['message'] = scrubValue(value.message, depth + 1);
+            return out;
+        }
+        const out = Object.create(null);
+        for (const [key, val] of Object.entries(value)) {
+            out[key] = isSensitiveKey(key) ? REDACTED : scrubValue(val, depth + 1);
+        }
+        return out;
+    }
+    return '[Unserializable]';
+}
+/** Scrub a free-form error message (string in → capped string out). */
+export function scrubMessage(message) {
+    return scrubValue(message);
+}
+/** Scrub a variadic `args` array before it reaches `observer.onLog`. */
+export function scrubArgs(args) {
+    return args.map(arg => scrubValue(arg));
+}
+//# sourceMappingURL=scrub.js.map

package/dist/observability/scrub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrub.js","sourceRoot":"","sources":["../../src/observability/scrub.ts"],"names":[],"mappings":"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"}

package/dist/observability/telemetry.d.ts

@@ -0,0 +1,157 @@
+import type { ConnectionMode, WalletError, WalletFlowType, Platform, LogLevel, Namespace, NetworkId, FailureKind, ErrorSource, LifecycleUnavailableReason } from '@meshconnect/uwc-types';
+import type { UWCEventName, UWCEventMap, UWCOperation } from '../events';
+/**
+ * Telemetry record schema version. Bump on any breaking change to the
+ * `UWCTelemetryEvent` shape so a downstream consumer can branch on it.
+ */
+export declare const TELEMETRY_SCHEMA_VERSION = 1;
+/**
+ * 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 declare function derivePlatform(): Platform;
+/**
+ * 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 declare function deriveWalletFlowType(connectionMode: ConnectionMode, platform: Platform): WalletFlowType;
+/**
+ * Normalize a bus event into a PII-safe `UWCTelemetryEvent`, dropping undefined
+ * optionals so the emitted shape is consistent across event kinds.
+ */
+export declare function normalizeEvent<K extends UWCEventName>(name: K, data: UWCEventMap[K], sdkSessionId: string, now: number, correlationId?: string): UWCTelemetryEvent;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/observability/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/observability/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,SAAS,EACT,WAAW,EACX,WAAW,EACX,0BAA0B,EAE3B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAIxE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AA4BzC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,aAAa,EAAE,OAAO,wBAAwB,CAAA;IAC9C;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,IAAI,EAAE,YAAY,CAAA;IAClB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,SAAS,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;IACpC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IAC3C,0EAA0E;IAC1E,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACjC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC/B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACzC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,kFAAkF;IAClF,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IACrC,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IAChC;;;;OAIG;IACH,eAAe,CAAC,EACZ;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,oBAAoB,EAAE,MAAM,EAAE,CAAA;KAAE,GAC9D,SAAS,CAAA;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IAC/B,oDAAoD;IACpD,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACnD;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAA;IAC9E;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACtD;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,qFAAqF;IACrF,MAAM,CAAC,EAAE,0BAA0B,GAAG,SAAS,CAAA;IAC/C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;IACzC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,iGAAiG;IACjG,OAAO,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACxC,8EAA8E;IAC9E,KAAK,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAWzC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,QAAQ,GACjB,cAAc,CAehB;AAuTD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,YAAY,EACnD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,aAAa,CAAC,EAAE,MAAM,GACrB,iBAAiB,CAInB"}