@fenelabs/fene-sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Changelog
+
+All notable changes to the Resonance SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-12-10
+
+### Added
+
+#### Analytics API Module (Subgraph Data)
+- **New `analytics` module** for accessing subgraph-indexed blockchain data
+- `getProtocolStats()` - Get protocol-level statistics (total staking, validator counts, rewards)
+- `getSyncStatus()` - Check synchronization status of analytics workers
+- `getAllValidators()` - Get paginated list of validators with analytics data
+- `getTopValidators()` - Get top validators sorted by uptime
+- `getValidatorAnalytics()` - Get detailed analytics for a specific validator
+- `getValidatorRewards()` - Get validator rewards and stakes with **mandatory pagination**
+- `getAllValidatorRewards()` - Auto-pagination helper for fetching complete reward data
+
+#### New Types
+- `ValidatorAnalytics` - Validator analytics data structure
+- `ValidatorAnalyticsListResponse` - Paginated validator list response
+- `ProtocolStats` - Protocol-level statistics
+- `ValidatorRewardsResponse` - Validator rewards with metadata
+- `SyncStatusResponse` - Worker synchronization status
+- `RewardDTO`, `StakeDTO`, `RewardSummary` - Reward-related types
+- `ResponseMetadata` - Response metadata with cache and pagination info
+- `PaginationOptions`, `ValidatorListOptions` - Pagination interfaces
+
+### Changed
+- Updated main SDK class to include `analytics` module
+- Enhanced README with comprehensive analytics documentation
+- Added `examples/analytics-usage.ts` with complete usage examples
+
+### Notes
+- Analytics data is sourced from The Graph subgraph and may have slight delays
+- Rewards endpoint requires pagination to prevent excessive data transfer
+- Always check `metadata.cached` and `metadata.stale` flags for data freshness
+- Use `getSyncStatus()` to verify subgraph synchronization before critical operations
+
+## [0.1.1] - 2025-11-26
+
+### Fixed
+- Fixed referral validate endpoint to use correct query parameter `code` instead of `referral_code`
+- Fixed indentation in referrals.ts validate method
+
+### Changed
+- Updated JSDoc comment to reflect correct query parameter format `?code=CODE`
+
+## [0.1.0] - 2024-11-26
+
+### Added
+
+#### Core SDK Features
+- Initial release of Resonance Network SDK
+- Full TypeScript support with comprehensive type definitions
+- Support for both CommonJS and ES modules
+- Browser and Node.js compatibility
+
+#### API Modules
+- **Global API**: Network statistics, APR calculations, and leaderboards
+  - `getStats()` - Get global network statistics
+  - `getNetworkAPR()` - Get network APR
+  - `getNetworkAPRBreakdown()` - Get detailed APR breakdown
+  - `getLeaderboardDelegators()` - Get delegator leaderboard
+  - `getLeaderboardValidators()` - Get validator leaderboard
+
+- **Validators API**: Complete validator information and metrics
+  - `getAll()` - List all validators
+  - `get()` - Get validator details
+  - `getDelegators()` - Get validator's delegators
+  - `getStakeBreakdown()` - Get stake distribution
+  - `getEpoch()` - Get epoch-specific data
+  - `getHistory()` - Get historical data
+  - `getWithdrawals()` - Get withdrawal history
+  - `getMetrics()` - Get performance metrics
+  - `getSlashing()` - Get slashing events
+  - `getAPR()` - Get validator-specific APR
+
+- **Delegators API**: Delegator data and staking information
+  - `getAll()` - List all delegators
+  - `get()` - Get delegator details
+  - `getStakes()` - Get stake breakdown
+  - `getRewards()` - Get reward history
+  - `getWithdrawals()` - Get withdrawal history
+  - `getUnbonding()` - Get unbonding status
+  - `getValidators()` - Get active validators
+
+- **Referrals API**: Referral code management
+  - `validate()` - Validate referral code
+  - `create()` - Create new referral code (authenticated)
+  - `apply()` - Apply referral code
+  - `delete()` - Delete referral code (authenticated)
+  - `unlink()` - Unlink delegator from referral (authenticated)
+  - `getDelegatorReferral()` - Get delegator's referral info
+  - `getValidatorReferral()` - Get validator's referral info
+
+- **Slashing API**: Slashing events and penalties
+  - `getEvents()` - Get slashing events with optional filters
+
+#### Authentication
+- Web3 wallet authentication support
+- JWT token management
+- Session storage for token persistence
+- Automatic token expiration checking
+- Support for both validator and delegator roles
+
+#### HTTP Client
+- Custom timeout configuration
+- Custom header support
+- Automatic error handling
+- Query parameter building
+- Request/response type safety
+
+#### Developer Experience
+- Comprehensive TypeScript types for all API responses
+- Example files for common use cases
+- React hooks example for authentication
+- Full JSDoc documentation
+- ESLint configuration
+- Build tooling with tsup
+
+### Documentation
+- Complete README with usage examples
+- API reference documentation
+- React and Next.js integration examples
+- Node.js usage examples
+- Authentication flow examples
+- Error handling examples
+
+### Build & Distribution
+- CommonJS (CJS) build for Node.js
+- ES Module (ESM) build for modern bundlers
+- TypeScript declaration files (.d.ts)
+- Tree-shakeable exports
+
+## [Unreleased]
+
+### Planned Features
+- WebSocket support for real-time updates
+- Caching layer for frequently accessed data
+- Rate limiting and retry logic
+- GraphQL support (if API adds GraphQL)
+- Additional utility functions for common operations
+- React hooks package (@resonance/sdk-react)
+- Vue composables package (@resonance/sdk-vue)
+
+---
+
+[0.1.0]: https://github.com/resonance-network/sdk/releases/tag/v0.1.0

