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

package/dist/src/utils/api-patterns.d.ts

@@ -0,0 +1,347 @@
+/**
+ * API/HTTP Pattern Utilities
+ *
+ * Consolidated HTTP and API-related patterns used across the SDK.
+ * Eliminates duplicate code for:
+ * - Concurrent batch requests with concurrency limiting
+ * - Pagination metadata extraction
+ * - Query parameter building with validation
+ * - Automatic HTTP request retries with exponential backoff
+ * - HTTP error response parsing
+ * - Multi-source API aggregation
+ *
+ * @category Utilities
+ * @since 6.5.0
+ */
+import { Logger } from './Logger';
+/**
+ * Pagination metadata extracted from API responses
+ * Provides consistent structure across different API response formats
+ */
+export interface PaginationMetadata {
+    /** Current page number (default: 1) */
+    page: number;
+    /** Items per page (default: 20) */
+    pageSize: number;
+    /** Total count of all items across all pages (default: -1 when unknown) */
+    totalCount: number;
+    /** Whether more pages are available (default: false) */
+    hasMore: boolean;
+}
+/**
+ * HTTP error response with standardized structure
+ * Normalizes errors from different HTTP libraries and APIs
+ */
+export interface ParsedHttpError {
+    /** HTTP status code (default: 0 for non-HTTP errors) */
+    statusCode: number;
+    /** Error message (extracted from response or error) */
+    errorMessage: string;
+    /** Additional error data from response body (if available) */
+    errorData?: unknown;
+    /** Raw error object for debugging */
+    raw: unknown;
+}
+/**
+ * Build and execute multiple API requests with concurrency limit
+ *
+ * Maintains request order while respecting concurrency constraints.
+ * Useful for batch operations like fetching multiple token prices, pool data,
+ * or other resources that benefit from parallel requests but need rate limiting.
+ *
+ * @typeParam T - Type of data returned by the fetcher function
+ * @param urls - Array of URLs or identifiers to fetch
+ * @param batchSize - Maximum number of concurrent requests
+ * @param fetcher - Function to fetch data for each URL/identifier
+ * @param options - Additional options (logger, timeout)
+ * @returns Promise<T[]> Array of results in original order
+ *
+ * @example Fetch multiple token prices with concurrency limit
+ * ```typescript
+ * const tokenNames = ['anime', 'dragon', 'mysterybox'];
+ * const prices = await buildConcurrentBatchRequests(
+ *   tokenNames,
+ *   3, // 3 concurrent requests max
+ *   async (tokenName) => sdk.fetchTokenPrice(tokenName),
+ *   { logger }
+ * );
+ * // Maintains original order: prices[0] = anime, prices[1] = dragon, etc.
+ * ```
+ *
+ * @example Fetch pool data with concurrency control
+ * ```typescript
+ * const poolIds = ['pool-1', 'pool-2', 'pool-3', 'pool-4', 'pool-5'];
+ * const pools = await buildConcurrentBatchRequests(
+ *   poolIds,
+ *   2, // 2 concurrent requests max
+ *   (poolId) => dexApi.getPoolInfo(poolId)
+ * );
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare function buildConcurrentBatchRequests<T>(urls: string[], batchSize: number, fetcher: (url: string) => Promise<T>, options?: {
+    logger?: Logger;
+    timeout?: number;
+}): Promise<T[]>;
+/**
+ * Extract pagination metadata from API response
+ *
+ * Safely extracts pagination info from various response formats.
+ * Provides sensible defaults when fields are missing.
+ * Handles both old and new pagination response structures.
+ *
+ * @param response - Raw API response (may be array, object, null, or undefined)
+ * @returns PaginationMetadata with page, pageSize, totalCount, and hasMore
+ *
+ * @example With standard response object
+ * ```typescript
+ * const metadata = extractPaginationMetadata({
+ *   page: 2,
+ *   pageSize: 20,
+ *   totalCount: 100,
+ *   hasMore: true
+ * });
+ * // Result: { page: 2, pageSize: 20, totalCount: 100, hasMore: true }
+ * ```
+ *
+ * @example With wrapped response
+ * ```typescript
+ * const metadata = extractPaginationMetadata({
+ *   data: {
+ *     items: [...],
+ *     meta: { page: 3, limit: 20, totalItems: 250 }
+ *   }
+ * });
+ * // Result: { page: 3, pageSize: 20, totalCount: 250, hasMore: true }
+ * ```
+ *
+ * @example With missing fields (uses defaults)
+ * ```typescript
+ * const metadata = extractPaginationMetadata({ items: [] });
+ * // Result: { page: 1, pageSize: 20, totalCount: -1, hasMore: false }
+ * ```
+ *
+ * @since 6.5.0
+ * @adoption_gap This pattern appears in 12+ locations with inline extraction (response.page ?? 1)
+ */
+export declare function extractPaginationMetadata(response: unknown): PaginationMetadata;
+/**
+ * Build query parameter string with automatic encoding and null removal
+ *
+ * Safely constructs query strings from parameter objects.
+ * Automatically:
+ * - Skips null/undefined values
+ * - URL-encodes special characters
+ * - Converts non-string values to strings
+ * - Handles arrays and nested objects
+ *
+ * @param params - Record of query parameters (values can be any type)
+ * @returns Formatted query string "?key1=value1&key2=value2" or "" if no params
+ *
+ * @example Simple parameters
+ * ```typescript
+ * const query = buildQueryParametersWithValidation({
+ *   page: 1,
+ *   limit: 20,
+ *   search: 'anime'
+ * });
+ * // Result: "?page=1&limit=20&search=anime"
+ * ```
+ *
+ * @example With special characters
+ * ```typescript
+ * const query = buildQueryParametersWithValidation({
+ *   search: 'hello world',
+ *   token: 'abc/def'
+ * });
+ * // Result: "?search=hello%20world&token=abc%2Fdef"
+ * ```
+ *
+ * @example With nullish values (automatically skipped)
+ * ```typescript
+ * const query = buildQueryParametersWithValidation({
+ *   page: 1,
+ *   search: undefined,
+ *   token: null,
+ *   limit: 20
+ * });
+ * // Result: "?page=1&limit=20" (search and token omitted)
+ * ```
+ *
+ * @example With arrays
+ * ```typescript
+ * const query = buildQueryParametersWithValidation({
+ *   tags: ['anime', 'popular'],
+ *   status: 'active'
+ * });
+ * // Result: "?tags=anime%2Cpopular&status=active" (comma-separated)
+ * ```
+ *
+ * @since 6.5.0
+ * @adoption_gap Manual query string construction appears in 8+ locations
+ */
+export declare function buildQueryParametersWithValidation(params: Record<string, any>): string;
+/**
+ * HTTP request wrapper with automatic retry logic
+ *
+ * Wraps async functions with exponential backoff retry on specific HTTP status codes.
+ * Helps handle transient failures like rate limiting, timeouts, and temporary service issues.
+ *
+ * @typeParam T - Type of the promised value
+ * @param fn - Async function to execute with retries
+ * @param options - Retry configuration
+ * @param options.maxRetries - Maximum number of retry attempts (default: 3)
+ * @param options.backoffMs - Initial backoff delay in milliseconds (default: 100)
+ * @param options.retryableStatus - HTTP status codes to retry (default: [429, 503, 504])
+ * @returns Result of the function or final error after max retries
+ * @throws Error if all retries exhausted or error is not retryable
+ *
+ * @example Retry on rate limit (429)
+ * ```typescript
+ * const result = await retryableHttpRequest(
+ *   () => sdk.fetchTokenPrice('anime'),
+ *   { maxRetries: 3, backoffMs: 100, retryableStatus: [429, 503] }
+ * );
+ * ```
+ *
+ * @example With default retry options
+ * ```typescript
+ * const result = await retryableHttpRequest(
+ *   () => http.get('/api/pool-data')
+ * );
+ * // Retries on 429, 503, 504 with default exponential backoff
+ * ```
+ *
+ * @example Fetch with custom retry behavior
+ * ```typescript
+ * try {
+ *   const data = await retryableHttpRequest(
+ *     () => fetch(url).then(r => r.json()),
+ *     { maxRetries: 5, backoffMs: 200, retryableStatus: [429, 500, 502, 503, 504] }
+ *   );
+ * } catch (error) {
+ *   console.log('Failed after all retries:', error);
+ * }
+ * ```
+ *
+ * @since 6.5.0
+ * @adoption_gap Manual retry logic appears in 3+ locations
+ */
+export declare function retryableHttpRequest<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    backoffMs?: number;
+    retryableStatus?: number[];
+}): Promise<T>;
+/**
+ * Parse HTTP error response into standardized structure
+ *
+ * Consistently extracts error details from various HTTP error formats:
+ * - Axios errors with response data
+ * - Fetch errors
+ * - Custom error objects with status codes
+ * - Plain text error responses
+ * - JSON error responses
+ *
+ * @param error - Unknown error object from HTTP request
+ * @returns ParsedHttpError with statusCode, errorMessage, errorData, and raw error
+ *
+ * @example Axios error
+ * ```typescript
+ * try {
+ *   await axios.get('/api/data');
+ * } catch (error) {
+ *   const parsed = parseHttpErrorResponse(error);
+ *   console.log(`Status: ${parsed.statusCode}, Message: ${parsed.errorMessage}`);
+ *   // Status: 404, Message: Not Found
+ * }
+ * ```
+ *
+ * @example Fetch error
+ * ```typescript
+ * try {
+ *   const response = await fetch('/api/data');
+ *   if (!response.ok) {
+ *     throw new Error(`HTTP ${response.status}`);
+ *   }
+ * } catch (error) {
+ *   const parsed = parseHttpErrorResponse(error);
+ *   // Extracts status code and error message
+ * }
+ * ```
+ *
+ * @example Error response with JSON body
+ * ```typescript
+ * try {
+ *   await api.post('/endpoint', data);
+ * } catch (error) {
+ *   const parsed = parseHttpErrorResponse(error);
+ *   console.log(`Error: ${parsed.errorData?.errorCode || parsed.statusCode}`);
+ * }
+ * ```
+ *
+ * @since 6.5.0
+ * @adoption_gap Error response parsing appears in 7+ locations with inconsistent patterns
+ */
+export declare function parseHttpErrorResponse(error: unknown): ParsedHttpError;
+/**
+ * Fetch same data from multiple API endpoints and aggregate results
+ *
+ * Useful for:
+ * - Redundancy: Query multiple APIs and use the first successful response
+ * - Fallback: Try primary API, then secondary, then tertiary
+ * - Aggregation: Combine partial results from multiple sources
+ *
+ * @typeParam T - Type of data returned from each endpoint
+ * @param endpoints - Array of API endpoints to query
+ * @param aggregator - Function to combine results from all endpoints
+ * @param options - Additional options (fetcher, logger)
+ * @returns Aggregated result from combining all endpoint responses
+ *
+ * @example Fallback to secondary API
+ * ```typescript
+ * const price = await aggregateMultipleApiSources(
+ *   ['https://api.primary.com/price', 'https://api.secondary.com/price'],
+ *   (results) => {
+ *     // Use first successful result
+ *     return results.find(r => r !== undefined) || { price: 0 };
+ *   },
+ *   { fetcher: (url) => fetch(url).then(r => r.json()) }
+ * );
+ * ```
+ *
+ * @example Aggregate price from multiple exchanges
+ * ```typescript
+ * const avgPrice = await aggregateMultipleApiSources(
+ *   ['exchange1.api/price', 'exchange2.api/price', 'exchange3.api/price'],
+ *   (results) => {
+ *     const prices = results.filter(r => typeof r === 'number') as number[];
+ *     if (prices.length === 0) return 0;
+ *     return prices.reduce((a, b) => a + b, 0) / prices.length;
+ *   }
+ * );
+ * ```
+ *
+ * @example Combine partial results from multiple sources
+ * ```typescript
+ * const combined = await aggregateMultipleApiSources(
+ *   [
+ *     'https://api1.com/liquidity',
+ *     'https://api2.com/liquidity',
+ *     'https://api3.com/liquidity'
+ *   ],
+ *   (results) => ({
+ *     totalLiquidity: results.reduce((sum, r) => sum + (r?.tvl || 0), 0),
+ *     sources: results.filter(r => r !== undefined).length
+ *   })
+ * );
+ * ```
+ *
+ * @since 6.5.0
+ * @adoption_gap Multi-source aggregation appears in 5+ locations with duplicate logic
+ */
+export declare function aggregateMultipleApiSources<T>(endpoints: string[], aggregator: (results: (T | undefined)[]) => T, options?: {
+    fetcher?: (endpoint: string) => Promise<T>;
+    logger?: Logger;
+}): Promise<T>;
+//# sourceMappingURL=api-patterns.d.ts.map

