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

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

@@ -0,0 +1,269 @@
+/**
+ * Moderator Invite Service
+ *
+ * Handles all moderator invite operations including creating/revoking invites,
+ * claiming invites, listing invites, and managing moderated tokens.
+ *
+ * @category Services
+ * @since 5.7.0
+ */
+import { HttpClient } from '../utils/http';
+import { StreamTokenServiceBase } from './StreamTokenServiceBase';
+import type { JwtAuth } from '../auth/JwtAuth';
+import { CreateModeratorInviteOptions, ClaimModeratorInviteOptions, ListModeratorInvitesOptions, GetModeratedTokensOptions, UpdateInviteRoleOptions, CreateModeratorInviteResult, ClaimModeratorInviteResult, ModeratorInviteListResult, ModeratedTokensResult, UpdateInviteRoleResult, PublicInviteInfo } from '../types/moderator.dto';
+/**
+ * Moderator Invite Service Class
+ *
+ * Provides methods for:
+ * - Creating and revoking moderator invites (token owner)
+ * - Claiming invites (moderators)
+ * - Listing invites for a token (owner)
+ * - Getting tokens a user moderates (moderator /studio dashboard)
+ * - Getting invite details by code (public - for claim page)
+ *
+ * All endpoints require JWT authentication except getInviteByCode which is public.
+ *
+ * @remarks
+ * **Case Normalization**: Token names are automatically normalized to lowercase
+ * in all requests and responses for consistency.
+ *
+ * **Security**: This service uses JWT authentication via Authorization header.
+ * When using from browser clients, ensure tokens are stored securely
+ * (e.g., in memory, not localStorage) to prevent XSS token theft.
+ *
+ * @example
+ * ```typescript
+ * const moderatorService = new ModeratorService(httpClient, undefined, jwtAuth, true);
+ *
+ * // Create an invite (as token owner)
+ * const invite = await moderatorService.createInvite({
+ *   tokenName: 'mytoken',
+ *   role: 'MODERATOR',
+ *   description: 'John - Friday shows'
+ * });
+ * console.log('Share this link:', invite.invite.inviteUrl);
+ *
+ * // Claim an invite (as moderator)
+ * const claimed = await moderatorService.claimInvite({
+ *   inviteCode: 'abc123...'
+ * });
+ * console.log('Now moderating:', claimed.token.tokenName);
+ *
+ * // Get tokens user moderates (for /studio dashboard)
+ * const moderated = await moderatorService.getModeratedTokens({ page: 1, limit: 20 });
+ * console.log('Moderating', moderated.tokens.length, 'tokens');
+ * ```
+ */
+export declare class ModeratorService extends StreamTokenServiceBase {
+    constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth, debugMode?: boolean);
+    /**
+     * Validate moderator role
+     */
+    private validateRole;
+    /**
+     * Validate invite code format
+     */
+    private validateInviteCodeFormat;
+    /**
+     * Validate invite scope
+     */
+    private validateInviteScope;
+    /**
+     * Create a moderator invite for a token
+     *
+     * JWT-authenticated endpoint - requires the authenticated user to be the token owner.
+     *
+     * Supports two invite scopes:
+     * - **TOKEN** (default): Access to a specific token only. `tokenName` is required.
+     * - **ALL_OWNER_TOKENS**: Blanket access to ALL tokens owned by the inviter.
+     *   The moderator gains access to current and future tokens. `tokenName` should be omitted.
+     *
+     * @param options Create options including inviteScope, tokenName (for TOKEN scope), role, and optional description/expiration
+     * @returns Created invite data including the invite URL for sharing
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if JWT is not configured
+     *
+     * @example
+     * ```typescript
+     * // Create a moderator invite for a specific token (TOKEN scope - default)
+     * const result = await moderatorService.createInvite({
+     *   tokenName: 'mytoken',
+     *   role: 'MODERATOR',
+     *   description: 'John - Friday evening shows'
+     * });
+     * console.log('Share link:', result.invite.inviteUrl);
+     *
+     * // Create a blanket invite for ALL tokens (ALL_OWNER_TOKENS scope)
+     * const blanketResult = await moderatorService.createInvite({
+     *   inviteScope: 'ALL_OWNER_TOKENS',
+     *   role: 'MANAGER',
+     *   description: 'Production team - full access'
+     * });
+     *
+     * // Create invite with expiration
+     * const result = await moderatorService.createInvite({
+     *   tokenName: 'mytoken',
+     *   role: 'TECHNICAL_PRODUCER',
+     *   expiresAt: '2025-12-31T23:59:59Z'
+     * });
+     * ```
+     */
+    createInvite(options: CreateModeratorInviteOptions): Promise<CreateModeratorInviteResult>;
+    /**
+     * List all invites for a token (owner only)
+     *
+     * JWT-authenticated endpoint - requires the authenticated user to be the token owner.
+     *
+     * @param options List options including tokenName and optional status filter/pagination
+     * @returns Paginated list of invites
+     * @throws ValidationError if token name is invalid
+     * @throws ConfigurationError if JWT is not configured
+     *
+     * @example
+     * ```typescript
+     * // Get all invites
+     * const result = await moderatorService.listInvites({
+     *   tokenName: 'mytoken'
+     * });
+     * console.log('Total invites:', result.meta.totalItems);
+     *
+     * // Filter by status
+     * const pending = await moderatorService.listInvites({
+     *   tokenName: 'mytoken',
+     *   status: 'PENDING'
+     * });
+     *
+     * // Paginate
+     * const page2 = await moderatorService.listInvites({
+     *   tokenName: 'mytoken',
+     *   page: 2,
+     *   limit: 10
+     * });
+     * ```
+     */
+    listInvites(options: ListModeratorInvitesOptions): Promise<ModeratorInviteListResult>;
+    /**
+     * Revoke a moderator invite (owner only)
+     *
+     * JWT-authenticated endpoint - requires the authenticated user to be the token owner.
+     * This revokes the invite, preventing it from being claimed. If already claimed,
+     * the moderator loses access.
+     *
+     * @param inviteId The ID of the invite to revoke
+     * @throws ValidationError if invite ID is invalid
+     * @throws ConfigurationError if JWT is not configured
+     * @throws Error if invite not found (404) or not authorized (403)
+     *
+     * @example
+     * ```typescript
+     * await moderatorService.revokeInvite(123);
+     * console.log('Invite revoked');
+     * ```
+     */
+    revokeInvite(inviteId: number): Promise<void>;
+    /**
+     * Update the role of a moderator invite (owner only)
+     *
+     * JWT-authenticated endpoint - requires the authenticated user to be the token owner.
+     * This changes the role granted by the invite. For claimed invites, the moderator's
+     * effective permissions change immediately (enforced at runtime).
+     *
+     * @param options Update options including inviteId and new role
+     * @returns Updated invite data
+     * @throws ValidationError if parameters are invalid
+     * @throws ConfigurationError if JWT is not configured
+     * @throws Error if invite not found (404) or not authorized (403)
+     *
+     * @example
+     * ```typescript
+     * // Upgrade a moderator to manager
+     * const result = await moderatorService.updateInviteRole({
+     *   inviteId: 123,
+     *   role: 'MANAGER'
+     * });
+     * console.log('Updated role:', result.invite.role);
+     *
+     * // Downgrade a manager to moderator
+     * await moderatorService.updateInviteRole({
+     *   inviteId: 456,
+     *   role: 'MODERATOR'
+     * });
+     * ```
+     */
+    updateInviteRole(options: UpdateInviteRoleOptions): Promise<UpdateInviteRoleResult>;
+    /**
+     * Claim a moderator invite
+     *
+     * JWT-authenticated endpoint - requires the user to be logged in.
+     * The authenticated user's wallet becomes the moderator for the token(s).
+     *
+     * Returns different result structure based on invite scope:
+     * - **TOKEN** scope: Returns `{ token }` with the specific token details
+     * - **ALL_OWNER_TOKENS** scope: Returns `{ blanketAccess }` with scope/role info
+     *
+     * @param options Claim options including the invite code
+     * @returns For TOKEN scope: `{ token }`. For ALL_OWNER_TOKENS: `{ blanketAccess }`
+     * @throws ValidationError if invite code is invalid or invite already claimed/revoked/expired
+     * @throws ConfigurationError if JWT is not configured
+     *
+     * @example
+     * ```typescript
+     * const result = await moderatorService.claimInvite({
+     *   inviteCode: 'abc123def456...'
+     * });
+     *
+     * // Check which type of invite was claimed
+     * if (result.token) {
+     *   // TOKEN scope - specific token access
+     *   console.log('Now moderating:', result.token.tokenName);
+     *   console.log('Role:', result.token.role);
+     * } else if (result.blanketAccess) {
+     *   // ALL_OWNER_TOKENS scope - blanket access to all owner's tokens
+     *   console.log('Granted blanket access as:', result.blanketAccess.role);
+     * }
+     * ```
+     */
+    claimInvite(options: ClaimModeratorInviteOptions): Promise<ClaimModeratorInviteResult>;
+    /**
+     * Get all tokens the current user moderates
+     *
+     * JWT-authenticated endpoint. Returns all tokens where the authenticated
+     * user has claimed a moderator invite and has active access.
+     * Used for the /studio dashboard.
+     *
+     * @param options Optional pagination options
+     * @returns Paginated list of moderated tokens
+     * @throws ConfigurationError if JWT is not configured
+     *
+     * @example
+     * ```typescript
+     * const result = await moderatorService.getModeratedTokens();
+     * console.log('Moderating', result.meta.totalItems, 'tokens');
+     *
+     * for (const token of result.tokens) {
+     *   console.log(`- ${token.tokenName} (${token.role})`);
+     * }
+     * ```
+     */
+    getModeratedTokens(options?: GetModeratedTokensOptions): Promise<ModeratedTokensResult>;
+    /**
+     * Get invite details by code (public endpoint)
+     *
+     * This is a public endpoint used by the frontend claim page to display
+     * invite information before the user logs in to claim.
+     *
+     * @param inviteCode The invite code from the magic link URL
+     * @returns Public invite information (token name, role, inviter info)
+     * @throws ValidationError if invite code format is invalid
+     * @throws Error if invite not found (404)
+     *
+     * @example
+     * ```typescript
+     * const info = await moderatorService.getInviteByCode('abc123def456...');
+     * console.log(`Invited to moderate ${info.tokenName} as ${info.role}`);
+     * console.log(`Invited by: ${info.invitedBy.fullName || info.invitedBy.address}`);
+     * ```
+     */
+    getInviteByCode(inviteCode: string): Promise<PublicInviteInfo>;
+}
+//# sourceMappingURL=ModeratorService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ModeratorService.d.ts","sourceRoot":"","sources":["../../../src/services/ModeratorService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAO3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAiBjB,MAAM,wBAAwB,CAAC;AAOhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,gBAAiB,SAAQ,sBAAsB;gBAExD,IAAI,EAAE,UAAU,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,EACjB,SAAS,GAAE,OAAe;IAK5B;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAShC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,YAAY,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAuD/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,WAAW,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAmC3F;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAenD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA2BzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,WAAW,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC;IA2B5F;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,kBAAkB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA2B7F;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAYrE"}

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

