@fenelabs/fene-sdk 0.3.2 → 0.3.3

package/README.md

@@ -1,485 +1,238 @@
-# Fene Network SDK
+# @resonance/sdk
 
-Official TypeScript/JavaScript SDK for interacting with the Fene Network API.
+TypeScript SDK for the Resonance API.
 
 ## Installation
 
 ```bash
-npm install @fenelabs/fene-sdk
-# or
-yarn add @fenelabs/fene-sdk
-# or
-pnpm add @fenelabs/fene-sdk
+pnpm add @resonance/sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { ResonanceSDK } from '@fenelabs/fene-sdk';
+import { createResonanceClient } from "@resonance/sdk";
 
-// Initialize the SDK
-const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.fene.network',
-  timeout: 30000, // Optional, default 30s
+const client = createResonanceClient({
+  baseUrl: "https://api.fene.network",
 });
 
-// Get global network statistics
-const stats = await sdk.global.getStats();
-console.log('Total Network Stake:', stats.total_network_stake);
+// Get network stats
+const stats = await client.getNetworkStats();
+console.log(`Total validators: ${stats.total_validators}`);
 
-// Get validator details
-const validator = await sdk.validators.get('0x1234...');
-console.log('Validator Status:', validator.status);
+// Get APR
+const apr = await client.getNetworkAPR();
+console.log(`Network APR: ${apr.network_apr}%`);
 ```
 
 ## Authentication
 
-The SDK supports wallet-based authentication using Web3 providers:
-
 ```typescript
-import { ethers } from 'ethers';
-import { ResonanceSDK } from '@fenelabs/fene-sdk';
+import { createResonanceClient } from "@resonance/sdk";
+import { signMessage } from "viem/wallet";
 
-const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.fene.network',
+const client = createResonanceClient({
+  baseUrl: "https://api.fene.network",
+  onTokenExpired: () => {
+    console.log("Token expired, please re-authenticate");
+  },
 });
 
-// Connect wallet (browser environment)
-const provider = new ethers.BrowserProvider(window.ethereum);
-const authResponse = await sdk.auth.connectWallet(provider, 'delegator');
+// 1. Get nonce
+const { message } = await client.getNonce("0x...");
 
-// Set the JWT token for authenticated requests
-sdk.setAuthToken(authResponse.token);
+// 2. Sign message (using viem or wagmi)
+const signature = await signMessage({ message });
 
-// Check authentication status
-if (sdk.isAuthenticated()) {
-  console.log('User is authenticated');
-}
+// 3. Verify and get JWT
+const auth = await client.verify("0x...", signature);
+console.log(`Logged in as: ${auth.role}`);
 
-// Logout
-sdk.logout();
+// Now authenticated requests work
+await client.updateGeoLocation({ latitude: 0, longitude: 0, node_type: "rpc" });
 ```
 
-## API Reference
+## Error Handling
 
