@gala-chain/launchpad-sdk 5.0.2-beta.1 → 5.0.4-beta.0

package/dist/src/services/BanService.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Ban Service
+ *
+ * Handles all user ban operations including creating/removing bans,
+ * listing banned users, and active user management.
+ *
+ * @category Services
+ * @since 5.5.0
+ */
+import { HttpClient } from '../utils/http';
+import { StreamTokenServiceBase } from './StreamTokenServiceBase';
+import type { JwtAuth } from '../auth/JwtAuth';
+import { CreateBanOptions, CreateBanResult, RemoveBanOptions, RemoveBanResult, ListBansOptions, BanListResult, GetBanStatusOptions, BanStatusResult, GetActiveUsersOptions, ActiveUsersResult } from '../types/ban.dto';
+/**
+ * Ban Service Class
+ *
+ * Provides methods for:
+ * - Creating and removing bans (per-token)
+ * - Listing banned users (paginated)
+ * - Checking ban status for specific users
+ * - Getting active users (viewers and chat participants)
+ *
+ * All endpoints require either JWT authentication (token owner) or
+ * admin API key. The service uses dual-auth pattern automatically.
+ *
+ * @remarks
+ * **Case Normalization**: Token names and user addresses are automatically
+ * normalized to lowercase in all requests and responses for consistency.
+ * For example, `tokenName: 'MyToken'` will return `tokenName: 'mytoken'`.
+ *
+ * **Security**: This service uses dual authentication:
+ * - **JWT (Bearer token)**: Provides CSRF protection inherently via Authorization header.
+ * - **Admin API key**: Intended for server-to-server communication only.
+ *
+ * When using JWT from browser clients, ensure tokens are stored securely
+ * (e.g., in memory, not localStorage) to prevent XSS token theft.
+ *
+ * @example
+ * ```typescript
+ * const banService = new BanService(httpClient, 'admin-api-key', jwtAuth, true);
+ *
+ * // Ban a user
+ * await banService.createBan({
+ *   tokenName: 'mytoken',
+ *   userAddress: 'eth|abc123...',
+ *   reason: 'Spam',
+ *   durationSeconds: 86400 // 24 hours
+ * });
+ *
+ * // List banned users
+ * const bans = await banService.listBans({ tokenName: 'mytoken', page: 1, limit: 20 });
+ *
+ * // Get active viewers
+ * const viewers = await banService.getActiveUsers({
+ *   tokenName: 'mytoken',
+ *   type: 'viewers'
+ * });
+ * ```
+ */
+export declare class BanService extends StreamTokenServiceBase {
+    constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth, debugMode?: boolean);
+    /**
+     * Create a ban for a user on a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * @param options Ban options including tokenName, userAddress, and optional reason/duration
+     * @returns Created ban data
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Permanent ban
+     * await banService.createBan({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...',
+     *   reason: 'Spam'
+     * });
+     *
+     * // Temporary ban (24 hours)
+     * await banService.createBan({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...',
+     *   reason: 'Warned for inappropriate content',
+     *   durationSeconds: 86400
+     * });
+     * ```
+     */
+    createBan(options: CreateBanOptions): Promise<CreateBanResult>;
+    /**
+     * Remove a ban for a user on a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * @param options Remove options including tokenName and userAddress
+     * @returns Removal confirmation
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws Error if ban not found (404)
+     *
+     * @example
+     * ```typescript
+     * const result = await banService.removeBan({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...'
+     * });
+     * console.log('Unbanned:', result.removed);
+     * ```
+     */
+    removeBan(options: RemoveBanOptions): Promise<RemoveBanResult>;
+    /**
+     * List all bans for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     * Returns paginated results with user profile information.
+     *
+     * @param options List options including tokenName and optional pagination
+     * @returns Paginated list of bans
+     * @throws ValidationError if token name is invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await banService.listBans({ tokenName: 'mytoken' });
+     * console.log('Total bans:', page1.meta.total);
+     *
+     * // Get next page
+     * if (page1.meta.page < page1.meta.totalPages) {
+     *   const page2 = await banService.listBans({
+     *     tokenName: 'mytoken',
+     *     page: 2,
+     *     limit: 20
+     *   });
+     * }
+     * ```
+     */
+    listBans(options: ListBansOptions): Promise<BanListResult>;
+    /**
+     * Get ban status for a specific user on a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * @param options Options including tokenName and userAddress
+     * @returns Ban status (banned: true/false with ban data if banned)
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * const status = await banService.getBanStatus({
+     *   tokenName: 'mytoken',
+     *   userAddress: 'eth|abc123...'
+     * });
+     * if (status.banned) {
+     *   console.log('User is banned:', status.ban?.reason);
+     *   console.log('Expires:', status.ban?.expiresAt);
+     * }
+     * ```
+     */
+    getBanStatus(options: GetBanStatusOptions): Promise<BanStatusResult>;
+    /**
+     * Get active users for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * Returns up to 1000 users. If more users are connected, the `truncated`
+     * flag will be true.
+     *
+     * @param options Options including tokenName and optional type filter
+     * @returns Active users list with metadata
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     *
+     * @example
+     * ```typescript
+     * // Get all viewers
+     * const viewers = await banService.getActiveUsers({
+     *   tokenName: 'mytoken',
+     *   type: 'viewers'
+     * });
+     * console.log('Viewers:', viewers.total);
+     * console.log('Truncated:', viewers.truncated);
+     *
+     * // Get chat participants only
+     * const chatters = await banService.getActiveUsers({
+     *   tokenName: 'mytoken',
+     *   type: 'chat_participants'
+     * });
+     * ```
+     */
+    getActiveUsers(options: GetActiveUsersOptions): Promise<ActiveUsersResult>;
+}
+//# sourceMappingURL=BanService.d.ts.map