@@ -21,6 +21,7 @@ import type { Socket } from 'socket.io-client';
 import type { SwapEventCallback, SubscribeSwapOptions, SwapMonitorConfig, SwapMonitorHealth, CleanupFunction } from '../types/swap-monitor.dto';
 import type { CompositePoolDataResult } from '../types/composite-pool.dto';
 import { Logger } from '../utils/Logger';
+import { LoggerBase } from './BaseService';
 import type { DexQuoteService } from './DexQuoteService';
 /**
  * Manages real-time DEX swap monitoring across multiple pools
@@ -30,11 +31,10 @@ import type { DexQuoteService } from './DexQuoteService';
  *
  * @internal
  */
-export declare class MultiPoolStateManager {
+export declare class MultiPoolStateManager extends LoggerBase {
     private socket;
     private socketReady;
     private readonly config;
-    private readonly logger;
     private readonly metrics;
     private readonly eventExtractor;
     private readonly quoteService;
@@ -50,10 +50,8 @@ export declare class MultiPoolStateManager {
     private handleSwapEvent;
     /** Background warming loop interval handle */
     private warmingIntervalHandle;
-    /** Reconnection state tracking */
-    private reconnectAttempts;
-    private maxReconnectAttempts;
-    private reconnectDelayMs;
+    /** Reconnection manager for handling connection failures */
+    private reconnectionManager;
     constructor(socket: Socket | Promise<Socket>, fetchPoolFn: (poolKey: string) => Promise<CompositePoolDataResult>, quoteService: DexQuoteService, config?: SwapMonitorConfig, logger?: Logger);
     /**
      * Subscribe to swap events for real-time monitoring

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

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

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

@@ -0,0 +1,185 @@
+/**
+ * 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/src/services/NetworkKeyedCacheService.d.ts.map

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