@solana/connector 0.0.0 → 0.1.1

package/dist/transaction-signer-D3csM_Mf.d.mts

@@ -0,0 +1,199 @@
+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
+ */
+declare abstract class ConnectorError extends Error {
+    abstract readonly code: string;
+    abstract readonly recoverable: boolean;
+    readonly context?: Record<string, unknown>;
+    readonly originalError?: Error;
+    readonly timestamp: string;
+    constructor(message: string, context?: Record<string, unknown>, originalError?: Error);
+    toJSON(): Record<string, unknown>;
+}
+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';
+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';
+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';
+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';
+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;
+};
+declare function toConnectorError(error: unknown, defaultMessage?: string): ConnectorError;
+declare function getUserFriendlyMessage(error: unknown): string;
+
+/**
+ * Transaction signing abstraction layer
+ */
+
+interface TransactionSigner {
+    /** The wallet address that will sign transactions */
+    readonly address: string;
+    signTransaction(transaction: SolanaTransaction): Promise<SolanaTransaction>;
+    signAllTransactions(transactions: SolanaTransaction[]): Promise<SolanaTransaction[]>;
+    signAndSendTransaction(transaction: SolanaTransaction, options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string>;
+    signAndSendTransactions(transactions: SolanaTransaction[], options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string[]>;
+    signMessage?(message: Uint8Array): Promise<Uint8Array>;
+    getCapabilities(): TransactionSignerCapabilities;
+}
+declare function createTransactionSigner(config: TransactionSignerConfig): TransactionSigner | null;
+/**
+ * @deprecated Use TransactionError from '../errors' instead
+ */
+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
+ */
+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 };

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

@@ -0,0 +1,199 @@
+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
+ */
+declare abstract class ConnectorError extends Error {
+    abstract readonly code: string;
+    abstract readonly recoverable: boolean;
+    readonly context?: Record<string, unknown>;
+    readonly originalError?: Error;
+    readonly timestamp: string;
+    constructor(message: string, context?: Record<string, unknown>, originalError?: Error);
+    toJSON(): Record<string, unknown>;
+}
+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';
+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';
+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';
+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';
+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;
+};
+declare function toConnectorError(error: unknown, defaultMessage?: string): ConnectorError;
+declare function getUserFriendlyMessage(error: unknown): string;
+
+/**
+ * Transaction signing abstraction layer
+ */
+
+interface TransactionSigner {
+    /** The wallet address that will sign transactions */
+    readonly address: string;
+    signTransaction(transaction: SolanaTransaction): Promise<SolanaTransaction>;
+    signAllTransactions(transactions: SolanaTransaction[]): Promise<SolanaTransaction[]>;
+    signAndSendTransaction(transaction: SolanaTransaction, options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string>;
+    signAndSendTransactions(transactions: SolanaTransaction[], options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string[]>;
+    signMessage?(message: Uint8Array): Promise<Uint8Array>;
+    getCapabilities(): TransactionSignerCapabilities;
+}
+declare function createTransactionSigner(config: TransactionSignerConfig): TransactionSigner | null;
+/**
+ * @deprecated Use TransactionError from '../errors' instead
+ */
+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
+ */
+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 };