@fenelabs/fene-sdk 0.2.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.1] - 2025-12-10
+
+### Added
+
+#### Analytics Helper Utilities
+- **Error handling helpers**: `isValidatorNotFound()`, `isServiceUnavailable()`, `isTimeout()`
+- **Data validation helpers**: `isStaleData()`, `isCachedData()`, `validatePagination()`
+- **Sync monitoring helpers**: `isSyncHealthy()`, `isSyncDegraded()`, `getSyncLag()`
+- **Data freshness**: `getDataFreshness()` - Calculate freshness score (0-100)
+- **Number formatting**: `formatNumber()`, `weiToEther()` - Format large numbers
+- **Batch optimization**: `getOptimalBatchSize()` - Calculate optimal pagination size
+
+#### Retry Logic
+- **`withRetry()`** - Execute functions with automatic retry on transient errors
+- **`createRetryWrapper()`** - Create retry-wrapped versions of functions
+- Configurable retry options: max retries, backoff, custom predicates
+- Built-in retry for timeout and 503 errors
+- Exponential backoff with max delay cap
+
+### Changed
+- Enhanced README with utility function documentation
+- Added `examples/analytics-advanced.ts` with advanced usage patterns
+- Improved error handling examples
+
 ## [0.2.0] - 2025-12-10
 
 ### Added

package/README.md

@@ -1,25 +1,25 @@
-# Resonance Network SDK
+# Fene Network SDK
 
-Official TypeScript/JavaScript SDK for interacting with the Resonance Network API.
+Official TypeScript/JavaScript SDK for interacting with the Fene Network API.
 
 ## Installation
 
 ```bash
-npm install @avenbreaks/resonance-sdk
+npm install @fenelabs/fene-sdk
 # or
-yarn add @avenbreaks/resonance-sdk
+yarn add @fenelabs/fene-sdk
 # or
-pnpm add @avenbreaks/resonance-sdk
+pnpm add @fenelabs/fene-sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+import { ResonanceSDK } from '@fenelabs/fene-sdk';
 
 // Initialize the SDK
 const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.resonance.network',
+  apiUrl: 'https://api.fene.network',
   timeout: 30000, // Optional, default 30s
 });
 
@@ -38,10 +38,10 @@ The SDK supports wallet-based authentication using Web3 providers:
 
 ```typescript
 import { ethers } from 'ethers';
-import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+import { ResonanceSDK } from '@fenelabs/fene-sdk';
 
 const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.resonance.network',
+  apiUrl: 'https://api.fene.network',
 });
 
 // Connect wallet (browser environment)
@@ -249,13 +249,69 @@ console.log('Total Stakes Fetched:', allRewards.stakes.length);
 - The rewards endpoint is heavy and **requires pagination** - never fetch without limit/offset
 - Use `getSyncStatus()` to verify data freshness before making critical decisions
 
+### Analytics Helper Utilities
+
+The SDK provides utility functions for working with analytics data:
+
+```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');
+  }
+}
+
+// Data freshness validation
+const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+if (isStaleData(rewards)) {
+  console.warn('Data may be outdated');
+}
+
+// Sync health monitoring
+const syncStatus = await sdk.analytics.getSyncStatus();
+if (isSyncHealthy(syncStatus, 'protocol_sync')) {
+  console.log('Sync is healthy');
+}
+
+// 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`);
+    }
+  }
+);
+
+// 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"
+```
+
 ## Advanced Usage
 
 ### Custom Headers
 
 ```typescript
 const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.resonance.network',
+  apiUrl: 'https://api.fene.network',
   headers: {
     'X-Custom-Header': 'value',
   },
