@solana/connector 0.0.0 → 0.1.0

package/dist/headless.d.mts

@@ -0,0 +1,400 @@
+import { B as StorageOptions, S as StorageAdapter, F as EnhancedStorageAccountOptions, G as EnhancedStorageClusterOptions, H as EnhancedStorageWalletOptions } from './wallet-standard-shim-Af7ejSld.mjs';
+export { q as AccountAddress, A as AccountInfo, K as ClipboardErrorType, N as ClipboardResult, i as ClusterType, j as ConnectorClient, d as ConnectorConfig, v as ConnectorDebugMetrics, x as ConnectorDebugState, y as ConnectorEvent, z as ConnectorEventListener, t as ConnectorHealth, e as ConnectorState, O as CopyOptions, D as DefaultConfigOptions, E as ExtendedConnectorConfig, L as Listener, M as MobileWalletAdapterConfig, a7 as PUBLIC_RPC_ENDPOINTS, a6 as SolanaNetwork, h as UnifiedConfig, U as UnifiedConfigOptions, J as WalletError, I as WalletErrorType, W as WalletInfo, p as WalletName, g as WalletStandardAccount, f as WalletStandardWallet, R as copyAddressToClipboard, T as copySignatureToClipboard, Q as copyToClipboard, n as createConfig, Z as getAddressUrl, $ as getBlockUrl, X as getClusterExplorerUrl, a4 as getClusterName, V as getClusterRpcUrl, a5 as getClusterType, l as getDefaultConfig, m as getDefaultMobileConfig, aa as getDefaultRpcUrl, af as getNetworkDisplayName, _ as getTokenUrl, Y as getTransactionUrl, k as getWalletsRegistry, s as isAccountAddress, P as isClipboardAvailable, ac as isDevnet, a1 as isDevnetCluster, a3 as isLocalCluster, ae as isLocalnet, ab as isMainnet, a0 as isMainnetCluster, ad as isTestnet, a2 as isTestnetCluster, o as isUnifiedConfig, r as isWalletName, a8 as normalizeNetwork, a9 as toClusterId } from './wallet-standard-shim-Af7ejSld.mjs';
+import { j as TransactionSigner } from './transaction-signer-BtJPGXIg.mjs';
+export { l as ConfigurationError, x as ConfigurationErrorCode, k as ConnectionError, v as ConnectionErrorCode, C as ConnectorError, E as Errors, N as NetworkError, y as NetworkErrorCode, a as SignedTransaction, S as SolanaTransaction, c as TransactionActivity, d as TransactionActivityStatus, m as TransactionError, z as TransactionErrorCode, f as TransactionMetadata, e as TransactionMethod, b as TransactionSignerCapabilities, T as TransactionSignerConfig, h as TransactionSignerError, V as ValidationError, w as ValidationErrorCode, g as createTransactionSigner, u as getUserFriendlyMessage, q as isConfigurationError, o as isConnectionError, n as isConnectorError, r as isNetworkError, s as isTransactionError, i as isTransactionSignerError, p as isValidationError, t as toConnectorError } from './transaction-signer-BtJPGXIg.mjs';
+import { TransactionModifyingSigner } from 'gill';
+import { Storage, SolanaClusterId } from '@wallet-ui/core';
+export { SolanaCluster, SolanaClusterId, createSolanaDevnet, createSolanaLocalnet, createSolanaMainnet, createSolanaTestnet } from '@wallet-ui/core';
+export { Wallet, WalletAccount } from '@wallet-standard/base';
+import 'react';
+import 'react/jsx-runtime';
+import '@solana/web3.js';
+
+/**
+ * @solana/connector - Formatting utilities
+ *
+ * Unified utility functions for formatting addresses, amounts, and other display values
+ * Consolidates both fast (number-based) and precise (bigint-based) formatting options
+ */
+/**
+ * Format a Solana address for display
+ *
+ * @example
+ * formatAddress('7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU')
+ * // Returns: '7xKX...gAsU'
+ *
+ * @example
+ * formatAddress('7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU', { length: 6 })
+ * // Returns: '7xKXtg...osgAsU'
+ */
+declare function formatAddress(address: string, options?: {
+    length?: number;
+    separator?: string;
+}): string;
+/**
+ * Format SOL amount for display
+ * Supports both precise bigint and fast number arithmetic
+ *
+ * @param lamports - Amount in lamports (number or bigint)
+ * @param options - Formatting options
+ * @param options.decimals - Number of decimal places (default: 4)
+ * @param options.suffix - Add 'SOL' suffix (default: true)
+ * @param options.fast - Use fast number arithmetic for amounts < 9000 SOL (default: false)
+ *
+ * @example
+ * formatSOL(1000000000n) // Returns: '1.0000 SOL' (precise)
+ * formatSOL(1000000000, { fast: true }) // Returns: '1.0000 SOL' (fast)
+ * formatSOL(1500000000, { decimals: 2 }) // Returns: '1.50 SOL'
+ */
+declare function formatSOL(lamports: number | bigint, options?: {
+    decimals?: number;
+    suffix?: boolean;
+    fast?: boolean;
+}): string;
+/**
+ * Format a number with thousands separators
+ *
+ * @example
+ * formatNumber(1234567.89) // Returns: '1,234,567.89'
+ */
+declare function formatNumber(value: number, options?: {
+    decimals?: number;
+    locale?: string;
+}): string;
+/**
+ * Truncate text with ellipsis
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length including ellipsis
+ * @param position - Where to truncate: 'middle' or 'end' (default: 'middle')
+ *
+ * @example
+ * truncate('Hello World', 8) // Returns: 'He...ld'
+ * truncate('Hello World', 8, 'end') // Returns: 'Hello...'
+ * truncate('Short', 10) // Returns: 'Short' (no truncation needed)
+ */
+declare function truncate(text: string, maxLength: number, position?: 'middle' | 'end'): string;
+/**
+ * Format token amount with proper decimals
+ *
+ * @example
+ * formatTokenAmount(1000000, 6) // Returns: '1.000000'
+ */
+declare function formatTokenAmount(amount: number | bigint, decimals: number, options?: {
+    minimumDecimals?: number;
+    maximumDecimals?: number;
+}): string;
+
+/**
+ * @solana/connector - Gill/Kit Transaction Signer Adapter
+ *
+ * Adapter that wraps connector-kit's TransactionSigner to be compatible with
+ * gill (@solana/kit) TransactionModifyingSigner interface.
+ *
+ * This enables connector-kit to work seamlessly with modern Solana libraries
+ * that expect @solana/kit's signer interface.
+ *
+ * Uses TransactionModifyingSigner to return fully signed Transaction objects,
+ * ensuring the exact bytes the wallet signed are preserved without re-encoding.
+ */
+
+/**
+ * Create a gill-compatible TransactionPartialSigner from connector-kit's TransactionSigner
+ *
+ * This adapter allows connector-kit to work with modern Solana libraries that use
+ * @solana/kit's signer interfaces (gill, etc.)
+ *
+ * @param connectorSigner - Connector-kit's TransactionSigner instance
+ * @returns Gill-compatible TransactionPartialSigner
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionSigner } from '@solana/connector';
+ * import { createGillTransactionSigner } from '@solana/connector/gill';
+ *
+ * const connectorSigner = createTransactionSigner({ wallet, account });
+ * const gillSigner = createGillTransactionSigner(connectorSigner);
+ *
+ * // Now compatible with gill libraries
+ * const instruction = getTransferSolInstruction({
+ *   source: gillSigner,
+ *   destination: address('...'),
+ *   amount: 1000000n
+ * });
+ * ```
+ */
+declare function createGillTransactionSigner<TAddress extends string = string>(connectorSigner: TransactionSigner): TransactionModifyingSigner<TAddress>;
+
+/**
+ * @solana/connector - Enhanced Storage
+ *
+ * Extended version of @wallet-ui/core Storage with additional features:
+ * - Validation hooks
+ * - Error handling and recovery
+ * - SSR/memory fallback
+ * - Transform utilities
+ * - Migration support
+ * - Storage availability checks
+ */
+
+/**
+ * Enhanced version of wallet-ui's Storage class
+ * Extends the base Storage with validation, error handling, and SSR support
+ */
+declare class EnhancedStorage<T> extends Storage<T> {
+    private options?;
+    private errorHandlers;
+    private validators;
+    private memoryFallback;
+    constructor(key: string, initial: T, options?: StorageOptions<T> | undefined);
+    /**
+     * Enhanced set with validation and error handling
+     * @returns boolean indicating success
+     */
+    set(value: T): boolean;
+    /**
+     * Enhanced get with error handling and fallback
+     */
+    get(): T;
+    /**
+     * Validate a value against all registered validators
+     */
+    validate(value: T): boolean;
+    /**
+     * Add a validation rule (chainable)
+     *
+     * @example
+     * ```ts
+     * storage
+     *   .addValidator((addr) => addr?.length === 44)
+     *   .addValidator((addr) => addr?.startsWith('5'))
+     * ```
+     */
+    addValidator(validator: (value: T) => boolean): this;
+    /**
+     * Add error handler (chainable)
+     */
+    onError(handler: (error: Error) => void): this;
+    /**
+     * Transform the stored value
+     *
+     * @example
+     * ```ts
+     * const formatted = storage.transform(
+     *   (address) => address ? formatAddress(address) : ''
+     * )
+     * ```
+     */
+    transform<U>(transformer: (value: T) => U): U;
+    /**
+     * Reset to initial value
+     */
+    reset(): void;
+    /**
+     * Clear storage (remove from localStorage)
+     */
+    clear(): void;
+    /**
+     * Check if storage is available (not in private mode, quota not exceeded)
+     */
+    isAvailable(): boolean;
+    /**
+     * Migrate from old key to new key
+     *
+     * @example
+     * ```ts
+     * EnhancedStorage.migrate(
+     *   'old-connector:account',
+     *   createEnhancedStorageAccount()
+     * )
+     * ```
+     */
+    static migrate<T>(oldKey: string, newStorage: EnhancedStorage<T>): boolean;
+    private handleError;
+}
+/**
+ * Create a storage instance for wallet account persistence
+ *
+ * @example
+ * ```ts
+ * const storage = createEnhancedStorageAccount({
+ *   validator: (address) => {
+ *     if (!address) return true
+ *     return isAddress(address)
+ *   }
+ * })
+ * ```
+ */
+declare function createEnhancedStorageAccount(options?: EnhancedStorageAccountOptions): EnhancedStorage<string | undefined>;
+/**
+ * Create a storage instance for cluster selection persistence
+ *
+ * @example
+ * ```ts
+ * const storage = createEnhancedStorageCluster({
+ *   initial: 'solana:mainnet',
+ *   validClusters: ['solana:mainnet', 'solana:devnet']
+ * })
+ * ```
+ */
+declare function createEnhancedStorageCluster(options?: EnhancedStorageClusterOptions): EnhancedStorage<SolanaClusterId>;
+/**
+ * Create a storage instance for wallet name persistence
+ *
+ * @example
+ * ```ts
+ * const storage = createEnhancedStorageWallet({
+ *   onError: (error) => console.error('Wallet storage error:', error)
+ * })
+ * ```
+ */
+declare function createEnhancedStorageWallet(options?: EnhancedStorageWalletOptions): EnhancedStorage<string | undefined>;
+/**
+ * Adapter to make EnhancedStorage compatible with StorageAdapter interface
+ * Exposes both the basic interface and enhanced methods for advanced usage
+ */
+declare class EnhancedStorageAdapter<T> implements StorageAdapter<T> {
+    private storage;
+    constructor(storage: EnhancedStorage<T>);
+    get(): T;
+    set(value: T): void;
+    subscribe(callback: (value: T) => void): () => void;
+    validate(value: T): boolean;
+    reset(): void;
+    clear(): void;
+    isAvailable(): boolean;
+    transform<U>(transformer: (value: T) => U): U;
+    addValidator(validator: (value: T) => boolean): this;
+    onError(handler: (error: Error) => void): this;
+}
+
+/**
+ * @solana/connector - Browser Compatibility Polyfills
+ *
+ * Ensures connector works across all browser environments including:
+ * - Mobile browsers (iOS Safari, Chrome Mobile, etc.)
+ * - Older desktop browsers
+ * - Environments with restricted crypto APIs
+ *
+ * Inspired by wallet-adapter-compat's polyfill strategy
+ */
+/**
+ * Install browser compatibility polyfills
+ *
+ * This function:
+ * - Installs WebCrypto Ed25519 polyfill for signature operations
+ * - Is safe to call multiple times (idempotent)
+ * - Only runs in browser environments
+ * - Fails gracefully if installation errors occur
+ *
+ * @example
+ * ```ts
+ * // Automatically called when connector-provider is imported
+ * import { ConnectorProvider } from '@solana/connector'
+ *
+ * // Can also be called manually if needed
+ * import { installPolyfills } from '@solana/connector/headless'
+ * installPolyfills()
+ * ```
+ */
+declare function installPolyfills(): void;
+/**
+ * Check if polyfills have been installed
+ * Useful for debugging and health checks
+ *
+ * @returns True if polyfills are installed, false otherwise
+ *
+ * @example
+ * ```ts
+ * import { isPolyfillInstalled } from '@solana/connector/headless'
+ *
+ * if (!isPolyfillInstalled()) {
+ *   console.warn('Polyfills not installed - may have issues on older browsers')
+ * }
+ * ```
+ */
+declare function isPolyfillInstalled(): boolean;
+/**
+ * Check if WebCrypto API is available
+ * Useful for detecting environments with restricted crypto capabilities
+ *
+ * @returns True if crypto.subtle is available, false otherwise
+ *
+ * @example
+ * ```ts
+ * import { isCryptoAvailable } from '@solana/connector/headless'
+ *
+ * if (!isCryptoAvailable()) {
+ *   // Show warning to user about unsupported browser
+ * }
+ * ```
+ */
+declare function isCryptoAvailable(): boolean;
+/**
+ * Get polyfill status information
+ * Returns detailed information about polyfill and crypto availability
+ *
+ * @returns Object with polyfill status details
+ *
+ * @example
+ * ```ts
+ * import { getPolyfillStatus } from '@solana/connector/headless'
+ *
+ * const status = getPolyfillStatus()
+ * console.log('Polyfills:', status.installed ? 'installed' : 'not installed')
+ * console.log('WebCrypto:', status.cryptoAvailable ? 'available' : 'unavailable')
+ * ```
+ */
+declare function getPolyfillStatus(): {
+    installed: boolean;
+    cryptoAvailable: boolean;
+    environment: 'browser' | 'server';
+};
+
+/**
+ * @solana/connector - Explorer URL Utilities
+ *
+ * Generate URLs for various Solana block explorers to view transactions,
+ * accounts, and other on-chain data.
+ */
+type ExplorerType = 'solana-explorer' | 'solscan' | 'xray' | 'solana-fm';
+interface ExplorerOptions {
+    /** Cluster to use for the explorer link */
+    cluster?: string;
+    /** Custom RPC URL for localnet */
+    customUrl?: string;
+}
+/**
+ * Generate Solana Explorer URL for a transaction signature
+ */
+declare function getSolanaExplorerUrl(signature: string, options?: ExplorerOptions): string;
+/**
+ * Generate Solscan URL for a transaction signature
+ */
+declare function getSolscanUrl(signature: string, options?: ExplorerOptions): string;
+/**
+ * Generate XRAY (Helius) URL for a transaction signature
+ * Note: XRAY works best with mainnet transactions
+ */
+declare function getXrayUrl(signature: string): string;
+/**
+ * Generate SolanaFM URL for a transaction signature
+ */
+declare function getSolanaFmUrl(signature: string, options?: ExplorerOptions): string;
+/**
+ * Get all explorer URLs for a transaction
+ */
+declare function getAllExplorerUrls(signature: string, options?: ExplorerOptions): Record<ExplorerType, string>;
+/**
+ * Format a transaction signature for display (truncated)
+ */
+declare function formatSignature(signature: string, chars?: number): string;
+/**
+ * Copy signature to clipboard with enhanced error handling
+ *
+ * @deprecated Use copySignatureToClipboard from utils/clipboard instead
+ * This is maintained for backwards compatibility but will be removed in a future version
+ */
+declare function copySignature(signature: string): Promise<boolean>;
+
+export { EnhancedStorage, EnhancedStorageAccountOptions, EnhancedStorageAdapter, EnhancedStorageClusterOptions, EnhancedStorageWalletOptions, type ExplorerOptions, type ExplorerType, StorageAdapter, StorageOptions, TransactionSigner, copySignature, createEnhancedStorageAccount, createEnhancedStorageCluster, createEnhancedStorageWallet, createGillTransactionSigner, formatAddress, formatNumber, formatSOL, formatSignature, formatTokenAmount, getAllExplorerUrls, getPolyfillStatus, getSolanaExplorerUrl, getSolanaFmUrl, getSolscanUrl, getXrayUrl, installPolyfills, isCryptoAvailable, isPolyfillInstalled, truncate };