@solana/connector 0.1.7 → 0.1.8

package/README.md

@@ -911,6 +911,85 @@ Token prices are cached for 60 seconds to minimize API calls. The retry logic on
 
 ## Advanced Usage
 
+### Error Handling with `tryCatch`
+
+ConnectorKit exports a `tryCatch` utility for consistent async error handling:
+
+```typescript
+import { tryCatch } from '@solana/connector/headless';
+
+// Instead of try/catch blocks
+async function sendTransaction() {
+    const { data: signature, error } = await tryCatch(signer.signAndSendTransaction(transaction));
+
+    if (error) {
+        console.error('Transaction failed:', error.message);
+        return;
+    }
+
+    console.log('Transaction sent:', signature);
+}
+```
+
+The `tryCatch` utility returns a `Result<T, E>` type that's either a success with `data` or a failure with `error`:
+
+```typescript
+interface Success<T> {
+    data: T;
+    error: null;
+}
+
+interface Failure<E> {
+    data: null;
+    error: E;
+}
+```
+
+Also available: `tryCatchSync` for synchronous operations, and `isSuccess`/`isFailure` type guards.
+
+### Cache Invalidation with Query Keys
+
+For advanced cache management, ConnectorKit exports query key generators:
+
+```typescript
+import {
+    getBalanceQueryKey,
+    getTokensQueryKey,
+    getTransactionsQueryKey,
+    invalidateSharedQuery,
+} from '@solana/connector/react';
+
+// After sending a transaction, invalidate relevant caches
+async function sendAndRefresh() {
+    await sendTransaction();
+
+    // Invalidate balance and tokens (they share the same cache)
+    const balanceKey = getBalanceQueryKey(rpcUrl, address);
+    if (balanceKey) invalidateSharedQuery(balanceKey);
+
+    // Invalidate transactions
+    const txKey = getTransactionsQueryKey({ rpcUrl, address, clusterId });
+    if (txKey) invalidateSharedQuery(txKey);
+}
+```
+
+### Configuration Validation
+
+Configuration is validated at runtime using Zod schemas. For manual validation:
+
+```typescript
+import { validateConfigOptions } from '@solana/connector/headless';
+
+const result = validateConfigOptions({
+    appName: 'My App',
+    network: 'mainnet',
+});
+
+if (!result.success) {
+    console.error('Validation errors:', result.error.issues);
+}
+```
+
 ### Headless Client (Vue, Svelte, Vanilla JS)
 
 Use `ConnectorClient` for non-React frameworks:
@@ -1021,11 +1100,10 @@ import { useConnector, useAccount } from '@solana/connector/react';
 
 ### Configuration Functions
 
-| Function                          | Description                                       |
-| --------------------------------- | ------------------------------------------------- |
-| `getDefaultConfig(options)`       | Create default connector configuration            |
-| `getDefaultMobileConfig(options)` | Create mobile wallet adapter configuration        |
-| `createConfig(options)`           | Create unified config for ConnectorKit + Armadura |
+| Function                          | Description                                |
+| --------------------------------- | ------------------------------------------ |
+| `getDefaultConfig(options)`       | Create default connector configuration     |
+| `getDefaultMobileConfig(options)` | Create mobile wallet adapter configuration |
 
 ### Utility Functions
 

package/dist/{chunk-APQGEW7S.mjs → chunk-6F6M6L7R.mjs}

@@ -1,4 +1,4 @@
-import { createLogger, __publicField, getPublicSolanaRpcUrl, getExplorerLink, isWeb3jsTransaction, prepareTransactionForWallet, convertSignedTransaction } from './chunk-QL3IT3TS.mjs';
+import { createLogger, getPublicSolanaRpcUrl, getExplorerLink, __publicField, tryCatchSync, TransactionError, isWeb3jsTransaction, Errors, prepareTransactionForWallet, convertSignedTransaction, ValidationError, isConnectorError } from './chunk-J7DHGLW6.mjs';
 import { Component, useTransition, useState, useCallback, useMemo } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { install } from '@solana/webcrypto-ed25519-polyfill';
@@ -6,8 +6,25 @@ import { address, isAddress } from '@solana/addresses';
 import { getTransactionDecoder, assertIsTransactionWithinSizeLimit } from '@solana/transactions';
 import { getBase58Decoder } from '@solana/codecs';
 
