@phantom/browser-sdk 0.3.4 → 0.3.6

package/README.md

@@ -11,11 +11,12 @@ npm install @phantom/browser-sdk
 ### Injected Provider (Browser Extension)
 
 ```typescript
-import { BrowserSDK, NetworkId } from "@phantom/browser-sdk";
+import { BrowserSDK, NetworkId, AddressType } from "@phantom/browser-sdk";
 
 // Connect to Phantom browser extension
 const sdk = new BrowserSDK({
   providerType: "injected",
+  addressTypes: [AddressType.solana],
 });
 
 const { addresses } = await sdk.connect();
@@ -41,8 +42,7 @@ const sdk = new BrowserSDK({
   organizationId: "your-org-id",
 });
 
-const { walletId, addresses } = await sdk.connect();
-console.log("Wallet ID:", walletId);
+const { addresses } = await sdk.connect();
 console.log("Addresses:", addresses);
 
 const result = await sdk.signAndSendTransaction({
@@ -69,6 +69,7 @@ Uses the Phantom browser extension installed by the user. No additional configur
 ```typescript
 const sdk = new BrowserSDK({
   providerType: "injected",
+  addressTypes: [AddressType.solana],
 });
 ```
 
@@ -89,10 +90,7 @@ const sdk = new BrowserSDK({
   },
   appName: "My DApp", // optional, for branding
   appLogo: "https://myapp.com/logo.png", // optional, for branding
-  debug: {
-    enabled: true, // optional, enable debug logging
-    level: "info", // optional, debug level
-  },
+  autoConnect: true, // optional, auto-connect to existing session (default: true for embedded)
 });
 ```
 
@@ -162,6 +160,45 @@ const sdk = new BrowserSDK({
 - **@solana/web3.js**: Better ecosystem compatibility, wider community support
 - **@solana/kit**: Better TypeScript support, modern architecture, smaller bundle size
 
+### Auto-Connect Feature
+
+The SDK can automatically reconnect to existing sessions when instantiated, providing a seamless user experience.
+
+```typescript
+const sdk = new BrowserSDK({
+  providerType: "embedded",
+  addressTypes: [AddressType.solana],
+  // ... other config
+  autoConnect: true, // Default: true for embedded, false for injected
+});
+
+// SDK will automatically check for existing valid session and connect in background
+// No need to call connect() if user already has a session
+
+// Check if already connected
+if (sdk.isConnected()) {
+  console.log("Already connected!");
+  const addresses = await sdk.getAddresses();
+} else {
+  // First time or session expired, need to connect manually
+  await sdk.connect();
+}
+```
+
+**Disabling Auto-Connect:**
+
+```typescript
+const sdk = new BrowserSDK({
+  providerType: "embedded",
+  addressTypes: [AddressType.solana],
+  // ... other config
+  autoConnect: false, // Disable auto-connect
+});
+
+// Now you must manually call connect() every time
+await sdk.connect();
+```
+
 ## API Reference
 
 ### Constructor
@@ -177,7 +214,7 @@ interface BrowserSDKConfig {
   providerType: "injected" | "embedded";
   appName?: string; // Optional app name for branding
   appLogo?: string; // Optional app logo URL for branding
-  addressTypes?: AddressType[]; // Networks to enable (e.g., [AddressType.solana])
+  addressTypes?: [AddressType, ...AddressType[]]; // Networks to enable (e.g., [AddressType.solana])
 
   // Required for embedded provider only
   apiBaseUrl?: string; // Phantom API base URL
@@ -188,13 +225,7 @@ interface BrowserSDKConfig {
   };
   embeddedWalletType?: "app-wallet" | "user-wallet"; // Wallet type
   solanaProvider?: "web3js" | "kit"; // Solana library choice (default: 'web3js')
-
-  // Debug options
-  debug?: {
-    enabled?: boolean; // Enable debug logging
-    level?: "info" | "warn" | "error"; // Debug level
-    callback?: (level: string, message: string, data?: any) => void; // Custom debug callback
-  };
+  autoConnect?: boolean; // Enable auto-connect to existing sessions (default: true)
 }
 ```
 
@@ -316,6 +347,118 @@ Disconnect from wallet and clear session.
 await sdk.disconnect();
 ```
 
+#### autoConnect()
+
+Attempt auto-connection using existing session. Should be called after setting up event listeners to avoid race conditions. Only works with embedded providers.
+
+```typescript
+await sdk.autoConnect();
+```
+
+## Debug Configuration
+
+The BrowserSDK provides dynamic debug configuration that can be changed at runtime without reinstantiating the SDK. This provides better performance and cleaner architecture.
+
+### Debug Methods
+
+```typescript
+// Enable debug logging
+sdk.enableDebug();
+
+// Disable debug logging  
+sdk.disableDebug();
+
+// Set debug level
+sdk.setDebugLevel(DebugLevel.INFO);
+
+// Set debug callback function
+sdk.setDebugCallback((message) => {
+  console.log(`[${message.category}] ${message.message}`, message.data);
+});
+
+// Configure all debug settings at once
+sdk.configureDebug({
+  enabled: true,
+  level: DebugLevel.DEBUG,
+  callback: (message) => {
+    // Handle debug messages
+    console.log(`[${message.level}] ${message.category}: ${message.message}`);
+  }
+});
+```
+
+### Debug Levels
+
+```typescript
+import { DebugLevel } from "@phantom/browser-sdk";
+
+// Available debug levels (in order of verbosity)
+DebugLevel.ERROR   // 0 - Only error messages
+DebugLevel.WARN    // 1 - Warning and error messages  
+DebugLevel.INFO    // 2 - Info, warning, and error messages
+DebugLevel.DEBUG   // 3 - All debug messages (most verbose)
+```
+
+### Debug Message Structure
+
+Debug callbacks receive a `DebugMessage` object:
+
+```typescript
+interface DebugMessage {
+  timestamp: number;     // Unix timestamp
+  level: DebugLevel;     // Message level
+  category: string;      // Component category (e.g., "BrowserSDK", "ProviderManager")
+  message: string;       // Debug message text
+  data?: any;           // Additional debug data (optional)
+}
+```
+
+### Example: Debug Console Implementation
+
+```typescript
+import { BrowserSDK, DebugLevel } from "@phantom/browser-sdk";
+
+const sdk = new BrowserSDK({
+  providerType: "embedded",
+  // ... other config
+});
+
+// Store debug messages
+const debugMessages: DebugMessage[] = [];
+
+// Set up debug system
+sdk.configureDebug({
+  enabled: true,
+  level: DebugLevel.INFO,
+  callback: (message) => {
+    debugMessages.push(message);
+    
+    // Keep only last 100 messages
+    if (debugMessages.length > 100) {
+      debugMessages.shift();
+    }
+    
+    // Update UI
+    updateDebugConsole();
+  }
+});
+
+// Dynamic debug level changing
+function changeDebugLevel(newLevel: DebugLevel) {
+  sdk.setDebugLevel(newLevel);
+  console.log(`Debug level changed to: ${DebugLevel[newLevel]}`);
+}
+
+// Toggle debug on/off
+function toggleDebug(enabled: boolean) {
+  if (enabled) {
+    sdk.enableDebug();
+  } else {
+    sdk.disableDebug();
+  }
+}
+```
+
 ## Transaction Examples
 
 ### Solana Transactions

package/dist/index.d.ts

@@ -1,7 +1,7 @@
+import { EmbeddedProviderConfig, AuthOptions, ConnectResult, SignMessageParams, SignMessageResult, SignAndSendTransactionParams, SignedTransaction, WalletAddress, EmbeddedProviderEvent, EventCallback } from '@phantom/embedded-provider-core';
+export { AuthOptions, ConnectResult, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
 import { AddressType } from '@phantom/client';
 export { AddressType } from '@phantom/client';
-import { AuthOptions, ConnectResult, SignMessageParams, SignMessageResult, SignAndSendTransactionParams, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
-export { AuthOptions, ConnectResult, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, WalletAddress } from '@phantom/embedded-provider-core';
 export { NetworkId } from '@phantom/constants';
 
 declare enum DebugLevel {
@@ -48,24 +48,18 @@ declare const DebugCategory: {
     readonly SESSION: "Session";
 };
 
-interface BrowserSDKConfig {
+interface DebugConfig {
+    enabled?: boolean;
+    level?: DebugLevel;
+    callback?: DebugCallback;
+}
+interface BrowserSDKConfig extends Partial<EmbeddedProviderConfig> {
     providerType: "injected" | "embedded" | (string & Record<never, never>);
-    appName?: string;
-    appLogo?: string;
-    addressTypes?: AddressType[];
+    addressTypes: [AddressType, ...AddressType[]];
     apiBaseUrl?: string;
     organizationId?: string;
-    authOptions?: {
-        authUrl?: string;
-        redirectUrl?: string;
-    };
     embeddedWalletType?: "app-wallet" | "user-wallet" | (string & Record<never, never>);
-    solanaProvider?: "web3js" | "kit";
-    debug?: {
-        enabled?: boolean;
-        level?: DebugLevel;
-        callback?: DebugCallback;
-    };
+    autoConnect?: boolean;
 }
 
 interface Provider {
@@ -137,6 +131,50 @@ declare class BrowserSDK {
      * Get the current wallet ID (for embedded wallets)
      */
     getWalletId(): string | null;
+    /**
+     * Add event listener for provider events (connect, connect_start, connect_error, disconnect, error)
+     * Works with both embedded and injected providers
+     */
+    on(event: EmbeddedProviderEvent, callback: EventCallback): void;
+    /**
+     * Remove event listener for provider events
+     * Works with both embedded and injected providers
+     */
+    off(event: EmbeddedProviderEvent, callback: EventCallback): void;
+    /**
+     * Attempt auto-connection using existing session
+     * Should be called after setting up event listeners
+     * Only works with embedded providers
+     */
+    autoConnect(): Promise<void>;
+    /**
+     * Debug configuration methods
+     * These allow dynamic debug configuration without SDK reinstantiation
+     */
+    /**
+     * Enable debug logging
+     */
+    enableDebug(): void;
+    /**
+     * Disable debug logging
+     */
+    disableDebug(): void;
+    /**
+     * Set debug level
+     */
+    setDebugLevel(level: DebugLevel): void;
+    /**
+     * Set debug callback function
+     */
+    setDebugCallback(callback: DebugCallback): void;
+    /**
+     * Configure debug settings all at once
+     */
+    configureDebug(config: {
+        enabled?: boolean;
+        level?: DebugLevel;
+        callback?: DebugCallback;
+    }): void;
 }
 
 /**
@@ -172,4 +210,4 @@ declare function getPlatformName(): string;
  */
 declare function getBrowserDisplayName(): string;
 
-export { BrowserInfo, BrowserSDK, BrowserSDKConfig, DEFAULT_AUTH_URL, DEFAULT_WALLET_API_URL, DebugCallback, DebugCategory, DebugLevel, DebugMessage, Provider, debug, detectBrowser, getBrowserDisplayName, getPlatformName, parseBrowserFromUserAgent };
+export { BrowserInfo, BrowserSDK, BrowserSDKConfig, DEFAULT_AUTH_URL, DEFAULT_WALLET_API_URL, DebugCallback, DebugCategory, DebugConfig, DebugLevel, DebugMessage, Provider, debug, detectBrowser, getBrowserDisplayName, getPlatformName, parseBrowserFromUserAgent };