@reown/appkit-controllers 1.8.21 → 1.8.22-coinbase-4100-provider-reauth.0

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

@@ -6,6 +6,7 @@ export { ChainController } from '../src/controllers/ChainController.js';
 export type { ChainControllerState, AccountState } from '../src/controllers/ChainController.js';
 export { ProviderController } from '../src/controllers/ProviderController.js';
 export type { ProviderControllerState } from '../src/controllers/ProviderController.js';
+export { isCoinbaseConnectorId, isUnauthorizedProviderError, maybeWrapCoinbaseProvider, withCoinbaseReauth } from '../src/utils/ProviderReauthUtil.js';
 export { OnRampController } from '../src/controllers/OnRampController.js';
 export type { OnRampControllerState, OnRampProvider } from '../src/controllers/OnRampController.js';
 export { AdapterController } from '../src/controllers/AdapterController/index.js';
@@ -73,5 +74,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, WalletConnectUriSnapshot, 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,112 @@
+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.prefetchWalletConnectUri}. */
+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;
+}
+/** The WalletConnect URI + connection-attempt signals, read imperatively. */
+export interface WalletConnectUriSnapshot {
+    /** Active WalletConnect pairing URI (for rendering a QR / deeplink), or undefined when none. */
+    wcUri: string | undefined;
+    /** Whether the last WalletConnect URI fetch / connection attempt errored. */
+    wcError: boolean;
+    /** Whether a WalletConnect URI is currently being fetched. */
+    wcFetchingUri: boolean;
+}
+/**
+ * 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 the result with {@link getWalletConnectUri};
+     * subscribe with {@link subscribeWalletConnectUri}. Call when a wallet is selected so a
+     * later connect can deeplink synchronously (required for iOS Safari) or render a QR. Uses
+     * 'auto' cache to reuse a valid URI or fetch a new one.
+     */
+    prefetchWalletConnectUri(_options?: ConnectOptions): Promise<void>;
+    /**
+     * Read the current WalletConnect URI state (the QR / deeplink URI plus the fetch/error
+     * signals) — the symmetric read for {@link prefetchWalletConnectUri}. Reads
+     * `ConnectionController` directly, so a headless host gets it ungated through the AppKit
+     * instance without importing the controllers package.
+     */
+    getWalletConnectUri(): WalletConnectUriSnapshot;
+    /**
+     * Subscribe to WalletConnect URI state changes (wcUri / wcError / wcFetchingUri). The
+     * callback receives no arguments — read the current values with {@link getWalletConnectUri}.
+     * Returns an unsubscribe.
+     */
+    subscribeWalletConnectUri(callback: () => void): () => 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/src/utils/ProviderReauthUtil.d.ts

@@ -0,0 +1,45 @@
+import type { ChainNamespace } from '@reown/appkit-common';
+/**
+ * True when `connectorId` is a Coinbase connector.
+ *
+ * The connector id (not the provider "type") is the reliable signal: it is a
+ * stable `'coinbaseWallet'` / `'coinbaseWalletSDK'` across every adapter and
+ * registration path, whereas the provider type is remapped to `'EXTERNAL'` by
+ * `PresetsUtil.ConnectorTypesMap` on most paths. Matched case-insensitively by
+ * substring to also tolerate the wagmi restore path's uppercased
+ * `connector.type` (`'COINBASEWALLET'`).
+ */
+export declare function isCoinbaseConnectorId(connectorId: string | undefined): boolean;
+/**
+ * EIP-1193 `4100` unauthorized error, matched by code or by the SDK's
+ * `eth_requestAccounts` wording, walking the `cause` chain (viem/provider
+ * wrappers nest the original error) with bounded depth.
+ */
+export declare function isUnauthorizedProviderError(err: unknown, depth?: number): boolean;
+/**
+ * Wrap a Coinbase provider so any signing RPC that fails with `4100` triggers a
+ * one-shot recovery: a single `eth_requestAccounts` re-authorization, an active-
+ * chain re-assert for state-changing calls, then exactly one retry.
+ *
+ * - Non-`4100` failures pass through untouched (no re-auth attempt).
+ * - A rejected re-auth prompt propagates and classifies as a user rejection.
+ * - A still-unauthorized retry fails once (no loop) — the recovery calls the raw
+ *   provider, never the wrapper, so it cannot recurse.
+ *
+ * Non-`request` members are delegated to the raw provider bound to the raw
+ * instance, so private class fields and EIP-1193 event emitters keep working.
+ * The wrapper is cached per raw instance so repeated `setProvider` calls with
+ * the same provider return a stable reference (no consumer identity churn).
+ */
+export declare function withCoinbaseReauth<T extends object>(provider: T): T;
+/**
+ * Apply {@link withCoinbaseReauth} to an eip155 Coinbase provider, returning
+ * every other provider untouched. This is the single decision the provider
+ * registration seam (`syncProvider`) needs — keeping the guard here (keyed on
+ * the reliable connector id) rather than in the state setter.
+ */
+export declare function maybeWrapCoinbaseProvider<T>(params: {
+    connectorId: string | undefined;
+    chainNamespace: ChainNamespace | undefined;
+    provider: T;
+}): T;

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

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

package/dist/types/tests/utils/ProviderReauthUtil.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-coinbase-4100-provider-reauth.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-coinbase-4100-provider-reauth.0",
+    "@reown/appkit-wallet": "1.8.22-coinbase-4100-provider-reauth.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "2.1.9",