@phantom/embedded-provider-core 0.1.1

package/README.md

@@ -0,0 +1,349 @@
+# @phantom/embedded-provider-core
+
+Platform-agnostic embedded provider core logic for Phantom Wallet SDK.
+
+## Overview
+
+This package contains the core business logic for Phantom's embedded wallet provider, designed to be shared across different platforms (browser, React Native, etc.). It provides a unified interface for wallet operations while allowing platform-specific implementations through adapters.
+
+## Architecture
+
+The embedded provider core follows a platform adapter pattern:
+
+```
+┌─────────────────────────────────────┐
+│         Platform SDK                │
+│    (browser-sdk, react-native)      │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│      EmbeddedProvider (Core)        │
+│  - Authentication flows             │
+│  - Session management               │
+│  - Wallet operations                │
+│  - Business logic                   │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│       Platform Adapters             │
+│  - Storage (IndexedDB/AsyncStorage) │
+│  - Auth (redirects/deep links)      │
+│  - URL params (window/linking)      │
+│  - Logger (debug/console)           │
+└─────────────────────────────────────┘
+```
+
+## Key Features
+
+- **Cross-platform compatibility**: Share 90%+ of wallet logic across platforms
+- **Clean separation of concerns**: Platform-specific code isolated in adapters
+- **Multiple auth flows**: JWT, Google OAuth, Apple OAuth, app-wallet creation
+- **Session management**: Persistent sessions with validation and recovery
+- **Retry logic**: Built-in retry with exponential backoff for network operations
+- **Type safety**: Full TypeScript support with comprehensive interfaces
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import {
+  EmbeddedProvider,
+  EmbeddedProviderConfig,
+  PlatformAdapter,
+  DebugLogger,
+} from "@phantom/embedded-provider-core";
+
+// 1. Define your configuration
+const config: EmbeddedProviderConfig = {
+  apiBaseUrl: "https://api.phantom.app",
+  organizationId: "your-org-id",
+  embeddedWalletType: "user-wallet", // or 'app-wallet'
+  addressTypes: ["solana", "ethereum"],
+  solanaProvider: "web3js",
+  authOptions: {
+    authUrl: "https://auth.phantom.app",
+    redirectUrl: "https://your-app.com/callback",
+  },
+};
+
+// 2. Implement platform adapters (see examples below)
+const platform: PlatformAdapter = {
+  storage: new YourStorageAdapter(),
+  authProvider: new YourAuthProvider(),
+  urlParamsAccessor: new YourURLParamsAccessor(),
+};
+
+// 3. Implement logger
+const logger: DebugLogger = new YourLogger();
+
+// 4. Create provider instance
+const provider = new EmbeddedProvider(config, platform, logger);
+
+// 5. Use the provider
+const result = await provider.connect();
+console.log("Connected addresses:", result.addresses);
+```
+
+## Platform Adapter Interfaces
+
+### Storage Adapter
+
+Handles persistent session storage:
+
+```typescript
+import { EmbeddedStorage, Session } from "@phantom/embedded-provider-core";
+
+export class YourStorageAdapter implements EmbeddedStorage {
+  async getSession(): Promise<Session | null> {
+    // Platform-specific session retrieval
+    // Browser: IndexedDB, React Native: AsyncStorage
+  }
+
+  async saveSession(session: Session): Promise<void> {
+    // Platform-specific session storage
+  }
+
+  async clearSession(): Promise<void> {
+    // Platform-specific session cleanup
+  }
+}
+```
+
+### Auth Provider
+
+Handles authentication flows:
+
+```typescript
+import { AuthProvider, AuthResult, PhantomConnectOptions, JWTAuthOptions } from "@phantom/embedded-provider-core";
+
+export class YourAuthProvider implements AuthProvider {
+  async authenticate(options: PhantomConnectOptions | JWTAuthOptions): Promise<void | AuthResult> {
+    // Platform-specific authentication
+    // Browser: window redirects, React Native: deep links
+  }
+
+  resumeAuthFromRedirect?(): AuthResult | null {
+    // Resume authentication after redirect/deep link
+  }
+}
+```
+
+### URL Params Accessor
+
+Handles URL parameter access:
+
+```typescript
+import { URLParamsAccessor } from "@phantom/embedded-provider-core";
+
+export class YourURLParamsAccessor implements URLParamsAccessor {
+  getParam(key: string): string | null {
+    // Platform-specific URL parameter access
+    // Browser: window.location.search, React Native: Linking.getInitialURL()
+  }
+}
+```
+
+### Debug Logger
+
+Handles logging:
+
+```typescript
+import { DebugLogger } from "@phantom/embedded-provider-core";
+
+export class YourLogger implements DebugLogger {
+  info(category: string, message: string, data?: any): void {
+    // Platform-specific logging
+  }
+
+  warn(category: string, message: string, data?: any): void {
+    // Platform-specific warning
+  }
+
+  error(category: string, message: string, data?: any): void {
+    // Platform-specific error logging
+  }
+
+  log(category: string, message: string, data?: any): void {
+    // Platform-specific debug logging
+  }
+}
+```
+
+## Authentication Flows
+
+### JWT Authentication
+
+For server-side authenticated users:
+
+```typescript
+const authOptions = {
+  provider: "jwt",
+  jwtToken: "your-jwt-token",
+  customAuthData: { userId: "user123" },
+};
+
+const result = await provider.connect(authOptions);
+```
+
+### OAuth Authentication
+
+For social login flows:
+
+```typescript
+// Google OAuth
+const authOptions = {
+  provider: "google",
+  customAuthData: { referrer: "landing-page" },
+};
+
+await provider.connect(authOptions); // Will redirect/deep link
+
+// Apple OAuth
+const authOptions = {
+  provider: "apple",
+};
+
+await provider.connect(authOptions); // Will redirect/deep link
+```
+
+### App Wallet
+
+For application-controlled wallets:
+
+```typescript
+const config = {
+  // ... other config
+  embeddedWalletType: "app-wallet",
+};
+
+const result = await provider.connect(); // No auth needed
+```
+
+## Session Management
+
+Sessions are automatically managed by the core provider:
+
+```typescript
+// Check connection status
+if (provider.isConnected()) {
+  const addresses = provider.getAddresses();
+  console.log("Available addresses:", addresses);
+}
+
+// Sign a message
+const signature = await provider.signMessage({
+  message: "Hello, world!",
+  networkId: "solana:mainnet",
+});
+
+// Sign and send transaction
+const result = await provider.signAndSendTransaction({
+  transaction: transactionBytes,
+  networkId: "solana:mainnet",
+});
+
+// Disconnect
+await provider.disconnect();
+```
+
+## Error Handling
+
+The core provider provides detailed error messages:
+
+```typescript
+try {
+  await provider.connect();
+} catch (error) {
+  if (error.message.includes("JWT")) {
+    // Handle JWT authentication errors
+  } else if (error.message.includes("Storage")) {
+    // Handle storage errors
+  } else if (error.message.includes("Network")) {
+    // Handle network errors
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+interface EmbeddedProviderConfig {
+  // Required
+  apiBaseUrl: string; // Phantom API base URL
+  organizationId: string; // Your organization ID
+  embeddedWalletType: "app-wallet" | "user-wallet";
+  addressTypes: AddressType[]; // Supported blockchain addresses
+
+  // Optional
+  solanaProvider?: "web3js" | "kit"; // Solana library preference
+  authOptions?: {
+    authUrl?: string; // Custom auth URL
+    redirectUrl?: string; // OAuth redirect URL
+  };
+}
+```
+
+## Session Object
+
+```typescript
+interface Session {
+  sessionId: string; // Unique session identifier
+  walletId: string; // Phantom wallet ID
+  organizationId: string; // Organization ID
+  keypair: {
+    // Cryptographic keypair
+    publicKey: string;
+    secretKey: string;
+  };
+  authProvider: string; // Auth method used
+  userInfo: Record<string, any>; // User information
+  status: "pending" | "completed"; // Session status
+  createdAt: number; // Creation timestamp
+  lastUsed: number; // Last access timestamp
+}
+```
+
+## Best Practices
+
+1. **Platform Adapters**: Keep platform-specific code in adapters only
+2. **Error Handling**: Always handle authentication and network errors
+3. **Session Validation**: The core automatically validates sessions
+4. **Logging**: Use structured logging with categories for debugging
+5. **Security**: Never log sensitive data like private keys
+
+## Examples
+
+See the `@phantom/browser-sdk` package for a complete implementation example using this core package with browser-specific adapters.
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the package
+yarn build
+
+# Run tests
+yarn test
+
+# Run linting
+yarn lint
+
+# Format code
+yarn prettier
+```
+
+## Contributing
+
+This package is designed to be extended for new platforms. When adding support for a new platform:
+
+1. Implement all required platform adapter interfaces
+2. Add comprehensive tests for your adapters
+3. Update documentation with platform-specific examples
+4. Ensure error handling covers platform-specific edge cases
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,154 @@
+import { AddressType, NetworkId } from '@phantom/client';
+
+interface Keypair {
+    publicKey: string;
+    secretKey: string;
+}
+interface Session {
+    sessionId: string;
+    walletId: string;
+    organizationId: string;
+    keypair: Keypair;
+    authProvider?: string;
+    userInfo?: Record<string, any>;
+    status: "pending" | "completed" | "failed";
+    createdAt: number;
+    lastUsed: number;
+}
+interface EmbeddedStorage {
+    getSession(): Promise<Session | null>;
+    saveSession(session: Session): Promise<void>;
+    clearSession(): Promise<void>;
+}
+
+/**
+ * URL parameter accessor abstraction
+ *
+ * This allows us to abstract URL parameter access for different environments:
+ * - Browser: window.location.search via URLSearchParams
+ * - React Native: deep links or webview callback URLs
+ * - Mobile WebView: in-app browser navigation state
+ *
+ * This abstraction makes the auth flow code portable across platforms
+ * without needing to mock window.location directly in tests.
+ */
+interface URLParamsAccessor {
+    /**
+     * Get a URL parameter value by key
+     * @param key - The parameter key to retrieve
+     * @returns The parameter value or null if not found
+     */
+    getParam(key: string): string | null;
+}
+
+interface AuthResult {
+    walletId: string;
+    provider?: string;
+    userInfo?: Record<string, any>;
+}
+interface PhantomConnectOptions {
+    organizationId: string;
+    parentOrganizationId: string;
+    provider?: "google" | "apple";
+    redirectUrl?: string;
+    customAuthData?: Record<string, any>;
+    authUrl?: string;
+    sessionId: string;
+}
+interface JWTAuthOptions {
+    organizationId: string;
+    parentOrganizationId: string;
+    jwtToken: string;
+    customAuthData?: Record<string, any>;
+}
+interface AuthProvider {
+    authenticate(options: PhantomConnectOptions | JWTAuthOptions): Promise<void | AuthResult>;
+    resumeAuthFromRedirect?(): AuthResult | null;
+}
+
+interface PlatformAdapter {
+    storage: EmbeddedStorage;
+    authProvider: AuthProvider;
+    urlParamsAccessor: URLParamsAccessor;
+}
+interface DebugLogger {
+    info(category: string, message: string, data?: any): void;
+    warn(category: string, message: string, data?: any): void;
+    error(category: string, message: string, data?: any): void;
+    log(category: string, message: string, data?: any): void;
+}
+
+interface WalletAddress {
+    addressType: AddressType;
+    address: string;
+}
+interface ConnectResult {
+    walletId?: string;
+    addresses: WalletAddress[];
+    status?: "pending" | "completed";
+}
+interface SignMessageParams {
+    message: string;
+    networkId: NetworkId;
+}
+interface SignAndSendTransactionParams {
+    transaction: any;
+    networkId: NetworkId;
+}
+interface SignedTransaction {
+    rawTransaction: string;
+}
+interface AuthOptions {
+    provider?: "google" | "apple" | "jwt";
+    jwtToken?: string;
+    customAuthData?: Record<string, any>;
+}
+interface EmbeddedProviderConfig {
+    apiBaseUrl: string;
+    organizationId: string;
+    authOptions?: {
+        authUrl?: string;
+        redirectUrl?: string;
+    };
+    embeddedWalletType: "app-wallet" | "user-wallet";
+    addressTypes: AddressType[];
+    solanaProvider: "web3js" | "kit";
+}
+
+declare class EmbeddedProvider {
+    private config;
+    private storage;
+    private authProvider;
+    private urlParamsAccessor;
+    private logger;
+    private client;
+    private walletId;
+    private addresses;
+    private jwtAuth;
+    constructor(config: EmbeddedProviderConfig, platform: PlatformAdapter, logger: DebugLogger);
+    private getAndFilterWalletAddresses;
+    private validateAndCleanSession;
+    private validateAuthOptions;
+    private createOrganizationAndKeypair;
+    connect(authOptions?: AuthOptions): Promise<ConnectResult>;
+    disconnect(): Promise<void>;
+    signMessage(params: SignMessageParams): Promise<string>;
+    signAndSendTransaction(params: SignAndSendTransactionParams): Promise<SignedTransaction>;
+    getAddresses(): WalletAddress[];
+    isConnected(): boolean;
+    private handleAuthFlow;
+    private handleJWTAuth;
+    private handleRedirectAuth;
+    private completeAuthConnection;
+    private initializeClientFromSession;
+}
+
+declare class JWTAuth {
+    authenticate(options: JWTAuthOptions): Promise<AuthResult>;
+}
+
+declare function generateSessionId(): string;
+
+declare function retryWithBackoff<T>(operation: () => Promise<T>, operationName: string, logger: DebugLogger, maxRetries?: number, baseDelay?: number): Promise<T>;
+
+export { AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedStorage, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignedTransaction, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import { AddressType, NetworkId } from '@phantom/client';
+
+interface Keypair {
+    publicKey: string;
+    secretKey: string;
+}
+interface Session {
+    sessionId: string;
+    walletId: string;
+    organizationId: string;
+    keypair: Keypair;
+    authProvider?: string;
+    userInfo?: Record<string, any>;
+    status: "pending" | "completed" | "failed";
+    createdAt: number;
+    lastUsed: number;
+}
+interface EmbeddedStorage {
+    getSession(): Promise<Session | null>;
+    saveSession(session: Session): Promise<void>;
+    clearSession(): Promise<void>;
+}
+
+/**
+ * URL parameter accessor abstraction
+ *
+ * This allows us to abstract URL parameter access for different environments:
+ * - Browser: window.location.search via URLSearchParams
+ * - React Native: deep links or webview callback URLs
+ * - Mobile WebView: in-app browser navigation state
+ *
+ * This abstraction makes the auth flow code portable across platforms
+ * without needing to mock window.location directly in tests.
+ */
+interface URLParamsAccessor {
+    /**
+     * Get a URL parameter value by key
+     * @param key - The parameter key to retrieve
+     * @returns The parameter value or null if not found
+     */
+    getParam(key: string): string | null;
+}
+
+interface AuthResult {
+    walletId: string;
+    provider?: string;
+    userInfo?: Record<string, any>;
+}
+interface PhantomConnectOptions {
+    organizationId: string;
+    parentOrganizationId: string;
+    provider?: "google" | "apple";
+    redirectUrl?: string;
+    customAuthData?: Record<string, any>;
+    authUrl?: string;
+    sessionId: string;
+}
+interface JWTAuthOptions {
+    organizationId: string;
+    parentOrganizationId: string;
+    jwtToken: string;
+    customAuthData?: Record<string, any>;
+}
+interface AuthProvider {
+    authenticate(options: PhantomConnectOptions | JWTAuthOptions): Promise<void | AuthResult>;
+    resumeAuthFromRedirect?(): AuthResult | null;
+}
+
+interface PlatformAdapter {
+    storage: EmbeddedStorage;
+    authProvider: AuthProvider;
+    urlParamsAccessor: URLParamsAccessor;
+}
+interface DebugLogger {
+    info(category: string, message: string, data?: any): void;
+    warn(category: string, message: string, data?: any): void;
+    error(category: string, message: string, data?: any): void;
+    log(category: string, message: string, data?: any): void;
+}
+
+interface WalletAddress {
+    addressType: AddressType;
+    address: string;
+}
+interface ConnectResult {
+    walletId?: string;
+    addresses: WalletAddress[];
+    status?: "pending" | "completed";
+}
+interface SignMessageParams {
+    message: string;
+    networkId: NetworkId;
+}
+interface SignAndSendTransactionParams {
+    transaction: any;
+    networkId: NetworkId;
+}
+interface SignedTransaction {
+    rawTransaction: string;
+}
+interface AuthOptions {
+    provider?: "google" | "apple" | "jwt";
+    jwtToken?: string;
+    customAuthData?: Record<string, any>;
+}
+interface EmbeddedProviderConfig {
+    apiBaseUrl: string;
+    organizationId: string;
+    authOptions?: {
+        authUrl?: string;
+        redirectUrl?: string;
+    };
+    embeddedWalletType: "app-wallet" | "user-wallet";
+    addressTypes: AddressType[];
+    solanaProvider: "web3js" | "kit";
+}
+
+declare class EmbeddedProvider {
+    private config;
+    private storage;
+    private authProvider;
+    private urlParamsAccessor;
+    private logger;
+    private client;
+    private walletId;
+    private addresses;
+    private jwtAuth;
+    constructor(config: EmbeddedProviderConfig, platform: PlatformAdapter, logger: DebugLogger);
+    private getAndFilterWalletAddresses;
+    private validateAndCleanSession;
+    private validateAuthOptions;
+    private createOrganizationAndKeypair;
+    connect(authOptions?: AuthOptions): Promise<ConnectResult>;
+    disconnect(): Promise<void>;
+    signMessage(params: SignMessageParams): Promise<string>;
+    signAndSendTransaction(params: SignAndSendTransactionParams): Promise<SignedTransaction>;
+    getAddresses(): WalletAddress[];
+    isConnected(): boolean;
+    private handleAuthFlow;
+    private handleJWTAuth;
+    private handleRedirectAuth;
+    private completeAuthConnection;
+    private initializeClientFromSession;
+}
+
+declare class JWTAuth {
+    authenticate(options: JWTAuthOptions): Promise<AuthResult>;
+}
+
+declare function generateSessionId(): string;
+
+declare function retryWithBackoff<T>(operation: () => Promise<T>, operationName: string, logger: DebugLogger, maxRetries?: number, baseDelay?: number): Promise<T>;
+
+export { AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedStorage, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignedTransaction, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };