@gala-chain/launchpad-sdk 3.9.1 → 3.11.0

package/dist/services/LaunchpadService.d.ts

@@ -68,9 +68,15 @@ export declare class LaunchpadService {
     /**
      * Fetches pools with filtering and pagination
      *
+     * Supports automatic multi-page fetching:
+     * - `limit <= 20`: Single API call (backward compatible)
+     * - `limit > 20`: Automatic concurrent multi-page fetching
+     * - `limit === 0`: Fetches all available pools
+     *
      * @param options Fetch options including type, search, and pagination
      * @returns Promise<PoolsResult> Clean pool data with full pagination
      * @since 2.0.0
+     * @updated 3.11.0 - Added auto-pagination support
      */
     fetchPools(options?: {
         search?: string;
@@ -79,6 +85,21 @@ export declare class LaunchpadService {
         page?: number;
         limit?: number;
     }): Promise<PoolsResult>;
+    /**
+     * Fetches all available pools with automatic pagination
+     *
+     * Convenience method that fetches all available pools. Delegates to PoolService.
+     * Equivalent to `fetchPools({ ...options, limit: 0 })`.
+     *
+     * @param options Optional filters (type, tokenName, search)
+     * @returns Promise<PoolsResult> with all pools
+     * @since 3.11.0
+     */
+    fetchAllPools(options?: {
+        search?: string;
+        tokenName?: string;
+        type?: 'recent' | 'popular';
+    }): Promise<PoolsResult>;
     /**
      * Checks if a pool exists for given token name or symbol
      *

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

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

package/dist/services/PoolService.d.ts

@@ -34,11 +34,40 @@ import { FetchVolumeDataOptions, HasTokenBadgeOptions } from '../types/options.d
 export declare class PoolService {
     private readonly http;
     constructor(http: HttpClient);
+    /**
+     * Fetches a single page of pools (internal helper)
+     * @internal
+     */
+    private fetchSinglePage;
+    /**
+     * Fetches multiple pages of pools concurrently with rate limiting
+     * @internal
+     */
+    private fetchMultiplePages;
     /**
      * Fetches pools with filtering and pagination
      *
+     * Supports automatic multi-page fetching:
+     * - `limit <= 20`: Single API call (backward compatible)
+     * - `limit > 20`: Automatic concurrent multi-page fetching
+     * - `limit === 0`: Fetches all available pools
+     *
      * @param options Fetch options including type, search, and pagination
      * @returns Promise<PoolsResult> Clean pool data with full pagination
+     * @since 3.6.0
+     * @updated 3.11.0 - Added auto-pagination support
+     *
+     * @example
+     * ```typescript
+     * // Single page fetch (backward compatible)
+     * const result1 = await poolService.fetchPools({ limit: 20 });
+     *
+     * // Auto-pagination (fetches 5 pages concurrently: 20+20+20+20+20)
+     * const result2 = await poolService.fetchPools({ limit: 100 });
+     *
+     * // Fetch all pools
+     * const result3 = await poolService.fetchPools({ limit: 0 });
+     * ```
      */
     fetchPools(options?: {
         search?: string;
@@ -47,6 +76,30 @@ export declare class PoolService {
         page?: number;
         limit?: number;
     }): Promise<PoolsResult>;
+    /**
+     * Fetches all available pools with automatic pagination
+     *
+     * Convenience method that fetches all available pools by automatically
+     * handling pagination. Equivalent to `fetchPools({ ...options, limit: 0 })`.
+     *
+     * @param options Optional filters (type, tokenName, search)
+     * @returns Promise<PoolsResult> with all pools
+     * @since 3.11.0
+     *
+     * @example
+     * ```typescript
+     * // Fetch all recent pools
+     * const all = await poolService.fetchAllPools({ type: 'recent' });
+     *
+     * // Fetch all pools matching search
+     * const matching = await poolService.fetchAllPools({ search: 'dragon' });
+     * ```
+     */
+    fetchAllPools(options?: {
+        search?: string;
+        tokenName?: string;
+        type?: 'recent' | 'popular';
+    }): Promise<PoolsResult>;
     /**
      * Checks if a pool exists for given token name or symbol
      *

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

@@ -1 +1 @@
-{"version":3,"file":"PoolService.d.ts","sourceRoot":"","sources":["../../src/services/PoolService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAS3C,OAAO,EAGL,WAAW,EACX,gBAAgB,EAIhB,eAAe,EAEf,uBAAuB,EAEvB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EAErB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;;OAKG;IACG,UAAU,CACd,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,OAAO,CAAC,WAAW,CAAC;IAgFvB;;;;;OAKG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAqC5D;;;;;OAKG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D;;;;;OAKG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW9D;;;;;OAKG;IACG,eAAe,CACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAiD3B;;;;;;;;OAQG;IACG,sBAAsB,CAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,uBAAuB,CAAC;IAoCnC;;;;;;;;OAQG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBrE;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBpE;;;;;;;;;;;;;;;;OAgBG;IACG,uBAAuB,CAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAoB1B"}
+{"version":3,"file":"PoolService.d.ts","sourceRoot":"","sources":["../../src/services/PoolService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAU3C,OAAO,EAGL,WAAW,EAEX,gBAAgB,EAIhB,eAAe,EAEf,uBAAuB,EAEvB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EAErB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;OAGG;YACW,eAAe;IA8C7B;;;OAGG;YACW,kBAAkB;IA0ChC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,UAAU,CACd,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,OAAO,CAAC,WAAW,CAAC;IA6IvB;;;;;;;;;;;;;;;;;;OAkBG;IACG,aAAa,CACjB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;KAC7B,GACA,OAAO,CAAC,WAAW,CAAC;IAIvB;;;;;OAKG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAqC5D;;;;;OAKG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D;;;;;OAKG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW9D;;;;;OAKG;IACG,eAAe,CACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAiD3B;;;;;;;;OAQG;IACG,sBAAsB,CAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,uBAAuB,CAAC;IAoCnC;;;;;;;;OAQG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBrE;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBpE;;;;;;;;;;;;;;;;OAgBG;IACG,uBAAuB,CAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAoB1B"}

package/dist/services/TokenMetadataCache.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Token Metadata Cache Service
+ *
+ * High-performance in-memory cache for immutable token metadata, optimized for
+ * local bonding curve calculations. Eliminates redundant API calls by caching:
+ * - Reverse bonding curve fee factors (from fetchPools)
+ * - Custom maxSupply values (auto-detected, defaults to 10M constant)
+ * - Vault addresses (via TokenResolverService)
+ *
+ * Cache persistence: Entire MCP server lifetime (survives across conversations)
+ *
+ * @category Services
+ * @since 3.9.2
+ */
+/**
+ * Token metadata cache entry
+ *
+ * Stores immutable token properties needed for local calculations.
+ * All properties are optional - cache can be partially populated.
+ */
+export interface TokenMetadata {
+    /** Minimum reverse bonding curve fee factor (0.0 - 1.0) */
+    reverseBondingCurveMinFeeFactor?: number;
+    /** Maximum reverse bonding curve fee factor (0.0 - 1.0) */
+    reverseBondingCurveMaxFeeFactor?: number;
+    /** Net reverse bonding curve fee factor (max - min) */
+    reverseBondingCurveNetFeeFactor?: number;
+    /** Vault address for this token (GalaChain format) */
+    vaultAddress?: string;
+    /** Custom maximum supply (only cached if != default 10M) */
+    maxSupply?: string;
+    /** Timestamp when this cache entry was last updated */
+    lastUpdated: number;
+}
+/**
+ * Cache statistics for monitoring and debugging
+ */
+export interface CacheStats {
+    /** Total number of tokens in cache */
+    totalTokens: number;
+    /** Approximate cache size in bytes */
+    cacheSize: number;
+    /** Timestamp of oldest cache entry */
+    oldestEntry: number;
+}
+/**
+ * Token Metadata Cache
+ *
+ * High-performance in-memory cache for immutable token properties used in local calculations.
+ *
+ * ## Cache Lifecycle
+ * - **Persistence**: Entire MCP server lifetime (survives across conversations)
+ * - **Bounded Size**: Maximum 10,000 tokens (~2.5MB max memory)
+ * - **Eviction Strategy**: LRU (Least Recently Updated) with O(1) eviction time
+ *
+ * ## Warming Strategy (Opportunistic Caching)
+ * Cache is automatically warmed during normal SDK operations:
+ * - `fetchPools()` - Caches RBC fees and vault addresses for all returned pools
+ * - `fetchPoolDetailsForCalculation()` - Caches maxSupply and RBC fees (including defaults)
+ * - `fetchCurrentSupply()` - Caches maxSupply when fetched
+ * - `fetchTokenDistribution()` - Caches vault address when resolved
+ *
+ * ## Performance Characteristics
+ * - **Get/Set**: O(1) average time complexity
+ * - **Eviction**: O(1) time (uses Map insertion order)
+ * - **Normalization**: Handles unicode, case-insensitive, whitespace cleanup
+ * - **Memory**: ~250-400 bytes per entry (depends on string field lengths)
+ *
+ * ## Smart Defaults
+ * - **maxSupply**: Returns constant 10M for uncached tokens (99%+ hit rate)
+ * - **RBC Fees**: Defensive defaults (0.0 min, 0.5 max) when API data missing
+ *
+ * @example Basic usage
+ * ```typescript
+ * const cache = new TokenMetadataCache();
+ *
+ * // Warm cache from pool data
+ * cache.warmFromPoolData('anime', {
+ *   reverseBondingCurveMinFeeFactor: 0.0,
+ *   reverseBondingCurveMaxFeeFactor: 0.5
+ * });
+ *
+ * // Retrieve cached data
+ * const metadata = cache.get('anime');
+ * const maxSupply = cache.getMaxSupply('anime'); // Returns '10000000' (default)
+ * ```
+ *
+ * @category Services
+ * @since 3.9.2
+ */
+export declare class TokenMetadataCache {
+    /** Maximum cache size (10,000 tokens ≈ 2.5MB max memory) */
+    private static readonly MAX_CACHE_SIZE;
+    private cache;
+    /**
+     * Get least recently updated entry for LRU eviction
+     *
+     * Leverages Map's insertion order: the first key is the oldest.
+     * O(1) time complexity vs O(n) scanning.
+     *
+     * @returns Token name of oldest entry, or null if cache is empty
+     * @private
+     */
+    private getLRUKey;
+    /**
+     * Normalize token name for consistent cache keys
+     *
+     * Handles edge cases: unicode control chars, multiple spaces, case insensitivity.
+     *
+     * @param tokenName Raw token name
+     * @returns Normalized token name (lowercase, trimmed, cleaned)
+     * @private
+     */
+    private normalizeTokenName;
+    /**
+     * Warm cache from pool data (opportunistic caching from fetchPools)
+     *
+     * Partially populates cache with reverse bonding curve fees and vault address
+     * from fetchPools response. This provides zero-cost cache warming during normal
+     * pool browsing operations.
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @param poolData Partial metadata from pool data
+     *
+     * @example Warming from fetchPools
+     * ```typescript
+     * pools.forEach(pool => {
+     *   cache.warmFromPoolData(pool.tokenName, {
+     *     reverseBondingCurveMinFeeFactor: parseFloat(pool.reverseBondingCurveMinFeePortion),
+     *     reverseBondingCurveMaxFeeFactor: parseFloat(pool.reverseBondingCurveMaxFeePortion),
+     *     vaultAddress: pool.vaultAddress
+     *   });
+     * });
+     * ```
+     */
+    warmFromPoolData(tokenName: string, poolData: Partial<TokenMetadata>): void;
+    /**
+     * Set or update cache entry for a token
+     *
+     * Updates cache with partial or complete metadata. Merges with existing data.
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @param metadata Partial or complete metadata to cache
+     *
+     * @example Caching custom maxSupply
+     * ```typescript
+     * cache.set('customtoken', {
+     *   maxSupply: '50000000' // Custom max supply detected
+     * });
+     * ```
+     */
+    set(tokenName: string, metadata: Partial<TokenMetadata>): void;
+    /**
+     * Get cached metadata for a token
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @returns Cached metadata or null if not cached
+     *
+     * @example Retrieving cached data
+     * ```typescript
+     * const metadata = cache.get('anime');
+     * if (metadata?.reverseBondingCurveMaxFeeFactor) {
+     *   console.log('RBC max fee:', metadata.reverseBondingCurveMaxFeeFactor);
+     * }
+     * ```
+     */
+    get(tokenName: string): TokenMetadata | null;
+    /**
+     * Get maxSupply for a token (returns cached or default constant)
+     *
+     * Returns cached custom maxSupply if available, otherwise returns the
+     * default constant (10,000,000). This eliminates the need to fetch maxSupply
+     * for 99%+ of tokens that use the default value.
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @returns maxSupply as decimal string (cached or default '10000000')
+     *
+     * @example Getting maxSupply with fallback
+     * ```typescript
+     * const maxSupply = cache.getMaxSupply('anime'); // '10000000' (default)
+     * const customSupply = cache.getMaxSupply('customtoken'); // '50000000' (cached custom)
+     * ```
+     */
+    getMaxSupply(tokenName: string): string;
+    /**
+     * Check if a token exists in cache
+     *
+     * @param tokenName Token name (normalized to lowercase)
+     * @returns True if token has any cached metadata
+     */
+    has(tokenName: string): boolean;
+    /**
+     * Clear cache (all tokens or specific token)
+     *
+     * @param tokenName Optional token name to clear (clears all if not provided)
+     *
+     * @example Clear specific token
+     * ```typescript
+     * cache.clear('anime'); // Clear only anime token
+     * ```
+     *
+     * @example Clear entire cache
+     * ```typescript
+     * cache.clear(); // Clear all tokens
+     * ```
+     */
+    clear(tokenName?: string): void;
+    /**
+     * Export entire cache as plain object
+     *
+     * Useful for debugging, monitoring, and cache inspection.
+     *
+     * @returns Cache contents as plain object (tokenName -> metadata)
+     *
+     * @example Dump cache for debugging
+     * ```typescript
+     * const cacheData = cache.dump();
+     * console.log('Cached tokens:', Object.keys(cacheData));
+     * console.log('Cache contents:', JSON.stringify(cacheData, null, 2));
+     * ```
+     */
+    dump(): Record<string, TokenMetadata>;
+    /**
+     * Get cache statistics
+     *
+     * Returns statistics about cache size and age for monitoring performance.
+     *
+     * ⚠️ **Performance**: O(n) - iterates over all cache entries to calculate size.
+     * Do not call in hot paths or frequently.
+     *
+     * @returns Cache statistics
+     *
+     * @example Get cache stats
+     * ```typescript
+     * const stats = cache.stats();
+     * console.log(`Cached ${stats.totalTokens} tokens (${stats.cacheSize} bytes)`);
+     * console.log(`Oldest entry: ${new Date(stats.oldestEntry).toISOString()}`);
+     * ```
+     */
+    stats(): CacheStats;
+}
+//# sourceMappingURL=TokenMetadataCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenMetadataCache.d.ts","sourceRoot":"","sources":["../../src/services/TokenMetadataCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,2DAA2D;IAC3D,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,uDAAuD;IACvD,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,kBAAkB;IAC7B,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAS;IAE/C,OAAO,CAAC,KAAK,CAAoC;IAEjD;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAyB3E;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAyB9D;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAK5C;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQvC;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAK/B;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAS/B;;;;;;;;;;;;;OAaG;IACH,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAQrC;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,IAAI,UAAU;CAsCpB"}

package/dist/utils/cacheWarmingHelpers.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Cache Warming Helpers
+ *
+ * Shared utilities for extracting and caching token metadata from pool data.
+ * This module provides type-safe, reusable logic for opportunistic cache warming
+ * that can be used across the SDK codebase.
+ *
+ * @category Utilities
+ * @since 3.9.2
+ */
+import type { TokenMetadata } from '../services/TokenMetadataCache';
+/**
+ * Pool data fields relevant for cache warming
+ *
+ * This is a focused subset of PoolData containing only fields needed
+ * for metadata extraction. Using a minimal interface keeps cache warming
+ * logic decoupled from full pool data structure.
+ */
+export interface PoolDataForCaching {
+    /** Token name (required for cache key) */
+    tokenName: string;
+    /** Vault address (GalaChain format) */
+    vaultAddress?: string;
+    /** Reverse bonding curve minimum fee portion (string representation) */
+    reverseBondingCurveMinFeePortion?: string;
+    /** Reverse bonding curve maximum fee portion (string representation) */
+    reverseBondingCurveMaxFeePortion?: string;
+}
+/**
+ * Extract cacheable metadata from pool data
+ *
+ * Converts pool API response data into structured token metadata suitable
+ * for caching. Handles string-to-number conversion, validation, and derived
+ * calculations (net fee factor).
+ *
+ * This is a pure function with no side effects - it only extracts and transforms data.
+ *
+ * @param pool - Pool data from API (must have tokenName field)
+ * @param logger - Optional logger for debugging invalid data
+ * @returns Metadata object if any fields could be extracted, null otherwise
+ *
+ * @example Basic extraction
+ * ```typescript
+ * const pool = {
+ *   tokenName: 'anime',
+ *   vaultAddress: 'service|Token$Unit$ANIME$...',
+ *   reverseBondingCurveMinFeePortion: '0.0',
+ *   reverseBondingCurveMaxFeePortion: '0.5'
+ * };
+ *
+ * const metadata = extractMetadataFromPoolData(pool);
+ * // Returns:
+ * // {
+ * //   vaultAddress: 'service|Token$Unit$ANIME$...',
+ * //   reverseBondingCurveMinFeeFactor: 0.0,
+ * //   reverseBondingCurveMaxFeeFactor: 0.5,
+ * //   reverseBondingCurveNetFeeFactor: 0.5
+ * // }
+ * ```
+ *
+ * @example With invalid data (graceful handling)
+ * ```typescript
+ * const pool = {
+ *   tokenName: 'test',
+ *   reverseBondingCurveMinFeePortion: 'invalid' // NaN after parseFloat
+ * };
+ *
+ * const metadata = extractMetadataFromPoolData(pool, logger);
+ * // Returns: null (no valid metadata)
+ * // Logger outputs: "Skipping invalid reverseBondingCurveMinFeePortion for test: 'invalid'"
+ * ```
+ *
+ * @example Partial metadata (some fields missing)
+ * ```typescript
+ * const pool = {
+ *   tokenName: 'partial',
+ *   vaultAddress: 'service|...'
+ *   // No RBC fee data
+ * };
+ *
+ * const metadata = extractMetadataFromPoolData(pool);
+ * // Returns: { vaultAddress: 'service|...' }
+ * ```
+ */
+export declare function extractMetadataFromPoolData(pool: PoolDataForCaching, logger?: {
+    debug: (message: string) => void;
+}): Partial<TokenMetadata> | null;
+/**
+ * Validate pool data structure for cache warming
+ *
+ * Checks that pool data has required fields and correct types before attempting
+ * metadata extraction. This prevents runtime errors from malformed API responses.
+ *
+ * @param pool - Pool data to validate
+ * @returns True if pool data is valid for caching, false otherwise
+ *
+ * @example Valid pool data
+ * ```typescript
+ * const pool = { tokenName: 'anime', vaultAddress: '...' };
+ * isValidPoolForCaching(pool); // true
+ * ```
+ *
+ * @example Invalid pool data
+ * ```typescript
+ * const badPool = { vaultAddress: '...' }; // Missing tokenName
+ * isValidPoolForCaching(badPool); // false
+ * ```
+ */
+export declare function isValidPoolForCaching(pool: any): pool is PoolDataForCaching;
+//# sourceMappingURL=cacheWarmingHelpers.d.ts.map

package/dist/utils/cacheWarmingHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheWarmingHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/cacheWarmingHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGpE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,gCAAgC,CAAC,EAAE,MAAM,CAAC;IAC1C,wEAAwE;IACxE,gCAAgC,CAAC,EAAE,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,kBAAkB,EACxB,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5C,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CA2C/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,IAAI,kBAAkB,CAQ3E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gala-chain/launchpad-sdk",
-  "version": "3.9.1",
+  "version": "3.11.0",
   "description": "TypeScript SDK for Gala Launchpad Backend API - Production-ready DeFi token launchpad integration with wallet-based authentication, GalaChain trading, and comprehensive user operations. 100% tested (22/22 endpoints working).",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -38,6 +38,7 @@
     "test:ci": "jest --coverage --ci --watchAll=false",
     "demo": "tsx examples/complete-sdk-demo.ts",
     "demo-trades": "tsx examples/demo-trades.ts",
+    "demo-cache": "tsx examples/demo-cache.ts",
     "lint": "eslint src --ext .ts,.tsx --fix",
     "lint:check": "eslint src --ext .ts,.tsx",
     "typecheck": "tsc --noEmit",