@defindex/sdk 0.1.0

package/README.md

@@ -0,0 +1,402 @@
+# DeFindex SDK
+
+Official TypeScript SDK for [DeFindex](https://defindex.io) - A decentralized vault management system built on Stellar using Soroban smart contracts.
+
+## 🌟 Features
+
+- **🔐 API Key Authentication**: Secure API key authentication with Bearer tokens (recommended)
+- **🏦 Vault Operations**: Create, deposit, withdraw, and manage decentralized vaults
+- **🏭 Factory Operations**: Deploy new vaults with custom configurations
+- **👑 Admin Operations**: Emergency rescue, strategy management for vault operators  
+- **📊 Real-time Data**: Vault balances, APY tracking, and comprehensive vault information
+- **🔒 Server-Side Focused**: Secure handling of credentials and sensitive operations
+- **📝 TypeScript Support**: Full type safety with comprehensive interfaces
+- **⚡ Lightweight**: Simple authentication and comprehensive error handling
+- **🧪 Well Tested**: Comprehensive unit and integration test coverage
+- **📚 Complete Examples**: Functional TypeScript examples and comprehensive documentation
+
+## 🚀 Installation
+
+```bash
+npm install @defindex/sdk
+```
+
+## 📖 Quick Start
+
+```typescript
+import { DefindexSDK, SupportedNetworks } from '@defindex/sdk';
+
+// Initialize with API key
+const sdk = new DefindexSDK({
+  apiKey: 'sk_your_api_key_here',
+  baseUrl: 'https://api.defindex.io'
+});
+
+// Check API health
+const health = await sdk.healthCheck();
+console.log('API Status:', health.status.reachable);
+
+// Get factory address
+const factory = await sdk.getFactoryAddress(SupportedNetworks.TESTNET);
+console.log('Factory Address:', factory.address);
+
+// Get vault information
+const vaultAddress = 'CVAULT_CONTRACT_ADDRESS...';
+const vaultInfo = await sdk.getVaultInfo(vaultAddress, SupportedNetworks.TESTNET);
+console.log(`Vault: ${vaultInfo.name} (${vaultInfo.symbol})`);
+
+// Deposit to vault
+const depositResponse = await sdk.depositToVault(vaultAddress, {
+  amounts: [1000000], // Amount for each asset (considering decimals)
+  caller: 'GUSER_ADDRESS...',
+  invest: true,
+  slippageBps: 100 // 1% slippage tolerance
+}, SupportedNetworks.TESTNET);
+
+// Sign the XDR with your wallet and submit
+const signedXdr = await yourWallet.sign(depositResponse.xdr);
+const result = await sdk.sendTransaction(signedXdr, SupportedNetworks.TESTNET, false);
+```
+
+## 🚀 Running the Example
+
+The SDK includes a comprehensive functional example:
+
+```bash
+# Install dependencies
+pnpm install
+
+# Copy environment configuration
+cp .env.example .env
+
+# Edit .env with your credentials
+# DEFINDEX_API_KEY=sk_your_api_key_here
+
+# Run the example
+pnpm run example
+```
+
+The example demonstrates:
+- SDK initialization and authentication
+- API health checking
+- Factory operations
+- Vault creation, deposits, and withdrawals
+- Administrative vault management
+- Error handling and best practices
+
+## 🔧 Configuration
+
+### SDK Configuration Options
+
+```typescript
+interface DefindexSDKConfig {
+  apiKey?: string;         // API key for authentication (recommended)
+  baseUrl?: string;        // Custom API base URL (defaults to 'https://api.defindex.io')
+  timeout?: number;        // Request timeout in ms (defaults to 30000)
+}
+```
+
+### Environment Variables
+
+For better security, use environment variables:
+
+```typescript
+// Using API key (recommended)
+const sdk = new DefindexSDK({
+  apiKey: process.env.DEFINDEX_API_KEY,
+  baseUrl: process.env.DEFINDEX_API_URL || 'https://api.defindex.io'
+});
+```
+
+## ✅ Current Status
+
+**Great News!** The DeFindex API is now fully operational on testnet:
+
+- ✅ **Health Check**: Working correctly
+- ✅ **SDK Authentication**: API key authentication implemented
+- ✅ **Factory Operations**: Factory deployed and working on testnet
+- ✅ **Vault Creation**: Create vaults with custom configurations
+- ✅ **Vault Operations**: Full deposit, withdrawal, and balance operations
+- ✅ **Vault Management**: Administrative operations (pause/unpause strategies, emergency rescue)
+- ✅ **Transaction Building**: All operations return signed XDR for wallet integration
+- ⚠️ **APY Calculation**: Working but some fields may be undefined for new vaults
+
+### Recent Updates
+
+1. ✅ **Factory Deployed**: Factory contract now available on testnet
+2. ✅ **Full Vault Operations**: Create, manage, and interact with vaults
+3. ✅ **Complete Example**: Run `pnpm run example` to see all functionality
+4. ✅ **Ready for Production**: All core functionality is operational
+
+## 📚 API Reference
+
+### System Operations
+
+#### Health Check
+```typescript
+const health = await sdk.healthCheck();
+if (health.status.reachable) {
+  console.log('API is healthy');
+}
+```
+
+### Factory Operations
+
+#### Get Factory Address
+```typescript
+const factory = await sdk.getFactoryAddress(SupportedNetworks.TESTNET);
+console.log('Factory address:', factory.address);
+```
+
+#### Create Vault
+```typescript
+const vaultConfig: CreateDefindexVault = {
+  roles: {
+    0: "GEMERGENCY_MANAGER_ADDRESS...",  // Emergency Manager
+    1: "GFEE_RECEIVER_ADDRESS...",       // Fee Receiver
+    2: "GVAULT_MANAGER_ADDRESS...",      // Vault Manager
+    3: "GREBALANCE_MANAGER_ADDRESS..."   // Rebalance Manager
+  },
+  vault_fee_bps: 100, // 1% fee
+  assets: [{
+    address: "CXLM_CONTRACT_ADDRESS...",
+    strategies: [{
+      address: "GSTRATEGY_CONTRACT_ADDRESS...",
+      name: "XLM Strategy",
+      paused: false
+    }]
+  }],
+  name_symbol: { 
+    name: "My DeFi Vault", 
+    symbol: "MDV" 
+  },
+  upgradable: true,
+  caller: "GCREATOR_ADDRESS..."
+};
+
+const response = await sdk.createVault(vaultConfig, SupportedNetworks.TESTNET);
+console.log('Vault XDR:', response.xdr);
+```
+
+### Vault Operations
+
+#### Get Vault Information
+```typescript
+const vaultInfo = await sdk.getVaultInfo(vaultAddress, SupportedNetworks.TESTNET);
+console.log(`Total Assets: ${vaultInfo.totalAssets}`);
+console.log(`Vault Fee: ${vaultInfo.feesBps.vaultFee / 100}%`);
+```
+
+#### Get Vault Balance
+```typescript
+const balance = await sdk.getVaultBalance(
+  vaultAddress, 
+  userAddress, 
+  SupportedNetworks.TESTNET
+);
+console.log(`Vault Shares: ${balance.dfTokens}`);
+```
+
+#### Deposit to Vault
+```typescript
+const depositResponse = await sdk.depositToVault(vaultAddress, {
+  amounts: [1000000, 2000000],
+  caller: 'GUSER_ADDRESS...',
+  invest: true,
+  slippageBps: 100
+}, SupportedNetworks.TESTNET);
+```
+
+#### Withdraw from Vault
+```typescript
+// Withdraw specific amounts
+const withdrawResponse = await sdk.withdrawFromVault(vaultAddress, {
+  amounts: [500000, 1000000],
+  caller: 'GUSER_ADDRESS...',
+  slippageBps: 100
+}, SupportedNetworks.TESTNET);
+
+// Withdraw by shares
+const shareResponse = await sdk.withdrawShares(vaultAddress, {
+  shares: 1000000,
+  caller: 'GUSER_ADDRESS...',
+  slippageBps: 100
+}, SupportedNetworks.TESTNET);
+```
+
+#### Get Vault APY
+```typescript
+const apy = await sdk.getVaultAPY(vaultAddress, SupportedNetworks.TESTNET);
+console.log(`Current APY: ${apy.apyPercent}%`);
+```
+
+### Vault Management (Admin Operations)
+
+#### Emergency Rescue
+```typescript
+// Requires Emergency Manager role
+const response = await sdk.emergencyRescue(vaultAddress, {
+  strategy_address: 'GSTRATEGY_TO_RESCUE...',
+  caller: 'GEMERGENCY_MANAGER_ADDRESS...'
+}, SupportedNetworks.TESTNET);
+```
+
+#### Pause/Unpause Strategy
+```typescript
+// Requires Strategy Manager role
+await sdk.pauseStrategy(vaultAddress, {
+  strategy_address: 'GSTRATEGY_TO_PAUSE...',
+  caller: 'GSTRATEGY_MANAGER_ADDRESS...'
+}, SupportedNetworks.TESTNET);
+
+await sdk.unpauseStrategy(vaultAddress, {
+  strategy_address: 'GSTRATEGY_TO_UNPAUSE...',
+  caller: 'GSTRATEGY_MANAGER_ADDRESS...'
+}, SupportedNetworks.TESTNET);
+```
+
+### Transaction Management
+
+#### Send Transaction
+```typescript
+// Submit via Stellar directly
+const response = await sdk.sendTransaction(
+  signedXDR, 
+  SupportedNetworks.TESTNET,
+  false // Don't use LaunchTube
+);
+
+// Submit via LaunchTube (faster, more reliable)
+const response = await sdk.sendTransaction(
+  signedXDR, 
+  SupportedNetworks.TESTNET,
+  true // Use LaunchTube
+);
+```
+
+### System Operations
+
+#### Health Check
+```typescript
+const health = await sdk.healthCheck();
+if (health.status.reachable) {
+  console.log('API is healthy');
+}
+```
+
+## 🔐 Security Best Practices
+
+1. **Environment Variables**: Store credentials in environment variables, not in code
+2. **Server-Side Only**: This SDK is designed for server-side use only
+3. **Credential Security**: Keep credentials secure and never commit them to version control
+4. **Error Handling**: Always wrap API calls in try-catch blocks
+5. **Token Management**: Use refresh tokens for long-running applications
+
+```typescript
+try {
+  const vaultInfo = await sdk.getVaultInfo(vaultAddress, network);
+  // Handle success
+} catch (error) {
+  console.error('Operation failed:', error.message);
+  // Handle error appropriately
+}
+```
+
+## 🔒 Vault Management Roles
+
+The SDK supports different operational roles:
+- **Vault Managers**: Can create and configure vaults
+- **Emergency Managers**: Can execute emergency rescues
+- **Strategy Managers**: Can pause/unpause individual strategies
+- **Regular Users**: Can deposit, withdraw, and view vault information
+
+## 🏗️ Development
+
+### Building
+```bash
+pnpm run build
+```
+
+### Testing
+
+#### Unit Tests (Mocked)
+```bash
+# Run unit tests
+pnpm test
+
+# Run with coverage
+pnpm run test:coverage
+
+# Watch mode
+pnpm run test:watch
+
+# Run integration tests
+pnpm run test:integration
+
+# Run all tests
+pnpm run test:all
+```
+
+### Code Quality
+```bash
+pnpm run lint
+pnpm run lint:fix
+```
+
+## 📊 Type Definitions
+
+The SDK exports comprehensive TypeScript types:
+
+```typescript
+import {
+  DefindexSDK,
+  DefindexSDKConfig,
+  SupportedNetworks,
+  CreateDefindexVault,
+  DepositToVaultParams,
+  WithdrawFromVaultParams,
+  WithdrawSharesParams,
+  VaultInfo,
+  VaultBalance,
+  VaultAPY,
+  // ... and many more
+} from '@defindex/sdk';
+```
+
+## 🌐 Frontend Integration
+
+While server-side focused, you can create secure frontend integrations:
+
+```typescript
+// Backend API endpoint using API key
+app.post('/api/vault-info', async (req, res) => {
+  try {
+    const sdk = new DefindexSDK({
+      apiKey: process.env.DEFINDEX_API_KEY
+    });
+    
+    const vaultInfo = await sdk.getVaultInfo(req.body.vaultAddress, req.body.network);
+    res.json(vaultInfo);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+## 📖 Documentation
+
+For comprehensive examples and detailed API documentation, see:
+- [examples/basic-example.ts](./examples/basic-example.ts) - Complete functional example
+- [EXAMPLES.md](./EXAMPLES.md) - Comprehensive usage examples  
+- [docs/defindex-sdk-docs.md](./docs/defindex-sdk-docs.md) - Complete SDK documentation
+- [CLAUDE.md](./CLAUDE.md) - Development guidance and architecture notes
+- [API Documentation](https://api.defindex.io) - Complete API reference
+
+## 🔗 Links
+
+- [DeFindex](https://defindex.io)
+- [GitHub Repository](https://github.com/paltalabs/defindex-sdk)
+
+---
+
+Built with ❤️ by the PaltaLabs team.

package/dist/clients/http-client.d.ts

@@ -0,0 +1,21 @@
+import { AxiosRequestConfig } from 'axios';
+/**
+ * HTTP client wrapper with API key authentication and error handling
+ */
+export declare class HttpClient {
+    private client;
+    constructor(baseURL: string, apiKey: string, timeout?: number);
+    /**
+     * GET request
+     */
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Build URL with query parameters
+     */
+    buildUrlWithQuery(baseUrl: string, params: Record<string, any>): string;
+}
+//# sourceMappingURL=http-client.d.ts.map

package/dist/clients/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../src/clients/http-client.ts"],"names":[],"mappings":"AACA,OAAc,EAAiB,kBAAkB,EAAiB,MAAM,OAAO,CAAC;AAEhF;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAgB;gBAG5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAAc;IAwCzB;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKlE;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAK/E;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM;CAaxE"}

package/dist/clients/http-client.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const axios_1 = __importDefault(require("axios"));
+/**
+ * HTTP client wrapper with API key authentication and error handling
+ */
+class HttpClient {
+    constructor(baseURL, apiKey, timeout = 30000) {
+        this.client = axios_1.default.create({
+            baseURL,
+            timeout,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` }),
+            },
+            // Add custom transformRequest to handle BigInt serialization
+            transformRequest: [
+                (data) => {
+                    if (data && typeof data === 'object') {
+                        return JSON.stringify(data, (_, value) => typeof value === 'bigint' ? value.toString() : value);
+                    }
+                    return data;
+                }
+            ],
+        });
+        // Add response interceptor for error handling
+        this.client.interceptors.response.use((response) => response, (error) => {
+            // Return the exact same error content from the API
+            if (error.response) {
+                // Server responded with error status - return the exact response data
+                return Promise.reject(error.response.data);
+            }
+            else {
+                // Network or other errors - return the original error
+                return Promise.reject(error);
+            }
+        });
+    }
+    /**
+     * GET request
+     */
+    async get(url, config) {
+        const response = await this.client.get(url, config);
+        return response.data;
+    }
+    /**
+     * POST request
+     */
+    async post(url, data, config) {
+        const response = await this.client.post(url, data, config);
+        return response.data;
+    }
+    /**
+     * Build URL with query parameters
+     */
+    buildUrlWithQuery(baseUrl, params) {
+        const queryString = Object.entries(params)
+            .filter(([, value]) => value !== undefined && value !== null)
+            .map(([key, value]) => {
+            if (Array.isArray(value)) {
+                return value.map(v => `${encodeURIComponent(key)}=${encodeURIComponent(v)}`).join('&');
+            }
+            return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+        })
+            .join('&');
+        return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+    }
+}
+exports.HttpClient = HttpClient;
+//# sourceMappingURL=http-client.js.map

package/dist/clients/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../../src/clients/http-client.ts"],"names":[],"mappings":"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"}