sphere-connect 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,553 @@
+import { Cedra, Account } from '@cedra-labs/ts-sdk';
+export { Account, Cedra, CedraConfig, Network as CedraNetwork, Ed25519PrivateKey, PrivateKey, PrivateKeyVariants } from '@cedra-labs/ts-sdk';
+import React, { ReactNode } from 'react';
+
+/**
+ * Simple, browser-compatible EventEmitter implementation
+ * Removes dependency on Node.js 'events' module
+ */
+declare class EventEmitter {
+    private listeners;
+    on(event: string, listener: Function): this;
+    off(event: string, listener: Function): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+}
+
+/**
+ * Type definitions for Sphere Account Abstraction SDK
+ */
+type Network = 'mainnet' | 'testnet' | 'devnet';
+interface SDKConfig {
+    /** Sphere network to connect to */
+    network?: Network;
+    /** Google OAuth Client ID */
+    googleClientId?: string;
+    /** Custom RPC endpoint */
+    rpcEndpoint?: string;
+    /** GraphQL indexer endpoint for querying blockchain data */
+    indexerUrl?: string;
+    /** Redirect URI for OAuth flows (optional) */
+    redirectUri?: string;
+}
+interface GoogleAuthResponse {
+    /** Google ID token (JWT) */
+    idToken: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name?: string;
+    /** User's profile picture URL */
+    picture?: string;
+    /** Google user ID */
+    sub: string;
+}
+interface WalletInfo {
+    /** Cedra wallet address (32 bytes hex) */
+    address: string;
+    /** Public key (hex) */
+    publicKey: string;
+    /** Whether the account exists on-chain */
+    existsOnChain: boolean;
+    /** Current sequence number (nonce) */
+    sequenceNumber: string;
+    /** Authentication key */
+    authKey: string;
+}
+interface TransactionOptions {
+    /** Recipient address */
+    to: string;
+    /** Amount to send (in smallest unit, e.g., 100000000 = 1 CED) */
+    amount: number;
+    /** Optional coin type (defaults to CedraCoin) */
+    coinType?: string;
+    /** Optional max gas amount */
+    maxGasAmount?: number;
+    /** Optional gas unit price */
+    gasUnitPrice?: number;
+}
+interface TransactionResult {
+    /** Transaction hash */
+    hash: string;
+    /** Whether transaction was successful (Executed) */
+    success: boolean;
+    /** If aborted, this contains the VM status/error */
+    vmStatus?: string;
+    /** Gas used */
+    gasUsed: string;
+    /** Block height */
+    version: string;
+}
+interface TransactionHistoryItem {
+    hash: string;
+    success: boolean;
+    type: string;
+    sender: string;
+    receiver?: string;
+    amount?: string;
+    timestamp: number;
+    version: string;
+}
+interface FungibleAssetMetadata {
+    asset_type: string;
+    creator_address: string;
+    decimals: number;
+    icon_uri?: string;
+    name: string;
+    project_uri?: string;
+    symbol: string;
+    token_standard: string;
+}
+interface BalanceInfo {
+    /** Coin type identifier */
+    coinType: string;
+    /** Balance amount (in smallest unit) */
+    amount: string;
+    /** Decimals for this coin */
+    decimals: number;
+    /** Human-readable balance */
+    formatted: string;
+    /** Token metadata (if available) */
+    metadata?: FungibleAssetMetadata;
+}
+interface KeylessConfig {
+    /** Google ID token (JWT) used for keyless proof */
+    idToken: string;
+    /** Ephemeral Key Pair (Ed25519) - Runtime only */
+    ephemeralKeyPair?: any;
+    /** Ephemeral Private Key Hex - Storage only */
+    ephemeralPrivateKey?: string;
+    /** Nonce blinding factor used during login */
+    nonceBlinding: string;
+    /** Expiry of the ephemeral session */
+    expiresAt: number;
+}
+interface SessionData {
+    /** Encrypted wallet data (deterministic private key) */
+    encryptedWallet: string;
+    /** Session expiration timestamp */
+    expiresAt: number;
+    /** Google refresh token (encrypted) */
+    refreshToken?: string;
+    /** Keyless session data (Petra way) */
+    keyless?: KeylessConfig;
+    /** User info */
+    userInfo: {
+        email: string;
+        name?: string;
+        picture?: string;
+    };
+}
+interface StorageProvider {
+    /** Get item from storage */
+    getItem(key: string): Promise<string | null>;
+    /** Set item in storage */
+    setItem(key: string, value: string): Promise<void>;
+    /** Remove item from storage */
+    removeItem(key: string): Promise<void>;
+    /** Clear all storage */
+    clear(): Promise<void>;
+}
+interface KeyDerivationOptions {
+    /** User identifier (e.g., Google sub) */
+    userId: string;
+    /** Application-specific salt */
+    salt: string;
+    /** Number of iterations for key derivation */
+    iterations?: number;
+}
+interface SphereWalletMethods {
+    /** Get wallet address */
+    getAddress(): string;
+    /** Get public key */
+    getPublicKey(): string;
+    /** Check if account exists on-chain */
+    existsOnChain(): Promise<boolean>;
+    /** Get account balance */
+    getBalance(coinType?: string): Promise<BalanceInfo>;
+    /** Get all token balances */
+    getAllBalances(): Promise<BalanceInfo[]>;
+    /** Send transaction */
+    sendTransaction(options: TransactionOptions, simulate?: boolean): Promise<TransactionResult>;
+    /** Update network and RPC endpoint */
+    updateNetwork(network: Network, rpcEndpoint: string): void;
+    /** Simulate transaction without submitting */
+    simulateTransaction(options: TransactionOptions): Promise<{
+        success: boolean;
+        gasUsed: string;
+        gasUnitPrice: string;
+        totalGasCost: number;
+        vmStatus: string;
+    }>;
+    /** Sign message */
+    signMessage(message: string): Promise<string>;
+    /** Get account info */
+    getAccountInfo(): Promise<WalletInfo>;
+    /** Wait for a transaction to be confirmed */
+    waitForTransaction(hash: string): Promise<TransactionResult>;
+    /** Get current network gas price */
+    getGasPrice(): Promise<number>;
+    /** Get transaction history */
+    getTransactionHistory(): Promise<TransactionHistoryItem[]>;
+    /** Disconnect wallet */
+    disconnect(): Promise<void>;
+}
+interface AccountAbstractionSDK {
+    /** Initialize SDK */
+    initialize(): Promise<void>;
+    /** Login with Google OAuth */
+    loginWithGoogle(): Promise<SphereWalletMethods>;
+    /** Handle Google OAuth response (for redirects) */
+    handleGoogleResponse(credential: string): Promise<SphereWalletMethods>;
+    /** Restore session if available */
+    restoreSession(): Promise<SphereWalletMethods | null>;
+    /** Logout and clear session */
+    logout(): Promise<void>;
+    /** Check if user is authenticated */
+    isAuthenticated(): boolean;
+    /** Get current wallet (if authenticated) */
+    getCurrentWallet(): SphereWalletMethods | null;
+    /** Get current user email (if authenticated) */
+    getUserEmail(): string | null;
+    /** Get the ephemeral public key for the current session */
+    getEphemeralPublicKey(): string | null;
+    /** Update network and RPC endpoint */
+    updateNetwork(network: Network, rpcEndpoint: string): Promise<void>;
+    getIndexerUrl(): string | undefined;
+    /** Subscribe to SDK events */
+    on(event: string, callback: (data: any) => void): void;
+    /** Unsubscribe from SDK events */
+    off(event: string, callback: (data: any) => void): void;
+}
+interface ErrorResponse {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Additional error details */
+    details?: unknown;
+}
+declare enum ErrorCode {
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    WALLET_CREATION_FAILED = "WALLET_CREATION_FAILED",
+    TRANSACTION_FAILED = "TRANSACTION_FAILED",
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    STORAGE_ERROR = "STORAGE_ERROR",
+    KEY_DERIVATION_FAILED = "KEY_DERIVATION_FAILED",
+    TRANSACTION_ABORTED = "TRANSACTION_ABORTED",
+    DISCARDED_TRANSACTION = "DISCARDED_TRANSACTION",
+    INVALID_CONFIG = "INVALID_CONFIG"
+}
+declare class SphereSDKError extends Error {
+    code: ErrorCode;
+    details?: unknown | undefined;
+    constructor(code: ErrorCode, message: string, details?: unknown | undefined);
+}
+
+/**
+ * Main SDK class for Sphere Account Abstraction
+ */
+declare class SphereAccountAbstraction extends EventEmitter implements AccountAbstractionSDK {
+    private cedra;
+    private config;
+    private authProvider;
+    private storage;
+    private sessionManager;
+    private currentWallet;
+    private initialized;
+    private readonly appName;
+    private readonly storageKey;
+    constructor(config: SDKConfig);
+    initialize(): Promise<void>;
+    loginWithGoogle(): Promise<SphereWalletMethods>;
+    restoreSession(): Promise<SphereWalletMethods | null>;
+    handleGoogleResponse(credential: string): Promise<SphereWalletMethods>;
+    logout(): Promise<void>;
+    isAuthenticated(): boolean;
+    getCurrentWallet(): SphereWalletMethods | null;
+    getUserEmail(): string | null;
+    getEphemeralPublicKey(): string | null;
+    updateNetwork(network: Network, rpcEndpoint: string): Promise<void>;
+    getIndexerUrl(): string | undefined;
+    private encryptWalletData;
+    private decryptWalletData;
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+}
+
+/**
+ * Sphere Wallet Implementation
+ */
+
+/**
+ * Sphere Wallet class
+ * Manages wallet operations and blockchain interactions
+ */
+declare class SphereWallet implements SphereWalletMethods {
+    private account;
+    private client;
+    private network;
+    private privateKeyHex;
+    private keylessConfig;
+    private _indexerUrl;
+    constructor(clientOrKey: Cedra | string, privateKeyOrNetwork?: string | Network, networkOrEndpoint?: Network | string, rpcEndpoint?: string, indexerUrl?: string);
+    getAddress(): string;
+    getPublicKey(): string;
+    getIndexerUrl(): string | null;
+    existsOnChain(): Promise<boolean>;
+    getBalance(coinType?: string): Promise<BalanceInfo>;
+    getAllBalances(): Promise<BalanceInfo[]>;
+    sendTransaction(options: TransactionOptions, simulate?: boolean): Promise<TransactionResult>;
+    waitForTransaction(hash: string): Promise<TransactionResult>;
+    getGasPrice(): Promise<number>;
+    getTransactionHistory(): Promise<TransactionHistoryItem[]>;
+    simulateTransaction(options: TransactionOptions): Promise<{
+        success: boolean;
+        gasUsed: string;
+        gasUnitPrice: string;
+        totalGasCost: number;
+        vmStatus: string;
+    }>;
+    signMessage(message: string): Promise<string>;
+    getAccountInfo(): Promise<WalletInfo>;
+    disconnect(): Promise<void>;
+    updateNetwork(network: Network, rpcEndpoint: string): void;
+    private mapNetwork;
+    getAccount(): Account;
+    getClient(): Cedra;
+    getPrivateKeyHex(): string;
+    setKeylessConfig(config: KeylessConfig): void;
+    isKeyless(): boolean;
+}
+
+/**
+ * Google OAuth Authentication Provider
+ * Handles Google Sign-In flow and token validation
+ */
+
+interface GoogleAuthConfig {
+    clientId: string;
+    redirectUri?: string;
+}
+/**
+ * Google OAuth Provider for authentication
+ */
+declare class GoogleAuthProvider {
+    private clientId;
+    private redirectUri?;
+    constructor(config: GoogleAuthConfig);
+    /**
+     * Initiate Google OAuth login flow
+     * Opens Google Sign-In popup
+     * @param nonce Optional OIDC nonce for keyless binding
+     */
+    login(nonce?: string): Promise<GoogleAuthResponse>;
+    /**
+     * Initialize Google Identity Services
+     * @param callback Credential handler
+     * @param nonce Optional OIDC nonce for binding
+     */
+    initialize(callback: (response: {
+        credential: string;
+    }) => void, nonce?: string): Promise<void>;
+    /**
+     * Handle the credential response from Google
+     */
+    handleCredentialResponse(credential: string): Promise<GoogleAuthResponse>;
+    /**
+     * Verify Google ID token (optional, for enhanced security)
+     * This should ideally be done server-side
+     */
+    verifyToken(idToken: string): Promise<boolean>;
+    /**
+     * Load Google Identity Services script
+     */
+    private loadGoogleIdentityScript;
+    /**
+     * Sign out from Google
+     */
+    logout(): Promise<void>;
+    /**
+     * Render Google Sign-In button
+     * @param elementId ID of the container element
+     * @param options Button customization options
+     * @param options Button customization options
+     */
+    renderButton(elementId: string, options?: {
+        theme?: 'outline' | 'filled_blue' | 'filled_black';
+        size?: 'large' | 'medium' | 'small';
+        text?: 'signin_with' | 'signup_with' | 'continue_with';
+        shape?: 'rectangular' | 'pill' | 'circle' | 'square';
+        width?: string | number;
+        nonce?: string;
+        callback?: (response: {
+            credential: string;
+        }) => void;
+    }): Promise<void>;
+}
+
+/**
+ * Key Derivation Module
+ * Implements secure, deterministic key derivation from Google OAuth credentials
+ */
+
+/**
+ * Derives a deterministic private key from user credentials
+ * Uses HKDF (HMAC-based Key Derivation Function) for security
+ */
+declare class KeyDerivation {
+    private static readonly DEFAULT_ITERATIONS;
+    private static readonly KEY_LENGTH;
+    /**
+     * Derive a private key from user ID and salt
+     * @param options Key derivation options
+     * @returns Hex-encoded private key (64 characters)
+     */
+    static derivePrivateKey(options: KeyDerivationOptions): string;
+    /**
+     * Generate a deterministic salt from app name and user email
+     * This ensures the same user gets the same wallet across devices
+     * @param appName Application name
+     * @param userEmail User's email address
+     * @returns Deterministic salt string
+     */
+    static generateDeterministicSalt(appName: string, userEmail: string): string;
+    /**
+     * Validate a private key format
+     * @param privateKey Hex-encoded private key
+     * @returns True if valid
+     */
+    static isValidPrivateKey(privateKey: string): boolean;
+    /**
+     * Securely clear sensitive data from memory
+     * @param data Sensitive string to clear
+     */
+    static clearSensitiveData(data: string): void;
+    /**
+     * Generates a temporary ephemeral key pair for the session
+     * @returns A fresh Ed25519 account/keypair
+     */
+    static generateEphemeralKeyPair(): Account;
+    /**
+     * Computes an OIDC-compliant nonce hash to bind the session key
+     * @param publicKey Ephemeral Public Key (hex or string)
+     * @param blinding A random blinding factor (hex)
+     * @param expiry Expiration timestamp (optional)
+     * @returns SHA256 hash of the nonce commitment
+     */
+    static computeNonce(publicKey: string, blinding: string, expiry?: number): string;
+}
+
+/**
+ * Secure Storage Module
+ * Handles encrypted storage of sensitive wallet data
+ */
+
+/**
+ * Browser-based secure storage implementation
+ */
+declare class SecureStorage implements StorageProvider {
+    private encryptionKey;
+    private storagePrefix;
+    constructor(encryptionKey?: string, storagePrefix?: string);
+    /**
+     * Get item from storage and decrypt
+     */
+    getItem(key: string): Promise<string | null>;
+    /**
+     * Encrypt and store item
+     */
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Remove item from storage
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Clear all SDK storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Generate encryption key from browser fingerprint
+     * This provides basic encryption without requiring user input
+     * Note: Not cryptographically secure, but better than plaintext
+     */
+    private generateEncryptionKey;
+    /**
+     * Check if storage is available
+     */
+    static isAvailable(): boolean;
+}
+/**
+ * Session Manager
+ * Manages user sessions with automatic expiration
+ */
+declare class SessionManager {
+    private storage;
+    private sessionKey;
+    private sessionDuration;
+    private cachedSession;
+    constructor(storage: StorageProvider, sessionDurationHours?: number);
+    /**
+     * Get cached session data (synchronous)
+     */
+    getCachedSession(): SessionData | null;
+    /**
+     * Save session data
+     */
+    saveSession(data: Omit<SessionData, 'expiresAt'>): Promise<void>;
+    /**
+     * Get current session
+     * Returns null if session doesn't exist or is expired
+     */
+    getSession(): Promise<SessionData | null>;
+    /**
+     * Clear current session
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Check if session is valid
+     */
+    isSessionValid(): Promise<boolean>;
+    /**
+     * Refresh session expiration
+     */
+    refreshSession(): Promise<void>;
+    /**
+     * Get time until session expires (in milliseconds)
+     */
+    getTimeUntilExpiration(): Promise<number | null>;
+}
+
+interface SphereContextType {
+    sdk: SphereAccountAbstraction;
+    wallet: SphereWalletMethods | null;
+    walletInfo: WalletInfo | null;
+    balance: BalanceInfo | null;
+    email: string | null;
+    indexerUrl: string | undefined;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+    login: () => Promise<void>;
+    logout: () => Promise<void>;
+    setIsLoading: (loading: boolean) => void;
+    refreshData: () => Promise<void>;
+    handleAuthSuccess: (wallet: SphereWalletMethods) => Promise<void>;
+}
+interface SphereProviderProps {
+    children: ReactNode;
+    config: SDKConfig;
+}
+declare const SphereProvider: React.FC<SphereProviderProps>;
+declare const useSphere: () => SphereContextType;
+
+interface SphereModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+}
+declare const SphereModal: React.FC<SphereModalProps>;
+
+export { type AccountAbstractionSDK, type BalanceInfo, ErrorCode, type ErrorResponse, type FungibleAssetMetadata, GoogleAuthProvider, type GoogleAuthResponse, KeyDerivation, type KeyDerivationOptions, type KeylessConfig, type Network, type SDKConfig, SecureStorage, type SessionData, SessionManager, SphereAccountAbstraction, SphereModal, SphereProvider, SphereSDKError, SphereWallet, type SphereWalletMethods, type StorageProvider, type TransactionHistoryItem, type TransactionOptions, type TransactionResult, type WalletInfo, useSphere };