@phantom/browser-sdk 0.2.2 → 0.3.1

package/README.md

@@ -37,7 +37,7 @@ import { BrowserSDK, AddressType, NetworkId } from "@phantom/browser-sdk";
 const sdk = new BrowserSDK({
   providerType: "embedded",
   addressTypes: [AddressType.solana, AddressType.ethereum],
-  apiBaseUrl: "https://api.phantom.com",
+  apiBaseUrl: "https://api.phantom.app/v1/wallets",
   organizationId: "your-org-id",
 });
 
@@ -80,9 +80,13 @@ 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.com",
+  apiBaseUrl: "https://api.phantom.app/v1/wallets",
   organizationId: "your-org-id",
   embeddedWalletType: "app-wallet", // or 'user-wallet'
+  authOptions: {
+    authUrl: "https://auth.phantom.app", // optional, defaults to "https://connect.phantom.app"
+    redirectUrl: "https://yourapp.com/callback", // optional, defaults to current page
+  },
 });
 ```
 
@@ -170,7 +174,10 @@ interface BrowserSDKConfig {
   addressTypes?: AddressType[]; // Networks to enable
   apiBaseUrl?: string; // Phantom API base URL
   organizationId?: string; // Your organization ID
-  authUrl?: string; // Custom auth URL (optional)
+  authOptions?: {
+    authUrl?: string; // Custom auth URL (default: "https://connect.phantom.app")
+    redirectUrl?: string; // Custom redirect URL after authentication
+  };
   embeddedWalletType?: "app-wallet" | "user-wallet"; // Wallet type
   solanaProvider?: "web3js" | "kit"; // Solana library choice (default: 'web3js')
 }
@@ -188,6 +195,57 @@ const result = await sdk.connect();
 // addresses only includes types from addressTypes config
 ```
 
+For embedded user-wallets, you can specify authentication options:
+
+```typescript
+// Phantom Connect with provider selection (default)
+const result = await sdk.connect();
+
+// Phantom Connect with Google authentication (skips provider selection)
+const result = await sdk.connect({
+  authOptions: {
+    provider: "google",
+  },
+});
+
+// Phantom Connect with Apple authentication (skips provider selection)
+const result = await sdk.connect({
+  authOptions: {
+    provider: "apple",
+  },
+});
+
+// JWT authentication (direct API call)
+const result = await sdk.connect({
+  authOptions: {
+    provider: "jwt",
+    jwtToken: "your-jwt-token",
+    customAuthData: { userId: "user123" },
+  },
+});
+```
+
+**Authentication Options:**
+
+- `provider` - Authentication method: `"google"`, `"apple"`, or `"jwt"`
+  - If not specified: Shows provider selection screen on Phantom Connect
+  - If `"google"` or `"apple"`: Skips provider selection and uses specified provider
+  - If `"jwt"`: Uses JWT authentication flow via API call
+- `jwtToken` - Required when `provider` is `"jwt"`. Your JWT token for authentication
+- `customAuthData` - Additional data to pass to authentication service
+
+**Authentication Flow Types:**
+
+1. **Phantom Connect (Redirect-based)**: Used when `provider` is undefined, `"google"`, or `"apple"`
+   - Redirects to `https://connect.phantom.app` (or custom `authOptions.authUrl` from config)
+   - Handles OAuth flow with selected provider
+   - Returns to your app with authentication result using `authOptions.redirectUrl` or current page
+
+2. **JWT Authentication (API-based)**: Used when `provider` is `"jwt"`
+   - Makes direct API call to `/api/auth/jwt` endpoint
+   - Validates JWT token server-side
+   - Returns wallet immediately without redirect
+
 #### signAndSendTransaction(transaction)
 
 Sign and send a native transaction object.
@@ -258,17 +316,35 @@ npm install @solana/web3.js
 ```
 
 ```typescript
-import { Transaction, SystemProgram, PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js";
+import {
+  VersionedTransaction,
+  TransactionMessage,
+  SystemProgram,
+  PublicKey,
+  LAMPORTS_PER_SOL,
+  Connection,
+} from "@solana/web3.js";
 import { BrowserSDK, NetworkId } from "@phantom/browser-sdk";
 
-// Create native Solana transaction
-const transaction = new Transaction().add(
-  SystemProgram.transfer({
-    fromPubkey: new PublicKey(fromAddress),
-    toPubkey: new PublicKey(toAddress),
-    lamports: 0.001 * LAMPORTS_PER_SOL,
-  }),
-);
+// Get recent blockhash
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const { blockhash } = await connection.getLatestBlockhash();
+
+// Create transfer instruction
+const transferInstruction = SystemProgram.transfer({
+  fromPubkey: new PublicKey(fromAddress),
+  toPubkey: new PublicKey(toAddress),
+  lamports: 0.001 * LAMPORTS_PER_SOL,
+});
+
+// Create VersionedTransaction
+const messageV0 = new TransactionMessage({
+  payerKey: new PublicKey(fromAddress),
+  recentBlockhash: blockhash,
+  instructions: [transferInstruction],
+}).compileToV0Message();
+
+const transaction = new VersionedTransaction(messageV0);
 
 // Send native transaction object - no encoding needed!
 const result = await sdk.signAndSendTransaction({
@@ -494,19 +570,31 @@ import { BrowserSDK, AddressType } from "@phantom/browser-sdk";
 
 const sdk = new BrowserSDK({
   addressTypes: [AddressType.solana, AddressType.ethereum, AddressType.sui],
-  apiBaseUrl: "https://api.phantom.com",
+  apiBaseUrl: "https://api.phantom.app/v1/wallets",
   organizationId: "your-org-id",
 });
 
 class MultiChainWallet {
   async sendSolana(amount: number, recipient: string) {
-    const transaction = new Transaction().add(
-      SystemProgram.transfer({
-        fromPubkey: new PublicKey(this.solanaAddress),
-        toPubkey: new PublicKey(recipient),
-        lamports: amount * LAMPORTS_PER_SOL,
-      }),
-    );
+    // Get recent blockhash
+    const connection = new Connection("https://api.mainnet-beta.solana.com");
+    const { blockhash } = await connection.getLatestBlockhash();
+
+    // Create transfer instruction
+    const transferInstruction = SystemProgram.transfer({
+      fromPubkey: new PublicKey(this.solanaAddress),
+      toPubkey: new PublicKey(recipient),
+      lamports: amount * LAMPORTS_PER_SOL,
+    });
+
+    // Create VersionedTransaction
+    const messageV0 = new TransactionMessage({
+      payerKey: new PublicKey(this.solanaAddress),
+      recentBlockhash: blockhash,
+      instructions: [transferInstruction],
+    }).compileToV0Message();
+
+    const transaction = new VersionedTransaction(messageV0);
 
     return await sdk.signAndSendTransaction({
       networkId: NetworkId.SOLANA_MAINNET,
@@ -669,7 +757,7 @@ For embedded wallets, you need to set up a backend endpoint. Add the `serverUrl`
 const sdk = new BrowserSDK({
   providerType: "embedded",
   addressTypes: [AddressType.solana],
-  apiBaseUrl: "https://api.phantom.com",
+  apiBaseUrl: "https://api.phantom.app/v1/wallets",
   organizationId: "your-org-id",
   serverUrl: "http://localhost:3000/api",
 });

package/dist/index.d.ts

@@ -1,5 +1,52 @@
-import { AddressType, NetworkId } from '@phantom/client';
-export { AddressType, NetworkId } from '@phantom/client';
+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 {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+interface DebugMessage {
+    timestamp: number;
+    level: DebugLevel;
+    category: string;
+    message: string;
+    data?: any;
+}
+type DebugCallback = (message: DebugMessage) => void;
+declare class Debug {
+    private static instance;
+    private callback?;
+    private level;
+    private enabled;
+    private constructor();
+    static getInstance(): Debug;
+    setCallback(callback: DebugCallback): void;
+    setLevel(level: DebugLevel): void;
+    enable(): void;
+    disable(): void;
+    private writeLog;
+    error(category: string, message: string, data?: any): void;
+    warn(category: string, message: string, data?: any): void;
+    info(category: string, message: string, data?: any): void;
+    debug(category: string, message: string, data?: any): void;
+    log(category: string, message: string, data?: any): void;
+}
+declare const debug: Debug;
+declare const DebugCategory: {
+    readonly BROWSER_SDK: "BrowserSDK";
+    readonly PROVIDER_MANAGER: "ProviderManager";
+    readonly EMBEDDED_PROVIDER: "EmbeddedProvider";
+    readonly INJECTED_PROVIDER: "InjectedProvider";
+    readonly PHANTOM_CONNECT_AUTH: "PhantomConnectAuth";
+    readonly JWT_AUTH: "JWTAuth";
+    readonly STORAGE: "Storage";
+    readonly SESSION: "Session";
+};
 
 interface BrowserSDKConfig {
     providerType: "injected" | "embedded" | (string & Record<never, never>);
@@ -7,29 +54,18 @@ interface BrowserSDKConfig {
     addressTypes?: AddressType[];
     apiBaseUrl?: string;
     organizationId?: string;
-    authUrl?: string;
+    authOptions?: {
+        authUrl?: string;
+        redirectUrl?: string;
+    };
     embeddedWalletType?: "app-wallet" | "user-wallet" | (string & Record<never, never>);
     solanaProvider?: "web3js" | "kit";
     serverUrl?: string;
-}
-interface WalletAddress {
-    addressType: AddressType;
-    address: string;
-}
-interface ConnectResult {
-    walletId?: string;
-    addresses: WalletAddress[];
-}
-interface SignMessageParams {
-    message: string;
-    networkId: NetworkId;
-}
-interface SignAndSendTransactionParams {
-    transaction: any;
-    networkId: NetworkId;
-}
-interface SignedTransaction {
-    rawTransaction: string;
+    debug?: {
+        enabled?: boolean;
+        level?: DebugLevel;
+        callback?: DebugCallback;
+    };
 }
 interface CreateUserOrganizationParams {
     userId: string;
@@ -38,10 +74,11 @@ interface CreateUserOrganizationParams {
 interface CreateUserOrganizationResult {
     organizationId: string;
 }
+
 interface Provider {
-    connect(): Promise<ConnectResult>;
+    connect(authOptions?: AuthOptions): Promise<ConnectResult>;
     disconnect(): Promise<void>;
-    signMessage(params: SignMessageParams): Promise<string>;
+    signMessage(params: SignMessageParams): Promise<SignMessageResult>;
     signAndSendTransaction(params: SignAndSendTransactionParams): Promise<SignedTransaction>;
     getAddresses(): WalletAddress[];
     isConnected(): boolean;
@@ -65,6 +102,7 @@ declare class BrowserSDK {
     connect(options?: {
         providerType?: "injected" | "embedded" | (string & Record<never, never>);
         embeddedWalletType?: "app-wallet" | "user-wallet" | (string & Record<never, never>);
+        authOptions?: AuthOptions;
     }): Promise<ConnectResult>;
     /**
      * Switch to a different provider type
@@ -88,7 +126,7 @@ declare class BrowserSDK {
      * @param networkId - Network identifier
      * @returns Signature string
      */
-    signMessage(params: SignMessageParams): Promise<string>;
+    signMessage(params: SignMessageParams): Promise<SignMessageResult>;
     /**
      * Sign and send a transaction
      * @param params - Transaction parameters with native transaction object
@@ -115,4 +153,37 @@ declare class BrowserSDK {
     createUserOrganization(params: CreateUserOrganizationParams): Promise<CreateUserOrganizationResult>;
 }
 
-export { BrowserSDK, BrowserSDKConfig, ConnectResult, CreateUserOrganizationParams, CreateUserOrganizationResult, Provider, SignAndSendTransactionParams, SignMessageParams, SignedTransaction, WalletAddress };
+/**
+ * Constants used throughout the browser SDK
+ */
+declare const DEFAULT_AUTH_URL = "https://connect.phantom.app";
+declare const DEFAULT_WALLET_API_URL = "https://api.phantom.app/v1/wallets";
+
+/**
+ * Browser detection utility to identify browser name and version
+ */
+interface BrowserInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Parse browser information from a user agent string
+ * This is the core parsing logic that can be unit tested independently
+ */
+declare function parseBrowserFromUserAgent(userAgent: string, hasBraveAPI?: boolean): BrowserInfo;
+/**
+ * Detect the current browser and version from the user agent string
+ */
+declare function detectBrowser(): BrowserInfo;
+/**
+ * Get a formatted platform name for use in authenticator names
+ * Format: "browsername-v123" (e.g., "chrome-v120", "firefox-v119")
+ */
+declare function getPlatformName(): string;
+/**
+ * Get detailed browser information as a string
+ * Format: "Chrome 120.0" or "Firefox 119.0"
+ */
+declare function getBrowserDisplayName(): string;
+
+export { BrowserInfo, BrowserSDK, BrowserSDKConfig, CreateUserOrganizationParams, CreateUserOrganizationResult, DEFAULT_AUTH_URL, DEFAULT_WALLET_API_URL, DebugCallback, DebugCategory, DebugLevel, DebugMessage, Provider, debug, detectBrowser, getBrowserDisplayName, getPlatformName, parseBrowserFromUserAgent };