package/dist/src/services/BanService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BanService.d.ts","sourceRoot":"","sources":["../../../src/services/BanService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EAWlB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,UAAW,SAAQ,sBAAsB;gBAElD,IAAI,EAAE,UAAU,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,EACjB,SAAS,GAAE,OAAe;IAS5B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA+BpE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsBpE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAyBhE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IA4B1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAkBjF"}

package/dist/src/services/BaseService.d.ts

@@ -9,6 +9,7 @@
  */
 import { HttpClient } from '../utils/http';
 import { Logger } from '../utils/Logger';
+import type { JwtAuth } from '../auth/JwtAuth';
 /**
  * Abstract base class for SDK services with optional HttpClient
  *
@@ -38,16 +39,56 @@ import { Logger } from '../utils/Logger';
 export declare abstract class BaseService {
     protected readonly http: HttpClient;
     protected readonly logger: Logger;
-    constructor(http: HttpClient, debugMode?: boolean);
+    protected jwtAuth: JwtAuth | undefined;
+    constructor(http: HttpClient, debugMode?: boolean, jwtAuth?: JwtAuth);
+    /**
+     * Set the JWT authentication manager.
+     * Allows dynamic configuration of JWT auth after service creation.
+     *
+     * @param jwtAuth - JWT auth manager instance
+     */
+    setJwtAuth(jwtAuth: JwtAuth): void;
+    /**
+     * Get JWT authorization headers.
+     * @throws ConfigurationError if JWT auth is not configured
+     *
+     * During Jest garbage collection/cleanup, returns empty headers if JWT is not configured
+     * to prevent spurious errors during test teardown.
+     */
+    protected getJwtHeaders(): Record<string, string>;
+    /**
+     * Check if the current call is coming from user code (test) vs garbage collection
+     * Uses multiple heuristics to detect call context:
+     * - Presence of expect/jest in stack (active test execution)
+     * - Presence of 'tests/' in stack (test file execution)
+     * - If neither found, likely garbage collection during cleanup
+     * @private
+     */
+    private isCalledFromUserCode;
+    /**
+     * Validate a positive integer (for IDs)
+     *
+     * @param value - Value to validate
+     * @param fieldName - Technical field name for error details
+     * @param displayName - Human-readable name for error message
+     * @throws {ValidationError} If value is not a positive integer
+     *
+     * @example
+     * ```typescript
+     * this.validatePositiveInteger(id, 'id', 'API key ID');
+     * ```
+     */
+    protected validatePositiveInteger(value: number, fieldName: string, displayName: string): void;
 }
 /**
  * Lightweight base class for services without HttpClient
  *
  * Provides:
  * - Standardized logger initialization with automatic context naming
+ * - Optional custom logger injection for advanced use cases
  * - For services that don't need HttpClient (e.g., SignatureService, WebSocketService)
  *
- * @example
+ * @example Basic usage (auto-created logger)
  * ```typescript
  * export class MyService extends LoggerBase {
  *   constructor(private walletProvider: WalletProvider, debugMode: boolean = false) {
@@ -61,9 +102,15 @@ export declare abstract class BaseService {
  *   }
  * }
  * ```
+ *
+ * @example With custom logger (for multi-service coordination)
+ * ```typescript
+ * const sharedLogger = new Logger({ debug: true, context: 'MyService' });
+ * const service = new MyService(provider, false, sharedLogger);
+ * ```
  */
 export declare abstract class LoggerBase {
     protected readonly logger: Logger;
-    constructor(debugMode?: boolean);
+    constructor(debugMode?: boolean, customLogger?: Logger);
 }
 //# sourceMappingURL=BaseService.d.ts.map

