@phantom/browser-sdk 1.0.0-beta.2 → 1.0.0-beta.21

package/README.md

@@ -19,7 +19,7 @@ const sdk = new BrowserSDK({
   addressTypes: [AddressType.solana, AddressType.ethereum],
 });
 
-const { addresses } = await sdk.connect();
+const { addresses } = await sdk.connect({ provider: "injected" });
 console.log("Connected addresses:", addresses);
 
 // Chain-specific operations
@@ -44,11 +44,10 @@ import { BrowserSDK, AddressType } from "@phantom/browser-sdk";
 const sdk = new BrowserSDK({
   providerType: "embedded",
   addressTypes: [AddressType.solana, AddressType.ethereum],
-  apiBaseUrl: "https://api.phantom.app/v1/wallets",
-  appId: "your-app-id",
+  appId: "your-app-id", // Get your app ID from phantom.com/portal
 });
 
-const { addresses } = await sdk.connect();
+const { addresses } = await sdk.connect({ provider: "phantom" });
 console.log("Addresses:", addresses);
 
 // Use chain-specific APIs
@@ -79,8 +78,8 @@ const sdk = new BrowserSDK({
   addressTypes: [AddressType.solana, AddressType.ethereum],
 });
 
-// 2. Connect to wallet
-const { addresses } = await sdk.connect();
+// 2. Connect to wallet (provider parameter is required)
+const { addresses } = await sdk.connect({ provider: "injected" });
 console.log("Connected addresses:", addresses);
 
 // 3. Use chain-specific methods
