@unicitylabs/sphere-sdk 0.12.0-dev.1 → 0.13.0

package/dist/connect/index.d.cts

@@ -30,7 +30,7 @@ declare const HOST_READY_TIMEOUT = 30000;
  * JSON-RPC-like message types for wallet ↔ dApp communication.
  */
 declare const SPHERE_CONNECT_NAMESPACE = "sphere-connect";
-declare const SPHERE_CONNECT_VERSION = "2.0";
+declare const SPHERE_CONNECT_VERSION = "2.1";
 
 declare const RPC_METHODS: {
     readonly GET_IDENTITY: "sphere_getIdentity";
@@ -83,12 +83,40 @@ declare const ERROR_CODES: {
     readonly RATE_LIMITED: 4006;
     readonly UNSUPPORTED_PROTOCOL_VERSION: 4007;
     readonly INCOMPATIBLE_NETWORK: 4008;
+    readonly WALLET_LOCKED: 4009;
     readonly INSUFFICIENT_BALANCE: 4100;
     readonly INVALID_RECIPIENT: 4101;
     readonly TRANSFER_FAILED: 4102;
     readonly INTENT_CANCELLED: 4200;
+    /**
+     * The intent was DELEGATED to the wallet and the host lost track of the answer — a host
+     * deadline fired, or the wallet locked / logged out mid-flight. **The outcome is UNKNOWN:
+     * the money may or may not have moved.**
+     *
+     * A dApp MUST NOT retry on this code. Reconcile out of band (poll the recipient, the
+     * aggregator, or your own backend) and only then decide.
+     *
+     * This code exists because every other answer would be a lie. `INTENT_CANCELLED` (4200)
+     * asserts the user declined and nothing happened; `WALLET_LOCKED` (4009) invites a retry
+     * after the unlock. Sending either for an intent the wallet had already submitted is how a
+     * paid-but-not-credited order — and then a double spend on retry — happens.
+     */
+    readonly INTENT_OUTCOME_UNKNOWN: 4201;
 };
 type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/** `data` carried by every WALLET_LOCKED (4009) refusal. */
+interface WalletLockedData {
+    /** Discriminator. Always the literal 'locked' — reserved for future refusal reasons. */
+    readonly reason: 'locked';
+    /**
+     * Whether the wallet's own unlock surface is currently on screen.
+     * DECLARED in the fail-fast release and always absent there; POPULATED in the resume
+     * release from ConnectHostConfig.unlockSurface(), evaluated at refusal time (visibility
+     * changes over time, so a static value would lie). Feeds
+     * ConnectClientConfig.onWalletAttention.
+     */
+    readonly unlockSurface?: 'visible' | 'background';
+}
 interface SphereMessageBase {
     readonly ns: typeof SPHERE_CONNECT_NAMESPACE;
     readonly v: typeof SPHERE_CONNECT_VERSION;
@@ -145,6 +173,11 @@ interface SphereHandshake extends SphereMessageBase {
     readonly error?: SphereRpcError;
     /** Response: non-fatal deprecation notice (does not block the connection). */
     readonly warning?: SphereRpcError;
+    /** Response only: the wallet is LOCKED and the session is ALIVE. The dApp is connected
+     *  and must not re-handshake; it will receive `wallet:unlocked` on the same session.
+     *  Additive and safe for old clients: handleHandshakeResponse reads only sessionId,
+     *  permissions, identity, network, warning and error and ignores unknown fields. */
+    readonly locked?: boolean;
 }
 interface SphereRpcError {
     readonly code: number;
@@ -169,14 +202,54 @@ interface PublicIdentity {
  * No sphere_subscribe call needed — host sends these unconditionally.
  */
 declare const WALLET_EVENTS: {
-    /** Wallet locked or user logged out. dApp shows locked state and waits for unlock.
-     *  Pushed automatically by ConnectHost — no sphere_subscribe needed. */
+    /** Wallet is LOCKED — the session is STILL ALIVE. Requests are answered
+     *  WALLET_LOCKED (4009) until `wallet:unlocked`. The dApp must NOT disconnect,
+     *  must NOT clear its sessionId, and must NOT re-handshake.
+     *  Payload: {@link WalletLockedPayload}. Pushed by ConnectHost.setLocked() and
+     *  immediately after a handshake response carrying `locked: true`. */
     readonly LOCKED: "wallet:locked";
+    /** Wallet was unlocked — the SAME session continues: no re-handshake, no re-approval,
+     *  no re-subscribe (the host re-arms the dApp's subscriptions before pushing this).
+     *  Payload: {@link WalletUnlockedPayload} — carries the CURRENT identity, which may
+     *  differ from the one the dApp connected with. Pushed by ConnectHost.updateSphere()
+     *  on the locked -> live edge only. */
+    readonly UNLOCKED: "wallet:unlocked";
+    /** The session is GONE (logout, wallet deleted, dApp sphere_disconnect, expiry seen at
+     *  unlock, a different seed behind the lock screen, host destroy).
+     *  The dApp must clear its session and re-handshake to continue. Unlocking does not cure it.
+     *  Payload: {@link WalletDisconnectedPayload}. Pushed by ConnectHost.revokeSession(). */
+    readonly DISCONNECTED: "wallet:disconnected";
     /** Active wallet address changed. dApp should update displayed identity.
      *  Pushed automatically by ConnectHost — no sphere_subscribe needed. */
     readonly IDENTITY_CHANGED: "identity:changed";
 };
 type WalletEvent = (typeof WALLET_EVENTS)[keyof typeof WALLET_EVENTS];
+/** Payload of {@link WALLET_EVENTS.LOCKED}. Intentionally empty — matches today's push,
+ *  so an old dApp sees no shape change. */
+type WalletLockedPayload = Record<string, never>;
+/** Payload of {@link WALLET_EVENTS.DISCONNECTED}. Intentionally empty. */
+type WalletDisconnectedPayload = Record<string, never>;
+/** Payload of {@link WALLET_EVENTS.UNLOCKED}. */
+interface WalletUnlockedPayload {
+    /** The wallet's public identity at unlock time. Absent when the rebound Sphere has no
+     *  identity yet (JSON transports drop undefined keys).
+     *  Unlock is NOT implicitly the same wallet: the lock screen's "Forgot password ->
+     *  restore from recovery phrase" installs a DIFFERENT seed while origin approvals are
+     *  keyed by origin alone. The host's own lock-edge guard is authoritative (it revokes
+     *  instead of pushing this event on a mismatch); this field is what lets a dApp render
+     *  honestly and what the client-side retry queue checks before draining. */
+    readonly identity?: PublicIdentity;
+}
+/** Payload of {@link WALLET_EVENTS.IDENTITY_CHANGED} — unchanged: the host forwards
+ *  Sphere's own event data verbatim and pushes a PublicIdentity from updateSphere().
+ *  Typed as the union for honesty. */
+type WalletIdentityChangedPayload = PublicIdentity | unknown;
+/** Events the host pushes unconditionally. They must NEVER be routed through
+ *  `sphere_subscribe`: Sphere.on() accepts any string and would silently never emit,
+ *  so the subscribe would succeed and deliver nothing forever. */
+declare const AUTO_PUSHED_EVENTS: readonly WalletEvent[];
+/** True for an event the host pushes unconditionally (see {@link AUTO_PUSHED_EVENTS}). */
+declare function isAutoPushedEvent(event: string): event is WalletEvent;
 /** Check if a message belongs to the Sphere Connect protocol.
  *  Handshakes are accepted at ANY version (the version decision happens in the
  *  handshake handler so an incompatible peer gets a clean typed error instead of a
@@ -242,11 +315,56 @@ interface ConnectSession {
     readonly expiresAt: number;
     active: boolean;
 }
+/**
+ * State of the host's binding to a Sphere instance. ORTHOGONAL to `session`:
+ * a locked wallet keeps its session, and a live wallet may have none.
+ *
+ * - 'live'        — Sphere bound and usable.
+ * - 'locked'      — the wallet is locked: the Sphere reference is DROPPED and the
+ *                   session is PRESERVED. Requests outside the allow-list answer
+ *                   WALLET_LOCKED (4009). Curable by updateSphere().
+ * - 'unavailable' — Sphere is gone for a NON-lock reason (a generic init failure leaves
+ *                   `sphere === null, isLocked === false`). Entering it revokes the
+ *                   session and pushes wallet:disconnected. NOT curable by unlocking.
+ */
+type WalletState = 'live' | 'locked' | 'unavailable';
+/** Context handed to {@link ConnectHostConfig.onLockedRequest}. Notify-only. */
+interface LockedRequestContext {
+    /** ConnectHostConfig.origin, when the wallet supplied one. NEVER the dApp-claimed
+     *  `session.dapp.url`. Absent = "a connected app"; make no claim you cannot verify. */
+    readonly origin?: string;
+    readonly kind: 'query' | 'intent' | 'handshake';
+    /** An RPC_METHODS value for 'query', an INTENT_ACTIONS value for 'intent',
+     *  the literal 'handshake' for 'handshake'. */
+    readonly name: string;
+}
+/** 4th argument of {@link ConnectHostConfig.onIntent} (Connect 2.1). */
+interface IntentContext {
+    readonly origin?: string;
+    /** Epoch ms after which the host answers on its own and aborts `signal`. */
+    readonly expiresAt: number;
+    /** Aborted when the host settles the intent for ANY reason (deadline, lock, revoke,
+     *  unavailable, destroy). The wallet MUST dismiss its modal on abort. */
+    readonly signal: AbortSignal;
+}
 interface ConnectHostConfig {
-    /** Sphere SDK instance to bridge */
+    /** Sphere SDK instance to bridge. MAY be null (or omitted-as-null) when
+     *  `initialWalletState` is 'locked' — the host never serves anything from a destroyed
+     *  Sphere. A null sphere with initialWalletState 'live' is coerced to 'unavailable' with
+     *  a logger.warn rather than throwing, because a throw here breaks the wallet's React
+     *  mount. */
     sphere: unknown;
     /** Transport layer for communication */
     transport: ConnectTransport;
+    /**
+     * The origin this host serves, when the wallet knows it (e.g. 'https://app.example.com').
+     * OPTIONAL and it stays optional: with the credential prompt gone, NO security decision
+     * depends on it — it only labels a passive badge and log lines. Requiring it would break
+     * the nodejs/ mock wallet host and any WebSocket host, neither of which has a browser
+     * origin. When absent, the wallet's badge says "a connected app" and claims no origin.
+     * Never confuse it with `session.dapp.url`, which is dApp-CLAIMED metadata.
+     */
+    origin?: string;
     /** Called when dApp requests connection. Wallet shows approval UI.
      *  When `silent` is true, the wallet must NOT open any UI — return rejected immediately if origin is unknown. */
     onConnectionRequest: (dapp: DAppMetadata, requestedPermissions: PermissionScope[], silent?: boolean, clientInfo?: {
@@ -257,8 +375,11 @@ interface ConnectHostConfig {
         approved: boolean;
         grantedPermissions: PermissionScope[];
     }>;
-    /** Called when dApp sends an intent. Wallet opens corresponding UI. */
-    onIntent: (action: string, params: Record<string, unknown>, session: ConnectSession) => Promise<{
+    /** Called when dApp sends an intent. Wallet opens corresponding UI.
+     *  `ctx` (added in Connect 2.1) carries the host-side deadline and an AbortSignal:
+     *  the wallet MUST dismiss its modal on abort, otherwise the host's own deadline
+     *  manufactures the double-submit it was added to prevent. */
+    onIntent: (action: string, params: Record<string, unknown>, session: ConnectSession, ctx?: IntentContext) => Promise<{
         result?: unknown;
         error?: {
             code: number;
@@ -271,14 +392,47 @@ interface ConnectHostConfig {
      *  in its UI. Does NOT affect the decision (the host already decided). `silent` is true for
      *  auto-connect attempts — the wallet should not show UI for those. */
     onConnectionRejected?: (dapp: DAppMetadata | undefined, error: SphereRpcError, silent?: boolean) => void;
+    /**
+     * Notify-only: the host has just answered WALLET_LOCKED (4009) — or refused a handshake
+     * while locked. The host has ALREADY answered and never waits for this callback;
+     * throwing from it must not break the host (the host wraps the call in try/catch).
+     *
+     * THIS MUST NOT RAISE A CREDENTIAL SURFACE. A dApp request may trigger a CONSENT
+     * prompt; it may never trigger a password field. The wallet's only permitted reaction
+     * is a PASSIVE badge in its PERMANENT chrome ("N requests waiting — Unlock"); the
+     * password field appears only after a human clicks it. Volume is already bounded by
+     * checkRateLimit(), which now guards all three entry points — there is no second
+     * anti-spam mechanism, no coalescing, no cooldown and no cap by design.
+     *
+     * Also the natural telemetry seam.
+     */
+    onLockedRequest?: (ctx: LockedRequestContext) => void;
     /** Session time-to-live in ms. Default: 86400000 (24h). 0 = no expiry. */
     sessionTtlMs?: number;
+    /**
+     * The wallet-binding state the host starts in. Default: 'live'.
+     * Pass 'locked' when constructing a host while the wallet is already locked (cold start
+     * with an encrypted wallet: initialize() takes the classifyInitFailure === 'locked'
+     * branch and returns without setting Sphere) — otherwise the host starts 'live' with
+     * `sphere: null` and dereferences null on the first request.
+     * 'unavailable' is not constructible: use setUnavailable() after construction.
+     */
+    initialWalletState?: 'live' | 'locked';
     /** Optional secondary npm-SDK floor (rarely needed — the Connect protocol version is the era gate). */
     minSdkVersion?: string;
     /** Optional MINOR floor within the current Connect MAJOR. */
     minMinorVersion?: number;
     /** Max requests per second per session. Default: 20. */
     maxRequestsPerSecond?: number;
+    /** Host-side deadline for a query, in ms. Default: 25000. The host answers within it
+     *  no matter what the router does. */
+    requestDeadlineMs?: number;
+    /** Host-side deadline for an intent, in ms. Default: 90000. Fires INTENT_CANCELLED
+     *  (4200) AND aborts ctx.signal — it must cancel, not merely answer. */
+    intentDeadlineMs?: number;
+    /** Host-side deadline for onConnectionRequest, in ms. Default: 120000. A handshake
+     *  carries no id, so expiry sends the empty refusal. */
+    handshakeDeadlineMs?: number;
 }
 interface ConnectClientConfig {
     /** Transport layer for communication */
@@ -305,6 +459,9 @@ interface ConnectResult {
     readonly sessionId: string;
     readonly permissions: PermissionScope[];
     readonly identity: PublicIdentity;
+    /** True when the wallet is locked but the session is alive — a resume during a lock,
+     *  the most common entry into this feature. Requests answer 4009 until wallet:unlocked. */
+    readonly locked?: boolean;
 }
 type ConnectEventHandler = (data: unknown) => void;
 
@@ -317,7 +474,27 @@ type ConnectEventHandler = (data: unknown) => void;
  */
 
 declare class ConnectHost {
+    /** Null whenever _walletState is 'locked' or 'unavailable' (invariant B). */
     private sphere;
+    /** The wallet-binding axis. Underscored because `walletState` is the public getter.
+     *  ORTHOGONAL to `session` — a locked wallet keeps its session, a live wallet may have
+     *  none. Written only by the WALLET (setLocked / setUnavailable / updateSphere / destroy);
+     *  `session` is written by the dApp handshake, sphere_disconnect and expiry. */
+    private _walletState;
+    /** Immutable public facts about the current binding. Refreshed on every bind
+     *  (constructor, updateSphere); FROZEN by setLocked(); EMPTY after setUnavailable() and
+     *  destroy(). Never read from Sphere while locked — that is a property of the types
+     *  here, not of code review. */
+    private snapshot;
+    /** Subscription KEYS captured by setLocked() BEFORE the unsub closures are detached.
+     *  Sphere.destroy() kills those closures, so the keys are the only recoverable
+     *  information. Excludes 'identity:changed' (autoSubscribeIdentityChanged re-arms it).
+     *  A Set, not an array: handleSubscribe may be called twice for the same key while
+     *  locked. */
+    private suspendedSubscriptions;
+    /** Every accepted id, with its own host-side timer. The single convergence point for
+     *  lock / revoke / unavailable / destroy / deadline. */
+    private readonly inFlight;
     private readonly transport;
     private readonly config;
     private session;
@@ -328,6 +505,16 @@ declare class ConnectHost {
     private rateLimitResetAt;
     private unsubscribeTransport;
     constructor(config: ConnectHostConfig);
+    /** The wallet-binding axis. Orthogonal to {@link getSession}. Read-only —
+     *  transitions go through setLocked() / setUnavailable() / updateSphere(). */
+    get walletState(): WalletState;
+    /** Both axes in one read, for UI that must render "connected AND locked".
+     *  Required by the wallet's ConnectPage, which today renders a green pulsing
+     *  "Connected to {dapp}" with no regard for lock state. */
+    getState(): {
+        readonly walletState: WalletState;
+        readonly session: ConnectSession | null;
+    };
     /** Get current active session */
     getSession(): ConnectSession | null;
     /** Register an auto-approve handler for an intent action (session-scoped). */
@@ -341,19 +528,64 @@ declare class ConnectHost {
     /** Remove auto-approve for an intent action. */
     clearIntentAutoApprove(action: string): void;
     /**
-     * Update the Sphere instance (e.g. user switched address — new Sphere created).
-     * Re-subscribes auto-push events and notifies connected dApp of the new identity.
+     * Bind a (new) Sphere instance. This is BOTH the re-arm path after setLocked() /
+     * setUnavailable() AND the existing address-switch path in a live wallet.
+     *
+     * From 'live' (address switch): today's behaviour, unchanged — re-arm identity:changed,
+     *   push identity:changed. NO identity comparison: an address switch is legal.
+     *
+     * On the 'locked' -> 'live' edge, in this order:
+     *   1. compare snapshot.identity?.chainPubkey with the new Sphere's chainPubkey.
+     *      MISMATCH => revokeSession() (which pushes wallet:disconnected) and RETURN.
+     *      Never wallet:unlocked. This is the "Forgot password -> restore recovery phrase
+     *      installed a different seed behind an origin-keyed approval" guard.
+     *   2. session.expiresAt passed => revokeSession() and RETURN. A wallet:unlocked into a
+     *      dead session would make the dApp's next request answer SESSION_EXPIRED 4004.
+     *   3. rebind, refresh the snapshot, go live, re-arm identity:changed, replay every
+     *      suspended sphere_subscribe key, and ONLY THEN push wallet:unlocked with the
+     *      CURRENT identity. Re-arm BEFORE push, so a dApp reacting synchronously cannot
+     *      race its own event streams.
+     *
+     * From 'unavailable' -> 'live': rebind + refresh the snapshot, no identity check
+     *   (nothing was bound to compare against) and no event (the session is already null).
      */
     updateSphere(newSphere: unknown): void;
-    /** Revoke the current session */
-    revokeSession(): void;
     /**
-     * Notify connected dApp that wallet is locked/logged out, then revoke session.
-     * Call this BEFORE destroy() when the wallet locks so the dApp gets a clean signal
-     * instead of receiving NOT_CONNECTED errors on the next request.
+     * The wallet locked (manual lock, idle auto-lock, cross-tab broadcast, cold start).
+     * The session is PRESERVED — a lock is a state, not a teardown. Every request outside
+     * the locked allow-list is answered WALLET_LOCKED (4009) until updateSphere().
+     *
+     * Idempotent: a second call is a no-op and pushes nothing. Required, because
+     * SphereProvider.lock(), ConnectPage's `sphere → null` effect and broadcastLock()'s
+     * same-tab loopback can all fire it for one user action.
+     *
+     * ORDERING CONTRACT: call this BEFORE sphere.destroy(). The host drops its Sphere
+     * reference here; destroying first leaves in-flight requests reading a dead instance
+     * (-32603, or `undefined` returned AS SUCCESS from sphere_getIdentity).
+     */
+    setLocked(): void;
+    /**
+     * The Sphere instance is gone for a NON-LOCK reason (a generic init failure leaves
+     * `sphere === null, isLocked === false` in the wallet).
+     * This is a DEAD END: unlocking does not cure it, so it revokes the session and pushes
+     * wallet:disconnected rather than promising an unlock that cannot help.
+     * Subsequent requests answer NOT_CONNECTED (4001); handshakes get the empty refusal
+     * WITHOUT dereferencing a null Sphere.
+     *
+     * Idempotent. Pushes no 'wallet:unavailable' — there is no such event.
      */
-    notifyWalletLocked(): void;
-    /** Destroy the host, clean up all resources */
+    setUnavailable(): void;
+    /**
+     * Destroy the SESSION (logout, wallet deleted, dApp sphere_disconnect, popup
+     * beforeunload, expiry, identity mismatch at unlock). Pushes wallet:disconnected BEFORE
+     * tearing down, so the dApp stops believing it is connected instead of finding out at
+     * its next 4001.
+     *
+     * This is the TEARDOWN verb. For a lock use setLocked() — a lock never destroys the
+     * session. revokeSession() does NOT touch walletState: the two axes are orthogonal.
+     */
+    revokeSession(): void;
+    /** Destroy the host, clean up all resources. Idempotent. */
     destroy(): void;
     private handleMessage;
     private handleHandshake;
@@ -367,6 +599,39 @@ declare class ConnectHost {
     private cleanupEventSubscriptions;
     /** Push an event to the dApp without requiring a sphere_subscribe call. */
     private pushClientEvent;
+    /** The bound Sphere, or a typed refusal. The ONLY way the router may reach Sphere.
+     *  Unreachable in practice — the gate guarantees 'live' before the router is entered —
+     *  so this is defence in depth, not the primary mechanism. */
+    private requireSphere;
+    /** SNAPSHOT read. `undefined` means "we never saw an identity": callers MUST refuse,
+     *  never answer undefined-as-success — a dApp reads that as "the wallet has no
+     *  identity". Two explicit methods instead of one dual-mode method, so nobody can serve
+     *  a snapshot believing it is live. */
+    private snapshotIdentity;
+    /** InFlightRegistry.onExpire sink. Filled in a later task; declared here so the
+     *  constructor can wire it. */
+    private settleExpired;
+    /** Answer every request already in flight with one coded frame each. A request in flight
+     *  when the Sphere goes away otherwise answers -32603 with a raw JS message, returns
+     *  `undefined` AS SUCCESS (sphere_getIdentity), or — for a delegated intent — never
+     *  answers at all until the client's own 120 s timeout. */
+    private settleInFlight;
+    /**
+     * Notify-only. The host has ALREADY answered and never waits for the wallet.
+     *
+     * The wallet's only permitted reaction is a PASSIVE badge in its PERMANENT chrome; a
+     * dApp request may trigger a CONSENT prompt but never a credential prompt. Volume is
+     * bounded by checkRateLimit(), which guards all three entry points — there is no
+     * coalescing, no cooldown and no cap by design.
+     *
+     * A throwing handler must not break the host.
+     */
+    private notifyLockedRequest;
+    /** Last-resort answer for a handler that threw before its own catch could run.
+     *  Id-bearing frames get a coded error (InFlightRegistry guarantees exactly one answer
+     *  per id); a handshake gets today's empty refusal, because a failed handshake must
+     *  reveal nothing. */
+    private sendUnhandledError;
     private getPublicIdentity;
     private stripTokenSdkData;
     private sendResult;
@@ -406,6 +671,8 @@ declare class ConnectClient {
     private grantedPermissions;
     private identity;
     private walletNet;
+    private walletProto;
+    private locked;
     private connected;
     private pendingRequests;
     private eventHandlers;
@@ -426,6 +693,27 @@ declare class ConnectClient {
     get walletIdentity(): PublicIdentity | null;
     /** Wallet's active network, received during handshake. */
     get walletNetwork(): NetworkInfo | null;
+    /**
+     * The wallet's Connect protocol version, captured from the handshake response `v`.
+     * Null before the first handshake response and after a disconnect.
+     *
+     * Feature-detect with it: compare against '2.1' to decide whether the wallet can be
+     * trusted to send wallet:unlocked / wallet:disconnected. A Connect 2.0 wallet destroys
+     * the session on lock and never emits either, so a dApp waiting for them against one
+     * waits forever.
+     *
+     * CAVEAT: on an ERROR response the host echoes the dApp's own `v` back
+     * (ConnectHost.sendHandshakeResponse), so after a refused connection this may be the
+     * dApp's version rather than the wallet's. Only trust it after a successful handshake.
+     */
+    get walletProtocol(): string | null;
+    /**
+     * Whether the wallet was locked at the last handshake or lifecycle event.
+     * A locked client is still CONNECTED: `isConnected` stays true and `session` stays valid.
+     * Requests answer WALLET_LOCKED (4009) until `wallet:unlocked` arrives on the SAME
+     * session — do not disconnect, do not clear the session, do not re-handshake.
+     */
+    get walletLocked(): boolean;
     /** Send a query request and return the result */
     query<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     /** Send an intent request. The wallet will open its UI for user confirmation. */
@@ -433,9 +721,10 @@ declare class ConnectClient {
     /** Subscribe to a wallet event. Returns unsubscribe function. */
     on(event: string, handler: ConnectEventHandler): () => void;
     private handleMessage;
+    private dispatchEvent;
     private handleHandshakeResponse;
     private handlePendingResponse;
     private cleanup;
 }
 
-export { ALL_PERMISSIONS, ConnectClient, type ConnectClientConfig, ConnectError, type ConnectEventHandler, ConnectHost, type ConnectHostConfig, type ConnectResult, type ConnectSession, type ConnectTransport, type DAppMetadata, DEFAULT_PERMISSIONS, ERROR_CODES, type ErrorCode, HOST_READY_TIMEOUT, HOST_READY_TYPE, INTENT_ACTIONS, INTENT_PERMISSIONS, type IntentAction, METHOD_PERMISSIONS, type NetworkInfo, PERMISSION_SCOPES, type PermissionScope, type PublicIdentity, RPC_METHODS, type RpcMethod, SPHERE_CONNECT_NAMESPACE, SPHERE_CONNECT_VERSION, SPHERE_NETWORKS, type SphereConnectMessage, type SphereEventMessage, type SphereHandshake, type SphereIntentRequest, type SphereIntentResult, type SphereRpcError, type SphereRpcRequest, type SphereRpcResponse, WALLET_EVENTS, type WalletEvent, createRequestId, hasIntentPermission, hasMethodPermission, isSphereConnectMessage, validatePermissions };
+export { ALL_PERMISSIONS, AUTO_PUSHED_EVENTS, ConnectClient, type ConnectClientConfig, ConnectError, type ConnectEventHandler, ConnectHost, type ConnectHostConfig, type ConnectResult, type ConnectSession, type ConnectTransport, type DAppMetadata, DEFAULT_PERMISSIONS, ERROR_CODES, type ErrorCode, HOST_READY_TIMEOUT, HOST_READY_TYPE, INTENT_ACTIONS, INTENT_PERMISSIONS, type IntentAction, type IntentContext, type LockedRequestContext, METHOD_PERMISSIONS, type NetworkInfo, PERMISSION_SCOPES, type PermissionScope, type PublicIdentity, RPC_METHODS, type RpcMethod, SPHERE_CONNECT_NAMESPACE, SPHERE_CONNECT_VERSION, SPHERE_NETWORKS, type SphereConnectMessage, type SphereEventMessage, type SphereHandshake, type SphereIntentRequest, type SphereIntentResult, type SphereRpcError, type SphereRpcRequest, type SphereRpcResponse, WALLET_EVENTS, type WalletDisconnectedPayload, type WalletEvent, type WalletIdentityChangedPayload, type WalletLockedData, type WalletLockedPayload, type WalletState, type WalletUnlockedPayload, createRequestId, hasIntentPermission, hasMethodPermission, isAutoPushedEvent, isSphereConnectMessage, validatePermissions };