@reown/appkit-controllers 1.8.14 → 1.8.15-23bb47b934ad6e2db0777e70bb49289c5630f47f.0

package/dist/types/exports/index.d.ts

@@ -19,7 +19,7 @@ export type { ConnectionControllerClient, ConnectionControllerState } from '../s
 export type { ConnectExternalOptions } from '../src/controllers/ConnectionController.js';
 export { ConnectorController } from '../src/controllers/ConnectorController.js';
 export { ConnectorControllerUtil } from '../src/utils/ConnectorControllerUtil.js';
-export type { ConnectorControllerState, ConnectorWithProviders } from '../src/controllers/ConnectorController.js';
+export type { ConnectorControllerState } from '../src/controllers/ConnectorController.js';
 export { SnackController } from '../src/controllers/SnackController.js';
 export type { SnackControllerState } from '../src/controllers/SnackController.js';
 export { ApiController } from '../src/controllers/ApiController.js';
@@ -55,7 +55,9 @@ export { ExchangeController } from '../src/controllers/ExchangeController.js';
 export type { ExchangeControllerState } from '../src/controllers/ExchangeController.js';
 export { AssetUtil } from '../src/utils/AssetUtil.js';
 export { ConstantsUtil } from '../src/utils/ConstantsUtil.js';
+export { WalletUtil } from '../src/utils/WalletUtil.js';
 export { CoreHelperUtil, type OpenTarget } from '../src/utils/CoreHelperUtil.js';
+export { ConnectorUtil } from '../src/utils/ConnectorUtil.js';
 export { StorageUtil } from '../src/utils/StorageUtil.js';
 export { RouterUtil } from '../src/utils/RouterUtil.js';
 export { OptionsUtil } from '../src/utils/OptionsUtil.js';