@@ -281,7 +337,7 @@ try {
 
 ```typescript
 const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.resonance.network',
+  apiUrl: 'https://api.fene.network',
   timeout: 60000, // 60 seconds
 });
 ```
@@ -295,7 +351,7 @@ import type {
   ValidatorDetailResponse,
   DelegatorDetailResponse,
   GlobalNetworkResponse,
-} from '@avenbreaks/resonance-sdk';
+} from '@fenelabs/fene-sdk';
 
 const processValidator = (validator: ValidatorDetailResponse) => {
   console.log(validator.validator_address);
@@ -307,10 +363,10 @@ const processValidator = (validator: ValidatorDetailResponse) => {
 
 ```typescript
 import { useEffect, useState } from 'react';
-import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+import { ResonanceSDK } from '@fenelabs/fene-sdk';
 
 const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.resonance.network',
+  apiUrl: 'https://api.fene.network',
 });
 
 function ValidatorList() {
@@ -348,10 +404,10 @@ function ValidatorList() {
 
 ```typescript
 // app/page.tsx
-import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+import { ResonanceSDK } from '@fenelabs/fene-sdk';
 
 const sdk = new ResonanceSDK({
-  apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.resonance.network',
+  apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.fene.network',
 });
 
 export default async function HomePage() {
@@ -371,10 +427,10 @@ export default async function HomePage() {
 ## Node.js Example
 
 ```typescript
-import { ResonanceSDK } from '@avenbreaks/resonance-sdk';
+import { ResonanceSDK } from '@fenelabs/fene-sdk';
 
 const sdk = new ResonanceSDK({
-  apiUrl: 'https://api.resonance.network',
+  apiUrl: 'https://api.fene.network',
 });
 
 async function main() {
@@ -425,5 +481,5 @@ MIT
 ## Support
 
 For issues and questions, please visit:
-- GitHub Issues: https://github.com/fenelabs/sdk/issues
+- GitHub Issues: https://github.com/fenelabs/fene-sdk/issues
 - Documentation: https://docs.fene.network

package/dist/index.d.mts

@@ -875,6 +875,316 @@ declare class AnalyticsAPI {
     }): Promise<ValidatorRewardsResponse>;
 }
 
+/**
+ * Analytics Helper Utilities
+ *
+ * Provides utility functions for working with analytics data,
+ * including error checking, data validation, and freshness checks.
+ */
+/**
+ * Check if error is a validator not found error
+ *
+ * @param error - Error object to check
+ * @returns True if validator was not found
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const validator = await sdk.analytics.getValidatorAnalytics(address);
+ * } catch (error) {
+ *   if (isValidatorNotFound(error)) {
+ *     console.log('Validator does not exist');
+ *   }
+ * }
+ * ```
+ */
+declare function isValidatorNotFound(error: any): boolean;
+/**
+ * Check if error is a service unavailable error (sync in progress)
+ *
+ * @param error - Error object to check
+ * @returns True if service is temporarily unavailable
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const stats = await sdk.analytics.getProtocolStats();
+ * } catch (error) {
+ *   if (isServiceUnavailable(error)) {
+ *     console.log('Analytics service is syncing, try again later');
+ *   }
+ * }
+ * ```
+ */
+declare function isServiceUnavailable(error: any): boolean;
+/**
+ * Check if error is a timeout error
+ *
+ * @param error - Error object to check
+ * @returns True if request timed out
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 1000 });
+ * } catch (error) {
+ *   if (isTimeout(error)) {
+ *     console.log('Request timed out, try with smaller limit');
+ *   }
+ * }
+ * ```
+ */
+declare function isTimeout(error: any): boolean;
+/**
+ * Check if analytics data is stale
+ *
+ * @param response - Response with metadata
+ * @returns True if data is marked as stale
+ *
+ * @example
+ * ```typescript
+ * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+ * if (isStaleData(rewards)) {
+ *   console.warn('Data may be outdated');
+ * }
+ * ```
+ */
+declare function isStaleData(response: ValidatorRewardsResponse): boolean;
+/**
+ * Check if analytics data is from cache
+ *
+ * @param response - Response with metadata
+ * @returns True if data was served from cache
+ *
+ * @example
+ * ```typescript
+ * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+ * if (isCachedData(rewards)) {
+ *   console.log('Serving from cache');
+ * }
+ * ```
+ */
+declare function isCachedData(response: ValidatorRewardsResponse): boolean;
+/**
+ * Check if sync worker is healthy
+ *
+ * @param syncStatus - Sync status response
+ * @param workerName - Worker name to check ('protocol_sync' or 'validator_sync')
+ * @returns True if worker is in success state
+ *
+ * @example
+ * ```typescript
+ * const status = await sdk.analytics.getSyncStatus();
+ * if (isSyncHealthy(status, 'protocol_sync')) {
+ *   console.log('Protocol sync is healthy');
+ * }
+ * ```
+ */
+declare function isSyncHealthy(syncStatus: SyncStatusResponse, workerName?: 'protocol_sync' | 'validator_sync'): boolean;
+/**
+ * Check if sync worker is degraded
+ *
+ * @param syncStatus - Sync status response
+ * @param workerName - Worker name to check
+ * @returns True if worker is in degraded state
+ *
+ * @example
+ * ```typescript
+ * const status = await sdk.analytics.getSyncStatus();
+ * if (isSyncDegraded(status, 'protocol_sync')) {
+ *   console.warn('Protocol sync is degraded, some data may be incomplete');
+ * }
+ * ```
+ */
+declare function isSyncDegraded(syncStatus: SyncStatusResponse, workerName?: 'protocol_sync' | 'validator_sync'): boolean;
+/**
+ * Get sync lag in blocks
+ *
+ * @param syncStatus - Sync status response
+ * @param currentBlock - Current blockchain block number
+ * @param workerName - Worker name to check
+ * @returns Number of blocks behind, or null if unknown
+ *
+ * @example
+ * ```typescript
+ * const status = await sdk.analytics.getSyncStatus();
+ * const currentBlock = await provider.getBlockNumber();
+ * const lag = getSyncLag(status, currentBlock);
+ * if (lag && lag > 100) {
+ *   console.warn(`Analytics is ${lag} blocks behind`);
+ * }
+ * ```
+ */
+declare function getSyncLag(syncStatus: SyncStatusResponse, currentBlock: number, workerName?: 'protocol_sync' | 'validator_sync'): number | null;
+/**
+ * Calculate data freshness score (0-100)
+ *
+ * @param response - Response with metadata
+ * @param currentBlock - Current blockchain block number
+ * @returns Freshness score (100 = perfectly fresh, 0 = very stale)
+ *
+ * @remarks
+ * Score calculation:
+ * - 100: Data is from current block
+ * - 90-99: Data is 1-10 blocks behind
+ * - 50-89: Data is 11-100 blocks behind
+ * - 0-49: Data is >100 blocks behind
+ *
+ * @example
+ * ```typescript
+ * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+ * const currentBlock = await provider.getBlockNumber();
+ * const freshness = getDataFreshness(rewards, currentBlock);
+ *
+ * if (freshness < 50) {
+ *   console.warn('Data is very stale');
+ * } else if (freshness < 90) {
+ *   console.log('Data is slightly behind');
+ * } else {
+ *   console.log('Data is fresh');
+ * }
+ * ```
+ */
+declare function getDataFreshness(response: ValidatorRewardsResponse, currentBlock: number): number;
+/**
+ * Validate pagination options
+ *
+ * @param limit - Limit value
+ * @param offset - Offset value
+ * @throws Error if pagination options are invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validatePagination(50, 0);
+ *   const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50, offset: 0 });
+ * } catch (error) {
+ *   console.error('Invalid pagination:', error.message);
+ * }
+ * ```
+ */
+declare function validatePagination(limit?: number, offset?: number): void;
+/**
+ * Calculate optimal batch size for pagination
+ *
+ * @param totalItems - Total number of items to fetch
+ * @param maxBatchSize - Maximum batch size (default: 100)
+ * @returns Optimal batch size
+ *
+ * @example
+ * ```typescript
+ * const totalStakers = 250;
+ * const batchSize = getOptimalBatchSize(totalStakers);
+ * // Returns 50 (250 / 5 batches)
+ * ```
+ */
+declare function getOptimalBatchSize(totalItems: number, maxBatchSize?: number): number;
+/**
+ * Format large numbers with commas
+ *
+ * @param value - Number or string to format
+ * @returns Formatted string with commas
+ *
+ * @example
+ * ```typescript
+ * const staking = stats.TotalStaking;
+ * console.log(formatNumber(staking)); // "26,883,345,073,055,930,973,683,712"
+ * ```
+ */
+declare function formatNumber(value: string | number): string;
+/**
+ * Convert Wei to Ether string
+ *
+ * @param wei - Wei amount as string
+ * @param decimals - Number of decimal places (default: 4)
+ * @returns Ether amount as string
+ *
+ * @example
+ * ```typescript
+ * const stake = "4000000000000000000000000";
+ * console.log(weiToEther(stake)); // "4000000.0000"
+ * ```
+ */
+declare function weiToEther(wei: string, decimals?: number): string;
+
+/**
+ * Retry Utilities
+ *
+ * Provides retry logic with exponential backoff for handling
+ * transient errors and timeouts.
+ */
+interface RetryOptions {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds between retries
+     * @default 10000
+     */
+    maxDelay?: number;
+    /**
+     * Backoff multiplier for exponential backoff
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Function to determine if error should be retried
+     * @default Retries on timeout and 503 errors
+     */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+    /**
+     * Callback called before each retry
+     */
+    onRetry?: (error: any, attempt: number, delay: number) => void;
+}
+/**
+ * Execute a function with retry logic
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Promise resolving to function result
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => sdk.analytics.getValidatorRewards(address, { limit: 100 }),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelay: 1000,
+ *     onRetry: (error, attempt, delay) => {
+ *       console.log(`Retry attempt ${attempt} after ${delay}ms`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Create a retry wrapper for a function
+ *
+ * @param fn - Function to wrap
+ * @param options - Retry options
+ * @returns Wrapped function with retry logic
+ *
+ * @example
+ * ```typescript
+ * const getRewardsWithRetry = createRetryWrapper(
+ *   (address: string, opts: any) => sdk.analytics.getValidatorRewards(address, opts),
+ *   { maxRetries: 3 }
+ * );
+ *
+ * const rewards = await getRewardsWithRetry(address, { limit: 50 });
+ * ```
+ */
+declare function createRetryWrapper<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+
 /**
  * Resonance Network SDK
  *
@@ -934,4 +1244,4 @@ declare class ResonanceSDK {
     logout(): void;
 }
 
-export { type APIError, type APIResponse, type ActiveValidator, AnalyticsAPI, type AuthResponse, AuthService, type DelegatorDetailResponse, type DelegatorListResponse, type DelegatorReward, type DelegatorRewardsResponse, type DelegatorStakeInfo, type DelegatorStakesResponse, type DelegatorUnbondingResponse, type DelegatorValidatorStake, type DelegatorValidatorsResponse, type DelegatorWithdrawal, type DelegatorWithdrawalsResponse, DelegatorsAPI, type EpochDistribution, type EpochReward, type EpochStakes, type EpochUnclaimed, GlobalAPI, type GlobalNetworkResponse, HTTPClient, type JWTClaims, type LeaderboardDelegatorResponse, type LeaderboardValidatorResponse, type NetworkAPRBreakdownResponse, type NetworkAPRResponse, type PaginationOptions, type ProtocolStats, type QueryParams, type ReferralApplyRequest, type ReferralCreateRequest, type ReferralDelegatorResponse, type ReferralValidateRequest, type ReferralValidateResponse, type ReferralValidatorResponse, ReferralsAPI, ResonanceSDK, type ResponseMetadata, type RewardDTO, type RewardSummary, type SDKConfig, SlashingAPI, type SlashingEventResponse, type StakeDTO, type SyncJobStatus, type SyncStatusResponse, type TopDelegatorRank, type UnbondingInfo, type UnclaimedDelegator, type ValidatorAPRResponse, type ValidatorAnalytics, type ValidatorAnalyticsListResponse, type ValidatorDelegatorsResponse, type ValidatorDetailResponse, type ValidatorEpochResponse, type ValidatorHistoryItem, type ValidatorHistoryResponse, type ValidatorListOptions, type ValidatorListResponse, type ValidatorMetricsResponse, type ValidatorRewardsResponse, type ValidatorStakeBreakdownResponse, type ValidatorWithdrawal, type ValidatorWithdrawalsResponse, ValidatorsAPI, ResonanceSDK as default };
+export { type APIError, type APIResponse, type ActiveValidator, AnalyticsAPI, type AuthResponse, AuthService, type DelegatorDetailResponse, type DelegatorListResponse, type DelegatorReward, type DelegatorRewardsResponse, type DelegatorStakeInfo, type DelegatorStakesResponse, type DelegatorUnbondingResponse, type DelegatorValidatorStake, type DelegatorValidatorsResponse, type DelegatorWithdrawal, type DelegatorWithdrawalsResponse, DelegatorsAPI, type EpochDistribution, type EpochReward, type EpochStakes, type EpochUnclaimed, GlobalAPI, type GlobalNetworkResponse, HTTPClient, type JWTClaims, type LeaderboardDelegatorResponse, type LeaderboardValidatorResponse, type NetworkAPRBreakdownResponse, type NetworkAPRResponse, type PaginationOptions, type ProtocolStats, type QueryParams, type ReferralApplyRequest, type ReferralCreateRequest, type ReferralDelegatorResponse, type ReferralValidateRequest, type ReferralValidateResponse, type ReferralValidatorResponse, ReferralsAPI, ResonanceSDK, type ResponseMetadata, type RetryOptions, type RewardDTO, type RewardSummary, type SDKConfig, SlashingAPI, type SlashingEventResponse, type StakeDTO, type SyncJobStatus, type SyncStatusResponse, type TopDelegatorRank, type UnbondingInfo, type UnclaimedDelegator, type ValidatorAPRResponse, type ValidatorAnalytics, type ValidatorAnalyticsListResponse, type ValidatorDelegatorsResponse, type ValidatorDetailResponse, type ValidatorEpochResponse, type ValidatorHistoryItem, type ValidatorHistoryResponse, type ValidatorListOptions, type ValidatorListResponse, type ValidatorMetricsResponse, type ValidatorRewardsResponse, type ValidatorStakeBreakdownResponse, type ValidatorWithdrawal, type ValidatorWithdrawalsResponse, ValidatorsAPI, createRetryWrapper, ResonanceSDK as default, formatNumber, getDataFreshness, getOptimalBatchSize, getSyncLag, isCachedData, isServiceUnavailable, isStaleData, isSyncDegraded, isSyncHealthy, isTimeout, isValidatorNotFound, validatePagination, weiToEther, withRetry };

package/dist/index.d.ts

@@ -875,6 +875,316 @@ declare class AnalyticsAPI {
     }): Promise<ValidatorRewardsResponse>;
 }
 
+/**
+ * Analytics Helper Utilities
+ *
+ * Provides utility functions for working with analytics data,
+ * including error checking, data validation, and freshness checks.
+ */
+/**
+ * Check if error is a validator not found error
+ *
+ * @param error - Error object to check
+ * @returns True if validator was not found
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const validator = await sdk.analytics.getValidatorAnalytics(address);
+ * } catch (error) {
+ *   if (isValidatorNotFound(error)) {
+ *     console.log('Validator does not exist');
+ *   }
+ * }
+ * ```
+ */
+declare function isValidatorNotFound(error: any): boolean;
+/**
+ * Check if error is a service unavailable error (sync in progress)
+ *
+ * @param error - Error object to check
+ * @returns True if service is temporarily unavailable
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const stats = await sdk.analytics.getProtocolStats();
+ * } catch (error) {
+ *   if (isServiceUnavailable(error)) {
+ *     console.log('Analytics service is syncing, try again later');
+ *   }
+ * }
+ * ```
+ */
+declare function isServiceUnavailable(error: any): boolean;
+/**
+ * Check if error is a timeout error
+ *
+ * @param error - Error object to check
+ * @returns True if request timed out
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 1000 });
+ * } catch (error) {
+ *   if (isTimeout(error)) {
+ *     console.log('Request timed out, try with smaller limit');
+ *   }
+ * }
+ * ```
+ */
+declare function isTimeout(error: any): boolean;
+/**
+ * Check if analytics data is stale
+ *
+ * @param response - Response with metadata
+ * @returns True if data is marked as stale
+ *
+ * @example
+ * ```typescript
+ * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+ * if (isStaleData(rewards)) {
+ *   console.warn('Data may be outdated');
+ * }
+ * ```
+ */
+declare function isStaleData(response: ValidatorRewardsResponse): boolean;
+/**
+ * Check if analytics data is from cache
+ *
+ * @param response - Response with metadata
+ * @returns True if data was served from cache
+ *
+ * @example
+ * ```typescript
+ * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+ * if (isCachedData(rewards)) {
+ *   console.log('Serving from cache');
+ * }
+ * ```
+ */
+declare function isCachedData(response: ValidatorRewardsResponse): boolean;
+/**
+ * Check if sync worker is healthy
+ *
+ * @param syncStatus - Sync status response
+ * @param workerName - Worker name to check ('protocol_sync' or 'validator_sync')
+ * @returns True if worker is in success state
+ *
+ * @example
+ * ```typescript
+ * const status = await sdk.analytics.getSyncStatus();
+ * if (isSyncHealthy(status, 'protocol_sync')) {
+ *   console.log('Protocol sync is healthy');
+ * }
+ * ```
+ */
+declare function isSyncHealthy(syncStatus: SyncStatusResponse, workerName?: 'protocol_sync' | 'validator_sync'): boolean;
+/**
+ * Check if sync worker is degraded
+ *
+ * @param syncStatus - Sync status response
+ * @param workerName - Worker name to check
+ * @returns True if worker is in degraded state
+ *
+ * @example
+ * ```typescript
+ * const status = await sdk.analytics.getSyncStatus();
+ * if (isSyncDegraded(status, 'protocol_sync')) {
+ *   console.warn('Protocol sync is degraded, some data may be incomplete');
+ * }
+ * ```
+ */
+declare function isSyncDegraded(syncStatus: SyncStatusResponse, workerName?: 'protocol_sync' | 'validator_sync'): boolean;
+/**
+ * Get sync lag in blocks
+ *
+ * @param syncStatus - Sync status response
+ * @param currentBlock - Current blockchain block number
+ * @param workerName - Worker name to check
+ * @returns Number of blocks behind, or null if unknown
+ *
+ * @example
+ * ```typescript
+ * const status = await sdk.analytics.getSyncStatus();
+ * const currentBlock = await provider.getBlockNumber();
+ * const lag = getSyncLag(status, currentBlock);
+ * if (lag && lag > 100) {
+ *   console.warn(`Analytics is ${lag} blocks behind`);
+ * }
+ * ```
+ */
+declare function getSyncLag(syncStatus: SyncStatusResponse, currentBlock: number, workerName?: 'protocol_sync' | 'validator_sync'): number | null;
+/**
+ * Calculate data freshness score (0-100)
+ *
+ * @param response - Response with metadata
+ * @param currentBlock - Current blockchain block number
+ * @returns Freshness score (100 = perfectly fresh, 0 = very stale)
+ *
+ * @remarks
+ * Score calculation:
+ * - 100: Data is from current block
+ * - 90-99: Data is 1-10 blocks behind
+ * - 50-89: Data is 11-100 blocks behind
+ * - 0-49: Data is >100 blocks behind
+ *
+ * @example
+ * ```typescript
+ * const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50 });
+ * const currentBlock = await provider.getBlockNumber();
+ * const freshness = getDataFreshness(rewards, currentBlock);
+ *
+ * if (freshness < 50) {
+ *   console.warn('Data is very stale');
+ * } else if (freshness < 90) {
+ *   console.log('Data is slightly behind');
+ * } else {
+ *   console.log('Data is fresh');
+ * }
+ * ```
+ */
+declare function getDataFreshness(response: ValidatorRewardsResponse, currentBlock: number): number;
+/**
+ * Validate pagination options
+ *
+ * @param limit - Limit value
+ * @param offset - Offset value
+ * @throws Error if pagination options are invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validatePagination(50, 0);
+ *   const rewards = await sdk.analytics.getValidatorRewards(address, { limit: 50, offset: 0 });
+ * } catch (error) {
+ *   console.error('Invalid pagination:', error.message);
+ * }
+ * ```
+ */
+declare function validatePagination(limit?: number, offset?: number): void;
+/**
+ * Calculate optimal batch size for pagination
+ *
+ * @param totalItems - Total number of items to fetch
+ * @param maxBatchSize - Maximum batch size (default: 100)
+ * @returns Optimal batch size
+ *
+ * @example
+ * ```typescript
+ * const totalStakers = 250;
+ * const batchSize = getOptimalBatchSize(totalStakers);
+ * // Returns 50 (250 / 5 batches)
+ * ```
+ */
+declare function getOptimalBatchSize(totalItems: number, maxBatchSize?: number): number;
+/**
+ * Format large numbers with commas
+ *
+ * @param value - Number or string to format
+ * @returns Formatted string with commas
+ *
+ * @example
+ * ```typescript
+ * const staking = stats.TotalStaking;
+ * console.log(formatNumber(staking)); // "26,883,345,073,055,930,973,683,712"
+ * ```
+ */
+declare function formatNumber(value: string | number): string;
+/**
+ * Convert Wei to Ether string
+ *
+ * @param wei - Wei amount as string
+ * @param decimals - Number of decimal places (default: 4)
+ * @returns Ether amount as string
+ *
+ * @example
+ * ```typescript
+ * const stake = "4000000000000000000000000";
+ * console.log(weiToEther(stake)); // "4000000.0000"
+ * ```
+ */
+declare function weiToEther(wei: string, decimals?: number): string;
+
+/**
+ * Retry Utilities
+ *
+ * Provides retry logic with exponential backoff for handling
+ * transient errors and timeouts.
+ */
+interface RetryOptions {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds between retries
+     * @default 10000
+     */
+    maxDelay?: number;
+    /**
+     * Backoff multiplier for exponential backoff
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Function to determine if error should be retried
+     * @default Retries on timeout and 503 errors
+     */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+    /**
+     * Callback called before each retry
+     */
+    onRetry?: (error: any, attempt: number, delay: number) => void;
+}
+/**
+ * Execute a function with retry logic
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Promise resolving to function result
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => sdk.analytics.getValidatorRewards(address, { limit: 100 }),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelay: 1000,
+ *     onRetry: (error, attempt, delay) => {
+ *       console.log(`Retry attempt ${attempt} after ${delay}ms`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Create a retry wrapper for a function
+ *
+ * @param fn - Function to wrap
+ * @param options - Retry options
+ * @returns Wrapped function with retry logic
+ *
+ * @example
+ * ```typescript
+ * const getRewardsWithRetry = createRetryWrapper(
+ *   (address: string, opts: any) => sdk.analytics.getValidatorRewards(address, opts),
+ *   { maxRetries: 3 }
+ * );
+ *
+ * const rewards = await getRewardsWithRetry(address, { limit: 50 });
+ * ```
+ */
+declare function createRetryWrapper<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+
 /**
  * Resonance Network SDK
  *
@@ -934,4 +1244,4 @@ declare class ResonanceSDK {
     logout(): void;
 }
 
-export { type APIError, type APIResponse, type ActiveValidator, AnalyticsAPI, type AuthResponse, AuthService, type DelegatorDetailResponse, type DelegatorListResponse, type DelegatorReward, type DelegatorRewardsResponse, type DelegatorStakeInfo, type DelegatorStakesResponse, type DelegatorUnbondingResponse, type DelegatorValidatorStake, type DelegatorValidatorsResponse, type DelegatorWithdrawal, type DelegatorWithdrawalsResponse, DelegatorsAPI, type EpochDistribution, type EpochReward, type EpochStakes, type EpochUnclaimed, GlobalAPI, type GlobalNetworkResponse, HTTPClient, type JWTClaims, type LeaderboardDelegatorResponse, type LeaderboardValidatorResponse, type NetworkAPRBreakdownResponse, type NetworkAPRResponse, type PaginationOptions, type ProtocolStats, type QueryParams, type ReferralApplyRequest, type ReferralCreateRequest, type ReferralDelegatorResponse, type ReferralValidateRequest, type ReferralValidateResponse, type ReferralValidatorResponse, ReferralsAPI, ResonanceSDK, type ResponseMetadata, type RewardDTO, type RewardSummary, type SDKConfig, SlashingAPI, type SlashingEventResponse, type StakeDTO, type SyncJobStatus, type SyncStatusResponse, type TopDelegatorRank, type UnbondingInfo, type UnclaimedDelegator, type ValidatorAPRResponse, type ValidatorAnalytics, type ValidatorAnalyticsListResponse, type ValidatorDelegatorsResponse, type ValidatorDetailResponse, type ValidatorEpochResponse, type ValidatorHistoryItem, type ValidatorHistoryResponse, type ValidatorListOptions, type ValidatorListResponse, type ValidatorMetricsResponse, type ValidatorRewardsResponse, type ValidatorStakeBreakdownResponse, type ValidatorWithdrawal, type ValidatorWithdrawalsResponse, ValidatorsAPI, ResonanceSDK as default };
+export { type APIError, type APIResponse, type ActiveValidator, AnalyticsAPI, type AuthResponse, AuthService, type DelegatorDetailResponse, type DelegatorListResponse, type DelegatorReward, type DelegatorRewardsResponse, type DelegatorStakeInfo, type DelegatorStakesResponse, type DelegatorUnbondingResponse, type DelegatorValidatorStake, type DelegatorValidatorsResponse, type DelegatorWithdrawal, type DelegatorWithdrawalsResponse, DelegatorsAPI, type EpochDistribution, type EpochReward, type EpochStakes, type EpochUnclaimed, GlobalAPI, type GlobalNetworkResponse, HTTPClient, type JWTClaims, type LeaderboardDelegatorResponse, type LeaderboardValidatorResponse, type NetworkAPRBreakdownResponse, type NetworkAPRResponse, type PaginationOptions, type ProtocolStats, type QueryParams, type ReferralApplyRequest, type ReferralCreateRequest, type ReferralDelegatorResponse, type ReferralValidateRequest, type ReferralValidateResponse, type ReferralValidatorResponse, ReferralsAPI, ResonanceSDK, type ResponseMetadata, type RetryOptions, type RewardDTO, type RewardSummary, type SDKConfig, SlashingAPI, type SlashingEventResponse, type StakeDTO, type SyncJobStatus, type SyncStatusResponse, type TopDelegatorRank, type UnbondingInfo, type UnclaimedDelegator, type ValidatorAPRResponse, type ValidatorAnalytics, type ValidatorAnalyticsListResponse, type ValidatorDelegatorsResponse, type ValidatorDetailResponse, type ValidatorEpochResponse, type ValidatorHistoryItem, type ValidatorHistoryResponse, type ValidatorListOptions, type ValidatorListResponse, type ValidatorMetricsResponse, type ValidatorRewardsResponse, type ValidatorStakeBreakdownResponse, type ValidatorWithdrawal, type ValidatorWithdrawalsResponse, ValidatorsAPI, createRetryWrapper, ResonanceSDK as default, formatNumber, getDataFreshness, getOptimalBatchSize, getSyncLag, isCachedData, isServiceUnavailable, isStaleData, isSyncDegraded, isSyncHealthy, isTimeout, isValidatorNotFound, validatePagination, weiToEther, withRetry };

package/dist/index.js

@@ -29,7 +29,22 @@ __export(index_exports, {
   ResonanceSDK: () => ResonanceSDK,
   SlashingAPI: () => SlashingAPI,
   ValidatorsAPI: () => ValidatorsAPI,
-  default: () => index_default
+  createRetryWrapper: () => createRetryWrapper,
+  default: () => index_default,
+  formatNumber: () => formatNumber,
+  getDataFreshness: () => getDataFreshness,
+  getOptimalBatchSize: () => getOptimalBatchSize,
+  getSyncLag: () => getSyncLag,
+  isCachedData: () => isCachedData,
+  isServiceUnavailable: () => isServiceUnavailable,
+  isStaleData: () => isStaleData,
+  isSyncDegraded: () => isSyncDegraded,
+  isSyncHealthy: () => isSyncHealthy,
+  isTimeout: () => isTimeout,
+  isValidatorNotFound: () => isValidatorNotFound,
+  validatePagination: () => validatePagination,
+  weiToEther: () => weiToEther,
+  withRetry: () => withRetry
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -927,6 +942,120 @@ var AnalyticsAPI = class {
   }
 };
 
+// src/utils/analytics-helpers.ts
+function isValidatorNotFound(error) {
+  return error instanceof ResonanceAPIError && error.statusCode === 404;
+}
+function isServiceUnavailable(error) {
+  return error instanceof ResonanceAPIError && error.statusCode === 503;
+}
+function isTimeout(error) {
+  return error instanceof Error && error.message.includes("timeout");
+}
+function isStaleData(response) {
+  return response.metadata?.stale === true;
+}
+function isCachedData(response) {
+  return response.metadata?.cached === true;
+}
+function isSyncHealthy(syncStatus, workerName = "protocol_sync") {
+  const worker = syncStatus[workerName];
+  return worker?.status === "success";
+}
+function isSyncDegraded(syncStatus, workerName = "protocol_sync") {
+  const worker = syncStatus[workerName];
+  return worker?.status === "degraded";
+}
+function getSyncLag(syncStatus, currentBlock, workerName = "protocol_sync") {
+  const worker = syncStatus[workerName];
+  if (!worker?.last_block) return null;
+  return currentBlock - worker.last_block;
+}
+function getDataFreshness(response, currentBlock) {
+  const subgraphBlock = response.metadata?.subgraph_block;
+  if (!subgraphBlock) return 0;
+  const blocksBehind = currentBlock - subgraphBlock;
+  if (blocksBehind <= 0) return 100;
+  if (blocksBehind <= 10) return 100 - blocksBehind;
+  if (blocksBehind <= 100) return 90 - Math.floor((blocksBehind - 10) * 0.44);
+  return Math.max(0, 50 - Math.floor((blocksBehind - 100) * 0.5));
+}
+function validatePagination(limit, offset) {
+  if (limit !== void 0 && (limit <= 0 || limit > 1e3)) {
+    throw new Error("Limit must be between 1 and 1000");
+  }
+  if (offset !== void 0 && offset < 0) {
+    throw new Error("Offset must be non-negative");
+  }
+}
+function getOptimalBatchSize(totalItems, maxBatchSize = 100) {
+  if (totalItems <= maxBatchSize) return totalItems;
+  const targetBatches = 7;
+  const calculatedSize = Math.ceil(totalItems / targetBatches);
+  return Math.min(calculatedSize, maxBatchSize);
+}
+function formatNumber(value) {
+  const num = typeof value === "string" ? value : value.toString();
+  return num.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function weiToEther(wei, decimals = 4) {
+  const weiNum = BigInt(wei);
+  const etherNum = Number(weiNum) / 1e18;
+  return etherNum.toFixed(decimals);
+}
+
+// src/utils/retry.ts
+function defaultShouldRetry(error, attempt) {
+  if (attempt >= 3) return false;
+  if (error instanceof Error && error.message.includes("timeout")) {
+    return true;
+  }
+  if (error.statusCode === 503) {
+    return true;
+  }
+  if (error instanceof Error && error.message.includes("fetch failed")) {
+    return true;
+  }
+  return false;
+}
+async function withRetry(fn, options = {}) {
+  const {
+    maxRetries = 3,
+    initialDelay = 1e3,
+    maxDelay = 1e4,
+    backoffMultiplier = 2,
+    shouldRetry = defaultShouldRetry,
+    onRetry
+  } = options;
+  let lastError;
+  let delay = initialDelay;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries && shouldRetry(error, attempt)) {
+        if (onRetry) {
+          onRetry(error, attempt + 1, delay);
+        }
+        await sleep(delay);
+        delay = Math.min(delay * backoffMultiplier, maxDelay);
+      } else {
+        throw error;
+      }
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createRetryWrapper(fn, options = {}) {
+  return ((...args) => {
+    return withRetry(() => fn(...args), options);
+  });
+}
+
 // src/index.ts
 var ResonanceSDK = class {
   constructor(config) {
@@ -985,5 +1114,20 @@ var index_default = ResonanceSDK;
   ReferralsAPI,
   ResonanceSDK,
   SlashingAPI,
-  ValidatorsAPI
+  ValidatorsAPI,
+  createRetryWrapper,
+  formatNumber,
+  getDataFreshness,
+  getOptimalBatchSize,
+  getSyncLag,
+  isCachedData,
+  isServiceUnavailable,
+  isStaleData,
+  isSyncDegraded,
+  isSyncHealthy,
+  isTimeout,
+  isValidatorNotFound,
+  validatePagination,
+  weiToEther,
+  withRetry
 });

package/dist/index.mjs

@@ -892,6 +892,120 @@ var AnalyticsAPI = class {
   }
 };
 
+// src/utils/analytics-helpers.ts
+function isValidatorNotFound(error) {
+  return error instanceof ResonanceAPIError && error.statusCode === 404;
+}
+function isServiceUnavailable(error) {
+  return error instanceof ResonanceAPIError && error.statusCode === 503;
+}
+function isTimeout(error) {
+  return error instanceof Error && error.message.includes("timeout");
+}
+function isStaleData(response) {
+  return response.metadata?.stale === true;
+}
+function isCachedData(response) {
+  return response.metadata?.cached === true;
+}
+function isSyncHealthy(syncStatus, workerName = "protocol_sync") {
+  const worker = syncStatus[workerName];
+  return worker?.status === "success";
+}
+function isSyncDegraded(syncStatus, workerName = "protocol_sync") {
+  const worker = syncStatus[workerName];
+  return worker?.status === "degraded";
+}
+function getSyncLag(syncStatus, currentBlock, workerName = "protocol_sync") {
+  const worker = syncStatus[workerName];
+  if (!worker?.last_block) return null;
+  return currentBlock - worker.last_block;
+}
+function getDataFreshness(response, currentBlock) {
+  const subgraphBlock = response.metadata?.subgraph_block;
+  if (!subgraphBlock) return 0;
+  const blocksBehind = currentBlock - subgraphBlock;
+  if (blocksBehind <= 0) return 100;
+  if (blocksBehind <= 10) return 100 - blocksBehind;
+  if (blocksBehind <= 100) return 90 - Math.floor((blocksBehind - 10) * 0.44);
+  return Math.max(0, 50 - Math.floor((blocksBehind - 100) * 0.5));
+}
+function validatePagination(limit, offset) {
+  if (limit !== void 0 && (limit <= 0 || limit > 1e3)) {
+    throw new Error("Limit must be between 1 and 1000");
+  }
+  if (offset !== void 0 && offset < 0) {
+    throw new Error("Offset must be non-negative");
+  }
+}
+function getOptimalBatchSize(totalItems, maxBatchSize = 100) {
+  if (totalItems <= maxBatchSize) return totalItems;
+  const targetBatches = 7;
+  const calculatedSize = Math.ceil(totalItems / targetBatches);
+  return Math.min(calculatedSize, maxBatchSize);
+}
+function formatNumber(value) {
+  const num = typeof value === "string" ? value : value.toString();
+  return num.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function weiToEther(wei, decimals = 4) {
+  const weiNum = BigInt(wei);
+  const etherNum = Number(weiNum) / 1e18;
+  return etherNum.toFixed(decimals);
+}
+
+// src/utils/retry.ts
+function defaultShouldRetry(error, attempt) {
+  if (attempt >= 3) return false;
+  if (error instanceof Error && error.message.includes("timeout")) {
+    return true;
+  }
+  if (error.statusCode === 503) {
+    return true;
+  }
+  if (error instanceof Error && error.message.includes("fetch failed")) {
+    return true;
+  }
+  return false;
+}
+async function withRetry(fn, options = {}) {
+  const {
+    maxRetries = 3,
+    initialDelay = 1e3,
+    maxDelay = 1e4,
+    backoffMultiplier = 2,
+    shouldRetry = defaultShouldRetry,
+    onRetry
+  } = options;
+  let lastError;
+  let delay = initialDelay;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries && shouldRetry(error, attempt)) {
+        if (onRetry) {
+          onRetry(error, attempt + 1, delay);
+        }
+        await sleep(delay);
+        delay = Math.min(delay * backoffMultiplier, maxDelay);
+      } else {
+        throw error;
+      }
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createRetryWrapper(fn, options = {}) {
+  return ((...args) => {
+    return withRetry(() => fn(...args), options);
+  });
+}
+
 // src/index.ts
 var ResonanceSDK = class {
   constructor(config) {
@@ -950,5 +1064,20 @@ export {
   ResonanceSDK,
   SlashingAPI,
   ValidatorsAPI,
-  index_default as default
+  createRetryWrapper,
+  index_default as default,
+  formatNumber,
+  getDataFreshness,
+  getOptimalBatchSize,
+  getSyncLag,
+  isCachedData,
+  isServiceUnavailable,
+  isStaleData,
+  isSyncDegraded,
+  isSyncHealthy,
+  isTimeout,
+  isValidatorNotFound,
+  validatePagination,
+  weiToEther,
+  withRetry
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fenelabs/fene-sdk",
-  "version": "0.2.0",
-  "description": "Resonance Network SDK for TypeScript/JavaScript - Official SDK for interacting with Resonance FPoS blockchain",
+  "version": "0.3.2",
+  "description": "Fene Network SDK for interacting with Resonance FPoS blockchain",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -44,18 +44,21 @@
     "web3",
     "validator",
     "delegator",
+    "dpos",
+    "organization",
+    "politics",
     "typescript"
   ],
   "author": "avenbreaks",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/avenbreaks/resonance-sdk.git"
+    "url": "https://github.com/fenelabs/fene-sdk"
   },
   "bugs": {
-    "url": "https://github.com/avenbreaks/resonance-sdk/issues"
+    "url": "https://github.com/fenelabs/fene-sdk/issues"
   },
-  "homepage": "https://github.com/avenbreaks/resonance-sdk#readme",
+  "homepage": "https://github.com/fenelabs/fene-sdk#readme",
   "publishConfig": {
     "access": "public"
   },