-### Global Network Stats
+The SDK provides structured error handling matching the API's error system:
 
 ```typescript
-// Get global network statistics
-const stats = await sdk.global.getStats();
-
-// Get network APR
-const apr = await sdk.global.getNetworkAPR();
-
-// Get network APR breakdown
-const breakdown = await sdk.global.getNetworkAPRBreakdown();
-
-// Get delegator leaderboard
-const delegatorLeaderboard = await sdk.global.getLeaderboardDelegators(10, 0);
-
-// Get validator leaderboard
-const validatorLeaderboard = await sdk.global.getLeaderboardValidators(10, 0);
-```
-
-### Validators
-
-```typescript
-// Get all validators
-const allValidators = await sdk.validators.getAll();
-
-// Get specific validator details
-const validator = await sdk.validators.get('0x1234...');
-
-// Get validator delegators
-const delegators = await sdk.validators.getDelegators('0x1234...');
-
-// Get validator stake breakdown
-const stakeBreakdown = await sdk.validators.getStakeBreakdown('0x1234...');
-
-// Get validator epoch details
-const epochData = await sdk.validators.getEpoch('0x1234...', 100);
-
-// Get validator history
-const history = await sdk.validators.getHistory('0x1234...', 1, 100);
-
-// Get validator withdrawals
-const withdrawals = await sdk.validators.getWithdrawals('0x1234...', 50, 0);
-
-// Get validator metrics
-const metrics = await sdk.validators.getMetrics('0x1234...');
-
-// Get validator slashing events
-const slashing = await sdk.validators.getSlashing('0x1234...');
-
-// Get validator APR
-const validatorAPR = await sdk.validators.getAPR('0x1234...');
-```
-
-### Delegators
-
-```typescript
-// Get all delegators
-const allDelegators = await sdk.delegators.getAll();
-
-// Get specific delegator details
-const delegator = await sdk.delegators.get('0xabcd...');
-
-// Get delegator stakes breakdown
-const stakes = await sdk.delegators.getStakes('0xabcd...');
-
-// Get delegator rewards history
-const rewards = await sdk.delegators.getRewards('0xabcd...', 50, 0);
+import {
+  createResonanceClient,
+  ResonanceError,
+  ErrorCode,
+  isAuthError,
+  isNotFoundError,
+} from "@resonance/sdk";
 
-// Get delegator withdrawals
-const withdrawals = await sdk.delegators.getWithdrawals('0xabcd...', 50, 0);
+const client = createResonanceClient({ baseUrl: "https://api.fene.network" });
 
-// Get delegator unbonding status
-const unbonding = await sdk.delegators.getUnbonding('0xabcd...');
+try {
+  const validator = await client.getValidator("0xinvalid");
+} catch (error) {
+  if (error instanceof ResonanceError) {
+    console.log(`Error code: ${error.code}`);
+    console.log(`Message: ${error.message}`);
+    console.log(`Status: ${error.statusCode}`);
+
+    // Check specific error types
+    if (error.is(ErrorCode.VALIDATOR_NOT_FOUND)) {
+      // Handle validator not found
+    }
 
-// Get delegator active validators
-const validators = await sdk.delegators.getValidators('0xabcd...');
+    // Or use helper functions
+    if (isAuthError(error)) {
+      // Re-authenticate
+    } else if (isNotFoundError(error)) {
+      // Handle not found
+    }
+  }
+}
 ```
 
-### Referrals
-
-```typescript
-// Validate a referral code
-const validation = await sdk.referrals.validate('REF123');
-
-// Create a new referral code (requires authentication)
-const referralCode = await sdk.referrals.create({
-  validator_address: '0x1234...',
-  max_quota: 100,
-  expires_in_days: 30,
-});
-
-// Apply a referral code
-await sdk.referrals.apply({
-  referral_code: 'REF123',
-  delegator_address: '0xabcd...',
-});
-
-// Delete a referral code (requires authentication)
-await sdk.referrals.delete('REF123');
+### Error Codes
 
-// Unlink a delegator from referral (requires authentication)
-await sdk.referrals.unlink('0xabcd...');
+The SDK recognizes these error codes from the API:
 
-// Get delegator referral information
-const delegatorRef = await sdk.referrals.getDelegatorReferral('0xabcd...');
+- **Validator**: `VALIDATOR_NOT_FOUND`, `VALIDATOR_INACTIVE`
+- **Delegator**: `DELEGATOR_NOT_FOUND`, `NOT_WHITELISTED`
+- **Referral**: `REFERRAL_KEY_INVALID`, `REFERRAL_KEY_EXPIRED`, `REFERRAL_KEY_USED`
+- **Auth**: `INVALID_SIGNATURE`, `NONCE_EXPIRED`, `UNAUTHORIZED`
+- **Service**: `RPC_UNAVAILABLE`, `CACHE_UNAVAILABLE`, `DATABASE_UNAVAILABLE`
+- **General**: `BAD_REQUEST`, `INTERNAL_ERROR`, `RATE_LIMITED`
 
-// Get validator referral information
-const validatorRef = await sdk.referrals.getValidatorReferral('0x1234...');
-```
-
-### Slashing
+## Architecture
 