-// src/lib/adapters/wallet-standard-shim.ts
-var registry = null;
+// src/lib/wallet/standard-shim.ts
+var registry = null, registryInitPromise = null, registryInitResolve = null, ready = new Promise((resolve, reject) => {
+  if (typeof window > "u") {
+    resolve();
+    return;
+  }
+  registryInitResolve = resolve;
+  let nav = window.navigator;
+  if (nav.wallets && typeof nav.wallets.get == "function") {
+    registry = nav.wallets, resolve();
+    return;
+  }
+  registryInitPromise = import('@wallet-standard/app').then((mod) => {
+    let walletStandardRegistry = mod.getWallets?.();
+    walletStandardRegistry && (registry = walletStandardRegistry), resolve();
+  }).catch((err) => {
+    console.warn("[standard-shim] Failed to load @wallet-standard/app:", err), resolve();
+  });
+});
 function getWalletsRegistry() {
   if (typeof window > "u")
     return {
@@ -15,12 +32,13 @@ function getWalletsRegistry() {
       on: () => () => {
       }
     };
-  if (!registry) {
+  if (!registry && !registryInitPromise) {
     let nav = window.navigator;
-    nav.wallets && typeof nav.wallets.get == "function" ? registry = nav.wallets : import('@wallet-standard/app').then((mod) => {
+    nav.wallets && typeof nav.wallets.get == "function" ? (registry = nav.wallets, registryInitResolve?.()) : registryInitPromise = import('@wallet-standard/app').then((mod) => {
       let walletStandardRegistry = mod.getWallets?.();
-      walletStandardRegistry && (registry = walletStandardRegistry);
+      walletStandardRegistry && (registry = walletStandardRegistry), registryInitResolve?.();
     }).catch(() => {
+      registryInitResolve?.();
     });
   }
   return {
@@ -49,135 +67,6 @@ function getWalletsRegistry() {
   };
 }
 
-// src/lib/errors/index.ts
-var ConnectorError = class extends Error {
-  constructor(message, context, originalError) {
-    super(message);
-    __publicField(this, "context");
-    __publicField(this, "originalError");
-    __publicField(this, "timestamp");
-    this.name = this.constructor.name, this.context = context, this.originalError = originalError, this.timestamp = (/* @__PURE__ */ new Date()).toISOString(), Error.captureStackTrace && Error.captureStackTrace(this, this.constructor);
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      recoverable: this.recoverable,
-      context: this.context,
-      timestamp: this.timestamp,
-      originalError: this.originalError?.message
-    };
-  }
-}, ConnectionError = class extends ConnectorError {
-  constructor(code, message, context, originalError) {
-    super(message, context, originalError);
-    __publicField(this, "code");
-    __publicField(this, "recoverable", true);
-    this.code = code;
-  }
-}, ValidationError = class extends ConnectorError {
-  constructor(code, message, context, originalError) {
-    super(message, context, originalError);
-    __publicField(this, "code");
-    __publicField(this, "recoverable", false);
-    this.code = code;
-  }
-}, ConfigurationError = class extends ConnectorError {
-  constructor(code, message, context, originalError) {
-    super(message, context, originalError);
-    __publicField(this, "code");
-    __publicField(this, "recoverable", false);
-    this.code = code;
-  }
-}, NetworkError = class extends ConnectorError {
-  constructor(code, message, context, originalError) {
-    super(message, context, originalError);
-    __publicField(this, "code");
-    __publicField(this, "recoverable", true);
-    this.code = code;
-  }
-}, TransactionError = class extends ConnectorError {
-  constructor(code, message, context, originalError) {
-    super(message, context, originalError);
-    __publicField(this, "code");
-    __publicField(this, "recoverable");
-    this.code = code, this.recoverable = ["USER_REJECTED", "SEND_FAILED", "SIMULATION_FAILED"].includes(code);
-  }
-};
-function isConnectorError(error) {
-  return error instanceof ConnectorError;
-}
-function isConnectionError(error) {
-  return error instanceof ConnectionError;
-}
-function isValidationError(error) {
-  return error instanceof ValidationError;
-}
-function isConfigurationError(error) {
-  return error instanceof ConfigurationError;
-}
-function isNetworkError(error) {
-  return error instanceof NetworkError;
-}
-function isTransactionError(error) {
-  return error instanceof TransactionError;
-}
-var Errors = {
-  walletNotConnected: (context) => new ConnectionError("WALLET_NOT_CONNECTED", "No wallet connected", context),
-  walletNotFound: (walletName) => new ConnectionError("WALLET_NOT_FOUND", `Wallet not found${walletName ? `: ${walletName}` : ""}`, {
-    walletName
-  }),
-  connectionFailed: (originalError) => new ConnectionError("CONNECTION_FAILED", "Failed to connect to wallet", void 0, originalError),
-  accountNotAvailable: (address) => new ConnectionError("ACCOUNT_NOT_AVAILABLE", "Requested account not available", { address }),
-  invalidTransaction: (reason, context) => new ValidationError("INVALID_TRANSACTION", `Invalid transaction: ${reason}`, context),
-  invalidFormat: (expectedFormat, actualFormat) => new ValidationError("INVALID_FORMAT", `Invalid format: expected ${expectedFormat}`, {
-    expectedFormat,
-    actualFormat
-  }),
-  unsupportedFormat: (format) => new ValidationError("UNSUPPORTED_FORMAT", `Unsupported format: ${format}`, { format }),
-  missingProvider: (hookName) => new ConfigurationError(
-    "MISSING_PROVIDER",
-    `${hookName} must be used within ConnectorProvider. Wrap your app with <ConnectorProvider> or <UnifiedProvider>.`,
-    { hookName }
-  ),
-  clusterNotFound: (clusterId, availableClusters) => new ConfigurationError(
-    "CLUSTER_NOT_FOUND",
-    `Cluster ${clusterId} not found. Available clusters: ${availableClusters.join(", ")}`,
-    { clusterId, availableClusters }
-  ),
-  rpcError: (message, originalError) => new NetworkError("RPC_ERROR", message, void 0, originalError),
-  networkTimeout: () => new NetworkError("NETWORK_TIMEOUT", "Network request timed out"),
-  signingFailed: (originalError) => new TransactionError("SIGNING_FAILED", "Failed to sign transaction", void 0, originalError),
-  featureNotSupported: (feature) => new TransactionError("FEATURE_NOT_SUPPORTED", `Wallet does not support ${feature}`, { feature }),
-  userRejected: (operation) => new TransactionError("USER_REJECTED", `User rejected ${operation}`, { operation })
-};
-function toConnectorError(error, defaultMessage = "An unexpected error occurred") {
-  if (isConnectorError(error))
-    return error;
-  if (error instanceof Error) {
-    let message = error.message.toLowerCase();
-    return message.includes("user rejected") || message.includes("user denied") ? Errors.userRejected("transaction") : message.includes("wallet not found") || message.includes("not installed") ? Errors.walletNotFound() : message.includes("not connected") ? Errors.walletNotConnected() : message.includes("network") || message.includes("fetch") ? Errors.rpcError(error.message, error) : message.includes("invalid") ? new ValidationError("VALIDATION_FAILED", error.message, void 0, error) : new TransactionError("SIGNING_FAILED", error.message, void 0, error);
-  }
-  return new TransactionError("SIGNING_FAILED", defaultMessage, { originalError: String(error) });
-}
-function getUserFriendlyMessage(error) {
-  return isConnectorError(error) ? {
-    WALLET_NOT_CONNECTED: "Please connect your wallet to continue.",
-    WALLET_NOT_FOUND: "Wallet not found. Please install a supported wallet.",
-    CONNECTION_FAILED: "Failed to connect to wallet. Please try again.",
-    USER_REJECTED: "Transaction was cancelled.",
-    FEATURE_NOT_SUPPORTED: "This wallet does not support this feature.",
-    SIGNING_FAILED: "Failed to sign transaction. Please try again.",
-    SEND_FAILED: "Failed to send transaction. Please try again.",
-    INVALID_CLUSTER: "Invalid network configuration.",
-    CLUSTER_NOT_FOUND: "Network not found.",
-    MISSING_PROVIDER: "Application not properly configured.",
-    RPC_ERROR: "Network error. Please check your connection.",
-    NETWORK_TIMEOUT: "Request timed out. Please try again."
-  }[error.code] || error.message || "An error occurred." : "An unexpected error occurred. Please try again.";
-}
-
 // src/utils/network.ts
 var PUBLIC_RPC_ENDPOINTS = {
   mainnet: "https://api.mainnet-beta.solana.com",
@@ -521,7 +410,7 @@ var BaseCollaborator = class {
   }
 };
 
-// src/lib/connection/wallet-authenticity-verifier.ts
+// src/lib/wallet/authenticity-verifier.ts
 var logger2 = createLogger("WalletAuthenticity"), WalletAuthenticityVerifier = class {
   /**
    * Verify a wallet's authenticity using dynamic heuristics
@@ -731,7 +620,7 @@ var logger2 = createLogger("WalletAuthenticity"), WalletAuthenticityVerifier = c
   }
 };
 
-// src/lib/connection/wallet-detector.ts
+// src/lib/wallet/detector.ts
 var logger3 = createLogger("WalletDetector");
 function hasFeature(wallet, featureName) {
   return wallet.features != null && wallet.features[featureName] !== void 0;
@@ -757,7 +646,14 @@ var WalletDetector = class extends BaseCollaborator {
     __publicField(this, "unsubscribers", []);
   }
   /**
-   * Initialize wallet detection
+   * Initialize wallet detection (synchronous)
+   *
+   * Sets up registry listeners immediately. Due to the async nature of registry initialization,
+   * the initial call to `get()` may return an empty array if called before the registry is ready.
+   * Event listeners will fire as wallets register, providing eventual consistency.
+   *
+   * For deterministic detection where you need all wallets available immediately,
+   * use `initializeAsync()` instead.
    */
   initialize() {
     if (!(typeof window > "u"))
@@ -780,6 +676,24 @@ var WalletDetector = class extends BaseCollaborator {
       } catch {
       }
   }
+  /**
+   * Initialize wallet detection with deterministic registry availability (async)
+   *
+   * Awaits the registry `ready` Promise before performing initial detection,
+   * ensuring all registered wallets are available on the first `get()` call.
+   *
+   * Use this when you need guaranteed wallet availability before proceeding
+   * (e.g., auto-reconnect logic, checking if a specific wallet is installed).
+   *
+   * @example
+   * ```ts
+   * await walletDetector.initializeAsync();
+   * const wallets = walletDetector.getDetectedWallets(); // Guaranteed populated
+   * ```
+   */
+  async initializeAsync() {
+    typeof window > "u" || (await ready, this.initialize());
+  }
   /**
    * Check if a specific wallet is available immediately via direct window object detection
    */
@@ -866,7 +780,7 @@ var WalletDetector = class extends BaseCollaborator {
   }
 };
 
-// src/lib/connection/connection-manager.ts
+// src/lib/wallet/connection-manager.ts
 function getConnectFeature(wallet) {
   return wallet.features["standard:connect"]?.connect ?? null;
 }
@@ -1076,7 +990,7 @@ var ConnectionManager = class extends BaseCollaborator {
   }
 };
 
-// src/lib/connection/auto-connector.ts
+// src/lib/wallet/auto-connector.ts
 var logger4 = createLogger("AutoConnector"), MIN_ADDRESS_LENGTH = 30, AutoConnector = class {
   constructor(walletDetector, connectionManager, stateManager, walletStorage, debug = false) {
     __publicField(this, "walletDetector");
@@ -1190,7 +1104,7 @@ var logger4 = createLogger("AutoConnector"), MIN_ADDRESS_LENGTH = 30, AutoConnec
           ]
         },
         true
-      );
+      ), await ready;
       let walletsApi = getWalletsRegistry(), registryWallet = walletsApi.get().find((w) => w.name === storedWalletName), walletToUse = registryWallet || wallet;
       return this.debug && logger4.info("Attempting to connect via instant auto-connect", {
         walletName: storedWalletName,
@@ -1446,16 +1360,15 @@ var logger5 = createLogger("ConnectorClient"), ConnectorClient = class {
     ), this.initialize();
   }
   initialize() {
-    if (!(typeof window > "u") && !this.initialized)
-      try {
-        this.walletDetector.initialize(), this.config.autoConnect && setTimeout(() => {
-          this.autoConnector.attemptAutoConnect().catch((err) => {
-            this.config.debug && logger5.error("Auto-connect error", { error: err });
-          });
-        }, 100), this.initialized = true;
-      } catch (e) {
-        this.config.debug && logger5.error("Connector initialization failed", { error: e });
-      }
+    if (typeof window > "u" || this.initialized) return;
+    let { error } = tryCatchSync(() => {
+      this.walletDetector.initialize(), this.config.autoConnect && setTimeout(() => {
+        this.autoConnector.attemptAutoConnect().catch((err) => {
+          this.config.debug && logger5.error("Auto-connect error", { error: err });
+        });
+      }, 100), this.initialized = true;
+    });
+    error && this.config.debug && logger5.error("Connector initialization failed", { error });
   }
   async select(walletName) {
     let wallet = this.stateManager.getSnapshot().wallets.find((w) => w.wallet.name === walletName)?.wallet;
@@ -1480,11 +1393,8 @@ var logger5 = createLogger("ConnectorClient"), ConnectorClient = class {
   getRpcUrl() {
     let cluster = this.clusterManager.getCluster();
     if (!cluster) return null;
-    try {
-      return getClusterRpcUrl(cluster);
-    } catch (error) {
-      return this.config.debug && logger5.error("Failed to get RPC URL", { error }), null;
-    }
+    let { data, error } = tryCatchSync(() => getClusterRpcUrl(cluster));
+    return error ? (this.config.debug && logger5.error("Failed to get RPC URL", { error }), null) : data;
   }
   subscribe(listener) {
     return this.stateManager.subscribe(listener);
@@ -1497,12 +1407,10 @@ var logger5 = createLogger("ConnectorClient"), ConnectorClient = class {
     let storageKeys = ["account", "wallet", "cluster"];
     for (let key of storageKeys) {
       let storage = this.config.storage?.[key];
-      if (storage && "reset" in storage && typeof storage.reset == "function")
-        try {
-          storage.reset(), this.config.debug && logger5.debug("Reset storage", { key });
-        } catch (error) {
-          this.config.debug && logger5.error("Failed to reset storage", { key, error });
-        }
+      if (storage && "reset" in storage && typeof storage.reset == "function") {
+        let resetFn = storage.reset, { error } = tryCatchSync(() => resetFn());
+        error ? this.config.debug && logger5.error("Failed to reset storage", { key, error }) : this.config.debug && logger5.debug("Reset storage", { key });
+      }
     }
     this.eventEmitter.emit({
       type: "storage:reset",
@@ -2518,6 +2426,6 @@ function createKitTransactionSigner(connectorSigner) {
 }
 var createGillTransactionSigner = createKitTransactionSigner;
 
-export { ClipboardErrorType, ConfigurationError, ConnectionError, ConnectorClient, ConnectorError, ConnectorErrorBoundary, DEFAULT_MAX_RETRIES, Errors, NetworkError, PUBLIC_RPC_ENDPOINTS, TransactionError, TransactionSignerError, ValidationError, WalletErrorType, copyAddressToClipboard, copySignatureToClipboard, copyToClipboard, createGillTransactionSigner, createKitTransactionSigner, createTransactionSigner, formatAddress, formatBigIntBalance, formatBigIntUsd, formatLamportsToSolSafe, formatNumber, formatSOL, formatTokenAmount, formatTokenBalanceSafe, getAddressUrl, getBlockUrl, getChainIdForWalletStandard, getClusterChainId, getClusterExplorerUrl, getClusterName, getClusterRpcUrl, getClusterType, getDefaultRpcUrl, getNetworkDisplayName, getPolyfillStatus, getTokenUrl, getTransactionUrl, getUserFriendlyMessage, getWalletsRegistry, installPolyfills, isClipboardAvailable, isConfigurationError, isConnectionError, isConnectorError, isCryptoAvailable, isDevnet, isDevnetCluster, isLocalCluster, isLocalnet, isMainnet, isMainnetCluster, isNetworkError, isPolyfillInstalled, isTestnet, isTestnetCluster, isTransactionError, isTransactionSignerError, isValidationError, normalizeNetwork, toClusterId, toConnectorError, truncate, withErrorBoundary };
-//# sourceMappingURL=chunk-APQGEW7S.mjs.map
-//# sourceMappingURL=chunk-APQGEW7S.mjs.map
+export { ClipboardErrorType, ConnectorClient, ConnectorErrorBoundary, DEFAULT_MAX_RETRIES, PUBLIC_RPC_ENDPOINTS, TransactionSignerError, WalletErrorType, copyAddressToClipboard, copySignatureToClipboard, copyToClipboard, createGillTransactionSigner, createKitTransactionSigner, createTransactionSigner, formatAddress, formatBigIntBalance, formatBigIntUsd, formatLamportsToSolSafe, formatNumber, formatSOL, formatTokenAmount, formatTokenBalanceSafe, getAddressUrl, getBlockUrl, getChainIdForWalletStandard, getClusterChainId, getClusterExplorerUrl, getClusterName, getClusterRpcUrl, getClusterType, getDefaultRpcUrl, getNetworkDisplayName, getPolyfillStatus, getTokenUrl, getTransactionUrl, getWalletsRegistry, installPolyfills, isClipboardAvailable, isCryptoAvailable, isDevnet, isDevnetCluster, isLocalCluster, isLocalnet, isMainnet, isMainnetCluster, isPolyfillInstalled, isTestnet, isTestnetCluster, isTransactionSignerError, normalizeNetwork, ready, toClusterId, truncate, withErrorBoundary };
+//# sourceMappingURL=chunk-6F6M6L7R.mjs.map
+//# sourceMappingURL=chunk-6F6M6L7R.mjs.map