@meshconnect/uwc-types 0.16.1 → 0.17.0

package/dist/bounded-dedup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bounded first-seen dedup — the shared "storm guard" for error-reporting
+ * sites (observer sinks, relay/bridge error callbacks). Evicts wholesale at
+ * the cap: it is a storm guard, not a permanent ledger, so a previously-seen
+ * key may report once more after eviction — an accepted trade for a bounded
+ * footprint. (`uwc-bridge-child` keeps a local copy of this logic to stay
+ * dependency-free; keep the two in sync.)
+ */
+export declare function createBoundedDedup(maxEntries: number): {
+    /** true the FIRST time a key is seen (and records it); false on repeats. */
+    firstSeen(key: string): boolean;
+};
+//# sourceMappingURL=bounded-dedup.d.ts.map

package/dist/bounded-dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-dedup.d.ts","sourceRoot":"","sources":["../src/bounded-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG;IACtD,4EAA4E;IAC5E,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAChC,CAUA"}

package/dist/bounded-dedup.js

@@ -0,0 +1,22 @@
+/**
+ * Bounded first-seen dedup — the shared "storm guard" for error-reporting
+ * sites (observer sinks, relay/bridge error callbacks). Evicts wholesale at
+ * the cap: it is a storm guard, not a permanent ledger, so a previously-seen
+ * key may report once more after eviction — an accepted trade for a bounded
+ * footprint. (`uwc-bridge-child` keeps a local copy of this logic to stay
+ * dependency-free; keep the two in sync.)
+ */
+export function createBoundedDedup(maxEntries) {
+    const seen = new Set();
+    return {
+        firstSeen(key) {
+            if (seen.has(key))
+                return false;
+            if (seen.size >= maxEntries)
+                seen.clear();
+            seen.add(key);
+            return true;
+        }
+    };
+}
+//# sourceMappingURL=bounded-dedup.js.map

package/dist/bounded-dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-dedup.js","sourceRoot":"","sources":["../src/bounded-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IAInD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,OAAO;QACL,SAAS,CAAC,GAAW;YACnB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC/B,IAAI,IAAI,CAAC,IAAI,IAAI,UAAU;gBAAE,IAAI,CAAC,KAAK,EAAE,CAAA;YACzC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACb,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/connector.d.ts

@@ -1,8 +1,41 @@
 import type { Network, NetworkId, Namespace } from './networks';
+import type { ConnectionMode } from './connection-mode';
 import type { AvailableAddress } from './session';
 import type { DetectedEIP6963WalletInfo, DetectedSolanaWalletInfo, DetectedTronWalletInfo, DetectedTonWalletInfo, ExtensionInjectedProvider, IntegratedBrowserInjectedProvider, WalletConnectProvider, TonConnectWalletProvider, WalletMetadata } from './UWC-state';
 import type { EVMCapabilities, TransactionRequest, TransactionResult } from './transactions';
 import type { SignatureType, EIP712TypedData } from './signature';
+/**
+ * A post-connect wallet lifecycle change observed from the live provider.
+ *
+ * PII-safe by construction: there is NO address field. For `accountChanged` we
+ * signal only THAT the account/list changed (the new address is dropped at the
+ * connector boundary). `chainChanged` carries the new CAIP-2 id (non-PII) when
+ * resolvable.
+ */
+export type WalletLifecycleEvent = {
+    type: 'accountChanged';
+} | {
+    type: 'chainChanged';
+    chainId?: NetworkId;
+} | {
+    type: 'disconnect';
+} | {
+    type: 'sessionExpired';
+};
+/**
+ * Names the session a lifecycle subscription is being attached FOR. The caller
+ * (core) resolves it from the active session and passes it explicitly — a
+ * connector must never infer it from its own ambient state, which can be
+ * ambiguous (a secondary-namespace gather leaves more than one internal
+ * service holding a live provider surface).
+ */
+export interface WalletLifecycleContext {
+    /** Transport of the session being observed. */
+    connectionMode: ConnectionMode;
+    /** ACTIVE namespace of the session — the surface the connector must observe. */
+    namespace?: Namespace;
+    walletId?: string;
+}
 /**
  * Result interface for connect operations
  */
