@tezos-x/octez.connect-dapp 4.8.4 → 4.8.5

package/README.md

@@ -21,3 +21,44 @@ This package is published from the Trilitech-maintained octez.connect repository
 
 - Trilitech publishes these packages under the `@tezos-x/octez.connect-*` scope
 - Release notes, package policy, and the current package list live in the repository README
+
+## Restoring persisted dApp sessions
+
+Applications should restore Beacon connection state from the SDK, for example by
+calling `client.getActiveAccount()`, instead of relying only on app-local markers
+such as `wallet-provider=beacon`.
+
+Treat a missing `beacon:active-account` storage entry as disconnected. Do not use
+checks like `localStorage.getItem('beacon:active-account') !== 'undefined'` as a
+valid restore guard, because `null` and corrupt stored state are not valid active
+accounts.
+
+When Beacon deactivates invalid stored active-account state, it emits
+`BeaconEvent.INVALID_ACCOUNT_DEACTIVATED` with this payload:
+
+```ts
+{
+  reason:
+    | 'missing_active_account'
+    | 'invalid_active_account_storage'
+    | 'storage_validation_failed'
+}
+```
+
+For backward compatibility, event handler types still allow this event data to
+be `undefined`. Beacon's invalid active-account deactivation path emits the
+object above; consumers that inspect the reason should handle an absent payload
+defensively if they also support direct event emission or older Beacon versions.
+
+Reason meanings:
+
+- `missing_active_account`: `beacon:active-account` pointed at an account
+  identifier that was not present in Beacon's persisted account list.
+- `invalid_active_account_storage`: Beacon could not read or parse the persisted
+  active-account/account storage needed to restore the account.
+- `storage_validation_failed`: Beacon restored an active account, but a later
+  storage validation pass still found invalid persisted session state.
+
+The default UI intentionally keeps a generic "session expired" message for end
+users, while the event payload and debug logs expose the specific restore failure
+reason for applications and diagnostics.

package/dist/cjs/dapp-client/DAppClient.d.ts

@@ -6,6 +6,20 @@ import { DAppClientOptions } from './DAppClientOptions';
 import { DappPostMessageTransport } from '../transports/DappPostMessageTransport';
 import { DappP2PTransport } from '../transports/DappP2PTransport';
 import { DappWalletConnectTransport } from '../transports/DappWalletConnectTransport';
+export interface DAppClientDisconnectOptions {
+    /**
+     * Send Beacon disconnect messages to stored wallet peers before tearing down the transport.
+     *
+     * Defaults to true because DAppClient.disconnect is the user-facing wallet logout path.
+     */
+    notifyPeers?: boolean;
+}
+export interface DAppClientRemoveAllPeersOptions {
+    /**
+     * Continue removing local peer/account state even if notifying one peer fails.
+     */
+    ignoreDisconnectErrors?: boolean;
+}
 /**
  * @publicapi
  *
@@ -39,12 +53,20 @@ export declare class DAppClient extends Client {
     protected walletConnectTransport: DappWalletConnectTransport | undefined;
     protected wcProjectId?: string;
     protected wcRelayUrl?: string;
+    /**
+     * When true, the WalletConnect transport is not built or listened to. See
+     * DAppClientOptions.disableWalletConnect.
+     */
+    protected disableWalletConnect: boolean;
     private isGetActiveAccountHandled;
     private readonly openRequestsOtherTabs;
     /**
      * A map of requests that are currently "open", meaning we have sent them to a wallet and are still awaiting a response.
      */
     private readonly openRequests;
+    private readonly acknowledgedRequests;
+    private readonly openRequestTimeouts;
+    private readonly requestTimeoutMs;
     /**
      * The currently active account. For all requests that are associated to a specific request (operation request, signing request),
      * the active account is used to determine the network and destination wallet
@@ -55,8 +77,22 @@ export declare class DAppClient extends Client {
      */
     private _activePeer;
     private _initPromise;
-    private isInitPending;
+    /**
+     * Rejector for the in-flight {@link _initPromise}. Populated while init is
+     * awaiting a peer pairing; cleared automatically when {@link _initPromise}
+     * settles. Abort paths (modal close, WC session-proposal rejection,
+     * transport-level connection failure) call this to unwedge any
+     * `await this.init()` caller, surfacing the error to handleRequestError
+     * instead of hanging.
+     */
+    private _initReject;
+    private _initSubstratePairing;
+    private _requestPermissionsPromise;
+    private _requestPermissionsKey;
+    private _sdkSecretSeedPromise;
+    private destroyed;
     private readonly activeAccountLoaded;
+    private readonly storageValidated;
     private readonly appMetadataManager;
     private readonly disclaimerText?;
     private readonly errorMessages;
