@solana/connector 0.0.0 → 0.1.0

package/dist/transaction-signer-BtJPGXIg.d.ts

@@ -0,0 +1,373 @@
+import { Wallet, WalletAccount } from '@wallet-standard/base';
+import { SolanaClusterId, SolanaCluster } from '@wallet-ui/core';
+import { Signature, Address, TransactionMessage } from 'gill';
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+
+/**
+ * Transaction and signer-related types
+ */
+
+/**
+ * Union type for all supported Solana transaction formats
+ * Supports both legacy (@solana/web3.js) and modern (gill) transaction types
+ */
+type SolanaTransaction = Transaction | VersionedTransaction | TransactionMessage | Uint8Array;
+/**
+ * Transaction status during its lifecycle
+ */
+type TransactionActivityStatus = 'pending' | 'confirmed' | 'failed';
+/**
+ * Methods used to send/sign transactions
+ */
+type TransactionMethod = 'signTransaction' | 'signAllTransactions' | 'signAndSendTransaction' | 'signAndSendTransactions' | 'sendTransaction' | 'sendRawTransaction';
+/**
+ * Transaction metadata for additional context
+ */
+interface TransactionMetadata {
+    /** Transaction size in bytes */
+    size?: number;
+    /** Compute units requested */
+    computeUnits?: number;
+    /** Priority fee in lamports */
+    priorityFee?: number;
+    /** Number of signatures required */
+    numSignatures?: number;
+    /** Whether preflight was skipped */
+    skipPreflight?: boolean;
+    /** Custom metadata fields */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for creating a transaction signer
+ */
+interface TransactionSignerConfig {
+    /** The Wallet Standard wallet instance */
+    wallet: Wallet;
+    /** The specific account to sign with */
+    account: WalletAccount;
+    /** Optional cluster/network context for chain-specific operations */
+    cluster?: SolanaCluster;
+    /** Optional event emitter for transaction lifecycle events */
+    eventEmitter?: {
+        emit: (event: unknown) => void;
+    };
+}
+/**
+ * Result of a signed transaction operation
+ */
+interface SignedTransaction {
+    /** The transaction signature/hash */
+    signature: string;
+    /** The signed transaction data */
+    transaction: SolanaTransaction;
+}
+/**
+ * Capabilities that a transaction signer supports
+ * Useful for conditionally enabling/disabling UI features
+ */
+interface TransactionSignerCapabilities {
+    /** Can sign transactions without sending */
+    canSign: boolean;
+    /** Can sign and send transactions in one operation */
+    canSend: boolean;
+    /** Can sign arbitrary messages */
+    canSignMessage: boolean;
+    /** Can sign multiple transactions at once */
+    supportsBatchSigning: boolean;
+}
+/**
+ * Transaction activity record for debugging and monitoring
+ */
+interface TransactionActivity {
+    /** Transaction signature */
+    signature: Signature;
+    /** When the transaction was sent */
+    timestamp: string;
+    /** Transaction status */
+    status: TransactionActivityStatus;
+    /** Error message if failed */
+    error?: string;
+    /** Cluster where transaction was sent */
+    cluster: SolanaClusterId;
+    /** Fee payer address */
+    feePayer?: Address;
+    /** Method used (signAndSendTransaction, sendTransaction, etc) */
+    method: TransactionMethod;
+    /** Additional metadata */
+    metadata?: TransactionMetadata;
+}
+
+/**
+ * @solana/connector - Unified Error System
+ *
+ * Provides consistent, structured error handling across the entire library.
+ * All errors extend ConnectorError and include:
+ * - Error codes for programmatic handling
+ * - Optional context data
+ * - Original error preservation
+ * - Stack trace capture
+ */
+/**
+ * Base error class for all Connector errors
+ * Provides common structure and metadata
+ */
+declare abstract class ConnectorError extends Error {
+    /**
+     * Error code for programmatic handling
+     */
+    abstract readonly code: string;
+    /**
+     * Whether this error is recoverable (user can retry)
+     */
+    abstract readonly recoverable: boolean;
+    /**
+     * Additional context about the error
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * The underlying error that caused this error
+     */
+    readonly originalError?: Error;
+    /**
+     * Timestamp when error occurred
+     */
+    readonly timestamp: string;
+    constructor(message: string, context?: Record<string, unknown>, originalError?: Error);
+    /**
+     * Get a JSON representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Connection-related errors (wallet connection, disconnection)
+ */
+declare class ConnectionError extends ConnectorError {
+    readonly code: ConnectionErrorCode;
+    readonly recoverable = true;
+    constructor(code: ConnectionErrorCode, message: string, context?: Record<string, unknown>, originalError?: Error);
+}
+type ConnectionErrorCode = 'WALLET_NOT_CONNECTED' | 'WALLET_NOT_FOUND' | 'CONNECTION_FAILED' | 'CONNECTION_REJECTED' | 'DISCONNECTION_FAILED' | 'ACCOUNT_NOT_AVAILABLE' | 'RECONNECTION_FAILED';
+/**
+ * Validation errors (invalid data, unsupported formats)
+ */
+declare class ValidationError extends ConnectorError {
+    readonly code: ValidationErrorCode;
+    readonly recoverable = false;
+    constructor(code: ValidationErrorCode, message: string, context?: Record<string, unknown>, originalError?: Error);
+}
+type ValidationErrorCode = 'INVALID_TRANSACTION' | 'INVALID_MESSAGE' | 'INVALID_ADDRESS' | 'INVALID_SIGNATURE' | 'INVALID_FORMAT' | 'UNSUPPORTED_FORMAT' | 'VALIDATION_FAILED';
+/**
+ * Configuration errors (setup issues, missing required options)
+ */
+declare class ConfigurationError extends ConnectorError {
+    readonly code: ConfigurationErrorCode;
+    readonly recoverable = false;
+    constructor(code: ConfigurationErrorCode, message: string, context?: Record<string, unknown>, originalError?: Error);
+}
+type ConfigurationErrorCode = 'MISSING_PROVIDER' | 'INVALID_CLUSTER' | 'CLUSTER_NOT_FOUND' | 'INVALID_CONFIG' | 'INITIALIZATION_FAILED';
+/**
+ * Network errors (RPC failures, timeout)
+ */
+declare class NetworkError extends ConnectorError {
+    readonly code: NetworkErrorCode;
+    readonly recoverable = true;
+    constructor(code: NetworkErrorCode, message: string, context?: Record<string, unknown>, originalError?: Error);
+}
+type NetworkErrorCode = 'RPC_ERROR' | 'NETWORK_TIMEOUT' | 'NETWORK_UNAVAILABLE' | 'TRANSACTION_SIMULATION_FAILED';
+/**
+ * Transaction errors (signing, sending transactions)
+ * Extends the existing TransactionSignerError pattern
+ */
+declare class TransactionError extends ConnectorError {
+    readonly code: TransactionErrorCode;
+    readonly recoverable: boolean;
+    constructor(code: TransactionErrorCode, message: string, context?: Record<string, unknown>, originalError?: Error);
+}
+type TransactionErrorCode = 'SIGNING_FAILED' | 'SEND_FAILED' | 'FEATURE_NOT_SUPPORTED' | 'USER_REJECTED' | 'SIMULATION_FAILED' | 'INVALID_TRANSACTION' | 'TRANSACTION_EXPIRED';
+declare function isConnectorError(error: unknown): error is ConnectorError;
+declare function isConnectionError(error: unknown): error is ConnectionError;
+declare function isValidationError(error: unknown): error is ValidationError;
+declare function isConfigurationError(error: unknown): error is ConfigurationError;
+declare function isNetworkError(error: unknown): error is NetworkError;
+declare function isTransactionError(error: unknown): error is TransactionError;
+declare const Errors: {
+    readonly walletNotConnected: (context?: Record<string, unknown>) => ConnectionError;
+    readonly walletNotFound: (walletName?: string) => ConnectionError;
+    readonly connectionFailed: (originalError?: Error) => ConnectionError;
+    readonly accountNotAvailable: (address?: string) => ConnectionError;
+    readonly invalidTransaction: (reason: string, context?: Record<string, unknown>) => ValidationError;
+    readonly invalidFormat: (expectedFormat: string, actualFormat?: string) => ValidationError;
+    readonly unsupportedFormat: (format: string) => ValidationError;
+    readonly missingProvider: (hookName: string) => ConfigurationError;
+    readonly clusterNotFound: (clusterId: string, availableClusters: string[]) => ConfigurationError;
+    readonly rpcError: (message: string, originalError?: Error) => NetworkError;
+    readonly networkTimeout: () => NetworkError;
+    readonly signingFailed: (originalError?: Error) => TransactionError;
+    readonly featureNotSupported: (feature: string) => TransactionError;
+    readonly userRejected: (operation: string) => TransactionError;
+};
+/**
+ * Convert any error to a ConnectorError
+ * Useful for wrapping unknown errors in a structured format
+ */
+declare function toConnectorError(error: unknown, defaultMessage?: string): ConnectorError;
+/**
+ * Get user-friendly error message
+ * Converts technical errors into messages suitable for display
+ */
+declare function getUserFriendlyMessage(error: unknown): string;
+
+/**
+ * @solana/connector - Transaction Signing Abstraction Layer
+ *
+ * Provides a clean, unified interface for transaction operations that works
+ * across both Wallet Standard and legacy wallet implementations.
+ *
+ * Inspired by wallet-adapter-compat's transaction signer pattern, this
+ * abstraction layer makes it easy to integrate with transaction libraries
+ * and provides consistent error handling and capability detection.
+ */
+
+/**
+ * Unified transaction signer interface
+ *
+ * This interface abstracts wallet-specific transaction signing methods
+ * into a consistent API that works across all Wallet Standard wallets.
+ *
+ * @example
+ * ```ts
+ * const signer = createTransactionSigner({
+ *   wallet: connectedWallet,
+ *   account: selectedAccount,
+ *   cluster: currentCluster
+ * })
+ *
+ * // Check capabilities before using
+ * const caps = signer.getCapabilities()
+ * if (!caps.canSend) {
+ *   console.warn('Wallet cannot send transactions directly')
+ * }
+ *
+ * // Sign and send a transaction
+ * const signature = await signer.signAndSendTransaction(transaction)
+ * console.log('Transaction sent:', signature)
+ * ```
+ */
+interface TransactionSigner {
+    /** The wallet address that will sign transactions */
+    readonly address: string;
+    /**
+     * Sign a single transaction without sending it
+     * The wallet prompts the user to approve the transaction
+     *
+     * @param transaction - The transaction to sign
+     * @returns The signed transaction
+     * @throws {TransactionSignerError} If wallet doesn't support signing or user rejects
+     */
+    signTransaction(transaction: SolanaTransaction): Promise<SolanaTransaction>;
+    /**
+     * Sign multiple transactions at once
+     * More efficient than signing one-by-one for batch operations
+     * Falls back to sequential signing if batch not supported
+     *
+     * @param transactions - Array of transactions to sign
+     * @returns Array of signed transactions in the same order
+     * @throws {TransactionSignerError} If signing fails for any transaction
+     */
+    signAllTransactions(transactions: SolanaTransaction[]): Promise<SolanaTransaction[]>;
+    /**
+     * Sign and send a transaction in one operation
+     * The wallet handles both signing and broadcasting to the network
+     *
+     * @param transaction - The transaction to sign and send
+     * @param options - Optional send options (e.g., skipPreflight)
+     * @returns The transaction signature/hash
+     * @throws {TransactionSignerError} If sending fails or user rejects
+     */
+    signAndSendTransaction(transaction: SolanaTransaction, options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string>;
+    /**
+     * Sign and send multiple transactions sequentially
+     * Waits for each transaction to be sent before sending the next
+     *
+     * @param transactions - Array of transactions to sign and send
+     * @param options - Optional send options
+     * @returns Array of transaction signatures in the same order
+     * @throws {TransactionSignerError} If any transaction fails
+     */
+    signAndSendTransactions(transactions: SolanaTransaction[], options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string[]>;
+    /**
+     * Sign an arbitrary message (for authentication, verification, etc.)
+     * Optional: not all wallets support message signing
+     *
+     * @param message - The message to sign (as Uint8Array)
+     * @returns The signature bytes
+     * @throws {TransactionSignerError} If wallet doesn't support message signing
+     */
+    signMessage?(message: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Get the signer's capabilities
+     * Use this to conditionally enable/disable features in your UI
+     *
+     * @returns Object describing what this signer can do
+     */
+    getCapabilities(): TransactionSignerCapabilities;
+}
+/**
+ * Create a transaction signer from a Wallet Standard wallet
+ *
+ * This factory function creates a TransactionSigner instance that bridges
+ * Wallet Standard features to a clean, consistent API.
+ *
+ * @param config - Configuration including wallet, account, and optional cluster
+ * @returns TransactionSigner instance, or null if wallet/account invalid
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const signer = createTransactionSigner({
+ *   wallet: connectedWallet,
+ *   account: selectedAccount
+ * })
+ *
+ * if (!signer) {
+ *   console.error('Failed to create signer - wallet or account missing')
+ *   return
+ * }
+ *
+ * // Use the signer
+ * try {
+ *   const sig = await signer.signAndSendTransaction(tx)
+ *   console.log('Success:', sig)
+ * } catch (error) {
+ *   if (error instanceof TransactionSignerError) {
+ *     console.error('Signing error:', error.code, error.message)
+ *   }
+ * }
+ * ```
+ */
+declare function createTransactionSigner(config: TransactionSignerConfig): TransactionSigner | null;
+/**
+ * @deprecated Use TransactionError from '../errors' instead
+ * Kept for backward compatibility
+ *
+ * Custom error class for transaction signer operations
+ * Provides structured error information for better error handling
+ */
+declare class TransactionSignerError extends TransactionError {
+    constructor(message: string, code: 'WALLET_NOT_CONNECTED' | 'FEATURE_NOT_SUPPORTED' | 'SIGNING_FAILED' | 'SEND_FAILED', originalError?: Error);
+}
+/**
+ * @deprecated Use isTransactionError from '../errors' instead
+ * Kept for backward compatibility
+ *
+ * Type guard to check if an error is a TransactionSignerError
+ */
+declare function isTransactionSignerError(error: unknown): error is TransactionSignerError;
+
+export { ConnectorError as C, Errors as E, NetworkError as N, type SolanaTransaction as S, type TransactionSignerConfig as T, ValidationError as V, type SignedTransaction as a, type TransactionSignerCapabilities as b, type TransactionActivity as c, type TransactionActivityStatus as d, type TransactionMethod as e, type TransactionMetadata as f, createTransactionSigner as g, TransactionSignerError as h, isTransactionSignerError as i, type TransactionSigner as j, ConnectionError as k, ConfigurationError as l, TransactionError as m, isConnectorError as n, isConnectionError as o, isValidationError as p, isConfigurationError as q, isNetworkError as r, isTransactionError as s, toConnectorError as t, getUserFriendlyMessage as u, type ConnectionErrorCode as v, type ValidationErrorCode as w, type ConfigurationErrorCode as x, type NetworkErrorCode as y, type TransactionErrorCode as z };