@gala-chain/launchpad-sdk 8.0.2 → 9.0.0-rc.0

package/dist/services/DexService.d.ts

@@ -1,440 +0,0 @@
-/**
- * DEX API Service
- *
- * This service handles DEX API spot price operations for tokens.
- * It provides methods to fetch current USD spot prices for DEX tokens
- * and calculate spot prices for launchpad tokens.
- */
-import type { TokenId } from '../types/common';
-import type { DexAggregatedVolumeSummary, DexSeason, GalaChainTokenDetails, LeaderboardResult, TokenSpotPrice } from '../types/launchpad.dto';
-import type { AmountCalculationResult } from '../types/launchpad.dto';
-import type { CalculateBuyAmountOptions, FetchTokenSpotPriceParams } from '../types/options.dto';
-import type { HttpClient } from '../utils/http';
-import { LoggerBase } from './BaseService';
-import type { GalaChainService } from './GalaChainService';
-import type { TokenMetadataCache } from './TokenMetadataCache';
-/**
- * DexService handles DEX API spot price operations
- *
- * This service provides access to token pricing information from the DEX API.
- * It supports both single and multiple token price queries, as well as
- * calculated spot prices for launchpad tokens.
- *
- * ## Caching Strategy
- * Optional TokenMetadataCache for symbol caching. When provided, DexService will:
- * - Check cache for token symbols before fetching from API
- * - Cache symbols after successful API fetch
- * - Reduces API calls by 50% on repeated token symbol queries
- *
- * @category Services
- * @since 1.0.0
- */
-export declare class DexService extends LoggerBase {
-    private readonly dexBackendHttp?;
-    private readonly cache?;
-    private readonly galaChainService?;
-    constructor(dexBackendHttp?: HttpClient | undefined, cache?: TokenMetadataCache | undefined, galaChainService?: GalaChainService | undefined, debugMode?: boolean);
-    /**
-     * Fetch USD spot price for DEX tokens with tokenId
-     *
-     * Smart router that accepts either tokenName or tokenId (mutually exclusive).
-     * LaunchpadSDK handles routing logic automatically:
-     * - tokenName: Routes to bonding curve calculation (launchpad tokens)
-     * - tokenId: Routes to DEX Backend API (graduated/DEX tokens)
-     *
-     * **Price Source:**
-     * - DEX Backend API `/market/price` endpoint (keyed by symbol)
-     * - Real-time spot prices from active DEX trading
-     * - USD-denominated pricing (via GALA/USD base pair)
-     *
-     * **Token Format Support:**
-     * - Pipe-delimited: `Token|Unit|GDOG|eth:0x...`
-     * - Object format: `{ collection: 'Token', category: 'Unit', type: 'GDOG', additionalKey: 'eth:0x...' }`
-     * - Auto-converts to dollar-delimited for API: `Token$Unit$GDOG$eth:0x...`
-     *
-     * @param params Options with either tokenName or tokenId (mutually exclusive)
-     * @returns Promise<TokenSpotPrice> Token symbol and USD price
-     * @throws ValidationError if neither tokenName nor tokenId provided
-     * @throws ValidationError if both tokenName and tokenId provided
-     * @throws NetworkError if API request fails
-     * @category Spot Price
-     * @since 3.0.0
-     *
-     * @example DEX token pricing (tokenId)
-     * ```typescript
-     * const price = await dexService.fetchTokenPrice({
-     *   tokenId: 'Token|Unit|GDOG|eth:0x...'
-     * });
-     * console.log(`${price.symbol}: $${price.price}`);
-     * // Output: GDOG: $0.00123
-     * ```
-     *
-     * @example Object format tokenId
-     * ```typescript
-     * const price = await dexService.fetchTokenPrice({
-     *   tokenId: {
-     *     collection: 'Token',
-     *     category: 'Unit',
-     *     type: 'BENE',
-     *     additionalKey: 'client:123'
-     *   }
-     * });
-     * ```
-     *
-     * @internal
-     */
-    fetchTokenPrice(params: FetchTokenSpotPriceParams): Promise<TokenSpotPrice>;
-    /**
-     * Resolve a token's symbol from the token metadata cache or the GalaChain token class.
-     * Never derives a symbol from the class key; throws if neither source has it.
-     * @private
-     */
-    private resolveAuthoritativeSymbol;
-    /**
-     * Internal method: Fetch spot price from DEX Backend API
-     *
-     * Queries the DEX Backend API for real-time spot prices of tokens actively
-     * trading on GalaSwap. Includes intelligent caching for token symbols to reduce
-     * API calls by 50% on repeated queries.
-     *
-     * **Price Calculation:**
-     * - Fetches token/GALA pair price from DEX
-     * - Converts to USD using GALA/USD base rate
-     * - Returns final USD-denominated price
-     *
-     * **Symbol Resolution:**
-     * 1. Check TokenMetadataCache (if available) - instant
-     * 2. Fetch from GalaChain token registry - authoritative
-     * There is no key-parsing fallback: a class key carries no symbol, so a token whose
-     * symbol cannot be resolved fails loudly.
-     *
-     * **Caching Strategy:**
-     * - Cache hit: Symbol returned instantly (no API call)
-     * - Cache miss: Fetch from GalaChain, cache for future queries
-     * - 50% reduction in API calls for repeated token queries
-     *
-     * @internal
-     * @param tokenId Token ID in pipe-delimited or object format
-     * @returns Promise<TokenSpotPrice> Spot price with symbol and USD price
-     * @throws NetworkError if token not found on DEX
-     * @throws NetworkError if API request fails
-     * @category Spot Price
-     * @since 3.0.0
-     */
-    private _fetchDexTokenSpotPrice;
-    /**
-     * Calculate spot price for a launchpad token using bonding curve mathematics
-     *
-     * Computes USD spot price for active bonding curve tokens by:
-     * 1. Calculating tokens received for 1 GALA (bonding curve)
-     * 2. Fetching GALA/USD spot price (DEX)
-     * 3. Computing token/USD price (GALA price ÷ tokens per GALA)
-     *
-     * **Graduation Detection:**
-     * - If token is graduated (saleStatus = 'Finished'), routes to DEX spot price
-     * - If token is active bonding curve, uses calculation above
-     * - Automatic routing ensures correct price source
-     *
-     * **Bonding Curve Pricing:**
-     * Uses exponential bonding curve: price = e^(k × supply)
-     * - Current supply determines current price point on curve
-     * - Higher supply = higher price (built-in scarcity)
-     * - 1 GALA buys fewer tokens as supply grows
-     *
-     * @param tokenName Launchpad token name (e.g., 'anime', 'demonkpop')
-     * @param calculateBuyAmount Callback to calculate buy amount via bonding curve
-     * @param fetchPoolDetails Optional callback to check graduation status
-     * @returns Promise<TokenSpotPrice> Token symbol and USD spot price
-     * @throws NetworkError if calculation fails
-     * @throws ValidationError if token name is invalid
-     * @category Spot Price
-     * @since 2.0.0
-     * @internal
-     */
-    fetchLaunchpadTokenSpotPrice(tokenName: string, calculateBuyAmount: (options: CalculateBuyAmountOptions) => Promise<AmountCalculationResult>, fetchPoolDetails?: (tokenName: string) => Promise<unknown>): Promise<TokenSpotPrice>;
-    /**
-     * Fetch comprehensive token details from GalaChain
-     *
-     * Queries the authoritative GalaChain token registry via FetchTokenClasses endpoint
-     * to retrieve complete token metadata including symbol, decimals, name, image,
-     * description, and blockchain-specific information.
-     *
-     * This method serves as the source of truth for token metadata by using the native
-     * GalaChain API instead of a secondary DEX index. This ensures:
-     * - Complete metadata for all tokens (including native GALA token)
-     * - Direct blockchain source of truth
-     * - Support for both native tokens and wrapped DEX tokens
-     *
-     * @param tokenId Token identifier (flexible format: string or object)
-     * @returns Promise<GalaChainTokenDetails> Token metadata from GalaChain
-     *
-     * @example String format
-     * ```typescript
-     * const details = await dexService.fetchTokenDetails('Token|Unit|BENE|client:xxxx');
-     * console.log(details.symbol);    // 'BENE'
-     *
-     * // Also works for native OG coins
-     * const gala = await dexService.fetchTokenDetails('GALA|Unit|none|none');
-     * console.log(gala.symbol);       // 'GALA'
-     * const gusdc = await dexService.fetchTokenDetails('GUSDC|Unit|none|none');
-     * console.log(gusdc.symbol);      // 'GUSDC'
-     * ```
-     *
-     * @example Object format
-     * ```typescript
-     * const details = await dexService.fetchTokenDetails({
-     *   collection: 'GUSDC',
-     *   category: 'Unit',
-     *   type: 'none',
-     *   additionalKey: 'none'
-     * });
-     * ```
-     *
-     * @throws ValidationError if tokenId format is invalid
-     * @throws NetworkError if API request fails or token not found
-     */
-    fetchTokenDetails(tokenId: TokenId): Promise<GalaChainTokenDetails>;
-    /**
-     * Fetch all available DEX leaderboard seasons
-     *
-     * Retrieves complete list of competitive trading seasons with their time ranges
-     * and rule configurations. Use season IDs with `fetchDexLeaderboardBySeasonId()`
-     * to query rankings.
-     *
-     * **Season Structure:**
-     * - id: Unique season identifier (used for queries)
-     * - name: Display name (e.g., "Season 1", "Winter 2025")
-     * - start: Season start date (Date object)
-     * - end: Season end date (Date object)
-     * - rulesId: Rule set identifier (scoring multipliers, XP rates)
-     *
-     * **Response Handling:**
-     * Supports multiple API response formats:
-     * - Direct array: `[...seasons...]`
-     * - Wrapped: `{ data: [...seasons...] }`
-     * - Nested: `{ data: { seasons: [...] } }`
-     *
-     * @returns Promise<DexSeason[]> Array of all seasons with time ranges
-     * @throws NetworkError If API request fails
-     * @category DEX Leaderboard
-     * @since 3.23.0
-     *
-     * @example List all seasons
-     * ```typescript
-     * const seasons = await dexService.fetchAllDexSeasons();
-     * seasons.forEach(season => {
-     *   console.log(`${season.name}: ${season.start.toISOString()} - ${season.end.toISOString()}`);
-     * });
-     * // Output:
-     * // Season 1: 2025-01-01T00:00:00Z - 2025-03-31T23:59:59Z
-     * // Season 2: 2025-04-01T00:00:00Z - 2025-06-30T23:59:59Z
-     * ```
-     *
-     * @example Find specific season by name
-     * ```typescript
-     * const seasons = await dexService.fetchAllDexSeasons();
-     * const winterSeason = seasons.find(s => s.name.includes('Winter'));
-     * if (winterSeason) {
-     *   const leaderboard = await dexService.fetchDexLeaderboardBySeasonId(winterSeason.id);
-     * }
-     * ```
-     *
-     * @internal
-     */
-    fetchAllDexSeasons(): Promise<DexSeason[]>;
-    /**
-     * Find the currently active DEX leaderboard season
-     *
-     * Determines which season is active by comparing current time with season start/end dates.
-     * Returns null if no season is currently active (between seasons or before first season).
-     *
-     * **Active Season Detection:**
-     * - Fetches all seasons via `fetchAllDexSeasons()`
-     * - Finds season where: `now >= season.start && now <= season.end`
-     * - Returns first matching season (should only be one)
-     * - Returns null if no match found
-     *
-     * **Use Cases:**
-     * - Display current leaderboard automatically
-     * - Show "No active season" message when null
-     * - Redirect users to current competition rankings
-     *
-     * @returns Promise<DexSeason | null> Current season or null if none active
-     * @throws NetworkError If API request fails
-     * @category DEX Leaderboard
-     * @since 3.23.0
-     *
-     * @example Get current season and leaderboard
-     * ```typescript
-     * const currentSeason = await dexService.fetchCurrentDexSeason();
-     * if (currentSeason) {
-     *   console.log(`Active season: ${currentSeason.name}`);
-     *   const leaderboard = await dexService.fetchDexLeaderboardBySeasonId(currentSeason.id);
-     *   console.log(`Top trader: ${leaderboard.entries[0].wallet} with ${leaderboard.entries[0].totalXp} XP`);
-     * } else {
-     *   console.log('No active season - check back later!');
-     * }
-     * ```
-     *
-     * @internal
-     */
-    fetchCurrentDexSeason(): Promise<DexSeason | null>;
-    /**
-     * Fetch DEX leaderboard for a specific season
-     *
-     * Returns complete leaderboard rankings with XP metrics, achievement titles, and
-     * reward distribution percentages. Non-paginated response includes all entries
-     * (typically 100-200 participants).
-     *
-     * **Leaderboard Entry Structure:**
-     * - wallet: Participant wallet address (eth|0x...)
-     * - rank: Position (1 = top trader, 2 = second, etc.)
-     * - totalXp: Cumulative XP earned this season
-     * - distributionPercent: Share of prize pool (0-100)
-     * - liquidityXp: XP from providing liquidity
-     * - tradingXp: XP from trading actions
-     * - masteryTitles: Achievement badges (e.g., "Volume Master", "LP Whale")
-     *
-     * **XP Calculation (Standard Rules):**
-     * - Buy token: +10 XP per GALA spent
-     * - Sell token: +5 XP per GALA received
-     * - DEX swap: +1 XP per $1 USD volume
-     * - Add liquidity: +bonus XP based on pool tier and size
-     * - Hold liquidity: +passive XP over time
-     *
-     * **Mastery Titles:**
-     * - Type: 'liquidity' (LP achievements) or 'trade' (trading achievements)
-     * - Order: Priority for display (lower = more prestigious)
-     * - Example titles: "Liquidity Legend", "Volume King", "Diamond Hands"
-     *
-     * @param seasonId Season identifier number (must be positive integer)
-     * @returns Promise<LeaderboardResult> Complete leaderboard with rankings and metrics
-     * @throws RequiredFieldError If seasonId is invalid
-     * @throws NetworkError If API request fails
-     * @category DEX Leaderboard
-     * @since 3.23.0
-     *
-     * @example Fetch season 3 leaderboard
-     * ```typescript
-     * const leaderboard = await dexService.fetchDexLeaderboardBySeasonId(3);
-     * console.log(`Season ${leaderboard.seasonId} - ${leaderboard.totalEntries} traders`);
-     *
-     * // Display top 5
-     * leaderboard.entries.slice(0, 5).forEach(entry => {
-     *   console.log(`#${entry.rank}: ${entry.wallet} - ${entry.totalXp} XP (${entry.distributionPercent}% rewards)`);
-     *   entry.masteryTitles.forEach(title => console.log(`  🏆 ${title.name}`));
-     * });
-     * ```
-     *
-     * @example Find your rank
-     * ```typescript
-     * const myWallet = 'eth|0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb';
-     * const leaderboard = await dexService.fetchDexLeaderboardBySeasonId(3);
-     * const myEntry = leaderboard.entries.find(e => e.wallet === myWallet);
-     *
-     * if (myEntry) {
-     *   console.log(`Your rank: #${myEntry.rank}`);
-     *   console.log(`Your XP: ${myEntry.totalXp} (Trading: ${myEntry.tradingXp}, LP: ${myEntry.liquidityXp})`);
-     *   console.log(`Reward share: ${myEntry.distributionPercent}%`);
-     * } else {
-     *   console.log('Not ranked this season - start trading!');
-     * }
-     * ```
-     *
-     * @internal
-     */
-    fetchDexLeaderboardBySeasonId(seasonId: number): Promise<LeaderboardResult>;
-    /**
-     * Fetch leaderboard for the currently active season
-     *
-     * Convenience method combining `fetchCurrentDexSeason()` and `fetchDexLeaderboardBySeasonId()`.
-     * Automatically detects the current season and fetches its leaderboard. Returns null if no
-     * season is active (between seasons).
-     *
-     * **Use Cases:**
-     * - Display current leaderboard without knowing season ID
-     * - Homepage "Current Rankings" widget
-     * - "Live Competition" page
-     *
-     * **Workflow:**
-     * 1. Fetch all seasons → find active season by date
-     * 2. If active season found → fetch its leaderboard
-     * 3. If no active season → return null
-     *
-     * @returns Promise<LeaderboardResult | null> Current leaderboard or null if no active season
-     * @throws NetworkError If API request fails
-     * @category DEX Leaderboard
-     * @since 3.23.0
-     *
-     * @example Display current leaderboard
-     * ```typescript
-     * const currentLeaderboard = await dexService.fetchCurrentDexLeaderboard();
-     * if (currentLeaderboard) {
-     *   console.log(`Season ${currentLeaderboard.seasonId} Rankings:`);
-     *   currentLeaderboard.entries.slice(0, 10).forEach(entry => {
-     *     console.log(`${entry.rank}. ${entry.wallet}: ${entry.totalXp} XP`);
-     *   });
-     * } else {
-     *   console.log('No active season - next season coming soon!');
-     * }
-     * ```
-     *
-     * @internal
-     */
-    fetchCurrentDexLeaderboard(): Promise<LeaderboardResult | null>;
-    /**
-     * Fetch DEX aggregated volume summary with trend metrics
-     *
-     * Returns platform-wide trading volume statistics across all DEX pools with
-     * multi-timeframe comparisons. Shows total USD volume and percentage changes
-     * relative to previous periods.
-     *
-     * **Volume Metrics:**
-     * - volume1d: 24-hour trading volume (USD)
-     * - volume1dDelta: % change vs previous 24 hours
-     * - volume7d: 7-day rolling volume (USD)
-     * - volume7dDelta: % change vs previous 7 days
-     * - volume30d: 30-day rolling volume (USD)
-     * - volume30dDelta: % change vs previous 30 days
-     *
-     * **Delta Interpretation:**
-     * - Positive delta (+10.5): Volume increased by 10.5%
-     * - Negative delta (-5.2): Volume decreased by 5.2%
-     * - Zero delta (0): No change from previous period
-     *
-     * **Use Cases:**
-     * - Platform health dashboard
-     * - Volume trend charts
-     * - Market activity indicators
-     * - "Trading volume up/down X%" alerts
-     *
-     * @returns Promise<DexAggregatedVolumeSummary> Volume metrics and deltas
-     * @throws NetworkError If API request fails
-     * @category Volume Analytics
-     * @since 4.0.0
-     *
-     * @example Display volume summary
-     * ```typescript
-     * const volumeSummary = await dexService.fetchDexAggregatedVolumeSummary();
-     *
-     * console.log(`24h Volume: $${volumeSummary.volume1d.toLocaleString()} (${volumeSummary.volume1dDelta > 0 ? '+' : ''}${volumeSummary.volume1dDelta.toFixed(2)}%)`);
-     * console.log(`7d Volume: $${volumeSummary.volume7d.toLocaleString()} (${volumeSummary.volume7dDelta > 0 ? '+' : ''}${volumeSummary.volume7dDelta.toFixed(2)}%)`);
-     * console.log(`30d Volume: $${volumeSummary.volume30d.toLocaleString()} (${volumeSummary.volume30dDelta > 0 ? '+' : ''}${volumeSummary.volume30dDelta.toFixed(2)}%)`);
-     * ```
-     *
-     * @example Volume trend indicator
-     * ```typescript
-     * const volumeSummary = await dexService.fetchDexAggregatedVolumeSummary();
-     *
-     * if (volumeSummary.volume1dDelta > 10) {
-     *   console.log('🚀 High trading activity - volume up ' + volumeSummary.volume1dDelta.toFixed(1) + '%');
-     * } else if (volumeSummary.volume1dDelta < -10) {
-     *   console.log('📉 Low trading activity - volume down ' + Math.abs(volumeSummary.volume1dDelta).toFixed(1) + '%');
-     * } else {
-     *   console.log('📊 Stable trading activity');
-     * }
-     * ```
-     */
-    fetchDexAggregatedVolumeSummary(): Promise<DexAggregatedVolumeSummary>;
-}
-//# sourceMappingURL=DexService.d.ts.map

