npm package: @prime-vaults/service
Description: TypeScript SDK for Prime Vaults API
Author: Prime Vaults Team
Latest version: 1.0.0

# Prime Vaults TypeScript SDK

Official TypeScript SDK for interacting with Prime Vaults API.

## Installation

```bash
npm install @prime-vaults/sdk
# or
yarn add @prime-vaults/sdk
# or
pnpm add @prime-vaults/sdk
```

## Quick Start

```typescript
import { PrimeVaultSDK, SDKPresets, BaseURL } from '@prime-vaults/sdk';

// Option 1: Use preset configuration (Recommended)
const sdk = new PrimeVaultSDK({
  ...SDKPresets.local, // Local development
  // ...SDKPresets.dev,      // Development environment
  // ...SDKPresets.production, // Production environment
  apiKey: 'your-api-key', // Optional, required for protected endpoints
});

// Option 2: Use specific baseURL
const sdk = new PrimeVaultSDK({
  baseURL: BaseURL.LOCAL_ANALYTICS, // or BaseURL.PROD_ANALYTICS
  apiKey: 'your-api-key',
});

// Option 3: Custom configuration
const sdk = new PrimeVaultSDK({
  baseURL: 'https://custom-api.example.com',
  apiKey: 'your-api-key',
  timeout: 30000, // Optional, default: 30000ms
});
```

## Configuration Presets

### Available BaseURLs

```typescript
import { BaseURL } from '@prime-vaults/sdk';

BaseURL.LOCAL_ANALYTICS; // http://localhost:3002
BaseURL.LOCAL_OPERATOR; // http://localhost:3003
BaseURL.DEV_ANALYTICS; // https://dev-analytics.primevaults.io
BaseURL.DEV_OPERATOR; // https://dev-operator.primevaults.io
BaseURL.PROD_ANALYTICS; // https://analytics.primevaults.io
BaseURL.PROD_OPERATOR; // https://operator.primevaults.io
```

### Available Presets

```typescript
import { SDKPresets } from '@prime-vaults/sdk';

SDKPresets.local; // Local analytics (port 3002)
SDKPresets.localWithOperator; // Local operator (port 3003)
SDKPresets.dev; // Development environment
SDKPresets.production; // Production environment
```

## Usage Examples

### Vault Operations

```typescript
// Get all vaults
const { data } = await sdk.vault.getAll();
console.log(`Total vaults: ${data?.totalVaults}`);

// Get specific vault
const vault = await sdk.vault.getByAddress('0x...');
console.log(`TVL: $${vault.data?.tvl}`);

// Get vault APR
const apr = await sdk.vault.getAPR('0x...');
console.log(`APR: ${apr.data?.apr}%`);

// Get TVL history
const history = await sdk.vault.getTVLHistory('0x...', 30); // Last 30 days
```

### Smart Account Operations

```typescript
// Get all smart accounts
const accounts = await sdk.smartAccount.getAll();

// Get positions for an address
const positions = await sdk.smartAccount.getPositions('0x...');

// Get vault stakers
const stakers = await sdk.smartAccount.getVaultStakers('0x...');
```

### Master Account Operations

```typescript
// Get all master accounts
const masters = await sdk.masterAccount.getAll(100); // Limit to 100

// Get master account details
const master = await sdk.masterAccount.getByAddress('0x...');
console.log(`Total staked: $${master.data?.masterAccount?.totalStakedValue}`);

// Get smart accounts for master
const smartAccounts = await sdk.masterAccount.getSmartAccounts('0x...');
```

### Withdrawal Operations

```typescript
// Get pending withdrawals for smart account
const pending = await sdk.withdrawal.getBySmartAccount('0x...');

// Get pending withdrawals for master
const masterPending = await sdk.withdrawal.getByMaster('0x...');

// Get pending totals for vault
const vaultPending = await sdk.withdrawal.getPending('0x...');

// Get withdrawals maturing before date
const cutoffDate = new Date('2025-12-31').toISOString();
const pendingUntil = await sdk.withdrawal.getPendingUntil(cutoffDate, '0x...'); // Optional asset filter
```

### Sync Operations (Requires API Key)

```typescript
// Trigger manual sync
const syncResult = await sdk.sync.trigger(); // Sync all vaults
const vaultSync = await sdk.sync.trigger('0x...'); // Sync specific vault

// Get sync status
const status = await sdk.sync.getStatus();
console.log(`Sync interval: ${status.data?.syncInterval}`);
```

### Compound Operations (Requires API Key)

```typescript
// Trigger compound for all eligible accounts
const result = await sdk.compound.trigger();
console.log(`Success: ${result.data?.successCount}, Failed: ${result.data?.failureCount}`);

// Compound for specific master
const masterResult = await sdk.compound.compoundForMaster('0x...');

// Compound specific smart account
const accountResult = await sdk.compound.compoundSmartAccount(
  '0x...', // smart account
  '0x...', // vault address
);

// Get compound status
const status = await sdk.compound.getStatus();
console.log(`Wallet balance: ${status.data?.wallet.balanceEth} ETH`);

// Get eligible accounts
const accounts = await sdk.compound.getSmartAccounts();
const vaultAccounts = await sdk.compound.getVaultSmartAccounts('0x...');
```

## API Reference

### Configuration

```typescript
interface SDKConfig {
  baseURL: string; // API base URL
  apiKey?: string; // Optional API key for protected endpoints
  timeout?: number; // Request timeout in ms (default: 30000)
  headers?: Record<string, string>; // Custom headers
}
```

### Services

The SDK provides the following services:

- **`vault`** - Vault analytics operations
- **`smartAccount`** - Smart account operations
- **`masterAccount`** - Master account operations
- **`withdrawal`** - Withdrawal request operations
- **`sync`** - Sync operations (requires API key)
- **`compound`** - Compound operations (requires API key)

### Error Handling

```typescript
try {
  const vault = await sdk.vault.getByAddress('0x...');
} catch (error) {
  console.error(`API Error: ${error.message}`);
  console.error(`Status: ${error.statusCode}`);
  console.error(`Response:`, error.response);
}
```

### TypeScript Support

Full TypeScript support with comprehensive type definitions:

```typescript
import {
  VaultMetrics,
  SmartAccount,
  MasterAccount,
  WithdrawalRequest,
  CompoundResult,
} from '@prime-vaults/sdk';
```

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Lint
pnpm lint
```

## License

MIT

## Support

For issues and questions, please visit [GitHub Issues](https://github.com/prime-vaults/prime-backend/issues)