@@ -94,24 +93,38 @@ const ethResult = await sdk.ethereum.sendTransaction({
 
 ### Connection Options
 
-For embedded user-wallets, you can specify authentication providers:
+The `connect()` method requires a `provider` parameter and automatically switches between providers based on the authentication method you specify:
 
 ```typescript
-// Default: Show provider selection screen
-const result = await sdk.connect();
+// Connect with injected provider (Phantom extension)
+// Automatically switches to injected provider if not already using it
+const result = await sdk.connect({
+  provider: "injected",
+});
 
-// Google authentication (skips provider selection)
+// Connect with Google authentication (embedded provider)
+// Automatically switches to embedded provider if not already using it
 const result = await sdk.connect({
-  authOptions: {
-    provider: "google",
-  },
+  provider: "google",
 });
 
-// Apple authentication (skips provider selection)
+// Connect with Apple authentication (embedded provider)
+// Automatically switches to embedded provider if not already using it
 const result = await sdk.connect({
-  authOptions: {
-    provider: "apple",
-  },
+  provider: "apple",
+});
+
+// Connect with Phantom authentication (embedded provider)
+// Uses Phantom extension or mobile app for authentication
+// Automatically switches to embedded provider if not already using it
+const result = await sdk.connect({
+  provider: "phantom",
+});
+
+// Connect with JWT authentication (embedded provider)
+const result = await sdk.connect({
+  provider: "jwt",
+  jwtToken: "your-jwt-token",
 });
 ```
 
@@ -190,48 +203,29 @@ Creates a non-custodial wallet embedded in your application. Requires API config
 const sdk = new BrowserSDK({
   providerType: "embedded",
   addressTypes: [AddressType.solana, AddressType.ethereum],
-  apiBaseUrl: "https://api.phantom.app/v1/wallets",
-  appId: "your-app-id",
-  embeddedWalletType: "app-wallet", // or 'user-wallet'
+  appId: "your-app-id", // Get your app ID from phantom.com/portal
   authOptions: {
-    authUrl: "https://auth.phantom.app", // optional, defaults to "https://connect.phantom.app"
+    authUrl: "https://connect.phantom.app/login", // optional, defaults to "https://connect.phantom.app/login"
     redirectUrl: "https://yourapp.com/callback", // optional, defaults to current page
   },
   autoConnect: true, // optional, auto-connect to existing session (default: true for embedded)
 });
 ```
 
-### Embedded Wallet Types
-
-#### App Wallet (`'app-wallet'`)
-
-- **New wallets** created per application
-- **Unfunded** by default - you need to fund them
-- **Independent** from user's existing Phantom wallet
-- **Perfect for**: Gaming, DeFi protocols, or apps that need fresh wallets
-
-```typescript
-const sdk = new BrowserSDK({
-  providerType: "embedded",
-  embeddedWalletType: "app-wallet",
-  addressTypes: [AddressType.solana],
-  // ... other config
-});
-```
+### Embedded Wallet Type
 
 #### User Wallet (`'user-wallet'`)
 
 - **Uses Phantom authentication** - user logs in with existing Phantom account
 - **Potentially funded** - brings in user's existing wallet balance
 - **Connected** to user's Phantom ecosystem
-- **Perfect for**: Trading platforms, NFT marketplaces, or apps needing funded wallets
+- **Perfect for**: All embedded wallet use cases
 
 ```typescript
 const sdk = new BrowserSDK({
   providerType: "embedded",
-  embeddedWalletType: "user-wallet",
+  appId: "your-app-id",
   addressTypes: [AddressType.solana, AddressType.ethereum],
-  // ... other config
 });
 ```
 
@@ -242,28 +236,6 @@ const sdk = new BrowserSDK({
 | `AddressType.solana`   | Solana Mainnet, Devnet, Testnet       |
 | `AddressType.ethereum` | Ethereum, Polygon, Arbitrum, and more |
 
-### Solana Provider Configuration
-
-When using `AddressType.solana`, you can choose between two Solana libraries:
-
-```typescript
-const sdk = new BrowserSDK({
-  providerType: "embedded",
-  addressTypes: [AddressType.solana],
-  solanaProvider: "web3js", // or 'kit'
-  // ... other config
-});
-```
-
-**Provider Options:**
-
-- `'web3js'` (default) - Uses `@solana/web3.js` library
-- `'kit'` - Uses `@solana/kit` library (modern, TypeScript-first)
-
-**When to use each:**
-
-- **@solana/web3.js**: Better ecosystem compatibility, wider community support
-- **@solana/kit**: Better TypeScript support, modern architecture, smaller bundle size
 
 ### Auto-Connect Feature
 
@@ -272,8 +244,8 @@ The SDK can automatically reconnect to existing sessions when instantiated, prov
 ```typescript
 const sdk = new BrowserSDK({
   providerType: "embedded",
+  appId: "your-app-id",
   addressTypes: [AddressType.solana],
-  // ... other config
   autoConnect: true, // Default: true for embedded, false for injected
 });
 
@@ -295,8 +267,8 @@ if (sdk.isConnected()) {
 ```typescript
 const sdk = new BrowserSDK({
   providerType: "embedded",
+  appId: "your-app-id",
   addressTypes: [AddressType.solana],
-  // ... other config
   autoConnect: false, // Disable auto-connect
 });
 
@@ -320,21 +292,24 @@ interface BrowserSDKConfig {
   addressTypes?: [AddressType, ...AddressType[]]; // Networks to enable (e.g., [AddressType.solana])
 
   // Required for embedded provider only
-  apiBaseUrl?: string; // Phantom API base URL
-  appId?: string; // Your app ID (required for embedded provider)
+  appId?: string; // Your app ID from phantom.com/portal (required for embedded provider)
+  
+  // Optional configuration
+  apiBaseUrl?: string; // Phantom API base URL (optional, has default)
   authOptions?: {
-    authUrl?: string; // Custom auth URL (default: "https://connect.phantom.app")
-    redirectUrl?: string; // Custom redirect URL after authentication
+    authUrl?: string; // Custom auth URL (optional, defaults to "https://connect.phantom.app/login")
+    redirectUrl?: string; // Custom redirect URL after authentication (optional)
   };
-  embeddedWalletType?: "app-wallet" | "user-wallet"; // Wallet type
-  solanaProvider?: "web3js" | "kit"; // Solana library choice (default: 'web3js')
-  autoConnect?: boolean; // Enable auto-connect to existing sessions (default: true)
+  embeddedWalletType?: "user-wallet"; // Wallet type (optional, defaults to "user-wallet", currently the only supported type)
+  autoConnect?: boolean; // Enable auto-connect to existing sessions (optional, defaults to true for embedded)
 }
 ```
 
 ### Extension Detection
 
-For injected provider usage, you can check if the Phantom extension is installed:
+#### waitForPhantomExtension
+
+Check if the Phantom extension is installed:
 
 ```typescript
 import { waitForPhantomExtension } from "@phantom/browser-sdk";
@@ -348,15 +323,46 @@ if (isAvailable) {
 }
 ```
 
+#### isPhantomLoginAvailable
+
+Check if Phantom Login is available (requires extension to be installed and support the `phantom_login` feature):
+
+```typescript
+import { isPhantomLoginAvailable } from "@phantom/browser-sdk";
+
+const isAvailable = await isPhantomLoginAvailable();
+
+if (isAvailable) {
+  console.log("Phantom Login is available!");
+  // Can use provider: "phantom" in connect()
+} else {
+  console.log("Phantom Login is not available");
+}
+```
+
 ### Core Methods
 
-#### connect()
+#### connect(options)
 
 Connect to wallet and get addresses for configured AddressTypes.
 
+**Parameters:**
+- `options: AuthOptions` (required) - Authentication options
+  - `provider: "google" | "apple" | "jwt" | "phantom" | "injected"` (required) - Authentication provider to use
+  - `jwtToken?: string` (optional) - JWT token (required when `provider` is "jwt")
+  - `customAuthData?: Record<string, any>` (optional) - Custom authentication data
+
 ```typescript
-const result = await sdk.connect();
-// Returns: { walletId?: string, addresses: WalletAddress[] }
+// Connect with injected provider
+const result = await sdk.connect({ provider: "injected" });
+
+// Connect with Phantom authentication
+const result = await sdk.connect({ provider: "phantom" });
+
+// Connect with Google authentication
+const result = await sdk.connect({ provider: "google" });
+
+// Returns: { addresses: WalletAddress[], status: "pending" | "completed", providerType: "embedded" | "injected" }
 // addresses only includes types from addressTypes config
 ```
 
@@ -385,15 +391,6 @@ Check if SDK is connected to a wallet.
 const connected = sdk.isConnected();
 ```
 
-#### getWalletId()
-
-Get the wallet ID (embedded wallets only).
-
-```typescript
-const walletId = sdk.getWalletId();
-// Returns string for embedded wallets, null for injected
-```
-
 ### Solana Chain Methods
 
 #### signMessage(message)
@@ -547,7 +544,7 @@ const result = await sdk.ethereum.sendTransaction({
 
 #### switchChain(chainId)
 
-Switch to a different Ethereum chain.
+Switch to a different Ethereum chain. Accepts a chain ID as a number or a hex string value.
 
 ```typescript
 await sdk.ethereum.switchChain(1); // Ethereum mainnet
@@ -555,6 +552,21 @@ await sdk.ethereum.switchChain(137); // Polygon
 await sdk.ethereum.switchChain(42161); // Arbitrum One
 ```
 
+**Supported EVM Networks:**
+
+| Network | Chain ID | Usage |
+|---------|----------|-------|
+| Ethereum Mainnet | `1` | `switchChain(1)` |
+| Ethereum Sepolia | `11155111` | `switchChain(11155111)` |
+| Polygon Mainnet | `137` | `switchChain(137)` |
+| Polygon Amoy | `80002` | `switchChain(80002)` |
+| Base Mainnet | `8453` | `switchChain(8453)` |
+| Base Sepolia | `84532` | `switchChain(84532)` |
+| Arbitrum One | `42161` | `switchChain(42161)` |
+| Arbitrum Sepolia | `421614` | `switchChain(421614)` |
+| Monad Mainnet | `143` | `switchChain(143)` |
+| Monad Testnet | `10143` | `switchChain(10143)` |
+
 #### getChainId()
 
 Get the current chain ID.
@@ -590,6 +602,106 @@ Attempt auto-connection using existing session. Should be called after setting u
 await sdk.autoConnect();
 ```
 
+### Event Handlers
+
+The SDK provides typed event handlers that allow you to listen for connection state changes. This is especially useful for `autoConnect()` flows where you need to track the connection result.
+
+#### Available Events
+
+```typescript
+import { BrowserSDK } from '@phantom/browser-sdk';
+import type {
+  ConnectEventData,
+  ConnectStartEventData,
+  ConnectErrorEventData,
+  DisconnectEventData
+} from '@phantom/browser-sdk';
+
+const sdk = new BrowserSDK({
+  providerType: 'embedded',
+  appId: 'your-app-id',
+  addressTypes: [AddressType.solana],
+});
+
+// 1. connect_start - Fired when connection starts
+sdk.on('connect_start', (data: ConnectStartEventData) => {
+  console.log('Connection starting:', data.source); // "auto-connect" | "manual-connect"
+  console.log('Auth options:', data.authOptions?.provider); // "google" | "apple" | etc.
+});
+
+// 2. connect - Fired when connection succeeds (includes full ConnectResult)
+sdk.on('connect', (data: ConnectEventData) => {
+  console.log('Connected successfully!');
+  console.log('Provider type:', data.providerType); // "embedded" | "injected"
+  console.log('Wallet ID:', data.walletId); // only for embedded providers
+  console.log('Addresses:', data.addresses); // WalletAddress[]
+  console.log('Status:', data.status); // "pending" | "completed"
+  console.log('Source:', data.source); // "auto-connect" | "manual-connect" | "manual-existing" | "existing-session" | "manual"
+});
+
+// 3. connect_error - Fired when connection fails
+sdk.on('connect_error', (data: ConnectErrorEventData) => {
+  console.error('Connection failed:', data.error);
+  console.log('Source:', data.source); // "auto-connect" | "manual-connect"
+});
+
+// 4. disconnect - Fired when disconnected
+sdk.on('disconnect', (data: DisconnectEventData) => {
+  console.log('Disconnected from wallet');
+  console.log('Source:', data.source); // "manual"
+});
+
+// 5. error - General error handler
+sdk.on('error', (error: unknown) => {
+  console.error('SDK error:', error);
+});
+
+// Don't forget to remove listeners when done
+sdk.off('connect', handleConnect);
+```
+
+#### Event Types
+
+| Event | Payload Type | When Fired | Key Data |
+|-------|-------------|------------|----------|
+| `connect_start` | `ConnectStartEventData` | Connection initiated | `source`, `authOptions` |
+| `connect` | `ConnectEventData` | Connection successful | `providerType`, `addresses`, `status`, `source`, `user`|
+| `connect_error` | `ConnectErrorEventData` | Connection failed | `error`, `source` |
+| `disconnect` | `DisconnectEventData` | Disconnected | `source` |
+| `error` | `unknown` | General SDK errors | Error details |
+
+#### Using Events with autoConnect()
+
+Event handlers are especially useful with `autoConnect()` since it doesn't return a value:
+
+```typescript
+const sdk = new BrowserSDK({
+  providerType: 'embedded',
+  appId: 'your-app-id',
+  addressTypes: [AddressType.solana],
+  autoConnect: true,
+});
+
+// Set up event listeners BEFORE autoConnect
+sdk.on('connect', (data: ConnectEventData) => {
+  console.log('Auto-connected successfully!');
+  console.log('Provider type:', data.providerType);
+  console.log('Addresses:', data.addresses);
+
+  // Update your UI state here
+  updateUIWithAddresses(data.addresses);
+});
+
+sdk.on('connect_error', (data: ConnectErrorEventData) => {
+  console.log('Auto-connect failed:', data.error);
+  // Show connect button to user
+  showConnectButton();
+});
+
+// Auto-connect will trigger events
+await sdk.autoConnect();
+```
+
 ### Auto-Confirm Methods (Injected Provider Only)
 
 The SDK provides auto-confirm functionality that allows automatic transaction confirmation for specified chains. This feature is only available when using the injected provider (Phantom browser extension).
@@ -647,33 +759,15 @@ console.log("Supported chains:", supportedChains.chains);
 
 #### Available NetworkId Values
 
+For a complete list of supported networks including Solana, Ethereum, Polygon, Base, Arbitrum, Monad, and more, see the [Network Support section in the main README](../../README.md#network-support).
+
 ```typescript
 import { NetworkId } from "@phantom/browser-sdk";
 
-// Solana networks
-NetworkId.SOLANA_MAINNET; // "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
-NetworkId.SOLANA_DEVNET; // "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
-NetworkId.SOLANA_TESTNET; // "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z"
-
-// Ethereum networks
-NetworkId.ETHEREUM_MAINNET; // "eip155:1"
-NetworkId.ETHEREUM_SEPOLIA; // "eip155:11155111"
-
-// Polygon networks
-NetworkId.POLYGON_MAINNET; // "eip155:137"
-NetworkId.POLYGON_AMOY; // "eip155:80002"
-
-// Arbitrum networks
-NetworkId.ARBITRUM_ONE; // "eip155:42161"
-NetworkId.ARBITRUM_SEPOLIA; // "eip155:421614"
-
-// Optimism networks
-NetworkId.OPTIMISM_MAINNET; // "eip155:10"
-NetworkId.OPTIMISM_GOERLI; // "eip155:420"
-
-// Base networks
-NetworkId.BASE_MAINNET; // "eip155:8453"
-NetworkId.BASE_SEPOLIA; // "eip155:84532"
+// Example: Use NetworkId for auto-confirm
+await sdk.enableAutoConfirm({
+  chains: [NetworkId.SOLANA_MAINNET, NetworkId.ETHEREUM_MAINNET],
+});
 ```
 
 **Important Notes:**
@@ -748,7 +842,7 @@ import { BrowserSDK, DebugLevel } from "@phantom/browser-sdk";
 
 const sdk = new BrowserSDK({
   providerType: "embedded",
-  // ... other config
+  appId: "your-app-id",
 });
 
 // Store debug messages
@@ -815,10 +909,9 @@ import { BrowserSDK, AddressType } from "@phantom/browser-sdk";
 const sdk = new BrowserSDK({
   providerType: "injected",
   addressTypes: [AddressType.solana],
-  solanaProvider: "web3js",
 });
 
-await sdk.connect();
+await sdk.connect({ provider: "injected" });
 
 // Get recent blockhash
 const connection = new Connection("https://api.mainnet-beta.solana.com");
@@ -869,10 +962,9 @@ import { BrowserSDK, AddressType } from "@phantom/browser-sdk";
 const sdk = new BrowserSDK({
   providerType: "injected",
   addressTypes: [AddressType.solana],
-  solanaProvider: "kit",
 });
 
-await sdk.connect();
+await sdk.connect({ provider: "injected" });
 
 // Create transaction with @solana/kit
 const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
@@ -902,7 +994,7 @@ const sdk = new BrowserSDK({
   addressTypes: [AddressType.ethereum],
 });
 
-await sdk.connect();
+await sdk.connect({ provider: "injected" });
 
 // Simple ETH transfer
 const result = await sdk.ethereum.sendTransaction({