package/README.md

@@ -0,0 +1,429 @@
+# Resonance Network SDK
+
+Official TypeScript/JavaScript SDK for interacting with the Resonance Network API.
+
+## Installation
+
+```bash
+npm install @avenbreaks/resonance-sdk
+# or
+yarn add @avenbreaks/resonance-sdk
+# or
+pnpm add @avenbreaks/resonance-sdk
+```
+
+## Quick Start
+
+```typescript
+import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+
+// Initialize the SDK
+const sdk = new ResonanceSDK({
+  apiUrl: 'https://api.resonance.network',
+  timeout: 30000, // Optional, default 30s
+});
+
+// Get global network statistics
+const stats = await sdk.global.getStats();
+console.log('Total Network Stake:', stats.total_network_stake);
+
+// Get validator details
+const validator = await sdk.validators.get('0x1234...');
+console.log('Validator Status:', validator.status);
+```
+
+## Authentication
+
+The SDK supports wallet-based authentication using Web3 providers:
+
+```typescript
+import { ethers } from 'ethers';
+import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+
+const sdk = new ResonanceSDK({
+  apiUrl: 'https://api.resonance.network',
+});
+
+// Connect wallet (browser environment)
+const provider = new ethers.BrowserProvider(window.ethereum);
+const authResponse = await sdk.auth.connectWallet(provider, 'delegator');
+
+// Set the JWT token for authenticated requests
+sdk.setAuthToken(authResponse.token);
+
+// Check authentication status
+if (sdk.isAuthenticated()) {
+  console.log('User is authenticated');
+}
+
+// Logout
+sdk.logout();
+```
+
+## API Reference
+
+### Global Network Stats
+
+```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);
+
+// Get delegator withdrawals
+const withdrawals = await sdk.delegators.getWithdrawals('0xabcd...', 50, 0);
+
+// Get delegator unbonding status
+const unbonding = await sdk.delegators.getUnbonding('0xabcd...');
+
+// Get delegator active validators
+const validators = await sdk.delegators.getValidators('0xabcd...');
+```
+
+### 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');
+
+// Unlink a delegator from referral (requires authentication)
+await sdk.referrals.unlink('0xabcd...');
+
+// Get delegator referral information
+const delegatorRef = await sdk.referrals.getDelegatorReferral('0xabcd...');
+
+// Get validator referral information
+const validatorRef = await sdk.referrals.getValidatorReferral('0x1234...');
+```
+
+### Slashing
+
+```typescript
+// Get all slashing events
+const allEvents = await sdk.slashing.getEvents();
+
+// Get slashing events for a specific validator
+const validatorEvents = await sdk.slashing.getEvents('0x1234...', 50, 0);
+```
+
+### 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',
+});
+
+// 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`);
+});
+
+// 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);
+
+// Get validator rewards with manual pagination (REQUIRED for this endpoint)
+const rewardsPage1 = await sdk.analytics.getValidatorRewards('0x1234...', {
+  limit: 50,
+  offset: 0,
+});
+
+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);
+
+// Fetch next page if available
+if (rewardsPage1.metadata.has_more) {
+  const rewardsPage2 = await sdk.analytics.getValidatorRewards('0x1234...', {
+    limit: 50,
+    offset: 50,
+  });
+}
+
+// Auto-pagination helper (use with caution - makes multiple API calls)
+const allRewards = await sdk.analytics.getAllValidatorRewards('0x1234...', {
+  batchSize: 50,
+  maxPages: 10, // Safety limit
+});
+
+console.log('Total Stakes Fetched:', allRewards.stakes.length);
+```
+
+**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
+
+## Advanced Usage
+
+### Custom Headers
+
+```typescript
+const sdk = new ResonanceSDK({
+  apiUrl: 'https://api.resonance.network',
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+});
+
+// Or set headers after initialization
+sdk.setHeader('X-API-Key', 'your-api-key');
+```
+
+### Error Handling
+
+```typescript
+try {
+  const validator = await sdk.validators.get('0x1234...');
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('API Error:', error.message);
+  }
+}
+```
+
+### Timeout Configuration
+
+```typescript
+const sdk = new ResonanceSDK({
+  apiUrl: 'https://api.resonance.network',
+  timeout: 60000, // 60 seconds
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  ValidatorDetailResponse,
+  DelegatorDetailResponse,
+  GlobalNetworkResponse,
+} from '@avenbreaks/resonance-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 '@avenbreaks/resonance-sdk';
+
+const sdk = new ResonanceSDK({
+  apiUrl: 'https://api.resonance.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 '@avenbreaks/resonance-sdk';
+
+const sdk = new ResonanceSDK({
+  apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.resonance.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>
+  );
+}
+```
+
+## Node.js Example
+
+```typescript
+import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+
+const sdk = new ResonanceSDK({
+  apiUrl: 'https://api.resonance.network',
+});
+
+async function main() {
+  // Get network statistics
+  const stats = await sdk.global.getStats();
+  console.log('Network Stats:', stats);
+
+  // Get validator leaderboard
+  const leaderboard = await sdk.global.getLeaderboardValidators(10);
+  console.log('Top 10 Validators:', leaderboard);
+}
+
+main().catch(console.error);
+```
+
+## 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
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the SDK
+pnpm build
+
+# Run type checking
+pnpm type-check
+
+# Watch mode (for development)
+pnpm dev
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please visit:
+- GitHub Issues: https://github.com/fenelabs/sdk/issues
+- Documentation: https://docs.fene.network