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

package/README.md

@@ -305,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";
@@ -319,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()
@@ -552,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';
@@ -68,6 +68,7 @@ interface PhantomAppLoginResult {
 }
 interface PhantomApp {
     login(options: PhantomAppLoginOptions): Promise<PhantomAppLoginResult>;
+    features(): Promise<string[]>;
 }
 declare global {
     interface Window {
@@ -297,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 };

package/dist/index.js

@@ -31,6 +31,7 @@ __export(src_exports, {
   getDeeplinkToPhantom: () => getDeeplinkToPhantom,
   getPlatformName: () => getPlatformName,
   isMobileDevice: () => isMobileDevice,
+  isPhantomLoginAvailable: () => isPhantomLoginAvailable,
   parseBrowserFromUserAgent: () => parseBrowserFromUserAgent,
   waitForPhantomExtension: () => waitForPhantomExtension
 });
@@ -476,7 +477,12 @@ var InjectedProvider = class {
             debug.info(DebugCategory.INJECTED_PROVIDER, "Solana connected successfully", { address: publicKey });
           }
         } catch (err) {
-          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Solana", { error: err });
+          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Solana, stopping", { error: err });
+          this.emit("connect_error", {
+            error: err instanceof Error ? err.message : "Failed to connect",
+            source: "manual-connect"
+          });
+          throw err;
         }
       }
       if (this.addressTypes.includes(import_client4.AddressType.ethereum)) {
@@ -492,7 +498,12 @@ var InjectedProvider = class {
             debug.info(DebugCategory.INJECTED_PROVIDER, "Ethereum connected successfully", { addresses: accounts });
           }
         } catch (err) {
-          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Ethereum", { error: err });
+          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Ethereum, stopping", { error: err });
+          this.emit("connect_error", {
+            error: err instanceof Error ? err.message : "Failed to connect",
+            source: "manual-connect"
+          });
+          throw err;
         }
       }
       if (connectedAddresses.length === 0) {
@@ -1129,7 +1140,7 @@ var BrowserAuthProvider = class {
         // OAuth session management - defaults to allow refresh unless explicitly clearing after logout
         clear_previous_session: (phantomOptions.clearPreviousSession ?? false).toString(),
         allow_refresh: (phantomOptions.allowRefresh ?? true).toString(),
-        sdk_version: "1.0.0-beta.15",
+        sdk_version: "1.0.0-beta.16",
         sdk_type: "browser",
         platform: detectBrowser().name
       });
@@ -1267,6 +1278,26 @@ var BrowserPhantomAppProvider = class {
         "Phantom extension authentication is not yet implemented. The extension needs to expose an app.login API (window.phantom.app.login)."
       );
     }
+    try {
+      if (!window.phantom?.app?.features || typeof window.phantom.app.features !== "function") {
+        throw new Error(
+          "Phantom Login is not available. The extension does not support the features API."
+        );
+      }
+      const features = await window.phantom.app.features();
+      if (!Array.isArray(features) || !features.includes("phantom_login")) {
+        throw new Error(
+          "Phantom Login is not available. Please update your Phantom extension to use this authentication method."
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(
+        "Failed to check Phantom Login availability. Please ensure you have the latest version of the Phantom extension."
+      );
+    }
     try {
       const result = await window.phantom.app.login({
         publicKey: options.publicKey,
@@ -1337,7 +1368,7 @@ var EmbeddedProvider = class extends import_embedded_provider_core.EmbeddedProvi
         // Full user agent for more detailed info
         [import_constants2.ANALYTICS_HEADERS.APP_ID]: config.appId,
         [import_constants2.ANALYTICS_HEADERS.WALLET_TYPE]: config.embeddedWalletType,
-        [import_constants2.ANALYTICS_HEADERS.SDK_VERSION]: "1.0.0-beta.15"
+        [import_constants2.ANALYTICS_HEADERS.SDK_VERSION]: "1.0.0-beta.16"
         // Replaced at build time
       }
     };
@@ -1457,9 +1488,11 @@ var ProviderManager = class {
             to: targetProviderType,
             requestedProvider
           });
-          this.switchProvider(targetProviderType, {
-            embeddedWalletType: currentInfo?.embeddedWalletType || this.config.embeddedWalletType
-          });
+          const switchOptions = {};
+          if (targetProviderType === "embedded") {
+            switchOptions.embeddedWalletType = currentInfo?.embeddedWalletType || this.config.embeddedWalletType;
+          }
+          this.switchProvider(targetProviderType, switchOptions);
         }
       }
     }
@@ -1469,12 +1502,16 @@ var ProviderManager = class {
     }
     debug.log(DebugCategory.PROVIDER_MANAGER, "Delegating to provider connect method");
     const result = await this.currentProvider.connect(authOptions);