-```typescript
-// Get all slashing events
-const allEvents = await sdk.slashing.getEvents();
+### Caching
 
-// Get slashing events for a specific validator
-const validatorEvents = await sdk.slashing.getEvents('0x1234...', 50, 0);
-```
+The Resonance API implements **server-side Redis caching** with graceful degradation. The SDK does not implement client-side caching as all caching is handled by the API layer. This ensures:
 
-### Analytics (Subgraph Data)
-
-The Analytics API provides access to aggregated and historical data indexed from the blockchain via The Graph subgraph. This data may have slight delays compared to real-time blockchain queries.
-
-```typescript
-// Get protocol-level statistics
-const protocolStats = await sdk.analytics.getProtocolStats();
-console.log('Total Staking:', protocolStats.TotalStaking);
-console.log('Active Validators:', protocolStats.ActiveValidators);
-
-// Check sync status of analytics workers
-const syncStatus = await sdk.analytics.getSyncStatus();
-console.log('Protocol Sync Status:', syncStatus.protocol_sync.status);
-console.log('Last Synced Block:', syncStatus.protocol_sync.last_block);
-
-// Get all validators with analytics data (paginated)
-const validators = await sdk.analytics.getAllValidators({
-  limit: 20,
-  offset: 0,
-  status: 'active',
-});
+- Consistent data across all API consumers
+- Reduced load on blockchain RPC nodes
+- Automatic cache invalidation on chain state changes
+- Cache TTLs optimized per endpoint (10s to 5min)
 
-// Get top validators by uptime
-const topValidators = await sdk.analytics.getTopValidators(10);
-topValidators.data.forEach((v, i) => {
-  console.log(`#${i + 1}: ${v.moniker} - ${v.uptime}% uptime`);
-});
+### Authentication
 
-// Get specific validator analytics
-const validatorAnalytics = await sdk.analytics.getValidatorAnalytics('0x1234...');
-console.log('Uptime:', validatorAnalytics.uptime);
-console.log('Signed Blocks:', validatorAnalytics.signed_blocks);
-console.log('Total Stakers:', validatorAnalytics.total_stakers);
+The SDK uses a standard Web3 authentication flow:
 
-// Get validator rewards with manual pagination (REQUIRED for this endpoint)
-const rewardsPage1 = await sdk.analytics.getValidatorRewards('0x1234...', {
-  limit: 50,
-  offset: 0,
-});
+1. Request a nonce from the API (`getNonce`)
+2. Sign the message with your wallet (using viem, wagmi, etc.)
+3. Submit signature for verification (`verify`)
+4. Receive JWT token for authenticated requests
 
-console.log('Total Rewards:', rewardsPage1.summary.total_rewards);
-console.log('Total Stakers:', rewardsPage1.summary.total_stakers);
-console.log('Has More Data:', rewardsPage1.metadata.has_more);
+The token is automatically included in all subsequent requests and managed by the client.
 
-// Fetch next page if available
-if (rewardsPage1.metadata.has_more) {
-  const rewardsPage2 = await sdk.analytics.getValidatorRewards('0x1234...', {
-    limit: 50,
-    offset: 50,
-  });
-}
+## API Reference
 
-// Auto-pagination helper (use with caution - makes multiple API calls)
-const allRewards = await sdk.analytics.getAllValidatorRewards('0x1234...', {
-  batchSize: 50,
-  maxPages: 10, // Safety limit
-});
+### Auth
 
