@gala-chain/launchpad-sdk 5.0.4-beta.6 → 5.0.4-beta.60

package/dist/services/WrappableTokenService.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Wrappable Token Service
+ *
+ * Service for fetching and caching wrappable tokens from the DEX API.
+ * Provides methods to query which tokens can be wrapped/unwrapped
+ * and retrieves their counterpart tokens dynamically.
+ *
+ * ## Key Features
+ * - Dynamic token discovery (fetches from DEX API)
+ * - Permanent caching for token metadata
+ * - Separate balance methods for user-specific queries
+ *
+ * ## Caching Strategy
+ * - Token metadata is always cached (fetchWrappableTokens, fetchAllWrappableTokens)
+ * - Balance methods never cache (fetchWrappableTokenBalances, fetchAllWrappableTokenBalances)
+ * - Cache persists for entire SDK lifetime
+ *
+ * @category Services
+ * @since 4.0.18
+ */
+import type { TokenId } from '../types/common.js';
+import type { FetchWrappableTokensOptions, FetchWrappableTokensResult, IsTokenWrappableResult, WrappableToken, WrappableTokenApiResponse, WrappableTokenCacheStats } from '../types/wrappable-token.dto.js';
+import type { HttpClient } from '../utils/http.js';
+import { AbstractTokenFetchService } from './AbstractTokenFetchService.js';
+/**
+ * WrappableTokenService
+ *
+ * Fetches and caches wrappable token information from the DEX API.
+ * Provides efficient lookups for wrap/unwrap operations.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const service = new WrappableTokenService(dexApiHttp, true);
+ *
+ * // Fetch all wrappable tokens (cached)
+ * const result = await service.fetchAllWrappableTokens();
+ * console.log(`Found ${result.tokenCount} tokens`);
+ *
+ * // Fetch with balance data for a specific address (not cached)
+ * const withBalances = await service.fetchAllWrappableTokenBalances('eth|0x1234...');
+ * console.log(`Found ${withBalances.tokenCount} tokens with balances`);
+ *
+ * // Check if a specific token is wrappable (by tokenId)
+ * const isWrappable = await service.isTokenWrappable('$MUSIC|Unit|none|none');
+ * console.log(`MUSIC wrappable: ${isWrappable.isWrappable}`);
+ *
+ * // Get wrap counterpart
+ * const counterpart = await service.getWrapCounterpart('$MUSIC|Unit|none|none');
+ * console.log(`MUSIC counterpart: ${counterpart?.symbol}`); // GMUSIC
+ * ```
+ */
+export declare class WrappableTokenService extends AbstractTokenFetchService<WrappableTokenApiResponse, WrappableToken> {
+    private readonly cache;
+    constructor(dexApiHttp: HttpClient, debugMode?: boolean);
+    /**
+     * Build API request parameters for wrappable tokens
+     *
+     * @param _context - Unused context parameter (required by base class)
+     * @returns Query parameters with wrappable filter
+     */
+    protected buildApiParams(_context?: Record<string, unknown>): Record<string, string | number | boolean>;
+    /**
+     * Transform API response tokens to SDK format
+     *
+     * @param apiTokens - Raw API response tokens
+     * @returns Array of transformed wrappable tokens
+     */
+    protected transformApiResponse(apiTokens: WrappableTokenApiResponse[]): WrappableToken[];
+    /**
+     * Fetch wrappable tokens with pagination (metadata only, cached)
+     *
+     * For user-specific balance data, use fetchWrappableTokenBalances() instead.
+     *
+     * @param options - Fetch options including pagination parameters
+     * @returns Promise resolving to fetch result with tokens array
+     * @throws NetworkError if API request fails
+     */
+    fetchWrappableTokens(options?: FetchWrappableTokensOptions): Promise<FetchWrappableTokensResult>;
+    /**
+     * Fetch ALL wrappable tokens (auto-pagination, cached)
+     *
+     * Returns cached data if available, otherwise fetches from API.
+     * For user-specific balance data, use fetchAllWrappableTokenBalances() instead.
+     *
+     * @returns Promise resolving to fetch result with all tokens
+     * @throws NetworkError if API request fails
+     */
+    fetchAllWrappableTokens(): Promise<FetchWrappableTokensResult>;
+    /**
+     * Get a wrappable token by tokenId
+     *
+     * Uses cache for efficient lookup. If cache not populated, fetches first.
+     *
+     * @param tokenId - Token identifier (pipe-delimited or TokenClassKey)
+     * @returns Promise resolving to wrappable token or undefined
+     */
+    getWrappableToken(tokenId: TokenId): Promise<WrappableToken | undefined>;
+    /**
+     * Get the wrap counterpart for a token
+     *
+     * @param tokenId - Token identifier (pipe-delimited or TokenClassKey)
+     * @returns Promise resolving to counterpart token or undefined
+     *
+     * @example
+     * ```typescript
+     * // Get GMUSIC from MUSIC
+     * const counterpart = await service.getWrapCounterpart('$MUSIC|Unit|none|none');
+     * console.log(counterpart?.symbol); // "GMUSIC"
+     * ```
+     */
+    getWrapCounterpart(tokenId: TokenId): Promise<WrappableToken | undefined>;
+    /**
+     * Check if a token is wrappable
+     *
+     * @param tokenId - Token identifier (pipe-delimited or TokenClassKey)
+     * @returns Promise resolving to wrappability result
+     */
+    isTokenWrappable(tokenId: TokenId): Promise<IsTokenWrappableResult>;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache statistics including token count and timestamp
+     */
+    getCacheStats(): WrappableTokenCacheStats;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=WrappableTokenService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WrappableTokenService.d.ts","sourceRoot":"","sources":["../../src/services/WrappableTokenService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,qBAAsB,SAAQ,yBAAyB,CAClE,yBAAyB,EACzB,cAAc,CACf;IACC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;gBAEhC,UAAU,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;IAK9D;;;;;OAKG;IACH,SAAS,CAAC,cAAc,CACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAI5C;;;;;OAKG;IACH,SAAS,CAAC,oBAAoB,CAAC,SAAS,EAAE,yBAAyB,EAAE,GAAG,cAAc,EAAE;IAwCxF;;;;;;;;OAQG;IACG,oBAAoB,CACxB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;IAoCtC;;;;;;;;OAQG;IACG,uBAAuB,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAqBpE;;;;;;;OAOG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAqB9E;;;;;;;;;;;;OAYG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAO/E;;;;;OAKG;IACG,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA6BzE;;;;OAIG;IACH,aAAa,IAAI,wBAAwB;IAIzC;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/dist/services/__mocks__/logger.mock.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mock Logger for testing
+ * Captures all logging calls for assertion in tests
+ * Provides duck-type compatibility with Logger class
+ */
+import type { Logger } from '../../utils/Logger';
+/**
+ * MockLogger interface - extends Logger with test-specific properties
+ * Provides access to captured log calls for assertions
+ */
+export interface MockLoggerInterface extends Logger {
+    debugCalls: string[];
+    infoCalls: string[];
+    warnCalls: string[];
+    errorCalls: string[];
+}
+/**
+ * Create a new MockLogger instance
+ * Constructor that returns a MockLogger-compatible mock
+ */
+export declare const MockLogger: {
+    new (): MockLoggerInterface;
+};
+//# sourceMappingURL=logger.mock.d.ts.map

package/dist/services/__mocks__/logger.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.mock.d.ts","sourceRoot":"","sources":["../../../src/services/__mocks__/logger.mock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAC,MAAM,oBAAoB,CAAC;AA2DhD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,MAAM;IACjD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAiC;IACtD,QAAQ,mBAAmB,CAAC;CAC7B,CAAC"}

package/dist/services/shared/cache-helpers.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Cache Helpers
+ *
+ * Shared utilities for caching operations across services.
+ * Eliminates duplicate cache-check-fetch-store patterns.
+ *
+ * @category Services
+ * @since 6.4.0
+ */
+import type { Logger } from '../../utils/Logger';
+/**
+ * Options for withCache wrapper
+ */
+export interface WithCacheOptions<K = string> {
+    /** Logger instance for debug output */
+    logger?: Logger;
+    /** Time-to-live in milliseconds (optional, for TTL-based caches) */
+    ttlMs?: number;
+    /** Key generator function (defaults to identity for string keys) */
+    keyGenerator?: (input: K) => string;
+    /** Whether to cache null/undefined results (default: false) */
+    cacheNullish?: boolean;
+}
+/**
+ * Simple in-memory cache with optional TTL support
+ *
+ * Used internally by cache helpers and can be used directly for
+ * custom caching scenarios.
+ *
+ * @typeParam V - Value type stored in cache
+ *
+ * @example
+ * ```typescript
+ * const cache = new SimpleCache<UserData>(60000); // 1 minute TTL
+ * cache.set('user:123', userData);
+ * const cached = cache.get('user:123'); // Returns userData or undefined if expired
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare class SimpleCache<V> {
+    private defaultTtlMs;
+    private cache;
+    /**
+     * Create a new SimpleCache
+     *
+     * @param defaultTtlMs - Default TTL in milliseconds (0 = no expiration)
+     */
+    constructor(defaultTtlMs?: number);
+    /**
+     * Get a value from cache
+     *
+     * @param key - Cache key
+     * @returns Cached value or undefined if not found/expired
+     */
+    get(key: string): V | undefined;
+    /**
+     * Set a value in cache
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttlMs - Optional TTL override (uses default if not specified)
+     */
+    set(key: string, value: V, ttlMs?: number): void;
+    /**
+     * Check if a key exists and is not expired
+     *
+     * @param key - Cache key
+     * @returns True if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from cache
+     *
+     * @param key - Cache key
+     */
+    delete(key: string): void;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Get cache size
+     */
+    get size(): number;
+}
+/**
+ * Wraps an async fetch operation with caching
+ *
+ * Handles the cache-check-fetch-store pattern in a single utility call.
+ *
+ * @typeParam V - The expected value type
+ * @param key - Cache key (string)
+ * @param fetcher - Async function that fetches the data if not cached
+ * @param cache - Cache instance (Map-like interface with get/set)
+ * @param options - Optional configuration
+ * @returns Promise resolving to cached or freshly fetched data
+ *
+ * @example Basic usage with Map
+ * ```typescript
+ * const cache = new Map<string, UserData>();
+ * const user = await withCache(
+ *   `user:${userId}`,
+ *   () => fetchUser(userId),
+ *   cache
+ * );
+ * ```
+ *
+ * @example With TTL-based cache
+ * ```typescript
+ * const cache = new SimpleCache<PoolData>(60000); // 1 minute TTL
+ * const pool = await withCache(
+ *   `pool:${tokenName}`,
+ *   () => fetchPool(tokenName),
+ *   cache,
+ *   { logger: this.logger }
+ * );
+ * ```
+ *
+ * @example With key generator
+ * ```typescript
+ * const user = await withCache(
+ *   { userId, includeProfile: true },
+ *   () => fetchUserWithProfile(userId),
+ *   cache,
+ *   { keyGenerator: (opts) => `user:${opts.userId}:${opts.includeProfile}` }
+ * );
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function withCache<V, K = string>(key: K, fetcher: () => Promise<V>, cache: {
+    get: (key: string) => V | undefined;
+    set: (key: string, value: V) => void;
+}, options?: WithCacheOptions<K>): Promise<V>;
+/**
+ * Creates a memoized version of an async function with caching
+ *
+ * Useful for creating cached service methods without manual cache management.
+ *
+ * @typeParam A - Argument type (used for cache key generation)
+ * @typeParam R - Return type
+ * @param fn - Function to memoize
+ * @param keyFn - Function to generate cache key from arguments
+ * @param ttlMs - Time-to-live in milliseconds (0 = no expiration)
+ * @returns Memoized function
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   // Create memoized fetcher with 5 minute TTL
+ *   private fetchUserCached = memoizeAsync(
+ *     (userId: string) => this.fetchUserFromApi(userId),
+ *     (userId) => `user:${userId}`,
+ *     300000 // 5 minutes
+ *   );
+ *
+ *   async getUser(userId: string) {
+ *     return this.fetchUserCached(userId);
+ *   }
+ * }
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function memoizeAsync<A, R>(fn: (arg: A) => Promise<R>, keyFn: (arg: A) => string, ttlMs?: number): (arg: A) => Promise<R>;
+/**
+ * Creates a cache key from multiple parts
+ *
+ * Utility for building consistent cache keys across services.
+ *
+ * @param parts - Key parts to join
+ * @param separator - Separator character (default: ':')
+ * @returns Joined cache key string
+ *
+ * @example
+ * ```typescript
+ * const key = buildCacheKey('user', userId, 'profile');
+ * // Result: 'user:abc123:profile'
+ *
+ * const key = buildCacheKey('pool', tokenName, 'stats', { separator: '/' });
+ * // Result: 'pool/mytoken/stats'
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function buildCacheKey(...parts: (string | number | boolean)[]): string;
+//# sourceMappingURL=cache-helpers.d.ts.map

package/dist/services/shared/cache-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-helpers.d.ts","sourceRoot":"","sources":["../../../src/services/shared/cache-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM;IAC1C,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACpC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW,CAAC,CAAC;IAQZ,OAAO,CAAC,YAAY;IAPhC,OAAO,CAAC,KAAK,CAAuD;IAEpE;;;;OAIG;gBACiB,YAAY,GAAE,MAAU;IAE5C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAa/B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAShD;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,EAC3C,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;CAAE,EACpF,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAChC,OAAO,CAAC,CAAC,CAAC,CAqCZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAC/B,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,EACzB,KAAK,GAAE,MAAU,GAChB,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAMxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,GAAG,MAAM,CAQ7E"}

package/dist/services/shared/http-helpers.d.ts

@@ -0,0 +1,146 @@
+/**
+ * HTTP Helpers
+ *
+ * Shared utilities for HTTP operations across services.
+ * Eliminates duplicate try/catch error handling patterns found in 30+ methods.
+ *
+ * @category Services
+ * @since 6.4.0
+ */
+import type { Logger } from '../../utils/Logger';
+/**
+ * Backend response shape accepted by error handling wrappers.
+ * More lenient than InternalApiResponse - accepts optional message field.
+ * @internal
+ */
+export interface BackendResponseLike<T = unknown> {
+    status: number;
+    error: boolean;
+    message?: string;
+    data?: T;
+}
+/**
+ * Options for withErrorHandling wrapper
+ */
+export interface WithErrorHandlingOptions {
+    /** Context message for error (e.g., "Failed to fetch pools") */
+    errorContext?: string;
+    /** Logger instance for debug output */
+    logger?: Logger;
+    /** Log level for operation start/end (debug only in debug mode) */
+    debugLogEnabled?: boolean;
+}
+/**
+ * Wraps an async HTTP operation with standardized error handling
+ *
+ * Handles try/catch pattern with optional logging in a single utility call.
+ *
+ * @typeParam T - The expected response data type
+ * @param operation - Async function that performs the HTTP operation
+ * @param options - Optional configuration for error handling
+ * @returns Promise resolving to the extracted data
+ *
+ * @example Basic usage
+ * ```typescript
+ * const data = await withErrorHandling(
+ *   () => this.http.get<InternalApiResponse<UserData>>(endpoint),
+ *   { errorContext: 'Failed to fetch user data' }
+ * );
+ * ```
+ *
+ * @example With logging
+ * ```typescript
+ * const data = await withErrorHandling(
+ *   () => this.http.post<InternalApiResponse<Result>>(endpoint, body),
+ *   { errorContext: 'Failed to create resource', logger: this.logger, debugLogEnabled: true }
+ * );
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function withErrorHandling<T>(operation: () => Promise<BackendResponseLike<T>>, options?: WithErrorHandlingOptions): Promise<T>;
+/**
+ * Wraps an async HTTP operation that returns raw data (no API wrapper)
+ *
+ * For operations that don't use the InternalApiResponse wrapper.
+ *
+ * @typeParam T - The expected response data type
+ * @param operation - Async function that performs the HTTP operation
+ * @param options - Optional configuration for error handling
+ * @returns Promise resolving to the raw response data
+ *
+ * @example
+ * ```typescript
+ * const data = await withErrorHandlingRaw(
+ *   () => this.http.get<UserData>(endpoint),
+ *   { errorContext: 'Failed to fetch user data', logger: this.logger }
+ * );
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function withErrorHandlingRaw<T>(operation: () => Promise<T>, options?: WithErrorHandlingOptions): Promise<T>;
+/**
+ * Wraps an async HTTP operation and returns the validated full response
+ *
+ * Unlike withErrorHandling which extracts response.data, this returns the full
+ * InternalApiResponse after validation. Useful when you need access to response
+ * properties like count, total, or status.
+ *
+ * @typeParam T - The expected response data type
+ * @param operation - Async function that performs the HTTP operation
+ * @param options - Optional configuration for error handling
+ * @returns Promise resolving to the full validated response
+ *
+ * @example
+ * ```typescript
+ * const response = await withResponseValidation(
+ *   () => this.http.get<InternalApiResponse<PoolsData>>(endpoint, params),
+ *   { errorContext: 'Failed to fetch pools' }
+ * );
+ * const pools = normalizePoolResponse(response.data!);
+ * const total = response.data!.count ?? 0;
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare function withResponseValidation<T>(operation: () => Promise<BackendResponseLike<T>>, options?: WithErrorHandlingOptions): Promise<BackendResponseLike<T>>;
+/**
+ * Type for HTTP method functions
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/**
+ * Creates a type-safe HTTP request executor with error handling
+ *
+ * Factory function for creating reusable HTTP executors within services.
+ * Reduces boilerplate when services make many HTTP calls with similar patterns.
+ *
+ * @param http - HttpClient instance
+ * @param logger - Optional logger for debug output
+ * @returns Executor function for making HTTP requests
+ *
+ * @example
+ * ```typescript
+ * class MyService extends BaseService {
+ *   private execute = createHttpExecutor(this.http, this.logger);
+ *
+ *   async getUser(id: string) {
+ *     return this.execute<UserData>('get', `/users/${id}`, 'Failed to get user');
+ *   }
+ *
+ *   async createUser(data: UserInput) {
+ *     return this.execute<UserData>('post', '/users', 'Failed to create user', data);
+ *   }
+ * }
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function createHttpExecutor(http: {
+    get: <T>(url: string, params?: Record<string, unknown>, headers?: Record<string, string>) => Promise<T>;
+    post: <T>(url: string, data?: unknown, headers?: Record<string, string>) => Promise<T>;
+    put: <T>(url: string, data?: unknown, headers?: Record<string, string>) => Promise<T>;
+    patch: <T>(url: string, data?: unknown, headers?: Record<string, string>) => Promise<T>;
+    delete: <T>(url: string, params?: Record<string, unknown> | undefined, headers?: Record<string, string>) => Promise<T>;
+}, logger?: Logger): <T>(method: HttpMethod, url: string, errorContext: string, dataOrParams?: unknown, headers?: Record<string, string>) => Promise<T>;
+//# sourceMappingURL=http-helpers.d.ts.map

package/dist/services/shared/http-helpers.d.ts.map

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

package/dist/services/shared/pagination-helpers.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Pagination Helpers
+ *
+ * Shared utilities for building pagination parameters and responses
+ * across multiple services. Eliminates duplicate pagination logic.
+ *
+ * @category Services
+ * @since 5.13.0
+ */
+/**
+ * Standard pagination metadata structure
+ * Used in ListResult<T> and paginated API responses
+ */
+export interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+}
+/**
+ * Options for building pagination parameters
+ * Cursor-based pagination only
+ *
+ * @updated 8.1.0 - Removed page/offset/limit, cursor-based pagination only
+ */
+export interface PaginationOptions {
+    cursor?: string;
+    pageSize?: number;
+}
+/**
+ * Build pagination query parameters with max page size enforcement
+ *
+ * Consolidates the common pagination building pattern used across services:
+ * - Uses cursor-based pagination
+ * - Enforces max page size constraint
+ * - Only includes params that are defined
+ *
+ * @param options - Options object with optional cursor and pageSize
+ * @param maxPageSize - Maximum allowed page size
+ * @returns Query params object with stringified cursor and pageSize
+ *
+ * @example
+ * ```typescript
+ * // Cursor-based pagination
+ * const params = buildPaginationParams(
+ *   { cursor: undefined, pageSize: 50 },
+ *   100
+ * );
+ * // Result: { pageSize: '50' }
+ *
+ * const params = buildPaginationParams(
+ *   { cursor: 'abc123', pageSize: 200 },
+ *   100
+ * );
+ * // Result: { cursor: 'abc123', pageSize: '100' } (pageSize capped at 100)
+ * ```
+ */
+export declare function buildPaginationParams(options: PaginationOptions, maxPageSize: number): Record<string, string>;
+/**
+ * Build pagination metadata from response data
+ *
+ * Creates standardized PaginationMeta from total count and request parameters.
+ * Handles edge cases like empty results and division by zero.
+ *
+ * @param total - Total item count from API response
+ * @param page - Current page number (default: 1)
+ * @param limit - Items per page (default: 20)
+ * @returns PaginationMeta object with calculated totalPages
+ *
+ * @example
+ * ```typescript
+ * const meta = buildPaginationMeta(total, page, actualLimit);
+ * return { items: pools, meta };
+ * ```
+ */
+export declare function buildPaginationMeta(total: number, page?: number, limit?: number): PaginationMeta;
+/**
+ * Build pagination metadata for auto-paginated (all items) results
+ *
+ * Creates PaginationMeta for results where all items have been fetched.
+ * Sets page=1, totalPages=1, and limit=items.length for flattened results.
+ *
+ * @param items - Array of fetched items
+ * @param total - Total count (usually same as items.length for auto-paginated)
+ * @returns PaginationMeta for flattened result
+ *
+ * @example
+ * ```typescript
+ * // After auto-pagination fetches all items
+ * const allItems = await autoPaginate(fetchFn, options);
+ * return {
+ *   items: allItems.items,
+ *   meta: buildFlattenedPaginationMeta(allItems.items, allItems.total)
+ * };
+ * ```
+ */
+export declare function buildFlattenedPaginationMeta<T>(items: T[], total?: number): PaginationMeta;
+/**
+ * Build endpoint URL with path parameters
+ *
+ * Replaces :param placeholders in URL templates with provided values.
+ * Values are lowercased and URI-encoded for safety.
+ *
+ * @param template - URL template with :param placeholders
+ * @param params - Parameters to substitute
+ * @returns Built URL with substituted parameters
+ *
+ * @example
+ * ```typescript
+ * const url = buildEndpoint('/api/:tokenName/status', { tokenName: 'MyToken' });
+ * // Returns: '/api/mytoken/status'
+ *
+ * const url = buildEndpoint('/api/:tokenName/assets/:assetId', {
+ *   tokenName: 'MyToken',
+ *   assetId: '12345'
+ * });
+ * // Returns: '/api/mytoken/assets/12345'
+ * ```
+ */
+export declare function buildEndpoint(template: string, params: Record<string, string>): string;
+/**
+ * Calculate if there's a next page based on current pagination state
+ *
+ * @param currentPage - Current page number
+ * @param totalPages - Total number of pages
+ * @returns True if there are more pages after the current one
+ */
+export declare function hasNextPage(currentPage: number, totalPages: number): boolean;
+/**
+ * Calculate if there's a previous page based on current pagination state
+ *
+ * @param currentPage - Current page number
+ * @returns True if there are pages before the current one
+ */
+export declare function hasPreviousPage(currentPage: number): boolean;
+/**
+ * Common filter fields that can be added to query parameters
+ */
+export interface CommonFilterOptions {
+    search?: string;
+    name?: string;
+    userAddress?: string;
+}
+/**
+ * Add optional filter parameters to a query params object
+ *
+ * Consolidates the common pattern of conditionally adding filter params:
+ * - Only adds params that have truthy values
+ * - Mutates the params object in place for efficiency
+ *
+ * @param params - Query params object to add to (mutated)
+ * @param options - Options object containing filter values
+ * @param fields - Array of field names to extract from options
+ * @returns The mutated params object (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const params = buildPaginationParams(options, MAX_LIMIT);
+ * addOptionalFilterParams(params, options, ['search', 'name', 'userAddress']);
+ * // Equivalent to:
+ * // if (options.search) params.search = options.search;
+ * // if (options.name) params.name = options.name;
+ * // if (options.userAddress) params.userAddress = options.userAddress;
+ * ```
+ */
+export declare function addOptionalFilterParams<T>(params: Record<string, string>, options: T, fields: (keyof T & string)[]): Record<string, string>;
+//# sourceMappingURL=pagination-helpers.d.ts.map

package/dist/services/shared/pagination-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination-helpers.d.ts","sourceRoot":"","sources":["../../../src/services/shared/pagination-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,EAAE,KAAK,GAAE,MAAW,GAAG,cAAc,CAOvG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,GAAE,MAAqB,GAAG,cAAc,CAOxG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAMtF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,EAAE,CAAC,EACV,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB"}