package/dist/src/utils/api-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-patterns.d.ts","sourceRoot":"","sources":["../../../src/utils/api-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAKlC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qCAAqC;IACrC,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACpC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,OAAO,GAAG,kBAAkB,CAwD/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAqCtF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,GACA,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAiEtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAsB,2BAA2B,CAAC,CAAC,EACjD,SAAS,EAAE,MAAM,EAAE,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,KAAK,CAAC,EAC7C,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,CAAC,CAAC,CAuCZ"}

package/dist/src/utils/array-helpers.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Array transformation and grouping utilities
+ *
+ * These utilities provide generic, type-safe array operations
+ * for common transformation patterns.
+ */
+/**
+ * Group array items by a computed key into a Map
+ *
+ * Provides a type-safe alternative to object-based grouping,
+ * supporting any key type (strings, numbers, objects, etc.)
+ *
+ * Replaces the common pattern:
+ * ```typescript
+ * const groups = new Map<K, T[]>();
+ * items.forEach((item) => {
+ *   const key = computeKey(item);
+ *   if (!groups.has(key)) groups.set(key, []);
+ *   groups.get(key)!.push(item);
+ * });
+ * ```
+ *
+ * @template T - The type of items in the array
+ * @template K - The type of the grouping key
+ *
+ * @param items - Array of items to group
+ * @param keyFn - Function that computes the grouping key for each item
+ * @returns Map with keys mapping to arrays of grouped items
+ *
+ * @example
+ * ```typescript
+ * // Group positions by token pair
+ * interface LiquidityPosition {
+ *   token0: string;
+ *   token1: string;
+ *   liquidity: string;
+ * }
+ *
+ * const positions: LiquidityPosition[] = [
+ *   { token0: 'GALA', token1: 'GUSDC', liquidity: '1000' },
+ *   { token0: 'GALA', token1: 'GWETH', liquidity: '500' },
+ *   { token0: 'GALA', token1: 'GUSDC', liquidity: '2000' },
+ * ];
+ *
+ * const grouped = groupByKey(
+ *   positions,
+ *   (pos) => `${pos.token0}/${pos.token1}`
+ * );
+ * // Result: Map {
+ * //   'GALA/GUSDC' => [{ token0: 'GALA', token1: 'GUSDC', liquidity: '1000' }, ...],
+ * //   'GALA/GWETH' => [{ token0: 'GALA', token1: 'GWETH', liquidity: '500' }]
+ * // }
+ *
+ * grouped.get('GALA/GUSDC'); // Array of both GALA/GUSDC positions
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Group trades by status
+ * interface Trade {
+ *   id: string;
+ *   status: 'pending' | 'completed' | 'failed';
+ *   amount: number;
+ * }
+ *
+ * const trades: Trade[] = [...];
+ * const byStatus = groupByKey(trades, (trade) => trade.status);
+ *
+ * const pending = byStatus.get('pending') || [];
+ * const completed = byStatus.get('completed') || [];
+ * const failed = byStatus.get('failed') || [];
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Group by numeric key
+ * interface DataPoint {
+ *   timestamp: number;
+ *   value: number;
+ * }
+ *
+ * const data: DataPoint[] = [...];
+ * // Group by hour (rounded timestamp)
+ * const byHour = groupByKey(
+ *   data,
+ *   (point) => Math.floor(point.timestamp / (60 * 60 * 1000))
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Group with object key (requires key to be serializable)
+ * interface Event {
+ *   chainId: number;
+ *   contractAddress: string;
+ *   data: unknown;
+ * }
+ *
+ * const events: Event[] = [...];
+ * // Group by contract on each chain
+ * const byChainContract = groupByKey(
+ *   events,
+ *   (event) => `${event.chainId}:${event.contractAddress}`
+ * );
+ * ```
+ *
+ * @remarks
+ * - Uses `Map` for better type safety and support for non-string keys
+ * - The key function is called once per item (O(n) complexity)
+ * - Maintains insertion order of keys
+ * - Suitable for large datasets due to Map's efficiency
+ * - Key equality determined by `===` comparison (or custom equals for objects)
+ */
+export declare function groupByKey<T, K>(items: T[], keyFn: (item: T) => K): Map<K, T[]>;
+//# sourceMappingURL=array-helpers.d.ts.map

package/dist/src/utils/array-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/array-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GACpB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAcb"}