-console.log('Total Stakes Fetched:', allRewards.stakes.length);
-```
+- `getNonce(address)` - Get authentication nonce
+- `verify(address, signature)` - Verify signature and get JWT
 
-**Important Notes:**
-- Analytics data is sourced from subgraph indexing and may lag behind real-time blockchain state
-- Always check `metadata.cached` and `metadata.stale` flags in responses
-- The rewards endpoint is heavy and **requires pagination** - never fetch without limit/offset
-- Use `getSyncStatus()` to verify data freshness before making critical decisions
+### Validators
 
-### Analytics Helper Utilities
+- `getValidators()` - Get all validators
+- `getActiveValidators()` - Get active validators
+- `getCandidates()` - Get validator candidates
+- `getValidator(address)` - Get validator details
+- `getValidatorDelegators(address)` - Get validator's delegators
 
-The SDK provides utility functions for working with analytics data:
+### Delegators
 
-```typescript
-import {
-  isValidatorNotFound,
-  isStaleData,
-  isCachedData,
-  isSyncHealthy,
-  getSyncLag,
-  getDataFreshness,
-  formatNumber,
-  weiToEther,
-  withRetry,
-} from '@avenbreaks/resonance-sdk';
-
-// Error handling
-try {
-  const validator = await sdk.analytics.getValidatorAnalytics(address);
-} catch (error) {
-  if (isValidatorNotFound(error)) {
-    console.log('Validator does not exist');
-  }
-}
+- `getDelegator(address)` - Get delegator info
+- `getDelegatorStakes(address)` - Get delegator stakes
+- `getDelegatorRewards(address)` - Get delegator rewards
 
-// Data freshness validation
-const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
-if (isStaleData(rewards)) {
-  console.warn('Data may be outdated');
-}
+### Referral
 
-// Sync health monitoring
-const syncStatus = await sdk.analytics.getSyncStatus();
-if (isSyncHealthy(syncStatus, 'protocol_sync')) {
-  console.log('Sync is healthy');
-}
+- `getReferralKey(key)` - Get referral key info
+- `getValidatorKeys(address)` - Get validator's referral keys
+- `checkWhitelist(data)` - Check if whitelisted (requires auth)
 
-// Retry logic for heavy queries
-const rewardsWithRetry = await withRetry(
-  () => sdk.analytics.getValidatorRewards(address, { limit: 100 }),
-  {
-    maxRetries: 3,
-    initialDelay: 1000,
-    onRetry: (error, attempt, delay) => {
-      console.log(`Retry ${attempt} after ${delay}ms`);
-    }
-  }
-);
+### Geo
 
-// Number formatting
-const stats = await sdk.analytics.getProtocolStats();
-console.log(formatNumber(stats.TotalStaking)); // "26,883,345,073,055,930,973,683,712"
-console.log(weiToEther(stats.TotalStaking));   // "26883345.0730"
-```
+- `getGeoNodes()` - Get all geo nodes
+- `getGeoValidators()` - Get validator locations
+- `getGeoStats()` - Get geo statistics
+- `updateGeoLocation(data)` - Update geo location (requires auth)
 
-## Advanced Usage
+### Stats
 
-### Custom Headers
+- `getNetworkStats()` - Get network statistics
+- `getCurrentEpoch()` - Get current epoch info
 
-```typescript
-const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.fene.network',
-  headers: {
-    'X-Custom-Header': 'value',
-  },
-});
+### APR
 