@@ -69,5 +71,6 @@ export type { Exchange, GetExchangesParams, PayUrlParams, PaymentAsset, CurrentP
 export { FetchUtil } from '../src/utils/FetchUtil.js';
 export type * from '../src/utils/TypeUtil.js';
 export type * from '../src/utils/SIWXUtil.js';
+export type { WalletItem } from '../src/utils/ConnectUtil.js';
 export * from '../src/utils/ChainControllerUtil.js';
 export * from '../src/utils/WalletConnectUtil.js';

package/dist/types/exports/react.d.ts

@@ -1,4 +1,5 @@
 import { type ChainNamespace, type Connection } from '@reown/appkit-common';
+import { type WalletItem } from '../src/utils/ConnectUtil.js';
 import type { UseAppKitAccountReturn, UseAppKitNetworkReturn } from '../src/utils/TypeUtil.js';
 export type { Connection } from '@reown/appkit-common';
 interface DisconnectParams {
@@ -75,3 +76,71 @@ export declare function useAppKitConnection({ namespace, onSuccess, onError }: U
     switchConnection: ({ connection: _connection, address }: SwitchConnectionParams) => Promise<void>;
     deleteConnection: ({ address, connectorId }: DeleteRecentConnectionProps) => void;
 };
+export interface UseAppKitWalletsReturn {
+    /**
+     * List of wallets for the initial connect view including WalletConnect wallet and injected wallets together. If user doesn't have any injected wallets, it'll fill the list with most ranked WalletConnect wallets.
+     */
+    wallets: WalletItem[];
+    /**
+     * List of WalletConnect wallets from Wallet Guide API. Useful to display all available WalletConnect wallets in a separate Search Wallets view.
+     * @see https://walletguide.walletconnect.network/.
+     */
+    wcWallets: WalletItem[];
+    /**
+     * Boolean that indicates if WalletConnect wallets are being fetched.
+     */
+    isFetchingWallets: boolean;
+    /**
+     * Boolean that indicates if a WalletConnect URI is being fetched.
+     */
+    isFetchingWcUri: boolean;
+    /**
+     * Boolean that indicates if the AppKit is initialized. It's useful to render a fallback UI when the AppKit initializes and detects all injected wallets.
+     */
+    isInitialized: boolean;
+    /**
+     * The current WalletConnect URI for QR code display. This is set when connecting to a WalletConnect wallet. Reset with resetWcUri().
+     */
+    wcUri?: string;
+    /**
+     * The wallet currently being connected to. This is set when a connection is initiated and cleared when it completes or fails. For WalletConnect wallets, resetWcUri() should be called to clear the state.
+     */
+    connectingWallet?: WalletItem;
+    /**
+     * The current page number of WalletConnect wallets.
+     */
+    page: number;
+    /**
+     * The total number of available WalletConnect wallets based on the AppKit configurations and given parameters.
+     */
+    count: number;
+    /**
+     * Function to fetch WalletConnect wallets from the explorer API. Allows to list, search and paginate through the wallets.
+     * @param options - Options for fetching wallets
+     * @param options.page - Page number to fetch (default: 1)
+     * @param options.query - Search query to filter wallets (default: '')
+     */
+    fetchWallets: (options?: {
+        page?: number;
+        query?: string;
+    }) => Promise<void>;
+    /**
+     * Function to connect to a wallet.
+     * - For WalletConnect wallets: initiates WC connection and returns the URI with the `wcUri` state.
+     * - For injected connectors: triggers the extension/wallet directly.
+     *
+     * @param wallet - The wallet item to connect to
+     * @param callbacks - Success and error callbacks
+     * @returns Promise that resolves when connection completes or rejects on error
+     */
+    connect: (wallet: WalletItem, namespace?: ChainNamespace) => Promise<void>;
+    /**
+     * Function to reset the WC URI. Useful to keep `connectingWallet` state sync with the WC URI. Can be called when the QR code is closed.
+     */
+    resetWcUri: () => void;
+}
+/**
+ * Headless hook for wallet connection.
+ * Provides all the data and functions needed to build a custom connect UI.
+ */
+export declare function useAppKitWallets(): UseAppKitWalletsReturn;

package/dist/types/src/controllers/ConnectionController.d.ts

@@ -99,6 +99,7 @@ export interface ConnectionControllerState {
     };
     wcBasic?: boolean;
     wcError?: boolean;
+    wcFetchingUri: boolean;
     recentWallet?: WcWallet;
     buffering: boolean;
     status?: 'connecting' | 'connected' | 'disconnected';

package/dist/types/src/controllers/ConnectorController.d.ts

@@ -1,8 +1,5 @@
 import { type ChainNamespace } from '@reown/appkit-common';
-import type { AuthConnector, Connector, WcWallet } from '../utils/TypeUtil.js';
-export interface ConnectorWithProviders extends Connector {
-    connectors?: Connector[];
-}
+import type { AuthConnector, Connector, ConnectorWithProviders, WcWallet } from '../utils/TypeUtil.js';
 export interface ConnectorControllerState {
     allConnectors: Connector[];
     connectors: ConnectorWithProviders[];
@@ -32,12 +29,11 @@ export declare const ConnectorController: {
     addConnector(connector: Connector | AuthConnector): void;
     getAuthConnector(chainNamespace?: ChainNamespace): AuthConnector | undefined;
     getAnnouncedConnectorRdns(): (string | undefined)[];
-    getConnectorById(id: string): Connector | undefined;
-    getConnector({ id, rdns, namespace }: {
-        id?: string;
-        rdns?: string | null;
-        namespace?: ChainNamespace;
-    }): Connector | undefined;
+    getConnectorById(id: string): ConnectorWithProviders | undefined;
+    getConnector({ id, namespace }: {
+        id: string;
+        namespace: ChainNamespace;
+    }): ConnectorWithProviders | undefined;
     syncIfAuthConnector(connector: Connector | AuthConnector): void;
     /**
      * Returns the connectors filtered by namespace.

package/dist/types/src/controllers/OptionsController.d.ts

@@ -1697,6 +1697,7 @@ export declare const OptionsController: {
             readonly collapseWallets?: boolean | undefined;
             readonly pay?: boolean | undefined;
             readonly reownAuthentication?: boolean | undefined;
+            readonly headless?: boolean | undefined;
         } | undefined;
         readonly siwx?: {
             readonly createMessage: (input: import("../utils/SIWXUtil.js").SIWXMessage.Input) => Promise<import("../utils/SIWXUtil.js").SIWXMessage>;
@@ -1725,7 +1726,7 @@ export declare const OptionsController: {
          */
          | undefined;
         readonly defaultAccountTypes: {
-            readonly eip155?: "eoa" | "smartAccount" | undefined;
+            readonly eip155?: "smartAccount" | "eoa" | undefined;
             readonly solana?: "eoa" | undefined;
             readonly bip122?: "payment" | "ordinal" | "stx" | undefined;
             readonly polkadot?: "eoa" | undefined;
@@ -1784,6 +1785,7 @@ export declare const OptionsController: {
             readonly payWithExchange?: boolean | undefined;
             readonly payments?: boolean | undefined;
             readonly onramp?: false | readonly "meld"[] | undefined;
+            readonly headless?: boolean | undefined;
         } | undefined;
     };
 };

package/dist/types/src/controllers/PublicStateController.d.ts

@@ -1,4 +1,5 @@
 import type { CaipNetworkId, ChainNamespace } from '@reown/appkit-common';
+import type { WalletItem } from '../utils/ConnectUtil.js';
 export interface PublicStateControllerState {
     /**
      * @description Indicates if the AppKit is loading.
@@ -25,6 +26,11 @@ export interface PublicStateControllerState {
      * @type {boolean}
      */
     initialized: boolean;
+    /**
+     * @description Indicates the wallet item that is currently being connecting.
+     * @type {WalletItem | undefined}
+     */
+    connectingWallet: WalletItem | undefined;
 }
 export declare const PublicStateController: {
     state: PublicStateControllerState;

package/dist/types/src/utils/ApiControllerUtil.d.ts

@@ -0,0 +1,8 @@
+import type { WcWallet } from './TypeUtil.js';
+export declare const ApiControllerUtil: {
+    /**
+     * Finds a wallet by ID across all wallet arrays (wallets, recommended, featured, search, etc.)
+     * This is useful when a wallet might be in different arrays depending on the context
+     */
+    getWalletById(walletId: string | undefined): WcWallet | undefined;
+};

package/dist/types/src/utils/AssetUtil.d.ts

@@ -13,4 +13,22 @@ export declare const AssetUtil: {
     getConnectorImage(connector?: Connector): string | undefined;
     getChainImage(chain: ChainNamespace): string | undefined;
     getTokenImage(symbol?: string): string | undefined;
+    /**
+     * Get the explorer wallet's image URL for the given image ID.
+     * @param imageId - The image id of the wallet.
+     * @returns The image URL for the wallet.
+     */
+    getWalletImageUrl(imageId: string | undefined): string;
+    /**
+     * Get the public asset's image URL with the given image ID.
+     * @param imageId - The image id of the asset.
+     * @returns The image URL for the asset.
+     */
+    getAssetImageUrl(imageId: string | undefined): string;
+    /**
+     * Get the image URL for the given chain namespace.
+     * @param chainNamespace - The chain namespace to get the image URL for.
+     * @returns The image URL for the chain namespace.
+     */
+    getChainNamespaceImageUrl(chainNamespace: ChainNamespace): string;
 };

package/dist/types/src/utils/ChainControllerUtil.d.ts

@@ -17,7 +17,7 @@ export declare function getActiveNetworkTokenAddress(): string;
  * @param namespace - The namespace of the account
  * @returns The preferred account type
  */
-export declare function getPreferredAccountType(namespace: ChainNamespace | undefined): "eoa" | "smartAccount" | "payment" | "ordinal" | "stx" | undefined;
+export declare function getPreferredAccountType(namespace: ChainNamespace | undefined): "payment" | "ordinal" | "stx" | "smartAccount" | "eoa" | undefined;
 /**
  * Get the active CAIP network for a given chain namespace, if no namespace is provided, it returns the active CAIP network
  * @param chainNamespace - The chain namespace to get the active CAIP network for

package/dist/types/src/utils/ConnectUtil.d.ts

@@ -0,0 +1,54 @@
+import type { ChainNamespace } from '@reown/appkit-common';
+import type { ConnectorItemWithKind, ConnectorWithProviders, WcWallet } from './TypeUtil.js';
+export type WalletItem = {
+    id: string;
+    name: string;
+    imageUrl: string;
+    connectors: {
+        id: string;
+        rdns?: string;
+        chain: ChainNamespace;
+        chainImageUrl?: string;
+    }[];
+    walletInfo: {
+        description?: WcWallet['description'];
+        supportedChains?: WcWallet['chains'];
+        supportedNamespaces?: ChainNamespace[];
+        website?: WcWallet['homepage'];
+        installationLinks?: {
+            appStore?: WcWallet['app_store'];
+            playStore?: WcWallet['play_store'];
+            chromeStore?: WcWallet['chrome_store'];
+            desktopLink?: WcWallet['desktop_link'];
+        };
+        deepLink?: WcWallet['mobile_link'];
+        isCertified?: boolean;
+    };
+    isInjected: boolean;
+    isRecent: boolean;
+};
+export declare const ConnectUtil: {
+    /**
+     * Maps the initial connect view wallets into WalletItems. Includes WalletConnect wallet and injected wallets. If user doesn't have any injected wallets, it'll fill the list with most ranked WalletConnect wallets.
+     * @returns The WalletItems for the initial connect view.
+     */
+    getInitialWallets(): WalletItem[];
+    /**
+     * Maps the WalletGuide explorer wallets to WalletItems including search results.
+     * @returns The WalletItems for the WalletGuide explorer wallets.
+     */
+    getWalletConnectWallets(wcAllWallets: WcWallet[], wcSearchWallets: WcWallet[]): WalletItem[];
+    /**
+     * Maps the connector to a WalletItem.
+     * @param connector - The connector to map to a WalletItem.
+     * @param subType - The subtype of the connector.
+     * @returns The WalletItem for the connector.
+     */
+    mapConnectorToWalletItem(connector: ConnectorWithProviders, subType: ConnectorItemWithKind["subtype"]): WalletItem;
+    /**
+     * Maps the WalletGuide explorer wallet to a WalletItem.
+     * @param w - The WalletGuide explorer wallet.
+     * @returns The WalletItem for the WalletGuide explorer wallet.
+     */
+    mapWalletToWalletItem(w: WcWallet): WalletItem;
+};

package/dist/types/src/utils/ConnectionControllerUtil.d.ts

@@ -1,5 +1,6 @@
 import { type ChainNamespace } from '@reown/appkit-common';
 import type { Connection } from '@reown/appkit-common';
+import type { WcWallet } from './TypeUtil.js';
 interface ExcludeConnectorAddressFromConnectionsParamters {
     connections: Connection[];
     connectorId?: string;
@@ -14,5 +15,6 @@ export declare const ConnectionControllerUtil: {
         connections: Connection[];
         recentConnections: Connection[];
     };
+    onConnectMobile(wallet: WcWallet | undefined): void;
 };
 export {};

package/dist/types/src/utils/ConnectorUtil.d.ts

@@ -0,0 +1,74 @@
+import type { Connector, ConnectorOrWalletItem, ConnectorTypeOrder, ConnectorWithProviders, CustomWallet, SocialProvider, WcWallet } from './TypeUtil.js';
+interface GetConnectorTypeOrderParameters {
+    recommended: WcWallet[];
+    featured: WcWallet[];
+    custom: CustomWallet[] | undefined;
+    recent: WcWallet[];
+    announced: WcWallet[];
+    injected: WcWallet[];
+    multiChain: WcWallet[];
+    external: WcWallet[];
+    overriddenConnectors?: ConnectorTypeOrder[];
+}
+export declare const ConnectorUtil: {
+    getConnectorsByType(connectors: ConnectorWithProviders[], recommended: WcWallet[], featured: WcWallet[]): {
+        custom: CustomWallet[] | undefined;
+        recent: WcWallet[];
+        external: ConnectorWithProviders[];
+        multiChain: ConnectorWithProviders[];
+        announced: ConnectorWithProviders[];
+        injected: ConnectorWithProviders[];
+        recommended: WcWallet[];
+        featured: WcWallet[];
+    };
+    showConnector(connector: ConnectorWithProviders): boolean;
+    /**
+     * Returns true if the user is connected to a WalletConnect connector in the any of the available namespaces.
+     * @returns boolean
+     */
+    getIsConnectedWithWC(): boolean;
+    /**
+     * Returns the connector positions in the order of the user's preference.
+     * @returns ConnectorTypeOrder[]
+     */
+    getConnectorTypeOrder({ recommended, featured, custom, recent, announced, injected, multiChain, external, overriddenConnectors }: GetConnectorTypeOrderParameters): string[];
+    sortConnectorsByExplorerWallet(connectors: ConnectorWithProviders[]): ConnectorWithProviders[];
+    /**
+     * Returns the priority of a connector. Base Account has highest priority, followed by Coinbase then the rest.
+     *
+     * This is needed because Base Account and Coinbase share the same explorer wallet ID.
+     * Without prioritization, selecting Base Account could incorrectly trigger the Coinbase Wallet extension.
+     *
+     * @param connector - The connector to get the priority of.
+     * @returns The priority of the connector.
+     */
+    getPriority(connector: ConnectorWithProviders): 1 | 0 | 2;
+    /**
+     * Sorts connectors by priority.
+     * @param connectors - The connectors to sort.
+     * @returns Sorted connectors.
+     */
+    sortConnectorsByPriority(connectors: ConnectorWithProviders[]): ConnectorWithProviders[];
+    getAuthName({ email, socialUsername, socialProvider }: {
+        email: string;
+        socialUsername?: string | null;
+        socialProvider?: SocialProvider | null;
+    }): string;
+    fetchProviderData(connector: Connector): Promise<{
+        accounts: string[];
+        chainId: number | undefined;
+    }>;
+    /**
+     * Filter out duplicate custom wallets by RDNS
+     * @param wallets
+     */
+    getFilteredCustomWallets(wallets: WcWallet[]): WcWallet[];
+    hasWalletConnector(wallet: WcWallet): boolean;
+    isWalletCompatibleWithCurrentChain(wallet: WcWallet): boolean;
+    getFilteredRecentWallets(): WcWallet[];
+    getCappedRecommendedWallets(wallets: WcWallet[]): WcWallet[];
+    processConnectorsByType(connectors: ConnectorWithProviders[], shouldFilter?: boolean): ConnectorWithProviders[];
+    connectorList(): ConnectorOrWalletItem[];
+    hasInjectedConnectors(): number;
+};
+export {};

package/dist/types/src/utils/ConstantsUtil.d.ts

@@ -1,4 +1,5 @@
 import { type ChainNamespace, type OnRampProvider, type SocialProvider, type SwapProvider } from '@reown/appkit-common';
+import type { ConnectMethod } from './TypeUtil.js';
 export declare const ONRAMP_PROVIDERS: {
     label: string;
     name: string;
@@ -58,6 +59,7 @@ export declare const ConstantsUtil: {
         payWithExchange: boolean;
         payments: boolean;
         reownAuthentication: boolean;
+        headless: boolean;
     };
     DEFAULT_REMOTE_FEATURES_DISABLED: {
         readonly email: false;
@@ -68,12 +70,13 @@ export declare const ConstantsUtil: {
         readonly reownBranding: false;
         readonly emailCapture: false;
         readonly reownAuthentication: false;
+        readonly headless: false;
     };
     DEFAULT_FEATURES: {
         receive: true;
         send: true;
         emailShowWallets: true;
-        connectorTypeOrder: ("custom" | "walletConnect" | "recent" | "injected" | "featured" | "external" | "recommended")[];
+        connectorTypeOrder: ("walletConnect" | "recent" | "injected" | "featured" | "custom" | "external" | "recommended")[];
         analytics: true;
         allWallets: true;
         legalCheckbox: false;
@@ -83,6 +86,7 @@ export declare const ConstantsUtil: {
         connectMethodsOrder: undefined;
         pay: false;
         reownAuthentication: false;
+        headless: false;
     };
     DEFAULT_SOCIALS: SocialProvider[];
     DEFAULT_ACCOUNT_TYPES: {
@@ -103,4 +107,6 @@ export declare const ConstantsUtil: {
     SIWX_DEFAULTS: {
         readonly signOutOnDisconnect: true;
     };
+    MANDATORY_WALLET_IDS_ON_MOBILE: (string | undefined)[];
+    DEFAULT_CONNECT_METHOD_ORDER: ConnectMethod[];
 };

package/dist/types/src/utils/TypeUtil.d.ts

@@ -71,6 +71,9 @@ export type Connector = {
     connectors?: Connector[];
     explorerWallet?: WcWallet;
 };
+export interface ConnectorWithProviders extends Connector {
+    connectors?: Connector[];
+}
 export interface AuthConnector extends Connector {
     provider: W3mFrameProvider;
     socials?: SocialProvider[];
@@ -95,6 +98,7 @@ export interface WcWallet {
     id: string;
     name: string;
     badge_type?: BadgeType;
+    description?: string;
     chains?: CaipNetworkId[];
     homepage?: string;
     image_id?: string;
@@ -1067,6 +1071,7 @@ export type RemoteFeatures = {
     payWithExchange?: boolean;
     payments?: boolean;
     onramp?: OnRampProvider[] | false;
+    headless?: boolean;
 };
 export type Features = {
     /**
@@ -1165,6 +1170,12 @@ export type Features = {
      * @type {boolean}
      */
     reownAuthentication?: boolean;
+    /**
+     * @description Enable or disable the AppKit Headless mode to build custom connect user interfaces.
+     * @default false
+     * @type {boolean}
+     */
+    headless?: boolean;
 };
 export type FeaturesKeys = Exclude<keyof Features, 'swaps' | 'onramp' | 'email' | 'socials' | 'history'>;
 export type WalletGuideType = 'get-started' | 'explore';
@@ -1196,13 +1207,13 @@ export type ConnectionStatus = 'connected' | 'disconnected' | 'connecting' | 're
 export type PreferredAccountTypes = {
     [Key in keyof NamespaceTypeMap]?: NamespaceTypeMap[Key];
 };
-export type FeatureID = 'multi_wallet' | 'activity' | 'onramp' | 'swap' | 'social_login' | 'reown_branding' | 'email_capture' | 'fund_from_exchange' | 'payments' | 'reown_authentication';
+export type FeatureID = 'multi_wallet' | 'activity' | 'onramp' | 'swap' | 'social_login' | 'reown_branding' | 'email_capture' | 'fund_from_exchange' | 'payments' | 'reown_authentication' | 'headless';
 export interface BaseFeature<T extends FeatureID, C extends string[] | null> {
     id: T;
     isEnabled: boolean;
     config: C;
 }
-export type TypedFeatureConfig = BaseFeature<'activity', null | []> | BaseFeature<'onramp', OnRampProvider[]> | BaseFeature<'swap', SwapProvider[]> | BaseFeature<'social_login', (SocialProvider | 'email')[]> | BaseFeature<'reown_branding', null | []> | BaseFeature<'multi_wallet', null | []> | BaseFeature<'email_capture', EmailCaptureOptions[]>;
+export type TypedFeatureConfig = BaseFeature<'activity', null | []> | BaseFeature<'onramp', OnRampProvider[]> | BaseFeature<'swap', SwapProvider[]> | BaseFeature<'social_login', (SocialProvider | 'email')[]> | BaseFeature<'reown_branding', null | []> | BaseFeature<'multi_wallet', null | []> | BaseFeature<'email_capture', EmailCaptureOptions[]> | BaseFeature<'headless', null | []>;
 export type ApiGetProjectConfigResponse = {
     features: TypedFeatureConfig[];
 };
@@ -1278,6 +1289,12 @@ export type FeatureConfigMap = {
         returnType: boolean;
         isLegacy: false;
     };
+    headless: {
+        apiFeatureName: 'headless';
+        localFeatureName: 'headless';
+        returnType: boolean;
+        isLegacy: false;
+    };
 };
 export type FeatureKey = keyof FeatureConfigMap;
 export type Tier = 'none' | 'starter' | 'pro' | 'enteprise';
@@ -1285,4 +1302,15 @@ export type ProjectLimits = {
     isAboveRpcLimit: boolean;
     isAboveMauLimit: boolean;
 };
+export type ConnectorItemWithKind = {
+    kind: 'connector';
+    subtype: 'injected' | 'announced' | 'multiChain' | 'external' | 'walletConnect';
+    connector: ConnectorWithProviders;
+};
+export type WalletItemWithKind = {
+    kind: 'wallet';
+    subtype: 'featured' | 'recommended' | 'custom' | 'recent';
+    wallet: WcWallet;
+};
+export type ConnectorOrWalletItem = ConnectorItemWithKind | WalletItemWithKind;
 export {};