package/dist/services/DexService.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DexService.d.ts","sourceRoot":"","sources":["../../src/services/DexService.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAgB,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EACV,0BAA0B,EAC1B,SAAS,EACT,qBAAqB,EAGrB,iBAAiB,EACjB,cAAc,EACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAQjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAShD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,SAAQ,UAAU;IAEtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;gBAFjB,cAAc,CAAC,EAAE,UAAU,YAAA,EAC3B,KAAK,CAAC,EAAE,kBAAkB,YAAA,EAC1B,gBAAgB,CAAC,EAAE,gBAAgB,YAAA,EACpD,SAAS,GAAE,OAAe;IAK5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC;IA6BjF;;;;OAIG;YACW,0BAA0B;IA8BxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;YAEW,uBAAuB;IA0ErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,4BAA4B,CAChC,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,uBAAuB,CAAC,EAE5F,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACzD,OAAO,CAAC,cAAc,CAAC;IAiF1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAgDzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACG,kBAAkB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAmFhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,qBAAqB,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAkBxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACG,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4GjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,0BAA0B,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAWrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACG,+BAA+B,IAAI,OAAO,CAAC,0BAA0B,CAAC;CAqC7E"}

package/dist/services/NetworkKeyedCacheService.d.ts

@@ -1,185 +0,0 @@
-/**
- * Network-Keyed Cache Service Base Class
- *
- * Abstraction for caches that store items partitioned by network key
- * (e.g., 'ETHEREUM', 'SOLANA'). Extends BatchedCacheService patterns
- * for network-partitioned storage with dual O(1) indices.
- *
- * ## Features
- * - Network-partitioned storage (Map<Network, Map<Key, Item>>)
- * - Primary index by symbol/key + secondary index by tokenId
- * - Batch operations per network (set, merge)
- * - Timestamp tracking per network
- * - Common normalization via normalizeTokenKey()
- *
- * ## Subclass Responsibilities
- * - Implement `extractPrimaryKey()` for primary index (e.g., symbol)
- * - Implement `extractSecondaryKey()` for secondary index (e.g., tokenId)
- * - Implement `getStats()` for domain-specific statistics
- *
- * @category Services
- * @since 5.12.0
- * @template V - Value type stored in cache
- * @template K - Network key type (e.g., 'ETHEREUM' | 'SOLANA')
- * @template S - Statistics type
- */
-import { LoggerBase } from './BaseService.js';
-/**
- * Base cache statistics for network-keyed caches
- */
-export interface NetworkKeyedCacheStats<K extends string = string> {
-    /** Networks with cached data */
-    networks: K[];
-    /** Total items across all networks */
-    totalItems: number;
-    /** Item count per network */
-    itemsByNetwork: Record<K, number>;
-    /** Fetch timestamps per network */
-    fetchTimestamps: Record<K, number>;
-}
-/**
- * Network-keyed cache service with dual O(1) indices
- *
- * Provides reusable cache operations for network-partitioned token data.
- * Uses dual Map indices for efficient lookups by both symbol and tokenId.
- *
- * @template V - Value type stored in cache
- * @template K - Network key type (e.g., 'ETHEREUM' | 'SOLANA')
- * @template S - Statistics type extending NetworkKeyedCacheStats
- */
-export declare abstract class NetworkKeyedCacheService<V, K extends string = string, S extends NetworkKeyedCacheStats<K> = NetworkKeyedCacheStats<K>> extends LoggerBase {
-    /** Primary index: network -> (primaryKey -> item) */
-    protected readonly primaryIndex: Map<K, Map<string, V>>;
-    /** Secondary index: network -> (secondaryKey -> item) */
-    protected readonly secondaryIndex: Map<K, Map<string, V>>;
-    /** Fetch timestamps per network */
-    protected readonly fetchTimestamps: Map<K, number>;
-    constructor(debugMode?: boolean);
-    /**
-     * Normalize key for consistent cache lookups
-     *
-     * Uses common tokenNameNormalizer for uppercase, trimmed keys.
-     *
-     * @param key - Raw key to normalize
-     * @returns Normalized key string
-     */
-    protected normalizeKey(key: string): string;
-    /**
-     * Extract the primary key from an item (e.g., symbol)
-     *
-     * @param item - Item to extract primary key from
-     * @returns Primary key string
-     */
-    protected abstract extractPrimaryKey(item: V): string;
-    /**
-     * Extract the secondary key from an item (e.g., stringifiedTokenClassKey)
-     *
-     * @param item - Item to extract secondary key from
-     * @returns Secondary key string
-     */
-    protected abstract extractSecondaryKey(item: V): string;
-    /**
-     * Check if cache has data for a network
-     *
-     * @param network - Network to check
-     * @returns True if network has cached items
-     */
-    has(network: K): boolean;
-    /**
-     * Get all items for a network
-     *
-     * @param network - Network to get items for
-     * @returns Array of cached items (empty if not cached)
-     */
-    getAll(network: K): V[];
-    /**
-     * Get item by primary key (e.g., symbol)
-     *
-     * @param network - Network to search
-     * @param key - Primary key (case-insensitive)
-     * @returns Item or undefined if not found
-     */
-    getByPrimaryKey(network: K, key: string): V | undefined;
-    /**
-     * Get item by secondary key (e.g., tokenId)
-     *
-     * Uses the secondary index for O(1) lookup performance.
-     *
-     * @param network - Network to search
-     * @param key - Secondary key (case-insensitive)
-     * @returns Item or undefined if not found
-     */
-    getBySecondaryKey(network: K, key: string): V | undefined;
-    /**
-     * Set items for a network (replaces all existing items)
-     *
-     * @param network - Network to set items for
-     * @param items - Array of items to cache
-     */
-    set(network: K, items: V[]): void;
-    /**
-     * Add items to a network cache (merges with existing)
-     *
-     * Used for pagination - adds new items without replacing existing.
-     *
-     * @param network - Network to add items to
-     * @param items - Array of items to add
-     */
-    merge(network: K, items: V[]): void;
-    /**
-     * Get fetch timestamp for a network
-     *
-     * @param network - Network to get timestamp for
-     * @returns Timestamp when network was last fetched, or undefined
-     */
-    getFetchTimestamp(network: K): number | undefined;
-    /**
-     * Get cache statistics
-     *
-     * Subclasses may override to add domain-specific statistics.
-     *
-     * @returns Cache statistics
-     */
-    abstract getStats(): S;
-    /**
-     * Build base statistics (helper for subclasses)
-     *
-     * @param defaultNetworks - Default networks to include in stats
-     * @returns Base statistics object
-     */
-    protected buildBaseStats(defaultNetworks: K[]): NetworkKeyedCacheStats<K>;
-    /**
-     * Clear cache for a network or all networks
-     *
-     * @param network - Optional network to clear (clears all if not provided)
-     */
-    clear(network?: K): void;
-    /**
-     * Get item count for a network
-     *
-     * @param network - Network to count items for
-     * @returns Number of cached items
-     */
-    size(network: K): number;
-    /**
-     * Check if item exists by primary key
-     *
-     * @param network - Network to check
-     * @param key - Primary key (case-insensitive)
-     * @returns True if item is cached
-     */
-    hasByPrimaryKey(network: K, key: string): boolean;
-    /**
-     * Get all cached networks
-     *
-     * @returns Array of networks with cached items
-     */
-    getCachedNetworks(): K[];
-    /**
-     * Dump entire cache contents
-     *
-     * @returns Full cache contents for all cached networks
-     */
-    dump(): Record<K, V[]>;
-}
-//# sourceMappingURL=NetworkKeyedCacheService.d.ts.map

package/dist/services/NetworkKeyedCacheService.d.ts.map

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