-// Or set headers after initialization
-sdk.setHeader('X-API-Key', 'your-api-key');
-```
+- `getNetworkAPR()` - Get network-wide APR
+- `getValidatorAPR(address)` - Get validator APR breakdown
 
-### Error Handling
+### Storage
 
-```typescript
-try {
-  const validator = await sdk.validators.get('0x1234...');
-} catch (error) {
-  if (error instanceof Error) {
-    console.error('API Error:', error.message);
-  }
-}
-```
+- `uploadAvatar(file)` - Upload avatar (requires auth)
+- `getAvatar(address)` - Get avatar URL
 
-### Timeout Configuration
+### Analytics
 
-```typescript
-const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.fene.network',
-  timeout: 60000, // 60 seconds
-});
-```
+- `getDailyBlockStats(days?)` - Get daily block stats
+- `getValidatorRewardHistory(address, limit?)` - Get reward history
 
-## TypeScript Support
+## Types
 
-The SDK is written in TypeScript and provides full type definitions:
+All types are exported for TypeScript users:
 
 ```typescript
 import type {
-  ValidatorDetailResponse,
-  DelegatorDetailResponse,
-  GlobalNetworkResponse,
-} from '@fenelabs/fene-sdk';
-
-const processValidator = (validator: ValidatorDetailResponse) => {
-  console.log(validator.validator_address);
-  console.log(validator.total_stake);
-};
-```
-
-## React Example
-
-```typescript
-import { useEffect, useState } from 'react';
-import { ResonanceSDK } from '@fenelabs/fene-sdk';
-
-const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.fene.network',
-});
-
-function ValidatorList() {
-  const [validators, setValidators] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    const fetchValidators = async () => {
-      try {
-        const data = await sdk.validators.getAll();
-        setValidators(data);
-      } catch (error) {
-        console.error('Failed to fetch validators:', error);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchValidators();
-  }, []);
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div>
-      {validators.map((validator) => (
-        <div key={validator.address}>{validator.address}</div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Next.js Example
-
-```typescript
-// app/page.tsx
-import { ResonanceSDK } from '@fenelabs/fene-sdk';
-
-const sdk = new ResonanceSDK({
-  apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.fene.network',
-});
-
-export default async function HomePage() {
-  const stats = await sdk.global.getStats();
-
-  return (
-    <div>
-      <h1>Network Stats</h1>
-      <p>Total Validators: {stats.total_validators}</p>
-      <p>Total Delegators: {stats.total_delegators}</p>
-      <p>Total Stake: {stats.total_network_stake}</p>
-    </div>
-  );
-}
+  Validator,
+  Delegator,
+  NetworkStats,
+  ValidatorAPR,
+  // Error types
+  ErrorCodeType,
+  APIErrorResponse,
+} from "@resonance/sdk";
+
+// Error handling utilities
+import {
+  ResonanceError,
+  ErrorCode,
+  isResonanceError,
+  hasErrorCode,
+  isAuthError,
+  isNetworkError,
+  isNotFoundError,
+} from "@resonance/sdk";
 ```
 
-## Node.js Example
+## Development
 
-```typescript
-import { ResonanceSDK } from '@fenelabs/fene-sdk';
+### Running Tests
 
-const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.fene.network',
-});
-
-async function main() {
-  // Get network statistics
-  const stats = await sdk.global.getStats();
-  console.log('Network Stats:', stats);
+```bash
+# Run all tests
+pnpm test
 
-  // Get validator leaderboard
-  const leaderboard = await sdk.global.getLeaderboardValidators(10);
-  console.log('Top 10 Validators:', leaderboard);
-}
+# Run tests in watch mode
+pnpm test -- --watch
 
-main().catch(console.error);
+# Run tests with coverage
+pnpm test -- --coverage
 ```
 
-## API Endpoints
-
-All API endpoints are available under the `/eth/v1` prefix. The SDK handles this automatically.
-
-| Module | Endpoint Pattern | Description |
-|--------|-----------------|-------------|
-| Global | `/eth/v1/global` | Network statistics and leaderboards |
-| Validators | `/eth/v1/validators/:address` | Validator information and history |
-| Delegators | `/eth/v1/delegators/:address` | Delegator information and history |
-| Referrals | `/eth/v1/referrals` | Referral code management |
-| Slashing | `/eth/v1/slashing/events` | Slashing events |
-
-## Development
+### Building
 
 ```bash
-# Install dependencies
-pnpm install
-
 # Build the SDK
-pnpm build
+pnpm run build
 
-# Run type checking
-pnpm type-check
+# Watch mode for development
+pnpm run dev
 
-# Watch mode (for development)
-pnpm dev
+# Type checking
+pnpm run lint
 ```
 
 ## License
 
 MIT
-
-## Support
-
-For issues and questions, please visit:
-- GitHub Issues: https://github.com/fenelabs/fene-sdk/issues
-- Documentation: https://docs.fene.network