@solana/connector 0.1.10 → 0.2.0

package/README.md

@@ -54,13 +54,11 @@ export function Providers({ children }: { children: React.ReactNode }) {
                   {
                       id: 'solana:mainnet' as const,
                       label: 'Mainnet (Custom RPC)',
-                      name: 'mainnet-beta' as const,
                       url: customRpcUrl,
                   },
                   {
                       id: 'solana:devnet' as const,
                       label: 'Devnet',
-                      name: 'devnet' as const,
                       url: 'https://api.devnet.solana.com',
                   },
               ]
@@ -97,22 +95,38 @@ export function Providers({ children }: { children: React.ReactNode }) {
 ```typescript
 'use client';
 
-import { useConnector, useAccount } from '@solana/connector';
+import { useConnector } from '@solana/connector/react';
 
 export function ConnectButton() {
-    const { wallets, select, disconnect, connected, connecting, selectedWallet, selectedAccount } = useConnector();
-    const { address, formatted, copy } = useAccount();
+    const {
+        connectors,
+        connectWallet,
+        disconnectWallet,
+        isConnected,
+        isConnecting,
+        isError,
+        walletError,
+        account,
+    } = useConnector();
 
-    if (connecting) {
-        return <button disabled>Connecting...</button>;
+    if (isError) {
+        return (
+            <div>
+                <p>Error: {walletError?.message ?? 'Unknown error'}</p>
+            </div>
+        );
     }
 
-    if (!connected) {
+    if (!isConnected) {
         return (
             <div>
-                {wallets.map(w => (
-                    <button key={w.wallet.name} onClick={() => select(w.wallet.name)}>
-                        Connect {w.wallet.name}
+                {connectors.map(connector => (
+                    <button
+                        key={connector.id}
+                        onClick={() => connectWallet(connector.id)}
+                        disabled={isConnecting || !connector.ready}
+                    >
+                        {isConnecting ? 'Connecting...' : `Connect ${connector.name}`}
                     </button>
                 ))}
             </div>
@@ -121,8 +135,10 @@ export function ConnectButton() {
 
     return (
         <div>
-            <button onClick={copy}>{formatted}</button>
-            <button onClick={disconnect}>Disconnect</button>
+            <span>{account}</span>
+            <button onClick={disconnectWallet}>
+                Disconnect
+            </button>
         </div>
     );
 }
@@ -141,21 +157,37 @@ These are the main hooks you'll use in your components.
 Main hook for wallet connection and state.
 
 ```typescript
-import { useConnector } from '@solana/connector';
+import { useConnector } from '@solana/connector/react';
 
 function Component() {
     const {
-        // State
-        wallets, // WalletInfo[] - All available wallets
-        selectedWallet, // Wallet | null - Currently connected wallet
-        selectedAccount, // string | null - Currently selected account address
-        accounts, // AccountInfo[] - Connected accounts
-        connected, // boolean - Connection status
-        connecting, // boolean - Connecting in progress
-
-        // Actions
-        select, // (walletName: string) => Promise<void>
-        disconnect, // () => Promise<void>
+        // vNext state (recommended)
+        connectors, // WalletConnectorMetadata[] - available wallet connectors
+        walletStatus, // WalletStatus - discriminated union state machine
+        connectorId, // WalletConnectorId | null - connected connector id
+        connector, // WalletConnectorMetadata | null - connected connector metadata
+        account, // Address | null - selected account address
+        sessionAccounts, // SessionAccount[] - all accounts in session
+        isConnected, // boolean - shorthand
+        isConnecting, // boolean - shorthand
+        isError, // boolean - shorthand
+        walletError, // Error | null - set when status is 'error'
+
+        // vNext actions (recommended)
+        connectWallet, // (connectorId, options?) => Promise<void>
+        disconnectWallet, // () => Promise<void>
+
+        // Legacy fields (deprecated; kept for backwards compatibility)
+        wallets,
+        selectedWallet,
+        selectedAccount,
+        accounts,
+        connected,
+        connecting,
+
+        // Legacy actions (deprecated; kept for backwards compatibility)
+        select,
+        disconnect,
     } = useConnector();
 }
 ```
@@ -165,32 +197,37 @@ function Component() {
 ```typescript
 'use client';
 
-import { useConnector } from '@solana/connector';
-import { useState } from 'react';
+import { useConnector } from '@solana/connector/react';
 
 export function ConnectButton() {
-    const [isModalOpen, setIsModalOpen] = useState(false);
-    const { connected, connecting, selectedWallet, selectedAccount, wallets, select } = useConnector();
+    const { connectors, connectWallet, disconnectWallet, isConnected, isConnecting, account } = useConnector();
 
-    if (connecting) {
+    if (isConnecting) {
         return <button disabled>Connecting...</button>;
     }
 
-    if (connected && selectedAccount && selectedWallet) {
-        const shortAddress = `${selectedAccount.slice(0, 4)}...${selectedAccount.slice(-4)}`;
+    if (isConnected && account) {
+        const shortAddress = `${account.slice(0, 4)}...${account.slice(-4)}`;
         return (
             <div>
                 <span>{shortAddress}</span>
-                <button onClick={() => select(selectedWallet.name)}>Switch Wallet</button>
+                <button onClick={disconnectWallet}>Disconnect</button>
             </div>
         );
     }
 
     return (
-        <>
-            <button onClick={() => setIsModalOpen(true)}>Connect Wallet</button>
-            {/* Wallet selection modal */}
-        </>
+        <div>
+            {connectors.map(connector => (
+                <button
+                    key={connector.id}
+                    onClick={() => connectWallet(connector.id)}
+                    disabled={isConnecting || !connector.ready}
+                >
+                    Connect {connector.name}
+                </button>
+            ))}
+        </div>
     );
 }
 ```
@@ -308,6 +345,214 @@ function Component() {
 
 ---
 
+## vNext API (Recommended)
+
+The vNext API provides a cleaner, more type-safe approach to wallet connections using stable connector IDs and a wallet status state machine.
+
+You can access the same vNext state + actions either through the focused hooks below, or via `useConnector()` (single hook) which also includes legacy compatibility fields.
+
+### `useWallet()`
+
+Primary hook for wallet status in vNext. Uses a discriminated union for type-safe status checks.
+
+```typescript
+import { useWallet } from '@solana/connector/react';
+
+function Component() {
+    const {
+        status,      // 'disconnected' | 'connecting' | 'connected' | 'error'
+        isConnected, // boolean shorthand
+        isConnecting,// boolean shorthand
+        account,     // Address | null - Selected account address
+        accounts,    // SessionAccount[] - All available accounts
+        connectorId, // WalletConnectorId | null - Connected wallet ID
+        error,       // Error | null - Error if status is 'error'
+    } = useWallet();
+
+    if (status === 'connected') {
+        // TypeScript knows account is non-null here
+        return <p>Connected: {account}</p>;
+    }
+}
+```
+
+### `useWalletConnectors()`
+
+Get available wallet connectors with stable IDs.
+
+```typescript
+import { useWalletConnectors } from '@solana/connector/react';
+
+function WalletList() {
+    const connectors = useWalletConnectors();
+
+    return (
+        <ul>
+            {connectors.map(connector => (
+                <li key={connector.id}>
+                    <img src={connector.icon} alt={connector.name} />
+                    {connector.name}
+                    {connector.ready ? '✓' : 'Not Ready'}
+                </li>
+            ))}
+        </ul>
+    );
+}
+```
+
+### `useConnectWallet()`
+
+Connect to a wallet using its stable connector ID.
+
+```typescript
+import { useConnectWallet, useWalletConnectors } from '@solana/connector/react';
+
+function ConnectButton() {
+    const { connect, isConnecting, error, resetError } = useConnectWallet();
+    const connectors = useWalletConnectors();
+
+    return (
+        <div>
+            {connectors.map(connector => (
+                <button
+                    key={connector.id}
+                    onClick={() => connect(connector.id)}
+                    disabled={isConnecting || !connector.ready}
+                >
+                    Connect {connector.name}
+                </button>
+            ))}
+            {error && (
+                <p>
+                    Error: {error.message}
+                    <button onClick={resetError}>Dismiss</button>
+                </p>
+            )}
+        </div>
+    );
+}
+```
+
+### `useDisconnectWallet()`
+
+Disconnect the current wallet session.
+
+```typescript
+import { useDisconnectWallet, useWallet } from '@solana/connector/react';
+
+function DisconnectButton() {
+    const { isConnected } = useWallet();
+    const { disconnect, isDisconnecting } = useDisconnectWallet();
+
+    if (!isConnected) return null;
+
+    return (
+        <button onClick={disconnect} disabled={isDisconnecting}>
+            {isDisconnecting ? 'Disconnecting...' : 'Disconnect'}
+        </button>
+    );
+}
+```
+
+### Silent-First Auto-Connect
+
+The vNext API supports silent-first auto-connect, which attempts to reconnect without prompting the user:
+
+```typescript
+const { connect } = useConnectWallet();
+
+// Silent connect (won't prompt user)
+await connect('wallet-standard:phantom', {
+    silent: true,
+    allowInteractiveFallback: false,
+});
+
+// Silent-first with interactive fallback (prompts if silent fails)
+await connect('wallet-standard:phantom', {
+    silent: true,
+    allowInteractiveFallback: true,
+});
+```
+
+---
+
+## Migration Guide (Legacy → vNext)
+
+### Connect by Wallet Name → Connect by Connector ID
+
+**Before (Legacy):**
+
+```typescript
+const { select, wallets } = useConnector();
+await select('Phantom');
+```
+
+**After (vNext):**
+
+```typescript
+const { connect } = useConnectWallet();
+await connect('wallet-standard:phantom');
+// Or use connectors from useWalletConnectors()
+```
+
+### Check Connection Status
+
+**Before (Legacy):**
+
+```typescript
+const { connected, connecting } = useConnector();
+if (connected) {
+    /* ... */
+}
+```
+
+**After (vNext):**
+
+```typescript
+const { status, isConnected, isConnecting } = useWallet();
+if (status === 'connected') {
+    /* ... */
+}
+// Or use the boolean shorthand:
+if (isConnected) {
+    /* ... */
+}
+```
+
+### Get Selected Account
+
+**Before (Legacy):**
+
+```typescript
+const { selectedAccount } = useConnector();
+```
+
+**After (vNext):**
+
+```typescript
+const { account } = useWallet();
+// Or for full account info:
+const { accounts, account } = useWallet();
+```
+
+### Disconnect
+
+**Before (Legacy):**
+
+```typescript
+const { disconnect } = useConnector();
+await disconnect();
+```
+
+**After (vNext):**
+
+```typescript
+const { disconnect } = useDisconnectWallet();
+await disconnect();
+```
+
+---
+
 ## Transaction Signing
 
 ConnectorKit provides powerful transaction signing capabilities with support for both legacy `@solana/web3.js` and modern `@solana/kit` APIs.
@@ -578,13 +823,11 @@ const config = getDefaultConfig({
         {
             id: 'solana:mainnet' as const,
             label: 'Mainnet (Custom RPC)',
-            name: 'mainnet-beta' as const,
             url: 'https://my-custom-rpc.com',
         },
         {
             id: 'solana:devnet' as const,
             label: 'Devnet',
-            name: 'devnet' as const,
             url: 'https://api.devnet.solana.com',
         },
     ],
@@ -620,69 +863,62 @@ npm install @walletconnect/universal-provider
 
 Visit [cloud.walletconnect.com](https://cloud.walletconnect.com/) and create a project to get your `projectId`.
 
-**3. Configure WalletConnect in your app:**
+**3. Enable WalletConnect in your config:**
 
 ```typescript
+'use client';
+
 import { getDefaultConfig } from '@solana/connector/headless';
-import { useState } from 'react';
+import { useMemo } from 'react';
+import { AppProvider } from '@solana/connector/react';
 
 export function Providers({ children }: { children: React.ReactNode }) {
-    const [walletConnectUri, setWalletConnectUri] = useState<string | null>(null);
-
     const connectorConfig = useMemo(() => {
         return getDefaultConfig({
             appName: 'My App',
             appUrl: 'https://myapp.com',
-            walletConnect: {
-                enabled: true,
-                projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!,
-                metadata: {
-                    name: 'My App',
-                    description: 'My Solana Application',
-                    url: 'https://myapp.com',
-                    icons: ['https://myapp.com/icon.png'],
-                },
-                // Handle the WalletConnect URI for QR code display
-                onDisplayUri: (uri) => {
-                    setWalletConnectUri(uri);
-                },
-                onSessionEstablished: () => {
-                    setWalletConnectUri(null);
-                },
-            },
+            // Reads NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID from env
+            walletConnect: true,
         });
     }, []);
 
     return (
         <AppProvider connectorConfig={connectorConfig}>
             {children}
-            {/* Render QR code modal when URI is available */}
-            {walletConnectUri && (
-                <WalletConnectQRModal
-                    uri={walletConnectUri}
-                    onClose={() => setWalletConnectUri(null)}
-                />
-            )}
+            <WalletConnectQRModal />
         </AppProvider>
     );
 }
 ```
 
-**4. Create a QR code modal:**
+**4. Render a QR code when a pairing URI is available:**
 
 ```typescript
-import QRCode from 'qrcode.react'; // npm install qrcode.react
+'use client';
+
+import { useConnector } from '@solana/connector/react';
+import { QRCodeSVG } from 'qrcode.react'; // npm install qrcode.react
+
+export function WalletConnectQRModal() {
+    const { walletConnectUri, clearWalletConnectUri } = useConnector();
+
+    if (!walletConnectUri) return null;
 
-function WalletConnectQRModal({ uri, onClose }: { uri: string; onClose: () => void }) {
     return (
-        <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
-            <div className="bg-white rounded-xl p-6 max-w-sm">
-                <h2 className="text-lg font-semibold mb-4">Scan with your wallet</h2>
-                <QRCode value={uri} size={256} />
-                <p className="text-sm text-gray-500 mt-4 text-center">
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+            <div className="w-full max-w-sm rounded-xl bg-white p-6">
+                <h2 className="text-lg font-semibold">Scan with your wallet</h2>
+                <div className="mt-4 flex justify-center">
+                    <QRCodeSVG value={walletConnectUri} size={256} />
+                </div>
+                <p className="mt-4 text-center text-sm text-gray-500">
                     Open your WalletConnect-compatible wallet and scan this QR code
                 </p>
-                <button onClick={onClose} className="mt-4 w-full py-2 bg-gray-100 rounded">
+                <button
+                    type="button"
+                    onClick={clearWalletConnectUri}
+                    className="mt-4 w-full rounded bg-gray-100 py-2"
+                >
                     Cancel
                 </button>
             </div>
@@ -691,9 +927,10 @@ function WalletConnectQRModal({ uri, onClose }: { uri: string; onClose: () => vo
 }
 ```
 
-Once enabled, "WalletConnect" appears as a wallet option in your wallet list. When selected, the `onDisplayUri` callback fires with a URI that should be displayed as a QR code for mobile wallet scanning.
+Once enabled, "WalletConnect" appears as a connector (id: `walletconnect`) in your wallet list. When selected, `useConnector().walletConnectUri` will be set to a `wc:` URI that you can display as a QR code or use for deep linking.
 
 **Supported WalletConnect Solana methods:**
+
 - `solana_getAccounts` / `solana_requestAccounts` - Get connected accounts
 - `solana_signMessage` - Sign arbitrary messages
 - `solana_signTransaction` - Sign transactions
@@ -758,7 +995,6 @@ const config = getDefaultConfig({
         {
             id: 'solana:mainnet' as const,
             label: 'Mainnet',
-            name: 'mainnet-beta' as const,
             url: `${getOrigin()}/api/rpc`, // Proxy URL
         },
         // ... other clusters
@@ -1091,27 +1327,28 @@ if (!result.success) {
 Use `ConnectorClient` for non-React frameworks:
 
 ```typescript
-import { ConnectorClient, getDefaultConfig } from '@solana/connector/headless';
+import { ConnectorClient, getDefaultConfig, createConnectorId } from '@solana/connector/headless';
 
 // Create client
 const client = new ConnectorClient(getDefaultConfig({ appName: 'My App' }));
 
 // Get state
 const state = client.getSnapshot();
-console.log('Wallets:', state.wallets);
+console.log('Connectors:', state.connectors);
 
-// Connect
-await client.select('Phantom');
+// Connect (vNext)
+await client.connectWallet(createConnectorId('Phantom'));
 
 // Subscribe to changes
 const unsubscribe = client.subscribe(state => {
     console.log('State updated:', state);
 });
 
-// Disconnect
-await client.disconnect();
+// Disconnect (vNext)
+await client.disconnectWallet();
 
 // Cleanup
+unsubscribe();
 client.destroy();
 ```
 
@@ -1159,7 +1396,7 @@ const config = getDefaultConfig({
 
 ```typescript
 // Full library - includes React and headless
-import { ConnectorProvider, useConnector, useAccount } from '@solana/connector';
+import { AppProvider, useConnector, getDefaultConfig } from '@solana/connector';
 ```
 
 ### Headless Export (Framework Agnostic)
@@ -1173,7 +1410,7 @@ import { ConnectorClient, getDefaultConfig } from '@solana/connector/headless';
 
 ```typescript
 // React-specific exports only
-import { useConnector, useAccount } from '@solana/connector/react';
+import { AppProvider, useConnector, useWallet, useConnectWallet } from '@solana/connector/react';
 ```
 
 ---
@@ -1182,9 +1419,20 @@ import { useConnector, useAccount } from '@solana/connector/react';
 
 ### Hooks
 
+#### vNext Hooks (Recommended)
+
+| Hook                    | Description                 | Returns                                                           |
+| ----------------------- | --------------------------- | ----------------------------------------------------------------- |
+| `useWallet()`           | Wallet status state machine | `{ status, isConnected, isConnecting, account, accounts, error }` |
+| `useWalletConnectors()` | Available wallet connectors | `WalletConnectorMetadata[]`                                       |
+| `useConnectWallet()`    | Connect by connector ID     | `{ connect, isConnecting, error, resetError }`                    |
+| `useDisconnectWallet()` | Disconnect current wallet   | `{ disconnect, isDisconnecting }`                                 |
+
+#### Legacy Hooks
+
 | Hook                        | Description                             | Returns                                                                            |
 | --------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
-| `useConnector()`            | Main wallet connection hook             | `{ wallets, selectedWallet, accounts, connected, connecting, select, disconnect }` |
+| `useConnector()`            | Main wallet connection hook (vNext + legacy) | `ConnectorSnapshot`                                                           |
 | `useAccount()`              | Account management hook                 | `{ address, formatted, copy, copied, accounts, selectAccount }`                    |
 | `useCluster()`              | Network/cluster management hook         | `{ cluster, clusters, setCluster, isMainnet, isDevnet, rpcUrl }`                   |
 | `useWalletInfo()`           | Wallet metadata hook                    | `{ name, icon, wallet, connecting }`                                               |
@@ -1220,7 +1468,7 @@ import type {
     // Configuration
     ConnectorConfig,
     DefaultConfigOptions,
-    UnifiedConfig,
+    ExtendedConnectorConfig,
 
     // State & Info
     ConnectorState,
@@ -1236,6 +1484,14 @@ import type {
     SolanaCluster,
     SolanaClusterId,
 
+    // vNext Session Types
+    WalletConnectorId,
+    WalletConnectorMetadata,
+    WalletSession,
+    WalletStatus,
+    SessionAccount,
+    ConnectOptions,
+
     // Hook Returns
     UseClusterReturn,
     UseAccountReturn,

package/dist/{chunk-MN7XNCYI.js → chunk-BJAVJQLK.js}

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk6AJJJG5B_js = require('./chunk-6AJJJG5B.js');
-var chunk64LV76OK_js = require('./chunk-64LV76OK.js');
+var chunkBZ2VBJCZ_js = require('./chunk-BZ2VBJCZ.js');
+var chunkSITQ4JWM_js = require('./chunk-SITQ4JWM.js');
 var core = require('@wallet-ui/core');
 var signers = require('@solana/signers');
 var addresses = require('@solana/addresses');
@@ -63,7 +63,7 @@ var SOLANA_CHAIN_IDS = {
   "solana:testnet": SOLANA_CHAIN_IDS.testnet
 };
 function getChainIdFromCluster(cluster) {
-  let clusterType = chunk6AJJJG5B_js.getClusterType(cluster);
+  let clusterType = chunkBZ2VBJCZ_js.getClusterType(cluster);
   return clusterType === "localnet" || clusterType === "custom" ? null : getChainIdFromClusterType(clusterType);
 }
 function getChainIdFromClusterId(clusterId) {
@@ -140,7 +140,7 @@ function getSolanaExplorerUrl(signature, options = {}) {
   if (normalizedCluster === "localnet")
     return `https://explorer.solana.com/tx/${signature}?cluster=custom&customUrl=${encodeURIComponent(customUrl || "http://localhost:8899")}`;
   let explorerCluster = ["mainnet", "devnet", "testnet"].includes(normalizedCluster) ? normalizedCluster : "devnet";
-  return chunk64LV76OK_js.getExplorerLink({
+  return chunkSITQ4JWM_js.getExplorerLink({
     transaction: signature,
     cluster: explorerCluster
   });
@@ -226,5 +226,5 @@ exports.isSolanaChain = isSolanaChain;
 exports.isWalletName = isWalletName;
 exports.sendRawTransaction = sendRawTransaction;
 exports.validateKnownSolanaChain = validateKnownSolanaChain;
-//# sourceMappingURL=chunk-MN7XNCYI.js.map
-//# sourceMappingURL=chunk-MN7XNCYI.js.map
+//# sourceMappingURL=chunk-BJAVJQLK.js.map
+//# sourceMappingURL=chunk-BJAVJQLK.js.map