@phantom/embedded-provider-core/dist/index.d.ts

Platform-agnostic embedded provider core logic for Phantom Wallet SDK

import { StamperWithKeyManagement } from '@phantom/sdk-types';
import { AddressType } from '@phantom/client';
import { NetworkId } from '@phantom/constants';
import { ParsedSignatureResult, ParsedTransactionResult } from '@phantom/parsers';

interface Keypair {
    publicKey: string;
    secretKey: string;
}
interface StamperInfo {
    keyId: string;
    publicKey: string;
    createdAt?: number;
    authenticatorId?: string;
}
interface Session {
    sessionId: string;
    walletId: string;
    organizationId: string;
    stamperInfo: StamperInfo;
    keypair?: Keypair;
    authProvider?: string;
    userInfo?: Record<string, any>;
    status: "pending" | "completed" | "failed";
    createdAt: number;
    lastUsed: number;
    authenticatorCreatedAt: number;
    authenticatorExpiresAt: number;
    lastRenewalAttempt?: number;
    username: string;
    accountDerivationIndex?: 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>;
    accountDerivationIndex?: number;
}
interface PhantomConnectOptions {
    organizationId: string;
    parentOrganizationId: string;
    provider?: "google" | "apple";
    redirectUrl?: string;
    customAuthData?: Record<string, any>;
    authUrl?: string;
    sessionId: string;
    appName?: string;
    appLogo?: string;
}
interface JWTAuthOptions {
    organizationId: string;
    parentOrganizationId: string;
    jwtToken: string;
    customAuthData?: Record<string, any>;
    appName?: string;
    appLogo?: string;
}
interface AuthProvider {
    authenticate(options: PhantomConnectOptions | JWTAuthOptions): Promise<void | AuthResult>;
    resumeAuthFromRedirect?(): AuthResult | null;
}

interface PlatformAdapter {
    name: string;
    storage: EmbeddedStorage;
    authProvider: AuthProvider;
    urlParamsAccessor: URLParamsAccessor;
    stamper: StamperWithKeyManagement;
}
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 SignMessageResult extends ParsedSignatureResult {
}
interface SignAndSendTransactionParams {
    transaction: any;
    networkId: NetworkId;
}
interface SignedTransaction extends ParsedTransactionResult {
}
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" | (string & Record<never, never>);
    addressTypes: [AddressType, ...AddressType[]];
    solanaProvider: "web3js" | "kit" | (string & Record<never, never>);
    appName?: string;
    appLogo?: string;
}

type EmbeddedProviderEvent = 'connect' | 'connect_start' | 'connect_error' | 'disconnect' | 'error';
type EventCallback = (data?: any) => void;
declare class EmbeddedProvider {
    private config;
    private platform;
    private storage;
    private authProvider;
    private urlParamsAccessor;
    private stamper;
    private logger;
    private client;
    private walletId;
    private addresses;
    private jwtAuth;
    private eventListeners;
    constructor(config: EmbeddedProviderConfig, platform: PlatformAdapter, logger: DebugLogger);
    on(event: EmbeddedProviderEvent, callback: EventCallback): void;
    off(event: EmbeddedProviderEvent, callback: EventCallback): void;
    private emit;
    private getAndFilterWalletAddresses;
    private validateAndCleanSession;
    private tryExistingConnection;
    private validateAuthOptions;
    private isSessionValid;
    autoConnect(): Promise<void>;
    private createOrganizationAndStamper;
    connect(authOptions?: AuthOptions): Promise<ConnectResult>;
    disconnect(): Promise<void>;
    signMessage(params: SignMessageParams): Promise<ParsedSignatureResult>;
    signAndSendTransaction(params: SignAndSendTransactionParams): Promise<ParsedTransactionResult>;
    getAddresses(): WalletAddress[];
    isConnected(): boolean;
    private handleAuthFlow;
    private handleJWTAuth;
    private handleRedirectAuth;
    private completeAuthConnection;
    private ensureValidAuthenticator;
    private renewAuthenticator;
    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>;

/**
 * Constants for authenticator lifecycle management
 */
/**
 * How long an authenticator is valid before it expires (in milliseconds)
 * Default: 7 days
 * For testing: Use smaller values like 5 * 60 * 1000 (5 minutes)
 */
declare const AUTHENTICATOR_EXPIRATION_TIME_MS: number;
/**
 * How long before expiration should we attempt to renew the authenticator (in milliseconds)
 * Default: 2 days before expiration
 * For testing: Use smaller values like 2 * 60 * 1000 (2 minutes)
 */
declare const AUTHENTICATOR_RENEWAL_WINDOW_MS: number;

export { AUTHENTICATOR_EXPIRATION_TIME_MS, AUTHENTICATOR_RENEWAL_WINDOW_MS, AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedProviderEvent, EmbeddedStorage, EventCallback, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, StamperInfo, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };