{"_id":"@apollosolution/vault-sdk","_rev":"2-3bf4fd1c64efefe8a535183e66d179b3","name":"@apollosolution/vault-sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@apollosolution/vault-sdk","version":"0.1.0","keywords":["solana","defi","vaults","sendit","myield","staking","liquidity"],"author":{"name":"sendit.fun"},"license":"MIT","_id":"@apollosolution/vault-sdk@0.1.0","maintainers":[{"name":"apollosolution","email":"mh@apso.tech"}],"dist":{"shasum":"6d5874982824f7260d22e2ead3d7e3eef1a3a050","tarball":"https://registry.npmjs.org/@apollosolution/vault-sdk/-/vault-sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-E7Itu0iZQZC0ksEDFbNxbLVARUl/kK2jNBNHgjotIdMYHXrwaWj6aTmf02QEN5IZO4haWfqpmqBp7rZaB+c+dA==","signatures":[{"sig":"MEUCIFD1GjC556wYt8+u8J30Xw+EqqZu7ArYCFOkdwmwmMNwAiEAihffjPoN8zHtaF7nnqGCMBC4Bf6jrNDnRdoC6/UZOH4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":58748},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"gitHead":"e97fac827f63fb5521ef24d6b04f9f92c5a429e9","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"jest","build":"tsup src/index.ts --format cjs,esm --dts --clean","publish:npm":"npm publish --access public","prepublishOnly":"npm run build"},"_npmUser":{"name":"apollosolution","email":"mh@apso.tech"},"_npmVersion":"11.4.2","description":"TypeScript SDK for integrating SendIt vaults into external applications","directories":{},"_nodeVersion":"24.3.0","dependencies":{"bs58":"^5.0.0","@solana/web3.js":"^1.87.6"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.0.1","ts-jest":"^29.1.1","typescript":"^5.3.2","@types/bs58":"^4.0.4","@types/jest":"^29.5.10","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/vault-sdk_0.1.0_1758728254058_0.6960534188237053","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@apollosolution/vault-sdk","version":"0.1.1","description":"TypeScript SDK for integrating SendIt vaults into external applications","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean","dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"jest","prepublishOnly":"npm run build","publish:npm":"npm publish --access public"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"keywords":["solana","defi","vaults","sendit","myield","staking","liquidity"],"author":{"name":"sendit.fun"},"license":"MIT","dependencies":{"@solana/web3.js":"^1.87.6","bs58":"^5.0.0"},"devDependencies":{"@types/bs58":"^4.0.4","@types/jest":"^29.5.10","@types/node":"^20.10.0","jest":"^29.7.0","ts-jest":"^29.1.1","tsup":"^8.0.1","typescript":"^5.3.2"},"engines":{"node":">=16.0.0"},"_id":"@apollosolution/vault-sdk@0.1.1","gitHead":"8d09e086b54348afd3f09881a661071e5047d22e","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-x7WYxq1wwVnJ54YCbtchXbW5sKTU2krb4T83h8qgTWCg1mzTE/BDQwJKP2Awz09d/GfZVlMMH44wf/j5ZyPjxg==","shasum":"e619c328c29b6c1d338d3bc2a6edfa620ca43de6","tarball":"https://registry.npmjs.org/@apollosolution/vault-sdk/-/vault-sdk-0.1.1.tgz","fileCount":6,"unpackedSize":58421,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBB7ojrs9eb2A0oCukLeLRO4Z6BBBxPVJMl31l2t+bWzAiEAjr6TI4W1hIZZOjzcz5/FMYptRQ+k+LTI6fTe6gQTT7I="}]},"_npmUser":{"name":"apollosolution","email":"mh@apso.tech"},"directories":{},"maintainers":[{"name":"apollosolution","email":"mh@apso.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vault-sdk_0.1.1_1758739589800_0.07325167562023305"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-24T15:37:33.987Z","modified":"2025-09-24T18:46:30.225Z","0.1.0":"2025-09-24T15:37:34.284Z","0.1.1":"2025-09-24T18:46:30.031Z"},"author":{"name":"sendit.fun"},"license":"MIT","keywords":["solana","defi","vaults","sendit","myield","staking","liquidity"],"description":"TypeScript SDK for integrating SendIt vaults into external applications","maintainers":[{"name":"apollosolution","email":"mh@apso.tech"}],"readme":"# @apollosolution/vault-sdk\n\nTypeScript SDK for integrating SendIt vaults into external applications.\n\n> **Note**: This SDK focuses on vault operations and transaction construction. For wallet management, we recommend using [@solana/wallet-adapter-react](https://github.com/solana-labs/wallet-adapter) or similar wallet integration libraries.\n\n## What This SDK Does\n\n✅ **Vault Discovery**: Find vaults by type or deposit token  \n✅ **Vault Information**: Get detailed vault metrics, APY, TVL, and configuration  \n✅ **User Positions**: Track user deposits and earnings across vaults  \n✅ **Transaction Construction**: Create unsigned transactions for deposits/withdrawals  \n✅ **Fee Calculations**: Calculate deposit fees and estimate future earnings  \n✅ **Analytics**: Get comprehensive vault statistics and performance metrics\n\n## What This SDK Doesn't Do\n\n❌ **Wallet Management**: Connect, disconnect, or manage wallet state  \n❌ **Transaction Signing**: Sign transactions with user's private keys  \n❌ **Transaction Submission**: Send transactions to the Solana network  \n\n> **Why this separation?** Wallet management is a security-sensitive area best handled by dedicated, audited libraries like `@solana/wallet-adapter-react`. This keeps our SDK focused, lightweight, and secure.\n\n## Installation\n\n```bash\nnpm install @apollosolution/vault-sdk\n# or\nyarn add @apollosolution/vault-sdk\n# or\npnpm add @apollosolution/vault-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { VaultClient } from '@apollosolution/vault-sdk';\n\n// Initialize the client\nconst client = new VaultClient({\n  apiUrl: 'https://backend.sendit.fun' // Optional, this is the default\n});\n\n// Get vault information\nconst vault = await client.singleSided.getVault('VAULT_ADDRESS');\nconsole.log(`Vault APY: ${vault.vault.metrics.grossAPY}%`);\n\n// Get user position\nconst position = await client.singleSided.getUserPosition(\n  'VAULT_ADDRESS',\n  'USER_WALLET_ADDRESS'\n);\nconsole.log(`User position: ${position.position.underlyingAmount} tokens`);\n```\n\n## Features\n\n- 🚀 Simple, intuitive API\n- 💼 Full TypeScript support\n- ⚡ Transaction construction\n- 📊 Position tracking and analytics\n- 💰 Fee calculation utilities\n\n## Documentation\n\nFor complete documentation and examples, see the [integration guide](../../staking-integration.md).\n\n## API Reference\n\n### VaultClient\n\nThe main client for interacting with SendIt vaults.\n\n```typescript\nconst client = new VaultClient({\n  apiUrl?: string;    // API endpoint (default: https://backend.sendit.fun)\n  apiKey?: string;    // Optional API key for authentication\n  timeout?: number;   // Request timeout in ms (default: 30000)\n});\n```\n\n### Single-Sided Vaults\n\nAccess single-sided vault functionality through `client.singleSided`:\n\n#### Vault Discovery\n```typescript\n// List all single-sided vaults\nconst vaults = await client.singleSided.listVaults();\n\n// Get vault by deposit token (e.g., NOBODY vault)\nconst nobodyVault = await client.singleSided.getVaultByToken('C29ebrgYjYoJPMGPnPSGY1q3mMGk4iDSqnQeQQA7moon');\n// Also accepts PublicKey objects\nconst vault = await client.singleSided.getVaultByToken(new PublicKey('C29ebrgYjYoJPMGPnPSGY1q3mMGk4iDSqnQeQQA7moon'));\n```\n\n#### Vault Information\n```typescript\n// Get detailed vault information\nconst vault = await client.singleSided.getVault(vaultId);\nconsole.log(vault.vault.metrics.grossAPY);  // Annual Percentage Yield\nconsole.log(vault.vault.tvl.totalValueUsd); // Total Value Locked in USD\n\n// Get vault statistics summary\nconst stats = await client.singleSided.getVaultStats(vaultId);\nconsole.log(stats); // { tvl, tvlUsd, grossAPR, grossAPY, depositFeePercent, etc. }\n```\n\n#### User Positions\n```typescript\n// Get user position in a vault\nconst position = await client.singleSided.getUserPosition(vaultId, walletAddress);\n// Also accepts PublicKey objects\nconst position = await client.singleSided.getUserPosition(vaultId, new PublicKey('WALLET_ADDRESS'));\n\nconsole.log(position.position.underlyingAmount);    // User's deposited amount\nconsole.log(position.position.underlyingAmountUsd); // USD value\nconsole.log(position.position.vaultTokens);         // Vault tokens owned\nconsole.log(position.position.share);               // % of vault owned\nconsole.log(position.wallet.depositToken.balance);  // Available wallet balance\n```\n\n#### Transactions\n```typescript\n// Create deposit transaction (returns unsigned transactions)\nconst depositTxs = await client.singleSided.deposit(vaultId, amount, walletAddress);\n\n// Create withdrawal transaction (returns unsigned transactions)\nconst withdrawTxs = await client.singleSided.withdraw(vaultId, amount, walletAddress);\n\n// Withdraw entire position (returns unsigned transactions)\nconst withdrawMaxTxs = await client.singleSided.withdrawMax(vaultId, walletAddress);\n\n// All transaction methods accept string or PublicKey for wallet address\nconst depositTxs = await client.singleSided.deposit(vaultId, amount, new PublicKey('WALLET_ADDRESS'));\n```\n\n#### Financial Calculations\n```typescript\n// Calculate deposit fees\nconst fees = await client.singleSided.calculateDepositFee(vaultId, amount);\nconsole.log(fees); // { fee, feePercentage, netDeposit }\n\n// Estimate earnings over time\nconst earnings = await client.singleSided.estimateEarnings(vaultId, amount);\nconsole.log(earnings); // { dailyEarnings, monthlyEarnings, yearlyEarnings, grossAPR, grossAPY }\n```\n\n## Examples\n\n### Wallet Integration with @solana/wallet-adapter-react\n\n```typescript\nimport { VaultClient } from '@apollosolution/vault-sdk';\nimport { useWallet, useConnection } from '@solana/wallet-adapter-react';\nimport { useState } from 'react';\n\nexport function DepositComponent() {\n  const { publicKey, signAllTransactions } = useWallet();\n  const { connection } = useConnection();\n  const [amount, setAmount] = useState('');\n  \n  const client = new VaultClient();\n\n  const handleDeposit = async () => {\n    if (!publicKey || !signAllTransactions) return;\n\n    try {\n      // Calculate fees before deposit\n      const fees = await client.singleSided.calculateDepositFee('VAULT_ADDRESS', amount);\n      console.log(`Deposit fee: ${fees.fee} (${fees.feePercentage}%)`);\n      console.log(`Net deposit: ${fees.netDeposit}`);\n\n      // Create deposit transactions (returns UNSIGNED transactions)\n      const transactions = await client.singleSided.deposit(\n        'VAULT_ADDRESS',\n        amount,\n        publicKey\n      );\n\n      // ⚠️ SDK returns unsigned transactions - you must sign them with your wallet\n      const signedTxs = await signAllTransactions(transactions);\n\n      // Send transactions using your preferred method\n      for (const tx of signedTxs) {\n        const signature = await connection.sendTransaction(tx, {\n          skipPreflight: false,\n          maxRetries: 3\n        });\n        await connection.confirmTransaction(signature, 'confirmed');\n        console.log(`Transaction confirmed: ${signature}`);\n      }\n    } catch (error) {\n      console.error('Deposit failed:', error);\n    }\n  };\n\n  return (\n    <div>\n      <input \n        value={amount} \n        onChange={(e) => setAmount(e.target.value)}\n        placeholder=\"Amount to deposit\" \n      />\n      <button onClick={handleDeposit}>Deposit</button>\n    </div>\n  );\n}\n```\n\n### Complete Vault Discovery Example\n\n```typescript\nimport { VaultClient, PublicKey } from '@apollosolution/vault-sdk';\n\nconst client = new VaultClient();\n\nasync function findAndAnalyzeVault() {\n  // Find NOBODY vault\n  const nobodyMint = 'C29ebrgYjYoJPMGPnPSGY1q3mMGk4iDSqnQeQQA7moon';\n  \n  try {\n    // Get the NOBODY vault directly by token\n    const vault = await client.singleSided.getVaultByToken(nobodyMint);\n    const stats = await client.singleSided.getVaultStats(vault.vault.address);\n    \n    console.log(`NOBODY Vault ${vault.vault.address}:`);\n    console.log(`  APY: ${vault.vault.metrics.grossAPY}%`);\n    console.log(`  TVL: $${stats.tvlUsd.toLocaleString()}`);\n    console.log(`  Deposit Fee: ${stats.depositFeePercent}%`);\n    console.log(`  Deposit Token: ${vault.vault.depositToken.symbol}`);\n    console.log(`  Vault Token: ${vault.vault.vaultToken.symbol}`);\n    \n    return vault;\n  } catch (error) {\n    console.log('NOBODY vault not found');\n    return null;\n  }\n}\n```\n\n### Monitor User Position\n\n```typescript\nimport { VaultClient } from '@apollosolution/vault-sdk';\n\nconst client = new VaultClient();\n\nasync function monitorPosition(vaultId: string, wallet: string) {\n  try {\n    const position = await client.singleSided.getUserPosition(vaultId, wallet);\n    \n    console.log('Current Position:', {\n      vaultTokens: position.position.vaultTokens,\n      underlyingValue: position.position.underlyingAmount,\n      valueUsd: position.position.underlyingAmountUsd,\n      shareOfVault: `${position.position.share}%`\n    });\n    \n    console.log('Wallet Balance:', {\n      depositToken: position.wallet.depositToken.balance,\n      valueUsd: position.wallet.depositToken.balanceUsd\n    });\n    \n    // Calculate potential earnings\n    const earnings = await client.singleSided.estimateEarnings(\n      vaultId, \n      position.position.underlyingAmount\n    );\n    \n    console.log('Estimated Earnings:', {\n      daily: `$${Number(earnings.dailyEarnings).toFixed(2)}`,\n      monthly: `$${Number(earnings.monthlyEarnings).toFixed(2)}`,\n      yearly: `$${Number(earnings.yearlyEarnings).toFixed(2)}`\n    });\n    \n  } catch (error) {\n    console.error('Failed to fetch position:', error);\n  }\n}\n\n// Monitor every 30 seconds\nsetInterval(() => {\n  monitorPosition('VAULT_ADDRESS', 'WALLET_ADDRESS');\n}, 30000);\n```\n\n### Error Handling Best Practices\n\n```typescript\nimport { VaultClient, ApiError } from '@apollosolution/vault-sdk';\n\nconst client = new VaultClient();\n\nasync function safeVaultOperation() {\n  try {\n    const vault = await client.singleSided.getVault('VAULT_ADDRESS');\n    return vault;\n  } catch (error) {\n    if (error instanceof ApiError) {\n      // Handle SDK-specific errors\n      console.error(`API Error (${error.code}):`, error.message);\n      \n      switch (error.code) {\n        case 'VAULT_NOT_FOUND':\n          console.log('This vault does not exist');\n          break;\n        case 'NETWORK_ERROR':\n          console.log('Please check your internet connection');\n          break;\n        default:\n          console.log('An unexpected error occurred');\n      }\n    } else {\n      // Handle other errors\n      console.error('Unexpected error:', error);\n    }\n    throw error;\n  }\n}\n```\n\n### TypeScript Types\n\nThe SDK provides comprehensive TypeScript types for all responses:\n\n```typescript\nimport { \n  VaultClient,\n  VaultResponse,\n  UserPositionResponse,\n  VaultListResponse,\n  VaultType,\n  TokenInfo,\n  VaultMetrics,\n  PublicKey\n} from '@apollosolution/vault-sdk';\n\n// All API responses are fully typed\nconst client = new VaultClient();\n\n// VaultResponse type includes all vault information\nconst vault: VaultResponse = await client.singleSided.getVault('VAULT_ID');\n\n// Access nested properties with full IntelliSense support\nconst apy: number = vault.vault.metrics.grossAPY;\nconst tvl: number = vault.vault.tvl.totalValueUsd;\nconst depositToken: TokenInfo = vault.vault.depositToken;\n\n// UserPositionResponse includes both position and wallet data\nconst position: UserPositionResponse = await client.singleSided.getUserPosition('VAULT_ID', 'WALLET');\nconst userBalance: string = position.wallet.depositToken.balance;\nconst vaultShare: number = position.position.share;\n```\n\n## Configuration\n\n### Client Configuration\n\n```typescript\nconst client = new VaultClient({\n  apiUrl: 'https://backend.sendit.fun',  // Default: https://backend.sendit.fun\n  apiKey: 'your-api-key',                // Optional: for authenticated endpoints\n  timeout: 30000                         // Default: 30000ms (30 seconds)\n});\n```\n\n### Environment Variables\n\nYou can also configure the SDK using environment variables:\n\n```bash\n# Optional: Override default API URL\nVAULT_SDK_API_URL=https://backend.sendit.fun\n\n# Optional: Set default API key\nVAULT_SDK_API_KEY=your-api-key\n\n# Optional: Set default timeout\nVAULT_SDK_TIMEOUT=30000\n```\n\n## Supported Vault Types\n\nCurrently supported vault types:\n- ✅ **single-sided**: Single-token vaults (accessible via `client.singleSided`)\n- 🔜 **sol**: SOL-specific vaults (coming soon)\n\n## Rate Limits\n\nThe SDK respects the backend API rate limits. If you encounter rate limiting:\n- Implement exponential backoff for retries\n- Cache vault information when possible\n- Use batch operations where available\n\n## Security\n\n- ✅ **No Private Keys**: SDK never handles private keys or seeds\n- ✅ **HTTPS Only**: All API calls use HTTPS\n- ✅ **Input Validation**: All inputs are validated before API calls\n- ✅ **Error Handling**: Comprehensive error handling with specific error codes\n\n## License\n\nMIT","readmeFilename":"README.md"}