@@ -89,5 +122,20 @@ export interface Connector {
      * signature, the relay broadcasts. Optional; not all connectors support it.
      */
     signSolanaTransactionBytes?(serializedTx: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Subscribe to post-connect wallet lifecycle changes from the live provider
+     * (account/chain switched in the wallet, disconnect, session expiry). For
+     * OBSERVABILITY only — it never changes connection behaviour.
+     *
+     * Implementations MUST NOT include an address in the emitted event (the PII
+     * boundary stays in core). The caller passes a `WalletLifecycleContext`
+     * naming the session being observed (active namespace / transport / wallet);
+     * implementations route by it rather than inferring from internal state.
+     * Returns an unsubscribe function, or `undefined` when this connector/session
+     * can't be observed (no live `.on`, unsupported namespace) — the core then
+     * emits `lifecycleTelemetryUnavailable`. Optional: a connector that never
+     * observes lifecycle leaves it undefined entirely.
+     */
+    onLifecycleEvent?(listener: (event: WalletLifecycleEvent) => void, context: WalletLifecycleContext): (() => void) | undefined;
 }
 //# sourceMappingURL=connector.d.ts.map

package/dist/connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACjD,OAAO,KAAK,EACV,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,EACzB,iCAAiC,EACjC,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACf,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAEjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,kBAAkB,EAAE,gBAAgB,EAAE,CAAA;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IAEH,OAAO,CACL,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EACL,yBAAyB,GACzB,iCAAiC,GACjC,qBAAqB,GACrB,wBAAwB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAAA;IAE3B;;;;;;;OAOG;IACH,gBAAgB,CAAC,IAAI,MAAM,CAAA;IAE3B;;;;OAIG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5B;;;;;OAKG;IAEH,aAAa,CACX,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EACL,yBAAyB,GACzB,iCAAiC,GACjC,qBAAqB,GACrB,wBAAwB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAE/B;;;;;;OAMG;IACH,mBAAmB,CAAC,CAClB,SAAS,EAAE,SAAS,EACpB,eAAe,CAAC,EAAE,cAAc,EAAE,GACjC,OAAO,CACN,yBAAyB,EAAE,GAC3B,wBAAwB,EAAE,GAC1B,sBAAsB,EAAE,GACxB,qBAAqB,EAAE,CAC1B,CAAA;IAED;;;;;OAKG;IACH,WAAW,CAAC,CACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EACL,yBAAyB,GACzB,iCAAiC,GACjC,qBAAqB,GACrB,wBAAwB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAAA;IAEzB;;;;;OAKG;IACH,aAAa,CAAC,CACZ,SAAS,EAAE,eAAe,EAC1B,QAAQ,CAAC,EACL,yBAAyB,GACzB,iCAAiC,GACjC,qBAAqB,GACxB,OAAO,CAAC,MAAM,CAAC,CAAA;IAElB;;;;;OAKG;IACH,eAAe,CAAC,CACd,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,CAAC,EACL,yBAAyB,GACzB,iCAAiC,GACjC,qBAAqB,GACrB,wBAAwB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAE7B,qBAAqB,CAAC,CACpB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,EAAE,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;IAE3C;;;;OAIG;IACH,0BAA0B,CAAC,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC3E"}
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -11,4 +11,19 @@ export declare class WalletConnectorError extends Error {
     type: ErrorType;
     constructor(walletError: WalletError);
 }
+/**
+ * Thrown at connect time when the wallet's supported networks and the configured
+ * networks share no common chain, so there is nothing to connect on. Carries both
+ * CAIP-2 id lists (non-PII) so telemetry can answer "wallet offered X, token
+ * configured Y" — the difference between a metadata gap, a client-config mistake,
+ * and a genuinely-unsupported wallet. It is the single most frequent connection
+ * failure in production, so it gets a dedicated, self-describing error.
+ */
+export declare class NoCommonNetworkError extends WalletConnectorError {
+    /** CAIP-2 ids the wallet's provider advertised. */
+    readonly walletNetworkIds: string[];
+    /** CAIP-2 ids configured on this UWC instance. */
+    readonly configuredNetworkIds: string[];
+    constructor(walletNetworkIds: string[], configuredNetworkIds: string[]);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAA;AAE1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,SAAS,CAAA;gBAEH,WAAW,EAAE,WAAW;CAKrC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAA;AAE1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,SAAS,CAAA;gBAEH,WAAW,EAAE,WAAW;CAKrC;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,oBAAoB;IAC5D,mDAAmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IACnC,kDAAkD;IAClD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,EAAE,CAAA;gBAE3B,gBAAgB,EAAE,MAAM,EAAE,EAAE,oBAAoB,EAAE,MAAM,EAAE;CAUvE"}

package/dist/errors.js

@@ -10,4 +10,27 @@ export class WalletConnectorError extends Error {
         this.type = walletError.type;
     }
 }
+/**
+ * Thrown at connect time when the wallet's supported networks and the configured
+ * networks share no common chain, so there is nothing to connect on. Carries both
+ * CAIP-2 id lists (non-PII) so telemetry can answer "wallet offered X, token
+ * configured Y" — the difference between a metadata gap, a client-config mistake,
+ * and a genuinely-unsupported wallet. It is the single most frequent connection
+ * failure in production, so it gets a dedicated, self-describing error.
+ */
+export class NoCommonNetworkError extends WalletConnectorError {
+    /** CAIP-2 ids the wallet's provider advertised. */
+    walletNetworkIds;
+    /** CAIP-2 ids configured on this UWC instance. */
+    configuredNetworkIds;
+    constructor(walletNetworkIds, configuredNetworkIds) {
+        super({
+            type: 'unknown',
+            message: 'No common supported network found between wallet and configured networks'
+        });
+        this.name = 'NoCommonNetworkError';
+        this.walletNetworkIds = walletNetworkIds;
+        this.configuredNetworkIds = configuredNetworkIds;
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,CAAW;IAEf,YAAY,WAAwB;QAClC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,CAAW;IAEf,YAAY,WAAwB;QAClC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAqB,SAAQ,oBAAoB;IAC5D,mDAAmD;IAC1C,gBAAgB,CAAU;IACnC,kDAAkD;IACzC,oBAAoB,CAAU;IAEvC,YAAY,gBAA0B,EAAE,oBAA8B;QACpE,KAAK,CAAC;YACJ,IAAI,EAAE,SAAS;YACf,OAAO,EACL,0EAA0E;SAC7E,CAAC,CAAA;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAA;QACxC,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAA;IAClD,CAAC;CACF"}

package/dist/index.d.ts

@@ -12,4 +12,7 @@ export * from './signature';
 export * from './transactions';
 export * from './errors';
 export * from './solana-message';
+export * from './observability';
+export * from './bounded-dedup';
+export * from './safe-error-message';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA"}

package/dist/index.js

@@ -12,4 +12,7 @@ export * from './signature';
 export * from './transactions';
 export * from './errors';
 export * from './solana-message';
+export * from './observability';
+export * from './bounded-dedup';
+export * from './safe-error-message';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA"}

package/dist/observability.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Vendor-agnostic observability primitives for the Universal Wallet Connector.
+ *
+ * These are leaf types — no dependency on the core event bus — so any package
+ * (including consumers below UWC in the dep graph, e.g. link-v2) can import them
+ * without pulling in `@meshconnect/uwc-core`. The richer `UWCTelemetryEvent` /
+ * `UWCObserver` shapes live in `@meshconnect/uwc-core` because they reference the
+ * core event names.
+ *
+ * UWC ships NO third-party telemetry SDK. The consumer implements the sinks and
+ * wires them to whatever backend they run (Datadog, Amplitude, Segment, …).
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Pluggable logger. The default implementation (`createLogger`) is console-backed
+ * and level-gated; inject your own to redirect UWC's internal logging into your
+ * stack. Kept to the four standard levels so a consumer's existing logger usually
+ * satisfies it without an adapter.
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Canonical wallet-handoff flow taxonomy.
+ *
+ * UWC is the single owner of this union so the two consumer layers (link-v2 and
+ * v3) don't drift. The string values are deliberately frozen to match link-v2's
+ * historical `wallet_flow_type` wire values so existing RUM / Segment facets keep
+ * matching after a consumer switches to importing this type — this is a
+ * lift-and-canonicalize, not a rename.
+ *
+ * Note: UWC's own `deriveWalletFlowType` only produces the extension / WC / TON /
+ * in-wallet / unknown values. The `dapp_*` members are part of the frozen wire
+ * taxonomy but are set only by a consumer with richer context — forward-compat,
+ * not dead code.
+ */
+export type WalletFlowType = 'browser_extension_flow' | 'wallet_connect_deep_link_flow' | 'wallet_connect_qr_flow' | 'dapp_deep_link_flow' | 'dapp_qr_flow' | 'ton_connect_qr_flow' | 'ton_connect_deep_link_flow' | 'in_wallet_browser_flow' | 'unknown';
+/**
+ * Coarse runtime surface. Intentionally a small enum — never a raw user-agent
+ * string, which is PII and high-cardinality. Used to decide whether mobile-only
+ * heuristics (e.g. focus bracketing) apply to a handoff.
+ */
+export type Platform = 'mobile' | 'desktop' | 'webview' | 'unknown';
+/**
+ * Coarse cause bucket for a non-success wallet outcome. Deliberately small and
+ * stable so it can drive failure dashboards without high cardinality. `unknown`
+ * is the honest default — UWC only classifies a kind when the evidence is
+ * reliable (a known EIP-1193 code, an explicit rejection, a typed connector
+ * error), never a guess from a message substring.
+ */
+export type FailureKind = 'user_rejected' | 'provider_error' | 'bridge_error' | 'network_error'
+/** Wallet and the configured networks share no chain — connect can't proceed. */
+ | 'no_common_network' | 'unsupported_method' | 'invalid_params' | 'expired' | 'unknown';
+/**
+ * Where a failure originated, as far as UWC can tell from the error shape. Used
+ * to triage whether a problem sits in the wallet/provider, our connector layer,
+ * or the iframe bridge. `unknown` when the shape carries no reliable signal.
+ */
+export type ErrorSource = 'provider' | 'connector' | 'bridge' | 'uwc' | 'unknown';
+/**
+ * Why post-connect wallet-lifecycle telemetry could not be attached. Emitted ONCE
+ * per connector/session/namespace so analytics can distinguish "lifecycle is
+ * genuinely silent" from "we never wired it" — an absent signal is itself signal.
+ */
+export type LifecycleUnavailableReason = 
+/** The live provider exposes no `.on` (or the connected namespace has no event surface yet). */
+'provider_subscription_unavailable'
+/** The iframe bridge couldn't forward provider events (no forwarder on the parent). */
+ | 'bridge_subscription_unavailable'
+/** The connected namespace has no lifecycle source UWC observes. */
+ | 'unsupported_namespace'
+/**
+ * RESERVED — not yet emitted. The parent's `uwc-bridge-parent` predates event
+ * forwarding; produced once cross-bridge lifecycle forwarding ships (MFS-576).
+ * Declared now so consumer switch statements are exhaustive ahead of it.
+ */
+ | 'old_bridge_parent'
+/**
+ * Lifecycle telemetry stopped mid-session: the per-attachment emission cap
+ * tripped (a storming provider). Emitted once at the moment of the trip.
+ */
+ | 'emission_cap';
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GACtB,wBAAwB,GACxB,+BAA+B,GAC/B,wBAAwB,GACxB,qBAAqB,GACrB,cAAc,GACd,qBAAqB,GACrB,4BAA4B,GAC5B,wBAAwB,GACxB,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,eAAe;AACjB,iFAAiF;GAC/E,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,SAAS,GACT,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,WAAW,GACX,QAAQ,GACR,KAAK,GACL,SAAS,CAAA;AAEb;;;;GAIG;AACH,MAAM,MAAM,0BAA0B;AACpC,gGAAgG;AAC9F,mCAAmC;AACrC,uFAAuF;GACrF,iCAAiC;AACnC,oEAAoE;GAClE,uBAAuB;AACzB;;;;GAIG;GACD,mBAAmB;AACrB;;;GAGG;GACD,cAAc,CAAA"}

package/dist/observability.js

@@ -0,0 +1,14 @@
+/**
+ * Vendor-agnostic observability primitives for the Universal Wallet Connector.
+ *
+ * These are leaf types — no dependency on the core event bus — so any package
+ * (including consumers below UWC in the dep graph, e.g. link-v2) can import them
+ * without pulling in `@meshconnect/uwc-core`. The richer `UWCTelemetryEvent` /
+ * `UWCObserver` shapes live in `@meshconnect/uwc-core` because they reference the
+ * core event names.
+ *
+ * UWC ships NO third-party telemetry SDK. The consumer implements the sinks and
+ * wires them to whatever backend they run (Datadog, Amplitude, Segment, …).
+ */
+export {};
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/safe-error-message.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract a bounded message from any thrown value without ever throwing.
+ * Error-reporting sites run inside catch blocks and third-party emitters,
+ * where a poisoned `message` getter or a throwing `toString()` would replace
+ * the real failure with its own — and an unbounded message retained as a
+ * dedup key is a memory footgun. (`uwc-bridge-child` keeps a local copy —
+ * that package stays dependency-free; keep the two in sync.)
+ */
+export declare function safeErrorMessage(error: unknown): string;
+//# sourceMappingURL=safe-error-message.d.ts.map

package/dist/safe-error-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-error-message.d.ts","sourceRoot":"","sources":["../src/safe-error-message.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CASvD"}

package/dist/safe-error-message.js

@@ -0,0 +1,26 @@
+/**
+ * Length cap for extracted messages. Aligned with the core scrubber's
+ * MAX_STRING_LENGTH so an error-reporting site never retains (dedup keys) or
+ * forwards more than the telemetry layer would keep anyway.
+ */
+const MAX_SAFE_ERROR_MESSAGE_LENGTH = 500;
+/**
+ * Extract a bounded message from any thrown value without ever throwing.
+ * Error-reporting sites run inside catch blocks and third-party emitters,
+ * where a poisoned `message` getter or a throwing `toString()` would replace
+ * the real failure with its own — and an unbounded message retained as a
+ * dedup key is a memory footgun. (`uwc-bridge-child` keeps a local copy —
+ * that package stays dependency-free; keep the two in sync.)
+ */
+export function safeErrorMessage(error) {
+    try {
+        const message = error instanceof Error ? error.message : String(error);
+        return message.length > MAX_SAFE_ERROR_MESSAGE_LENGTH
+            ? message.slice(0, MAX_SAFE_ERROR_MESSAGE_LENGTH)
+            : message;
+    }
+    catch {
+        return 'Unreadable error object';
+    }
+}
+//# sourceMappingURL=safe-error-message.js.map

package/dist/safe-error-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-error-message.js","sourceRoot":"","sources":["../src/safe-error-message.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,6BAA6B,GAAG,GAAG,CAAA;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,OAAO,OAAO,CAAC,MAAM,GAAG,6BAA6B;YACnD,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,6BAA6B,CAAC;YACjD,CAAC,CAAC,OAAO,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,yBAAyB,CAAA;IAClC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/uwc-types",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "TypeScript types for Universal Wallet Connector",
   "type": "module",
   "main": "dist/index.js",

package/src/bounded-dedup.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { createBoundedDedup } from './bounded-dedup'
+
+describe('createBoundedDedup', () => {
+  it('reports a key only the first time it is seen', () => {
+    const dedup = createBoundedDedup(10)
+    expect(dedup.firstSeen('a')).toBe(true)
+    expect(dedup.firstSeen('a')).toBe(false)
+    expect(dedup.firstSeen('b')).toBe(true)
+  })
+
+  it('evicts wholesale at the cap, so a bounded footprint beats permanence', () => {
+    const dedup = createBoundedDedup(2)
+    expect(dedup.firstSeen('a')).toBe(true)
+    expect(dedup.firstSeen('b')).toBe(true)
+    // Cap hit — the set clears, then records 'c'.
+    expect(dedup.firstSeen('c')).toBe(true)
+    // 'a' was evicted: it may report once more (storm guard, not a ledger).
+    expect(dedup.firstSeen('a')).toBe(true)
+    // 'c' survived the post-eviction add.
+    expect(dedup.firstSeen('c')).toBe(false)
+  })
+})

package/src/bounded-dedup.ts

@@ -0,0 +1,22 @@
+/**
+ * Bounded first-seen dedup — the shared "storm guard" for error-reporting
+ * sites (observer sinks, relay/bridge error callbacks). Evicts wholesale at
+ * the cap: it is a storm guard, not a permanent ledger, so a previously-seen
+ * key may report once more after eviction — an accepted trade for a bounded
+ * footprint. (`uwc-bridge-child` keeps a local copy of this logic to stay
+ * dependency-free; keep the two in sync.)
+ */
+export function createBoundedDedup(maxEntries: number): {
+  /** true the FIRST time a key is seen (and records it); false on repeats. */
+  firstSeen(key: string): boolean
+} {
+  const seen = new Set<string>()
+  return {
+    firstSeen(key: string): boolean {
+      if (seen.has(key)) return false
+      if (seen.size >= maxEntries) seen.clear()
+      seen.add(key)
+      return true
+    }
+  }
+}

package/src/connector.ts

@@ -1,4 +1,5 @@
 import type { Network, NetworkId, Namespace } from './networks'
+import type { ConnectionMode } from './connection-mode'
 import type { AvailableAddress } from './session'
 import type {
   DetectedEIP6963WalletInfo,
@@ -18,6 +19,35 @@ import type {
 } from './transactions'
 import type { SignatureType, EIP712TypedData } from './signature'
 
+/**
+ * A post-connect wallet lifecycle change observed from the live provider.
+ *
+ * PII-safe by construction: there is NO address field. For `accountChanged` we
+ * signal only THAT the account/list changed (the new address is dropped at the
+ * connector boundary). `chainChanged` carries the new CAIP-2 id (non-PII) when
+ * resolvable.
+ */
+export type WalletLifecycleEvent =
+  | { type: 'accountChanged' }
+  | { type: 'chainChanged'; chainId?: NetworkId }
+  | { type: 'disconnect' }
+  | { type: 'sessionExpired' }
+
+/**
+ * Names the session a lifecycle subscription is being attached FOR. The caller
+ * (core) resolves it from the active session and passes it explicitly — a
+ * connector must never infer it from its own ambient state, which can be
+ * ambiguous (a secondary-namespace gather leaves more than one internal
+ * service holding a live provider surface).
+ */
+export interface WalletLifecycleContext {
+  /** Transport of the session being observed. */
+  connectionMode: ConnectionMode
+  /** ACTIVE namespace of the session — the surface the connector must observe. */
+  namespace?: Namespace
+  walletId?: string
+}
+
 /**
  * Result interface for connect operations
  */
@@ -162,4 +192,23 @@ export interface Connector {
    * signature, the relay broadcasts. Optional; not all connectors support it.
    */
   signSolanaTransactionBytes?(serializedTx: Uint8Array): Promise<Uint8Array>
+
+  /**
+   * Subscribe to post-connect wallet lifecycle changes from the live provider
+   * (account/chain switched in the wallet, disconnect, session expiry). For
+   * OBSERVABILITY only — it never changes connection behaviour.
+   *
+   * Implementations MUST NOT include an address in the emitted event (the PII
+   * boundary stays in core). The caller passes a `WalletLifecycleContext`
+   * naming the session being observed (active namespace / transport / wallet);
+   * implementations route by it rather than inferring from internal state.
+   * Returns an unsubscribe function, or `undefined` when this connector/session
+   * can't be observed (no live `.on`, unsupported namespace) — the core then
+   * emits `lifecycleTelemetryUnavailable`. Optional: a connector that never
+   * observes lifecycle leaves it undefined entirely.
+   */
+  onLifecycleEvent?(
+    listener: (event: WalletLifecycleEvent) => void,
+    context: WalletLifecycleContext
+  ): (() => void) | undefined
 }

package/src/errors.ts

@@ -18,3 +18,29 @@ export class WalletConnectorError extends Error {
     this.type = walletError.type
   }
 }
+
+/**
+ * Thrown at connect time when the wallet's supported networks and the configured
+ * networks share no common chain, so there is nothing to connect on. Carries both
+ * CAIP-2 id lists (non-PII) so telemetry can answer "wallet offered X, token
+ * configured Y" — the difference between a metadata gap, a client-config mistake,
+ * and a genuinely-unsupported wallet. It is the single most frequent connection
+ * failure in production, so it gets a dedicated, self-describing error.
+ */
+export class NoCommonNetworkError extends WalletConnectorError {
+  /** CAIP-2 ids the wallet's provider advertised. */
+  readonly walletNetworkIds: string[]
+  /** CAIP-2 ids configured on this UWC instance. */
+  readonly configuredNetworkIds: string[]
+
+  constructor(walletNetworkIds: string[], configuredNetworkIds: string[]) {
+    super({
+      type: 'unknown',
+      message:
+        'No common supported network found between wallet and configured networks'
+    })
+    this.name = 'NoCommonNetworkError'
+    this.walletNetworkIds = walletNetworkIds
+    this.configuredNetworkIds = configuredNetworkIds
+  }
+}

package/src/index.ts

@@ -12,3 +12,6 @@ export * from './signature'
 export * from './transactions'
 export * from './errors'
 export * from './solana-message'
+export * from './observability'
+export * from './bounded-dedup'
+export * from './safe-error-message'

package/src/observability.ts

@@ -0,0 +1,114 @@
+/**
+ * Vendor-agnostic observability primitives for the Universal Wallet Connector.
+ *
+ * These are leaf types — no dependency on the core event bus — so any package
+ * (including consumers below UWC in the dep graph, e.g. link-v2) can import them
+ * without pulling in `@meshconnect/uwc-core`. The richer `UWCTelemetryEvent` /
+ * `UWCObserver` shapes live in `@meshconnect/uwc-core` because they reference the
+ * core event names.
+ *
+ * UWC ships NO third-party telemetry SDK. The consumer implements the sinks and
+ * wires them to whatever backend they run (Datadog, Amplitude, Segment, …).
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+/**
+ * Pluggable logger. The default implementation (`createLogger`) is console-backed
+ * and level-gated; inject your own to redirect UWC's internal logging into your
+ * stack. Kept to the four standard levels so a consumer's existing logger usually
+ * satisfies it without an adapter.
+ */
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void
+  info(message: string, ...args: unknown[]): void
+  warn(message: string, ...args: unknown[]): void
+  error(message: string, ...args: unknown[]): void
+}
+
+/**
+ * Canonical wallet-handoff flow taxonomy.
+ *
+ * UWC is the single owner of this union so the two consumer layers (link-v2 and
+ * v3) don't drift. The string values are deliberately frozen to match link-v2's
+ * historical `wallet_flow_type` wire values so existing RUM / Segment facets keep
+ * matching after a consumer switches to importing this type — this is a
+ * lift-and-canonicalize, not a rename.
+ *
+ * Note: UWC's own `deriveWalletFlowType` only produces the extension / WC / TON /
+ * in-wallet / unknown values. The `dapp_*` members are part of the frozen wire
+ * taxonomy but are set only by a consumer with richer context — forward-compat,
+ * not dead code.
+ */
+export type WalletFlowType =
+  | 'browser_extension_flow'
+  | 'wallet_connect_deep_link_flow'
+  | 'wallet_connect_qr_flow'
+  | 'dapp_deep_link_flow'
+  | 'dapp_qr_flow'
+  | 'ton_connect_qr_flow'
+  | 'ton_connect_deep_link_flow'
+  | 'in_wallet_browser_flow'
+  | 'unknown'
+
+/**
+ * Coarse runtime surface. Intentionally a small enum — never a raw user-agent
+ * string, which is PII and high-cardinality. Used to decide whether mobile-only
+ * heuristics (e.g. focus bracketing) apply to a handoff.
+ */
+export type Platform = 'mobile' | 'desktop' | 'webview' | 'unknown'
+
+/**
+ * Coarse cause bucket for a non-success wallet outcome. Deliberately small and
+ * stable so it can drive failure dashboards without high cardinality. `unknown`
+ * is the honest default — UWC only classifies a kind when the evidence is
+ * reliable (a known EIP-1193 code, an explicit rejection, a typed connector
+ * error), never a guess from a message substring.
+ */
+export type FailureKind =
+  | 'user_rejected'
+  | 'provider_error'
+  | 'bridge_error'
+  | 'network_error'
+  /** Wallet and the configured networks share no chain — connect can't proceed. */
+  | 'no_common_network'
+  | 'unsupported_method'
+  | 'invalid_params'
+  | 'expired'
+  | 'unknown'
+
+/**
+ * Where a failure originated, as far as UWC can tell from the error shape. Used
+ * to triage whether a problem sits in the wallet/provider, our connector layer,
+ * or the iframe bridge. `unknown` when the shape carries no reliable signal.
+ */
+export type ErrorSource =
+  | 'provider'
+  | 'connector'
+  | 'bridge'
+  | 'uwc'
+  | 'unknown'
+
+/**
+ * Why post-connect wallet-lifecycle telemetry could not be attached. Emitted ONCE
+ * per connector/session/namespace so analytics can distinguish "lifecycle is
+ * genuinely silent" from "we never wired it" — an absent signal is itself signal.
+ */
+export type LifecycleUnavailableReason =
+  /** The live provider exposes no `.on` (or the connected namespace has no event surface yet). */
+  | 'provider_subscription_unavailable'
+  /** The iframe bridge couldn't forward provider events (no forwarder on the parent). */
+  | 'bridge_subscription_unavailable'
+  /** The connected namespace has no lifecycle source UWC observes. */
+  | 'unsupported_namespace'
+  /**
+   * RESERVED — not yet emitted. The parent's `uwc-bridge-parent` predates event
+   * forwarding; produced once cross-bridge lifecycle forwarding ships (MFS-576).
+   * Declared now so consumer switch statements are exhaustive ahead of it.
+   */
+  | 'old_bridge_parent'
+  /**
+   * Lifecycle telemetry stopped mid-session: the per-attachment emission cap
+   * tripped (a storming provider). Emitted once at the moment of the trip.
+   */
+  | 'emission_cap'

package/src/safe-error-message.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { safeErrorMessage } from './safe-error-message'
+
+describe('safeErrorMessage', () => {
+  it('extracts the message from an Error', () => {
+    expect(safeErrorMessage(new Error('boom'))).toBe('boom')
+  })
+
+  it('stringifies non-Error values', () => {
+    expect(safeErrorMessage('plain string')).toBe('plain string')
+    expect(safeErrorMessage(42)).toBe('42')
+  })
+
+  it('never throws for a throwing toString()', () => {
+    const evil = {
+      toString(): string {
+        throw new Error('poisoned toString')
+      }
+    }
+    expect(safeErrorMessage(evil)).toBe('Unreadable error object')
+  })
+
+  it('never throws for a poisoned message getter', () => {
+    const evil = new Error('real')
+    Object.defineProperty(evil, 'message', {
+      get() {
+        throw new Error('poisoned message')
+      }
+    })
+    expect(safeErrorMessage(evil)).toBe('Unreadable error object')
+  })
+
+  it('caps a huge message so dedup keys stay bounded', () => {
+    const out = safeErrorMessage(new Error('x'.repeat(10_000)))
+    expect(out).toHaveLength(500)
+  })
+})

package/src/safe-error-message.ts

@@ -0,0 +1,25 @@
+/**
+ * Length cap for extracted messages. Aligned with the core scrubber's
+ * MAX_STRING_LENGTH so an error-reporting site never retains (dedup keys) or
+ * forwards more than the telemetry layer would keep anyway.
+ */
+const MAX_SAFE_ERROR_MESSAGE_LENGTH = 500
+
+/**
+ * Extract a bounded message from any thrown value without ever throwing.
+ * Error-reporting sites run inside catch blocks and third-party emitters,
+ * where a poisoned `message` getter or a throwing `toString()` would replace
+ * the real failure with its own — and an unbounded message retained as a
+ * dedup key is a memory footgun. (`uwc-bridge-child` keeps a local copy —
+ * that package stays dependency-free; keep the two in sync.)
+ */
+export function safeErrorMessage(error: unknown): string {
+  try {
+    const message = error instanceof Error ? error.message : String(error)
+    return message.length > MAX_SAFE_ERROR_MESSAGE_LENGTH
+      ? message.slice(0, MAX_SAFE_ERROR_MESSAGE_LENGTH)
+      : message
+  } catch {
+    return 'Unreadable error object'
+  }
+}