@@ -64,15 +100,22 @@ export declare class DAppClient extends Client {
     private readonly storageValidator;
     private readonly beaconIDB;
     private debounceSetActiveAccount;
+    private hasEmittedInvalidAccountDeactivated;
+    private _disconnectPromise?;
+    private _disconnectNotifyPeers;
     private multiTabChannel;
     constructor(config: DAppClientOptions);
     private checkIfBCLeaderExists;
     private onElectedLeaderhandler;
     private onBCMessageHandler;
     private prepareRequest;
+    private buildDelegatedRequestError;
     private createStateSnapshot;
     private initUserID;
     initInternalTransports(): Promise<void>;
+    private getOrCreateSDKSecretSeed;
+    private loadOrCreateSDKSecretSeed;
+    private isValidSDKSecretSeed;
     private initEvents;
     private onRelayerError;
     private wcToastHandler;
@@ -85,11 +128,30 @@ export declare class DAppClient extends Client {
      * If you wish to disconnect your dApp, use `disconnect` instead.
      */
     destroy(): Promise<void>;
+    private destroyInternalTransports;
+    private abortPendingInit;
+    private createAbortedError;
+    /**
+     * @internal
+     */
+    isDestroyed(): boolean;
+    private assertNotDestroyed;
     init(transport?: Transport<any>, substratePairing?: boolean): Promise<TransportType>;
+    /**
+     * Attach a settle observer to {@link _initPromise} that drops
+     * {@link _initReject} once the promise settles (resolved or rejected).
+     * Errors on the observer chain are swallowed; only the original
+     * {@link _initPromise} surfaces them to its awaiters.
+     */
+    private clearInitRejectOnSettle;
     /**
      * Returns the active account
      */
     getActiveAccount(): Promise<AccountInfo | undefined>;
+    private retainStorageValidationPromise;
+    private deactivateInvalidAccountState;
+    private repairMissingActiveAccount;
+    private hasStoredActiveAccountPointer;
     private isInvalidState;
     private resetInvalidState;
     /**
@@ -98,6 +160,8 @@ export declare class DAppClient extends Client {
      * @param account The account that will be set as the active account
      */
     setActiveAccount(account?: AccountInfo): Promise<void>;
+    private isActiveAccountAlreadyCleared;
+    private recoverActiveAccountFromAccountsChange;
     /**
      * Clear the active account
      */
@@ -115,7 +179,6 @@ export declare class DAppClient extends Client {
     private tryToAppSwitch;
     private addQueryParam;
     private buildPayload;
-    private updateMetricsStorage;
     private sendMetrics;
     private checkMakeRequest;
     /**
@@ -137,7 +200,7 @@ export declare class DAppClient extends Client {
     /**
      * Remove all peers and all accounts that have been connected through those peers
      */
-    removeAllPeers(sendDisconnectToPeers?: boolean): Promise<void>;
+    removeAllPeers(sendDisconnectToPeers?: boolean, options?: DAppClientRemoveAllPeersOptions): Promise<void>;
     /**
      * Allows the user to subscribe to specific events that are fired in the SDK
      *
@@ -166,6 +229,9 @@ export declare class DAppClient extends Client {
      * @param input The message details we need to prepare the PermissionRequest message.
      */
     requestPermissions(input?: RequestPermissionInput): Promise<PermissionResponseOutput>;
+    private requestPermissionsInternal;
+    private getPermissionRequestScopes;
+    private getPermissionRequestKey;
     /**
      * Send a proof of event request to the wallet. The wallet will either accept or decline the challenge.
      * If it is accepted, the challenge will be stored, meaning that even if the user refresh the page, the DAppClient will keep checking if the challenge has been fulfilled.
@@ -230,6 +296,29 @@ export declare class DAppClient extends Client {
      */
     private removeAccountsForPeers;
     private removeAccountsForPeerIds;
+    /**
+     * Run the standard request-error side effects (abort/error metric,
+     * timer stop, {@link handleRequestError}) on a single awaited control
+     * flow so callers can re-throw the original {@link ErrorResponse} without
+     * leaking an UnhandledPromiseRejection.
+     *
+     * Why this exists: every request method historically used a fire-and-
+     * forget `res.catch(handler)` whose handler did `throw await
+     * this.handleRequestError(...)`. The catch returned a detached promise
+     * nobody awaited; `handleRequestError`'s thrown wrapped error became an
+     * unhandled rejection. The bug rarely surfaced before the dapp-init
+     * promise was made rejectable, because pre-pairing rejection paths used
+     * to hang instead of routing through these handlers. Once init started
+     * rejecting reliably, the unhandled rejection started firing on every
+     * WC session-proposal rejection. We swallow the wrapped throw here so
+     * callers can re-throw the original `ErrorResponse`, matching the
+     * post-pairing rejection contract at the openRequest path.
+     *
+     * @param request The request we sent
+     * @param requestError The error we received
+     * @param logId The {@link logger.time} label opened for this request
+     */
+    private runRequestErrorSideEffects;
     /**
      * This message handles errors that we receive from the wallet.
      *
@@ -268,7 +357,22 @@ export declare class DAppClient extends Client {
      */
     private makeRequestV3;
     private makeRequestBC;
-    disconnect(): Promise<void>;
+    /**
+     * Disconnects all resolved transports (postMessage, P2P, WalletConnect), removes their peers,
+     * and clears active account state. After calling, the DAppClient remains usable for a new
+     * requestPermissions().
+     */
+    disconnect(options?: DAppClientDisconnectOptions): Promise<void>;
+    private disconnectInternal;
+    private getInitializedTransports;
+    private getResolvedTransports;
+    private clearInternalTransportReferences;
+    private removeAllPeersFromTransports;
+    private getUniquePeerNotifications;
+    private getPeerNotificationKey;
+    private disconnectResolvedTransports;
+    private hasClientCleanup;
+    private isTransportConnected;
     /**
      * Adds a requests to the "openRequests" set so we know what messages have already been answered/handled.
      *
@@ -276,6 +380,11 @@ export declare class DAppClient extends Client {
      * @param promise A promise that resolves once the response for that specific message is received
      */
     private addOpenRequest;
+    private addOpenRequestTimeout;
+    private clearOpenRequest;
+    private clearOpenRequestTimeout;
+    private clearAllOpenRequestTimeouts;
+    private abortOpenRequests;
     private sendNotificationWithAccessToken;
     private onNewAccount;
 }