@reown/appkit-controllers 1.8.21 → 1.8.22-headless-js.0

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

@@ -73,5 +73,7 @@ export { MobileWalletUtil } from '../src/utils/MobileWallet.js';
 export type * from '../src/utils/TypeUtil.js';
 export type * from '../src/utils/SIWXUtil.js';
 export type { WalletItem } from '../src/utils/ConnectUtil.js';
+export { HeadlessWalletUtil } from '../src/utils/HeadlessWalletUtil.js';
+export type { ConnectOptions, FetchWalletsOptions, WalletListSnapshot } from '../src/utils/HeadlessWalletUtil.js';
 export * from '../src/utils/ChainControllerUtil.js';
 export * from '../src/utils/WalletConnectUtil.js';

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

@@ -1,6 +1,7 @@
 import { type CaipNetwork, type ChainNamespace, type Connection } from '@reown/appkit-common';
 import { type WalletItem } from '../src/utils/ConnectUtil.js';
-import type { BadgeType, UseAppKitAccountReturn, UseAppKitNetworkReturn } from '../src/utils/TypeUtil.js';
+import { type ConnectOptions, type FetchWalletsOptions } from '../src/utils/HeadlessWalletUtil.js';
+import type { UseAppKitAccountReturn, UseAppKitNetworkReturn } from '../src/utils/TypeUtil.js';
 export type { Connection } from '@reown/appkit-common';
 interface DisconnectParams {
     id?: string;
@@ -25,9 +26,7 @@ interface DeleteRecentConnectionProps {
     address: string;
     connectorId: string;
 }
-export interface ConnectOptions {
-    wcPayUrl?: string;
-}
+export type { ConnectOptions, FetchWalletsOptions } from '../src/utils/HeadlessWalletUtil.js';
 export declare function useAppKitProvider<T>(chainNamespace: ChainNamespace): {
     walletProvider: T;
     walletProviderType: import("./index.js").ConnectorType | undefined;
@@ -81,29 +80,6 @@ export declare function useAppKitConnection({ namespace, onSuccess, onError }: U
     switchConnection: ({ connection: _connection, address }: SwitchConnectionParams) => Promise<void>;
     deleteConnection: ({ address, connectorId }: DeleteRecentConnectionProps) => void;
 };
-export interface FetchWalletsOptions {
-    /** Page number to fetch (default: 1) */
-    page?: number;
-    /** @deprecated Use `search` instead */
-    query?: string;
-    /** Search query to filter wallets. When provided, switches to search mode. */
-    search?: string;
-    /** Number of entries per page. Defaults to 40 for list mode, 100 for search mode. */
-    entries?: number;
-    /** Filter wallets by badge type ('none' | 'certified') */
-    badge?: BadgeType;
-    /** Wallet IDs to include. Overrides the global includeWalletIds config when provided. */
-    include?: string[];
-    /** Wallet IDs to exclude. Overrides the default exclude list when provided. */
-    exclude?: string[];
-    /**
-     * Include wallets that support WalletConnect Pay but are not v2-compatible.
-     * By default these are filtered out. Enable for WalletConnect Pay surfaces.
-     */
-    includePayOnly?: boolean;
-    /** Sort mode. 'wcpay' bubbles WalletConnect Pay-supporting wallets to the top. */
-    sort?: 'default' | 'wcpay';
-}
 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.

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

@@ -0,0 +1,89 @@
+import type { ChainNamespace } from '@reown/appkit-common';
+import { type WalletItem } from './ConnectUtil.js';
+/** Options for {@link HeadlessWalletUtil.fetchWallets}. */
+export interface FetchWalletsOptions {
+    /** Page number to fetch (default: 1) */
+    page?: number;
+    /** @deprecated Use `search` instead */
+    query?: string;
+    /** Search query to filter wallets. When provided, switches to search mode. */
+    search?: string;
+    /** Number of entries per page. Defaults to 40 for list mode, 100 for search mode. */
+    entries?: number;
+    /** Filter wallets by badge type ('none' | 'certified') */
+    badge?: 'none' | 'certified';
+    /** Wallet IDs to include. Overrides the global includeWalletIds config when provided. */
+    include?: string[];
+    /** Wallet IDs to exclude. Overrides the default exclude list when provided. */
+    exclude?: string[];
+    /**
+     * Include wallets that support WalletConnect Pay but are not v2-compatible.
+     * By default these are filtered out. Enable for WalletConnect Pay surfaces.
+     */
+    includePayOnly?: boolean;
+    /** Sort mode. 'wcpay' bubbles WalletConnect Pay-supporting wallets to the top. */
+    sort?: 'default' | 'wcpay';
+}
+/** Options for {@link HeadlessWalletUtil.connect} / {@link HeadlessWalletUtil.getWalletConnectUri}. */
+export interface ConnectOptions {
+    /**
+     * A WalletConnect Pay deeplink appended to the WC URI, so a WCPay-capable wallet
+     * returns to — and processes — this payment after pairing.
+     */
+    wcPayUrl?: string;
+}
+/** The headless wallet list, read imperatively. */
+export interface WalletListSnapshot {
+    /** Initial connect-view wallets: installed extensions + top-ranked WalletConnect wallets. */
+    wallets: WalletItem[];
+    /** The full WalletGuide WalletConnect list (with the current search results applied). */
+    wcWallets: WalletItem[];
+    /** Current page of the WalletConnect list. */
+    page: number;
+    /** Total number of available WalletConnect wallets for the current parameters. */
+    count: number;
+}
+/**
+ * Framework-agnostic headless wallet-list logic — the imperative core behind the
+ * `useAppKitWallets` React hook and the `AppKit` client's wallet methods.
+ *
+ * AppKit runs headless (no modal): the host renders its own picker and connects a
+ * chosen wallet programmatically. That orchestration (list / search / paginate the
+ * WalletGuide wallets, fetch the WalletConnect URI, and connect injected / API / mobile
+ * wallets) lived only inside the React hook; lifting it here lets a non-React host
+ * (e.g. `@walletconnect/pay-appkit`) drive the same flow through `appKit.*` methods,
+ * with the hook and the client sharing one tested code path.
+ *
+ * Reads/writes the global controllers directly (valtio singletons), so it takes no
+ * AppKit instance — exactly like {@link ConnectionControllerUtil}.
+ */
+export declare const HeadlessWalletUtil: {
+    /**
+     * Fetch / search / paginate the WalletConnect wallet list from the explorer API.
+     * With a `search` (or the deprecated `query`), switches to search mode; otherwise
+     * lists/paginates. Reads results from `ApiController.state` (see {@link getWalletList}).
+     */
+    fetchWallets(fetchOptions?: FetchWalletsOptions): Promise<void>;
+    /** Read the current wallet list (initial view + WalletConnect list + pagination). */
+    getWalletList(): WalletListSnapshot;
+    /** Subscribe to wallet-list changes (the WalletGuide list + search results). */
+    subscribeWalletList(callback: () => void): () => void;
+    /**
+     * Pre-fetch the WalletConnect URI (read from `ConnectionController.state.wcUri`).
+     * Call when a wallet is selected so a later connect can deeplink synchronously
+     * (required for iOS Safari). Uses 'auto' cache to reuse a valid URI or fetch a new one.
+     */
+    getWalletConnectUri(_options?: ConnectOptions): Promise<void>;
+    /**
+     * Connect a chosen wallet programmatically (headless — no modal).
+     *
+     * Handles injected wallets, API wallets (from the "all wallets" list), and mobile
+     * deeplinks. For API wallets without pre-populated connectors, falls back to a lookup
+     * by the wallet's ID via `explorerId` matching (e.g. Coinbase/Base from "all wallets").
+     */
+    connect(wallet: WalletItem, namespace?: ChainNamespace, options?: ConnectOptions): Promise<void>;
+    /** Reset the WalletConnect URI + linking state (e.g. when a QR is closed). */
+    resetWcUri(): void;
+    /** Clear the `connectingWallet` state. */
+    resetConnectingWallet(): void;
+};

package/dist/types/tests/utils/HeadlessWalletUtil.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reown/appkit-controllers",
-  "version": "1.8.21",
+  "version": "1.8.22-headless-js.0",
   "sideEffects": false,
   "type": "module",
   "main": "./dist/esm/exports/index.js",
@@ -56,8 +56,8 @@
     "@walletconnect/universal-provider": "2.23.7",
     "valtio": "2.1.7",
     "viem": ">=2.45.0",
-    "@reown/appkit-common": "1.8.21",
-    "@reown/appkit-wallet": "1.8.21"
+    "@reown/appkit-common": "1.8.22-headless-js.0",
+    "@reown/appkit-wallet": "1.8.22-headless-js.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "2.1.9",