@phantom/browser-sdk 1.0.0-beta.14 → 1.0.0-beta.16

package/README.md

@@ -93,24 +93,36 @@ const ethResult = await sdk.ethereum.sendTransaction({
 
 ### Connection Options
 
-For embedded user-wallets, you can specify authentication providers:
+The `connect()` method automatically switches between providers based on the authentication method you specify:
 
 ```typescript
-// Default: Show provider selection screen
+// Connect with current provider (no switching)
 const result = await sdk.connect();
 
-// Google authentication (skips provider selection)
+// Connect with injected provider (Phantom extension)
+// Automatically switches to injected provider if not already using it
 const result = await sdk.connect({
-  authOptions: {
-    provider: "google",
-  },
+  provider: "injected",
 });
 
-// Apple 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: "apple",
-  },
+  provider: "google",
+});
+
+// Connect with Apple authentication (embedded provider)
+// Automatically switches to embedded provider if not already using it
+const result = await sdk.connect({
+  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",
 });
 ```
 
@@ -293,7 +305,9 @@ interface BrowserSDKConfig {
 
 ### 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";
@@ -307,6 +321,23 @@ 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()
@@ -540,6 +571,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).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { EmbeddedProviderConfig, AuthOptions, ConnectResult, WalletAddress, EmbeddedProviderEvent, EventCallback } from '@phantom/embedded-provider-core';
-export { AuthOptions, ConnectResult, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
+export { AuthOptions, ConnectErrorEventData, ConnectEventData, ConnectResult, ConnectStartEventData, DisconnectEventData, EmbeddedProviderEvent, EmbeddedProviderEventMap, EventCallback, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
 import { ISolanaChain, IEthereumChain } from '@phantom/chain-interfaces';
 export { EthTransactionRequest, IEthereumChain, ISolanaChain } from '@phantom/chain-interfaces';
 import { AddressType } from '@phantom/client';
@@ -52,14 +52,34 @@ declare const DebugCategory: {
     readonly SESSION: "Session";
 };
 
+/**
+ * Phantom extension app.login API types
+ */
+interface PhantomAppLoginOptions {
+    publicKey: string;
+    appId: string;
+    sessionId: string;
+}
+interface PhantomAppLoginResult {
+    walletId: string;
+    organizationId: string;
+    accountDerivationIndex?: number;
+    expiresInMs?: number;
+}
+interface PhantomApp {
+    login(options: PhantomAppLoginOptions): Promise<PhantomAppLoginResult>;
+    features(): Promise<string[]>;
+}
 declare global {
     interface Window {
         phantom?: {
             solana?: unknown;
             ethereum?: unknown;
-        };
+            app?: PhantomApp;
+        } | undefined;
     }
 }
+
 interface InjectedProviderConfig {
     addressTypes: AddressType[];
 }
@@ -105,9 +125,6 @@ interface ProviderPreference {
     type: "injected" | "embedded";
     embeddedWalletType?: "app-wallet" | "user-wallet";
 }
-interface SwitchProviderOptions {
-    embeddedWalletType?: "app-wallet" | "user-wallet" | (string & Record<never, never>);
-}
 
 /**
  * Browser SDK with chain-specific API
@@ -141,10 +158,6 @@ declare class BrowserSDK {
      * Disconnect from the wallet
      */
     disconnect(): Promise<void>;
-    /**
-     * Switch between provider types (injected vs embedded)
-     */
-    switchProvider(type: "injected" | "embedded", options?: SwitchProviderOptions): Promise<void>;
     /**
      * Check if the SDK is connected to a wallet
      */
@@ -285,4 +298,26 @@ declare function getDeeplinkToPhantom(ref?: string): string;
  */
 declare function waitForPhantomExtension(timeoutMs?: number): Promise<boolean>;
 
-export { BrowserInfo, BrowserSDK, BrowserSDKConfig, DebugCallback, DebugCategory, DebugConfig, DebugLevel, DebugMessage, Provider, debug, detectBrowser, getBrowserDisplayName, getDeeplinkToPhantom, getPlatformName, isMobileDevice, parseBrowserFromUserAgent, waitForPhantomExtension };
+/**
+ * Check if Phantom Login is available
+ *
+ * This function checks if:
+ * 1. The Phantom extension is installed
+ * 2. The extension supports the phantom_login feature
+ *
+ * @param timeoutMs - Maximum time to wait for extension in milliseconds (default: 3000)
+ * @returns Promise<boolean> - true if Phantom Login is available, false otherwise
+ *
+ * Usage:
+ * ```typescript
+ * const isAvailable = await isPhantomLoginAvailable();
+ * if (isAvailable) {
+ *   console.log("Phantom Login is available!");
+ * } else {
+ *   console.log("Phantom Login is not available");
+ * }
+ * ```
+ */
+declare function isPhantomLoginAvailable(timeoutMs?: number): Promise<boolean>;
+
+export { BrowserInfo, BrowserSDK, BrowserSDKConfig, DebugCallback, DebugCategory, DebugConfig, DebugLevel, DebugMessage, Provider, debug, detectBrowser, getBrowserDisplayName, getDeeplinkToPhantom, getPlatformName, isMobileDevice, isPhantomLoginAvailable, parseBrowserFromUserAgent, waitForPhantomExtension };