package/dist/src/services/BaseService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseService.d.ts","sourceRoot":"","sources":["../../../src/services/BaseService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,WAAW;IAGnB,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU;IAF/C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEH,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;CAO5E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,UAAU;IAC9B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEtB,SAAS,GAAE,OAAe;CAOvC"}
+{"version":3,"file":"BaseService.d.ts","sourceRoot":"","sources":["../../../src/services/BaseService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,WAAW;IAInB,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU;IAH/C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;gBAER,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe,EAAE,OAAO,CAAC,EAAE,OAAO;IAS9F;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAYjD;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;CAG/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,UAAU;IAC9B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEtB,SAAS,GAAE,OAAe,EAAE,YAAY,CAAC,EAAE,MAAM;CAY9D"}

package/dist/src/services/BatchedCacheService.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Batched Cache Service Base Class
+ *
+ * Intermediate abstraction for caches that operate on batches of items
+ * (setAll, merge) rather than individual key-value pairs. Extends
+ * AbstractCacheService with common batch operation patterns.
+ *
+ * ## Features
+ * - Batch set operations (setAll - replace all)
+ * - Batch merge operations (merge - add/update without removing)
+ * - Timestamp tracking for cache freshness
+ * - Common normalization via normalizeTokenKey()
+ *
+ * ## Subclass Responsibilities
+ * - Override setAll/merge if custom indexing needed (e.g., network-partitioned caches)
+ * - Implement getStats() for domain-specific statistics
+ * - Optionally add domain-specific lookup methods
+ *
+ * @category Services
+ * @since 5.10.0
+ * @template V - Value type stored in cache
+ * @template S - Statistics type (must extend BaseCacheStats)
+ */
+import { AbstractCacheService, BaseCacheStats } from './AbstractCacheService.js';
+/**
+ * Batched cache service with common token cache operations
+ *
+ * Provides reusable setAll/merge operations for token-like caches.
+ * Subclasses must define how to extract the key from each item.
+ *
+ * @template V - Value type stored in cache (must have a key field)
+ * @template S - Statistics type (must extend BaseCacheStats)
+ */
+export declare abstract class BatchedCacheService<V, S extends BaseCacheStats = BaseCacheStats> extends AbstractCacheService<string, V, S> {
+    /** Timestamp when cache was last populated */
+    protected lastFetchedAt: number | null;
+    constructor(debugMode?: boolean);
+    /**
+     * Normalize key for consistent cache lookups
+     *
+     * Uses the common tokenNameNormalizer for uppercase, trimmed keys.
+     *
+     * @param key - Raw key to normalize
+     * @returns Normalized key string
+     */
+    protected normalizeKey(key: string): string;
+    /**
+     * Extract the cache key from an item
+     *
+     * Subclasses must implement this to define how items are keyed.
+     * For token caches, this is typically stringifiedTokenClassKey or symbol.
+     *
+     * @param item - Item to extract key from
+     * @returns Key string for cache storage
+     */
+    protected abstract extractKey(item: V): string;
+    /**
+     * Check if cache is populated
+     *
+     * @returns True if cache has items
+     */
+    hasItems(): boolean;
+    /**
+     * Get all cached items
+     *
+     * @returns Array of cached items (empty if not cached)
+     */
+    getAllItems(): V[];
+    /**
+     * Set all items (replaces existing cache)
+     *
+     * @param items - Array of items to cache
+     */
+    setAll(items: V[]): void;
+    /**
+     * Add items to cache (merges with existing)
+     *
+     * Used for pagination - adds new items without replacing existing.
+     *
+     * @param items - Array of items to add
+     */
+    merge(items: V[]): void;
+    /**
+     * Get fetch timestamp
+     *
+     * @returns Timestamp when cache was last updated, or null if never fetched
+     */
+    getFetchTimestamp(): number | null;
+    /**
+     * Clear cache and reset timestamp
+     */
+    clear(): void;
+    /**
+     * Get item by normalized key
+     *
+     * @param key - Key to look up (will be normalized)
+     * @returns Item if found, undefined if not cached
+     */
+    getByKey(key: string): V | undefined;
+    /**
+     * Check if item exists by key
+     *
+     * @param key - Key to check (will be normalized)
+     * @returns True if item is cached
+     */
+    hasKey(key: string): boolean;
+    /**
+     * Build base statistics (helper for subclasses)
+     *
+     * Provides common stats fields that most batched caches need.
+     * Subclasses can extend this with domain-specific stats.
+     *
+     * @returns Base statistics with totalItems, isPopulated, lastFetchedAt
+     *
+     * @example Extending in subclass
+     * ```typescript
+     * public getStats(): MyCacheStats {
+     *   return {
+     *     ...this.buildBaseStats(),
+     *     tokenCount: this.cache.size, // alias
+     *     customMetric: this.calculateCustomMetric(),
+     *   };
+     * }
+     * ```
+     */
+    protected buildBaseStats(): {
+        totalItems: number;
+        isPopulated: boolean;
+        lastFetchedAt: number | null;
+    };
+}
+//# sourceMappingURL=BatchedCacheService.d.ts.map

package/dist/src/services/BatchedCacheService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchedCacheService.d.ts","sourceRoot":"","sources":["../../../src/services/BatchedCacheService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGjF;;;;;;;;GAQG;AACH,8BAAsB,mBAAmB,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,oBAAoB,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAChI,8CAA8C;IAC9C,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAElC,SAAS,GAAE,OAAe;IAItC;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI3C;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IAE9C;;;;OAIG;IACI,QAAQ,IAAI,OAAO;IAI1B;;;;OAIG;IACI,WAAW,IAAI,CAAC,EAAE;IAIzB;;;;OAIG;IACI,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAa/B;;;;;;OAMG;IACI,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAW9B;;;;OAIG;IACI,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIzC;;OAEG;IACa,KAAK,IAAI,IAAI;IAK7B;;;;;OAKG;IACI,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAK3C;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKnC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,cAAc,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAOvG"}

package/dist/src/services/BridgeableTokenCache.d.ts

@@ -20,21 +20,18 @@
  *
  * @category Services
  * @since 3.33.0
+ * @refactored 5.12.0 - Now extends NetworkKeyedCacheService for DRY compliance
  */
 import type { BridgeableToken, BridgeableNetwork } from '../bridge/types/bridgeable-token.dto.js';
-import { LoggerBase } from './BaseService.js';
+import { NetworkKeyedCacheService, type NetworkKeyedCacheStats } from './NetworkKeyedCacheService.js';
 /**
  * Cache statistics for monitoring and debugging
  */
-export interface BridgeableTokenCacheStats {
-    /** Networks with cached tokens */
-    networks: BridgeableNetwork[];
-    /** Total tokens across all networks */
+export interface BridgeableTokenCacheStats extends NetworkKeyedCacheStats<BridgeableNetwork> {
+    /** Total tokens across all networks (alias for totalItems) */
     totalTokens: number;
-    /** Token count per network */
+    /** Token count per network (alias for itemsByNetwork) */
     tokensByNetwork: Record<BridgeableNetwork, number>;
-    /** Fetch timestamps per network */
-    fetchTimestamps: Record<BridgeableNetwork, number>;
 }
 /**
  * Bridgeable Token Cache
@@ -42,6 +39,8 @@ export interface BridgeableTokenCacheStats {
  * High-performance permanent cache for bridgeable token data.
  * Tokens are organized by network for efficient lookups during bridge operations.
  *
+ * Extends NetworkKeyedCacheService for common network-keyed cache patterns.
+ *
  * @example Basic usage
  * ```typescript
  * const cache = new BridgeableTokenCache();
@@ -54,54 +53,47 @@ export interface BridgeableTokenCacheStats {
  *   const tokens = cache.getAll('ETHEREUM');
  * }
  *
- * // Get specific token
+ * // Get specific token by symbol
  * const gala = cache.getBySymbol('ETHEREUM', 'GALA');
+ *
+ * // Get specific token by tokenId
+ * const token = cache.getByTokenId('ETHEREUM', 'GALA|Unit|none|none');
  * ```
  */
-export declare class BridgeableTokenCache extends LoggerBase {
-    /** Primary index: network → (symbol → token) */
-    private readonly cache;
-    /** Secondary index: network → (tokenId → token) for O(1) tokenId lookups */
-    private readonly tokenIdIndex;
-    /** Fetch timestamps per network */
-    private readonly fetchTimestamps;
+export declare class BridgeableTokenCache extends NetworkKeyedCacheService<BridgeableToken, BridgeableNetwork, BridgeableTokenCacheStats> {
     constructor(debugMode?: boolean);
     /**
-     * Normalize symbol for consistent cache keys
+     * Extract the primary key from a bridgeable token (symbol)
      *
-     * @param symbol - Raw token symbol
-     * @returns Normalized symbol (uppercase, trimmed)
+     * @param token - Bridgeable token
+     * @returns Token symbol as primary key
      */
-    private normalizeSymbol;
+    protected extractPrimaryKey(token: BridgeableToken): string;
     /**
-     * Normalize tokenId for consistent cache keys
+     * Extract the secondary key from a bridgeable token (tokenId)
      *
-     * @param tokenId - Stringified TokenClassKey (e.g., "GALA|Unit|none|none")
-     * @returns Normalized tokenId (uppercase, trimmed)
+     * @param token - Bridgeable token
+     * @returns stringifiedTokenClassKey as secondary key
      */
-    private normalizeTokenId;
+    protected extractSecondaryKey(token: BridgeableToken): string;
     /**
-     * Check if tokens for a network are cached
+     * Get a specific token by symbol
      *
-     * @param network - Network to check
-     * @returns True if network has cached tokens
+     * @param network - Network to search
+     * @param symbol - Token symbol (case-insensitive)
+     * @returns Bridgeable token or undefined if not found
      */
-    has(network: BridgeableNetwork): boolean;
+    getBySymbol(network: BridgeableNetwork, symbol: string): BridgeableToken | undefined;
     /**
-     * Get all tokens for a network
+     * Get a token by its stringified TokenClassKey (tokenId)
      *
-     * @param network - Network to get tokens for
-     * @returns Array of bridgeable tokens (empty if not cached)
-     */
-    getAll(network: BridgeableNetwork): BridgeableToken[];
-    /**
-     * Get a specific token by symbol
+     * Uses the secondary tokenId index for O(1) lookup performance.
      *
      * @param network - Network to search
-     * @param symbol - Token symbol (case-insensitive)
+     * @param tokenId - Stringified TokenClassKey (e.g., "GALA|Unit|none|none")
      * @returns Bridgeable token or undefined if not found
      */
-    getBySymbol(network: BridgeableNetwork, symbol: string): BridgeableToken | undefined;
+    getByTokenId(network: BridgeableNetwork, tokenId: string): BridgeableToken | undefined;
     /**
      * Get contract address for a token on a network
      *
@@ -110,48 +102,6 @@ export declare class BridgeableTokenCache extends LoggerBase {
      * @returns Contract address or undefined if not found
      */
     getContractAddress(network: BridgeableNetwork, symbol: string): string | undefined;
-    /**
-     * Set tokens for a network (replaces all existing tokens)
-     *
-     * @param network - Network to set tokens for
-     * @param tokens - Array of bridgeable tokens
-     */
-    set(network: BridgeableNetwork, tokens: BridgeableToken[]): void;
-    /**
-     * Add tokens to a network cache (merges with existing)
-     *
-     * Used for pagination - adds new tokens without replacing existing.
-     *
-     * @param network - Network to add tokens to
-     * @param tokens - Array of bridgeable tokens to add
-     */
-    merge(network: BridgeableNetwork, tokens: BridgeableToken[]): void;
-    /**
-     * Get fetch timestamp for a network
-     *
-     * @param network - Network to get timestamp for
-     * @returns Timestamp when network was last fetched, or undefined if never fetched
-     */
-    getFetchTimestamp(network: BridgeableNetwork): number | undefined;
-    /**
-     * Get cache statistics
-     *
-     * @returns Cache statistics including token counts and timestamps
-     */
-    getStats(): BridgeableTokenCacheStats;
-    /**
-     * Clear cache for a network or all networks
-     *
-     * @param network - Optional network to clear (clears all if not provided)
-     */
-    clear(network?: BridgeableNetwork): void;
-    /**
-     * Get token count for a network
-     *
-     * @param network - Network to count tokens for
-     * @returns Number of cached tokens
-     */
-    size(network: BridgeableNetwork): number;
     /**
      * Check if a token is bridgeable to a network
      *
@@ -161,26 +111,10 @@ export declare class BridgeableTokenCache extends LoggerBase {
      */
     isTokenBridgeable(network: BridgeableNetwork, symbol: string): boolean;
     /**
-     * Get a token by its stringified TokenClassKey (tokenId)
-     *
-     * Uses the secondary tokenId index for O(1) lookup performance.
-     *
-     * @param network - Network to search
-     * @param tokenId - Stringified TokenClassKey (e.g., "GALA|Unit|none|none")
-     * @returns Bridgeable token or undefined if not found
-     */
-    getByTokenId(network: BridgeableNetwork, tokenId: string): BridgeableToken | undefined;
-    /**
-     * Get all cached networks
-     *
-     * @returns Array of networks with cached tokens
-     */
-    getCachedNetworks(): BridgeableNetwork[];
-    /**
-     * Dump entire cache for debugging
+     * Get cache statistics
      *
-     * @returns Full cache contents
+     * @returns Cache statistics including token counts and timestamps
      */
-    dump(): Record<BridgeableNetwork, BridgeableToken[]>;
+    getStats(): BridgeableTokenCacheStats;
 }
 //# sourceMappingURL=BridgeableTokenCache.d.ts.map

package/dist/src/services/BridgeableTokenCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BridgeableTokenCache.d.ts","sourceRoot":"","sources":["../../../src/services/BridgeableTokenCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAClG,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,kCAAkC;IAClC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IACnD,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuD;IAE7E,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuD;IAEpF,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;gBAErD,SAAS,GAAE,OAAe;IAOtC;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO;IAKxC;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,EAAE;IAKrD;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKpF;;;;;;OAMG;IACH,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASlF;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAqBhE;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IA6BlE;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS;IAIjE;;;;OAIG;IACH,QAAQ,IAAI,yBAAyB;IAoBrC;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAcxC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAIxC;;;;;;OAMG;IACH,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAItE;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKtF;;;;OAIG;IACH,iBAAiB,IAAI,iBAAiB,EAAE;IAIxC;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAC,iBAAiB,EAAE,eAAe,EAAE,CAAC;CAWrD"}
+{"version":3,"file":"BridgeableTokenCache.d.ts","sourceRoot":"","sources":["../../../src/services/BridgeableTokenCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAClG,OAAO,EAAE,wBAAwB,EAAE,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEtG;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB,CAAC,iBAAiB,CAAC;IAC1F,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;CACpD;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,oBAAqB,SAAQ,wBAAwB,CAChE,eAAe,EACf,iBAAiB,EACjB,yBAAyB,CAC1B;gBACa,SAAS,GAAE,OAAe;IAItC;;;;;OAKG;IACH,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM;IAI3D;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM;IAI7D;;;;;;OAMG;IACI,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI3F;;;;;;;;OAQG;IACI,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI7F;;;;;;OAMG;IACI,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASzF;;;;;;OAMG;IACI,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAI7E;;;;OAIG;IACI,QAAQ,IAAI,yBAAyB;CAU7C"}