@gala-chain/launchpad-sdk 5.1.1 → 7.0.0-beta.1

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

@@ -1,347 +0,0 @@
-/**
- * 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 type { 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, unknown>): 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

@@ -1 +0,0 @@
-{"version":3,"file":"api-patterns.d.ts","sourceRoot":"","sources":["../../../src/utils/api-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAIvC;;;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,CAsDd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,OAAO,GAAG,kBAAkB,CA2D/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAuC1F;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

@@ -1,115 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}