@solana/connector 0.1.5 → 0.1.7

package/README.md

@@ -1,5 +1,5 @@
 ---
-title: @solana/connector
+title: '@solana/connector'
 description: Production-ready wallet connector for Solana applications
 ---
 
@@ -30,7 +30,7 @@ npm install @solana/connector
 pnpm add @solana/connector
 # or
 yarn add @solana/connector
-# or 
+# or
 bun add @solana/connector
 ```
 
@@ -610,6 +610,72 @@ const mobile = getDefaultMobileConfig({
 
 ## Security Considerations
 
+### RPC API Key Protection
+
+If you're using a paid RPC provider (Helius, QuickNode, etc.), avoid exposing your API key client-side. Anyone can grab it from the browser's network tab.
+
+**Solution: RPC Proxy Route**
+
+Create an API route that proxies RPC requests, keeping the API key server-side:
+
+```typescript
+// app/api/rpc/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+// Server-side only - not exposed to client
+const RPC_URL = process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
+
+export async function POST(request: NextRequest) {
+    try {
+        const body = await request.json();
+
+        const response = await fetch(RPC_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+
+        const data = await response.json();
+        return NextResponse.json(data);
+    } catch (error) {
+        return NextResponse.json({ error: 'RPC request failed' }, { status: 500 });
+    }
+}
+```
+
+Then configure the connector to use the proxy:
+
+```typescript
+'use client';
+
+import { getDefaultConfig } from '@solana/connector/headless';
+
+// Get origin for absolute URL (Kit requires full URLs)
+const getOrigin = () => {
+    if (typeof window !== 'undefined') return window.location.origin;
+    return 'http://localhost:3000';
+};
+
+const config = getDefaultConfig({
+    appName: 'My App',
+    clusters: [
+        {
+            id: 'solana:mainnet' as const,
+            label: 'Mainnet',
+            name: 'mainnet-beta' as const,
+            url: `${getOrigin()}/api/rpc`, // Proxy URL
+        },
+        // ... other clusters
+    ],
+});
+```
+
+Your `.env` file (no `NEXT_PUBLIC_` prefix):
+
+```
+SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your-key
+```
+
 ### Token Image Privacy
 
 When using `useTokens()` or `useTransactions()`, token metadata (including logo URLs) is fetched from external APIs. By default, these image URLs are returned directly, which means when your users' browsers fetch these images, the image host can see:
@@ -643,12 +709,12 @@ https://raw.githubusercontent.com/.../token-logo.png
 
 ### Common Proxy Options
 
-| Service | Configuration |
-|---------|---------------|
-| **Next.js Image** | `imageProxy: '/_next/image?w=64&q=75&url='` |
-| **Cloudflare** | `imageProxy: '/cdn-cgi/image/width=64,quality=75/'` |
-| **imgproxy** | `imageProxy: 'https://imgproxy.example.com/insecure/fill/64/64/'` |
-| **Custom API** | `imageProxy: '/api/image-proxy?url='` |
+| Service           | Configuration                                                     |
+| ----------------- | ----------------------------------------------------------------- |
+| **Next.js Image** | `imageProxy: '/_next/image?w=64&q=75&url='`                       |
+| **Cloudflare**    | `imageProxy: '/cdn-cgi/image/width=64,quality=75/'`               |
+| **imgproxy**      | `imageProxy: 'https://imgproxy.example.com/insecure/fill/64/64/'` |
+| **Custom API**    | `imageProxy: '/api/image-proxy?url='`                             |
 
 ### Custom Proxy API Route (Next.js Example)
 
@@ -725,14 +791,12 @@ function validateUrl(urlString: string): URL | null {
 
 // Check if hostname is in the allowlist
 function isAllowedDomain(hostname: string): boolean {
-    return ALLOWED_DOMAINS.some(
-        (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
-    );
+    return ALLOWED_DOMAINS.some(domain => hostname === domain || hostname.endsWith(`.${domain}`));
 }
 
 export async function GET(request: NextRequest) {
     const urlParam = request.nextUrl.searchParams.get('url');
-    
+
     // (1) Ensure URL exists and parses correctly with http/https
     if (!urlParam) {
         return new NextResponse('Missing URL parameter', { status: 400 });
@@ -764,7 +828,7 @@ export async function GET(request: NextRequest) {
     try {
         const response = await fetch(parsedUrl.toString());
         const buffer = await response.arrayBuffer();
-        
+
         return new NextResponse(buffer, {
             headers: {
                 'Content-Type': response.headers.get('Content-Type') || 'image/png',
@@ -785,16 +849,17 @@ The `useTokens()` hook fetches token prices from CoinGecko. CoinGecko has rate l
 
 ### Rate Limits (as of 2024)
 
-| Tier | Rate Limit | API Key Required |
-|------|------------|------------------|
-| **Free (Public)** | 10-30 requests/minute | No |
-| **Demo** | 30 requests/minute | Yes (free) |
-| **Analyst** | 500 requests/minute | Yes (paid) |
-| **Pro** | 1000+ requests/minute | Yes (paid) |
+| Tier              | Rate Limit            | API Key Required |
+| ----------------- | --------------------- | ---------------- |
+| **Free (Public)** | 10-30 requests/minute | No               |
+| **Demo**          | 30 requests/minute    | Yes (free)       |
+| **Analyst**       | 500 requests/minute   | Yes (paid)       |
+| **Pro**           | 1000+ requests/minute | Yes (paid)       |
 
 ### Handling Rate Limits
 
 ConnectorKit automatically handles rate limits with:
+
 - **Exponential backoff**: Retries with increasing delays
 - **Jitter**: Random delay added to prevent thundering herd
 - **Retry-After header**: Honors server-specified wait times
@@ -822,16 +887,16 @@ const config = getDefaultConfig({
     coingecko: {
         // API key for higher rate limits (optional)
         apiKey: process.env.COINGECKO_API_KEY,
-        
+
         // Set to true if using a Pro API key (default: false for Demo keys)
         isPro: false,
-        
+
         // Maximum retry attempts on 429 (default: 3)
         maxRetries: 3,
-        
+
         // Base delay for exponential backoff in ms (default: 1000)
         baseDelay: 1000,
-        
+
         // Maximum total timeout in ms (default: 30000)
         maxTimeout: 30000,
     },
@@ -942,35 +1007,35 @@ import { useConnector, useAccount } from '@solana/connector/react';
 
 ### Hooks
 
-| Hook | Description | Returns |
-|------|-------------|---------|
-| `useConnector()` | Main wallet connection hook | `{ wallets, selectedWallet, accounts, connected, connecting, select, disconnect }` |
-| `useAccount()` | Account management hook | `{ address, formatted, copy, copied, accounts, selectAccount }` |
-| `useCluster()` | Network/cluster management hook | `{ cluster, clusters, setCluster, isMainnet, isDevnet, rpcUrl }` |
-| `useWalletInfo()` | Wallet metadata hook | `{ name, icon, wallet, connecting }` |
-| `useTransactionSigner()` | Legacy transaction signer (web3.js) | `{ signer, ready, address, capabilities }` |
-| `useKitTransactionSigner()` | Modern transaction signer (@solana/kit) | `{ signer, ready, address }` |
-| `useBalance()` | SOL balance hook | `{ solBalance, isLoading, refetch }` |
-| `useTokens()` | SPL tokens hook | `{ tokens, isLoading, refetch }` |
-| `useTransactions()` | Transaction history hook | `{ transactions, isLoading, refetch }` |
+| Hook                        | Description                             | Returns                                                                            |
+| --------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
+| `useConnector()`            | Main wallet connection hook             | `{ wallets, selectedWallet, accounts, connected, connecting, select, disconnect }` |
+| `useAccount()`              | Account management hook                 | `{ address, formatted, copy, copied, accounts, selectAccount }`                    |
+| `useCluster()`              | Network/cluster management hook         | `{ cluster, clusters, setCluster, isMainnet, isDevnet, rpcUrl }`                   |
+| `useWalletInfo()`           | Wallet metadata hook                    | `{ name, icon, wallet, connecting }`                                               |
+| `useTransactionSigner()`    | Legacy transaction signer (web3.js)     | `{ signer, ready, address, capabilities }`                                         |
+| `useKitTransactionSigner()` | Modern transaction signer (@solana/kit) | `{ signer, ready, address }`                                                       |
+| `useBalance()`              | SOL balance hook                        | `{ solBalance, isLoading, refetch }`                                               |
+| `useTokens()`               | SPL tokens hook                         | `{ tokens, isLoading, refetch }`                                                   |
+| `useTransactions()`         | Transaction history hook                | `{ transactions, isLoading, refetch }`                                             |
 
 ### 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        |
+| `createConfig(options)`           | Create unified config for ConnectorKit + Armadura |
 
 ### Utility Functions
 
-| Function | Description |
-|----------|-------------|
-| `formatAddress(address, options?)` | Format Solana address |
-| `formatSOL(lamports, options?)` | Format SOL amount |
-| `copyAddressToClipboard(address)` | Copy address to clipboard |
+| Function                                | Description                         |
+| --------------------------------------- | ----------------------------------- |
+| `formatAddress(address, options?)`      | Format Solana address               |
+| `formatSOL(lamports, options?)`         | Format SOL amount                   |
+| `copyAddressToClipboard(address)`       | Copy address to clipboard           |
 | `getTransactionUrl(cluster, signature)` | Get Solana Explorer transaction URL |
-| `getAddressUrl(cluster, address)` | Get Solana Explorer address URL |
+| `getAddressUrl(cluster, address)`       | Get Solana Explorer address URL     |
 
 ---
 

package/dist/{chunk-VMSZJPR5.mjs → chunk-APQGEW7S.mjs}

@@ -228,6 +228,11 @@ function getNetworkDisplayName(network) {
 }
 
 // src/utils/cluster.ts
+function getMaybeStringProp(value, prop) {
+  if (typeof value != "object" || value === null) return;
+  let v = value[prop];
+  return typeof v == "string" ? v : void 0;
+}
 function getClusterRpcUrl(cluster) {
   if (typeof cluster == "string") {
     let presets2 = {
@@ -238,7 +243,7 @@ function getClusterRpcUrl(cluster) {
       return presets2[cluster];
     throw new Error(`Unknown cluster: ${cluster}`);
   }
-  let url = cluster.url || cluster.rpcUrl;
+  let url = cluster.url ?? getMaybeStringProp(cluster, "rpcUrl");
   if (!url)
     throw new Error("Cluster URL is required");
   if (url.startsWith("http://") || url.startsWith("https://"))
@@ -283,16 +288,17 @@ function isTestnetCluster(cluster) {
   return cluster.id === "solana:testnet";
 }
 function isLocalCluster(cluster) {
-  let url = cluster.url || cluster.rpcUrl;
+  let url = cluster.url ?? getMaybeStringProp(cluster, "rpcUrl");
   return url ? cluster.id === "solana:localnet" || url.includes("localhost") || url.includes("127.0.0.1") : cluster.id === "solana:localnet";
 }
 function getClusterName(cluster) {
   if (cluster.label) return cluster.label;
-  if (cluster.name) return cluster.name;
+  let name = getMaybeStringProp(cluster, "name");
+  if (name) return name;
   let parts = cluster.id.split(":");
   if (parts.length >= 2 && parts[1]) {
-    let name = parts.slice(1).join(":");
-    return name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, " ");
+    let name2 = parts.slice(1).join(":");
+    return name2.charAt(0).toUpperCase() + name2.slice(1).replace(/-/g, " ");
   }
   return "Unknown";
 }
@@ -1284,7 +1290,7 @@ var TransactionTracker = class extends BaseCollaborator {
    * Track a transaction for debugging and monitoring
    */
   trackTransaction(activity) {
-    let clusterId = this.getState().cluster?.id || "solana:devnet", fullActivity = {
+    let clusterId = this.getState().cluster?.id ?? "solana:devnet", fullActivity = {
       ...activity,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       cluster: clusterId
@@ -1300,10 +1306,10 @@ var TransactionTracker = class extends BaseCollaborator {
    * Update transaction status (e.g., from pending to confirmed/failed)
    */
   updateStatus(signature, status, error) {
-    let tx = this.transactions.find((t) => t.signature === signature);
+    let tx = this.transactions.find((t) => String(t.signature) === signature);
     tx && (tx.status = status, error && (tx.error = error), this.eventEmitter.emit({
       type: "transaction:updated",
-      signature,
+      signature: tx.signature,
       status,
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     }), this.log("[Connector] Transaction updated:", { signature, status, error }));
@@ -1886,6 +1892,71 @@ function formatTokenAmount(amount, decimals, options = {}) {
     maximumFractionDigits: maxDecimals
   });
 }
+var MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
+function isSafeInteger(value) {
+  return value >= -MAX_SAFE_INTEGER && value <= MAX_SAFE_INTEGER;
+}
+function splitBigIntDecimals(amount, decimals) {
+  if (decimals <= 0)
+    return { whole: amount.toString(), fraction: "" };
+  let str = amount.toString(), isNegative = str.startsWith("-"), absStr = isNegative ? str.slice(1) : str;
+  if (absStr.length <= decimals) {
+    let padded = absStr.padStart(decimals, "0");
+    return {
+      whole: isNegative ? "-0" : "0",
+      fraction: padded
+    };
+  }
+  let splitPoint = absStr.length - decimals;
+  return {
+    whole: (isNegative ? "-" : "") + absStr.slice(0, splitPoint),
+    fraction: absStr.slice(splitPoint)
+  };
+}
+function formatBigIntBalance(amount, decimals, options = {}) {
+  let { maxDecimals = Math.min(decimals, 6), minDecimals = 0, locale, useGrouping = true } = options;
+  if (isSafeInteger(amount))
+    return (Number(amount) / Math.pow(10, decimals)).toLocaleString(locale, {
+      minimumFractionDigits: minDecimals,
+      maximumFractionDigits: maxDecimals,
+      useGrouping
+    });
+  let { whole, fraction } = splitBigIntDecimals(amount, decimals), truncatedFraction = fraction.slice(0, maxDecimals);
+  for (; truncatedFraction.length > minDecimals && truncatedFraction.endsWith("0"); )
+    truncatedFraction = truncatedFraction.slice(0, -1);
+  truncatedFraction = truncatedFraction.padEnd(minDecimals, "0");
+  let formattedWhole = whole;
+  if (useGrouping) {
+    let isNegative = whole.startsWith("-"), absWhole = isNegative ? whole.slice(1) : whole, parts = [];
+    for (let i = absWhole.length; i > 0; i -= 3)
+      parts.unshift(absWhole.slice(Math.max(0, i - 3), i));
+    formattedWhole = (isNegative ? "-" : "") + parts.join(",");
+  }
+  return truncatedFraction.length === 0 ? formattedWhole : `${formattedWhole}.${truncatedFraction}`;
+}
+function formatLamportsToSolSafe(lamports, options = {}) {
+  let { maxDecimals = 4, minDecimals = 0, suffix = false, locale } = options, formatted = formatBigIntBalance(lamports, 9, {
+    maxDecimals,
+    minDecimals,
+    locale
+  });
+  return suffix ? `${formatted} SOL` : formatted;
+}
+function formatBigIntUsd(amount, decimals, usdPrice, options = {}) {
+  let { locale, currency = "USD" } = options, { whole, fraction } = splitBigIntDecimals(amount, decimals), wholeNum = parseFloat(whole), fractionNum = fraction ? parseFloat("0." + fraction) : 0;
+  return ((wholeNum + fractionNum) * usdPrice).toLocaleString(locale, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2
+  });
+}
+function formatTokenBalanceSafe(amount, decimals, options = {}) {
+  return formatBigIntBalance(amount, decimals, {
+    maxDecimals: options.maxDecimals ?? Math.min(decimals, 6),
+    locale: options.locale
+  });
+}
 var ClipboardErrorType = /* @__PURE__ */ ((ClipboardErrorType2) => (ClipboardErrorType2.NOT_SUPPORTED = "not_supported", ClipboardErrorType2.PERMISSION_DENIED = "permission_denied", ClipboardErrorType2.SSR = "ssr", ClipboardErrorType2.EMPTY_VALUE = "empty_value", ClipboardErrorType2.INVALID_VALUE = "invalid_value", ClipboardErrorType2.UNKNOWN = "unknown", ClipboardErrorType2))(ClipboardErrorType || {});
 function isClipboardAvailable() {
   if (typeof window > "u" || typeof document > "u")
@@ -2447,6 +2518,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, formatNumber, formatSOL, formatTokenAmount, 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-VMSZJPR5.mjs.map
-//# sourceMappingURL=chunk-VMSZJPR5.mjs.map
+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