+    const providerInfo = this.getCurrentProviderInfo();
+    result.providerType = providerInfo?.type;
     debug.log(DebugCategory.PROVIDER_MANAGER, "Connection successful, saving preferences", {
-      addressCount: result.addresses?.length || 0
+      addressCount: result.addresses?.length || 0,
+      providerType: result.providerType
     });
     this.saveProviderPreference();
     debug.info(DebugCategory.PROVIDER_MANAGER, "Connect completed", {
-      addresses: result.addresses
+      addresses: result.addresses,
+      providerType: result.providerType
     });
     return result;
   }
@@ -1658,7 +1695,11 @@ var ProviderManager = class {
     }
     debug.log(DebugCategory.PROVIDER_MANAGER, "Creating injected provider");
     this.createProvider("injected");
-    this.switchProvider(defaultType, { embeddedWalletType: defaultEmbeddedType });
+    const switchOptions = {};
+    if (defaultType === "embedded") {
+      switchOptions.embeddedWalletType = defaultEmbeddedType;
+    }
+    this.switchProvider(defaultType, switchOptions);
   }
   /**
    * Create a provider instance
@@ -2030,6 +2071,49 @@ function getDeeplinkToPhantom(ref) {
   return `https://phantom.app/ul/browse/${currentUrl}${refParam}`;
 }
 
+// src/isPhantomLoginAvailable.ts
+var import_browser_injected_sdk4 = require("@phantom/browser-injected-sdk");
+async function isPhantomLoginAvailable(timeoutMs = 3e3) {
+  const extensionInstalled = await waitForExtension(timeoutMs);
+  if (!extensionInstalled) {
+    return false;
+  }
+  try {
+    if (!window.phantom?.app?.features || typeof window.phantom.app.features !== "function") {
+      return false;
+    }
+    const features = await window.phantom.app.features();
+    if (!Array.isArray(features)) {
+      return false;
+    }
+    return features.includes("phantom_login");
+  } catch (error) {
+    return false;
+  }
+}
+async function waitForExtension(timeoutMs) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    const checkInterval = 100;
+    const checkForExtension = () => {
+      try {
+        if ((0, import_browser_injected_sdk4.isPhantomExtensionInstalled)()) {
+          resolve(true);
+          return;
+        }
+      } catch (error) {
+      }
+      const elapsed = Date.now() - startTime;
+      if (elapsed >= timeoutMs) {
+        resolve(false);
+        return;
+      }
+      setTimeout(checkForExtension, checkInterval);
+    };
+    checkForExtension();
+  });
+}
+
 // src/index.ts
 var import_constants5 = require("@phantom/constants");
 var import_client5 = require("@phantom/client");

package/dist/index.mjs

@@ -440,7 +440,12 @@ var InjectedProvider = class {
             debug.info(DebugCategory.INJECTED_PROVIDER, "Solana connected successfully", { address: publicKey });
           }
         } catch (err) {
-          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Solana", { error: err });
+          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Solana, stopping", { error: err });
+          this.emit("connect_error", {
+            error: err instanceof Error ? err.message : "Failed to connect",
+            source: "manual-connect"
+          });
+          throw err;
         }
       }
       if (this.addressTypes.includes(AddressType4.ethereum)) {
@@ -456,7 +461,12 @@ var InjectedProvider = class {
             debug.info(DebugCategory.INJECTED_PROVIDER, "Ethereum connected successfully", { addresses: accounts });
           }
         } catch (err) {
-          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Ethereum", { error: err });
+          debug.warn(DebugCategory.INJECTED_PROVIDER, "Failed to connect Ethereum, stopping", { error: err });
+          this.emit("connect_error", {
+            error: err instanceof Error ? err.message : "Failed to connect",
+            source: "manual-connect"
+          });
+          throw err;
         }
       }
       if (connectedAddresses.length === 0) {
@@ -1093,7 +1103,7 @@ var BrowserAuthProvider = class {
         // OAuth session management - defaults to allow refresh unless explicitly clearing after logout
         clear_previous_session: (phantomOptions.clearPreviousSession ?? false).toString(),
         allow_refresh: (phantomOptions.allowRefresh ?? true).toString(),
-        sdk_version: "1.0.0-beta.15",
+        sdk_version: "1.0.0-beta.16",
         sdk_type: "browser",
         platform: detectBrowser().name
       });
@@ -1231,6 +1241,26 @@ var BrowserPhantomAppProvider = class {
         "Phantom extension authentication is not yet implemented. The extension needs to expose an app.login API (window.phantom.app.login)."
       );
     }
+    try {
+      if (!window.phantom?.app?.features || typeof window.phantom.app.features !== "function") {
+        throw new Error(
+          "Phantom Login is not available. The extension does not support the features API."
+        );
+      }
+      const features = await window.phantom.app.features();
+      if (!Array.isArray(features) || !features.includes("phantom_login")) {
+        throw new Error(
+          "Phantom Login is not available. Please update your Phantom extension to use this authentication method."
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(
+        "Failed to check Phantom Login availability. Please ensure you have the latest version of the Phantom extension."
+      );
+    }
     try {
       const result = await window.phantom.app.login({
         publicKey: options.publicKey,
@@ -1301,7 +1331,7 @@ var EmbeddedProvider = class extends CoreEmbeddedProvider {
         // Full user agent for more detailed info
         [ANALYTICS_HEADERS.APP_ID]: config.appId,
         [ANALYTICS_HEADERS.WALLET_TYPE]: config.embeddedWalletType,
-        [ANALYTICS_HEADERS.SDK_VERSION]: "1.0.0-beta.15"
+        [ANALYTICS_HEADERS.SDK_VERSION]: "1.0.0-beta.16"
         // Replaced at build time
       }
     };
@@ -1421,9 +1451,11 @@ var ProviderManager = class {
             to: targetProviderType,
             requestedProvider
           });
-          this.switchProvider(targetProviderType, {
-            embeddedWalletType: currentInfo?.embeddedWalletType || this.config.embeddedWalletType
-          });
+          const switchOptions = {};
+          if (targetProviderType === "embedded") {
+            switchOptions.embeddedWalletType = currentInfo?.embeddedWalletType || this.config.embeddedWalletType;
+          }
+          this.switchProvider(targetProviderType, switchOptions);
         }
       }
     }
@@ -1433,12 +1465,16 @@ var ProviderManager = class {
     }
     debug.log(DebugCategory.PROVIDER_MANAGER, "Delegating to provider connect method");
     const result = await this.currentProvider.connect(authOptions);
+    const providerInfo = this.getCurrentProviderInfo();
+    result.providerType = providerInfo?.type;
     debug.log(DebugCategory.PROVIDER_MANAGER, "Connection successful, saving preferences", {
-      addressCount: result.addresses?.length || 0
+      addressCount: result.addresses?.length || 0,
+      providerType: result.providerType
     });
     this.saveProviderPreference();
     debug.info(DebugCategory.PROVIDER_MANAGER, "Connect completed", {
-      addresses: result.addresses
+      addresses: result.addresses,
+      providerType: result.providerType
     });
     return result;
   }
@@ -1622,7 +1658,11 @@ var ProviderManager = class {
     }
     debug.log(DebugCategory.PROVIDER_MANAGER, "Creating injected provider");
     this.createProvider("injected");
-    this.switchProvider(defaultType, { embeddedWalletType: defaultEmbeddedType });
+    const switchOptions = {};
+    if (defaultType === "embedded") {
+      switchOptions.embeddedWalletType = defaultEmbeddedType;
+    }
+    this.switchProvider(defaultType, switchOptions);
   }
   /**
    * Create a provider instance
@@ -1994,6 +2034,49 @@ function getDeeplinkToPhantom(ref) {
   return `https://phantom.app/ul/browse/${currentUrl}${refParam}`;
 }
 
+// src/isPhantomLoginAvailable.ts
+import { isPhantomExtensionInstalled as isPhantomExtensionInstalled3 } from "@phantom/browser-injected-sdk";
+async function isPhantomLoginAvailable(timeoutMs = 3e3) {
+  const extensionInstalled = await waitForExtension(timeoutMs);
+  if (!extensionInstalled) {
+    return false;
+  }
+  try {
+    if (!window.phantom?.app?.features || typeof window.phantom.app.features !== "function") {
+      return false;
+    }
+    const features = await window.phantom.app.features();
+    if (!Array.isArray(features)) {
+      return false;
+    }
+    return features.includes("phantom_login");
+  } catch (error) {
+    return false;
+  }
+}
+async function waitForExtension(timeoutMs) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    const checkInterval = 100;
+    const checkForExtension = () => {
+      try {
+        if (isPhantomExtensionInstalled3()) {
+          resolve(true);
+          return;
+        }
+      } catch (error) {
+      }
+      const elapsed = Date.now() - startTime;
+      if (elapsed >= timeoutMs) {
+        resolve(false);
+        return;
+      }
+      setTimeout(checkForExtension, checkInterval);
+    };
+    checkForExtension();
+  });
+}
+
 // src/index.ts
 import { NetworkId } from "@phantom/constants";
 import { AddressType as AddressType5 } from "@phantom/client";
@@ -2009,6 +2092,7 @@ export {
   getDeeplinkToPhantom,
   getPlatformName,
   isMobileDevice,
+  isPhantomLoginAvailable,
   parseBrowserFromUserAgent,
   waitForPhantomExtension
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/browser-sdk",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.16",
   "description": "Browser SDK for Phantom Wallet",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -31,9 +31,9 @@
     "@phantom/base64url": "^1.0.0-beta.7",
     "@phantom/browser-injected-sdk": "^1.0.0-beta.5",
     "@phantom/chain-interfaces": "^1.0.0-beta.7",
-    "@phantom/client": "^1.0.0-beta.15",
+    "@phantom/client": "^1.0.0-beta.16",
     "@phantom/constants": "^1.0.0-beta.7",
-    "@phantom/embedded-provider-core": "^1.0.0-beta.15",
+    "@phantom/embedded-provider-core": "^1.0.0-beta.16",
     "@phantom/indexed-db-stamper": "^1.0.0-beta.1",
     "@phantom/parsers": "^1.0.0-beta.7",
     "@phantom/sdk-types": "^1.0.0-beta.7",