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

package/dist/utils/response-handlers.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Response Handlers
+ *
+ * Standardized response validation, data extraction, and error handling for API calls.
+ * Eliminates duplicate patterns across 40+ service files:
+ * - Response error checking (18+ instances)
+ * - Response.data extraction (25+ instances)
+ * - Null/undefined validation patterns
+ *
+ * @category Utilities
+ * @since 3.6.1
+ * @since 6.5.0 - Added response data extraction helpers
+ */
+/**
+ * Standard backend response structure
+ */
+interface BackendResponse<T = unknown> {
+    status: number;
+    error: boolean;
+    message?: string;
+    data?: T;
+}
+/**
+ * Type guard to check if value has data property
+ * Used internally for extractResponseData type narrowing
+ */
+interface HasData<T = unknown> {
+    data?: T;
+}
+/**
+ * Type guard to check if response has data property
+ * Can be used to safely access response.data
+ *
+ * Common pattern eliminated (25+ locations):
+ * ```typescript
+ * // Before: Scattered null/undefined checks
+ * const result = response.data;
+ * const pools = apiResponse.data.pools;
+ * const userData = response?.data?.user || null;
+ * if (!response.data) { throw new Error('No data in response'); }
+ * ```
+ *
+ * @param response Value to check
+ * @returns Type guard: true if value has data property (TypeScript narrows type)
+ *
+ * @example Basic check
+ * ```typescript
+ * const response = await api.get('/pools');
+ * if (hasResponseData(response)) {
+ *   // TypeScript now knows response.data exists
+ *   const pools = response.data.pools;
+ * }
+ * ```
+ *
+ * @example With optional chaining
+ * ```typescript
+ * if (hasResponseData(response) && response.data) {
+ *   processData(response.data);
+ * }
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare function hasResponseData<T = unknown>(response: unknown): response is HasData<T>;
+/**
+ * Asserts that a backend response is successful, throwing an error if not.
+ *
+ * This utility eliminates the duplicate error checking pattern found across
+ * all service files. It provides a single source of truth for response validation.
+ *
+ * ## Error Checking Logic
+ *
+ * A response is considered **failed** if any of these conditions are true:
+ * 1. `response.error === true` - Explicit error flag from backend
+ * 2. `requireData === true && !response.data` - Data is required but missing
+ *
+ * Note: The status code is NOT checked - the `error` flag is the authoritative
+ * indicator of success/failure. Status codes like 201 (Created) are valid success
+ * responses that should not be rejected.
+ *
+ * ## Replaces Patterns
+ *
+ * This function replaces 18+ instances of duplicate error checking:
+ *
+ * ### Before (Duplicate Pattern in Every Service):
+ * ```typescript
+ * // StreamTokenServiceBase.ts
+ * if (response.error) {
+ *   throw new ValidationError(response.message, 'response', 'BACKEND_ERROR');
+ * }
+ * if (!response.data) {
+ *   throw new ValidationError('No data in response', 'response', 'NO_DATA');
+ * }
+ *
+ * // TradeService.ts
+ * if (response.error) {
+ *   throw new Error(response.message || 'Failed to execute trade');
+ * }
+ *
+ * // ... more duplicate instances across different services
+ * ```
+ *
+ * ### After (Single Source of Truth):
+ * ```typescript
+ * // StreamTokenServiceBase.ts
+ * assertResponseSuccess(response, 'Backend request failed', true);
+ *
+ * // TradeService.ts
+ * assertResponseSuccess(response, 'Failed to execute trade');
+ *
+ * // All services use the same consistent error handling
+ * ```
+ *
+ * @template T The expected type of response.data
+ * @param response Backend response object to validate
+ * @param defaultErrorMessage Default error message if response.message is unavailable
+ * @param requireData Whether to require response.data to be present (default: false)
+ * @throws Error if the response indicates failure
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - check error flag only
+ * const response = await http.post('/api/endpoint', data);
+ * assertResponseSuccess(response, 'Operation failed');
+ * // No return value - throws if response.error is true
+ *
+ * // Require data to be present
+ * const response = await http.get('/api/pools');
+ * assertResponseSuccess(response, 'Failed to fetch pools', true);
+ * // Throws if response.error OR !response.data
+ *
+ * // Custom error message context
+ * assertResponseSuccess(response, 'Token creation failed');
+ * assertResponseSuccess(response, 'Profile update failed');
+ * assertResponseSuccess(response, 'Trade execution failed');
+ * ```
+ */
+export declare function assertResponseSuccess<T = unknown>(response: BackendResponse<T>, defaultErrorMessage: string, requireData?: boolean): void;
+/**
+ * Safely extract data from API response
+ *
+ * Extracts response.data with TypeScript type narrowing and null-safety.
+ * Returns the data if present, otherwise returns undefined.
+ * Does NOT throw on missing data - use getResponseDataOrThrow for strict mode.
+ *
+ * Common pattern eliminated (25+ locations):
+ * ```typescript
+ * // Before: Scattered throughout services
+ * const result = response.data;
+ * const pools = apiResponse.data?.pools;
+ * const userData = response?.data?.user || null;
+ * ```
+ *
+ * @typeParam T - Type of data being extracted
+ * @param response Response object that might contain data
+ * @returns The data if it exists, otherwise undefined
+ *
+ * @example Basic extraction
+ * ```typescript
+ * const response = await http.get('/api/endpoint');
+ * const data = extractResponseData(response);
+ * if (data) {
+ *   console.log('Got data:', data);
+ * }
+ * ```
+ *
+ * @example With type narrowing
+ * ```typescript
+ * const pools = extractResponseData<PoolData>(response);
+ * // pools: PoolData | undefined
+ * if (pools) {
+ *   processPools(pools.items);
+ * }
+ * ```
+ *
+ * @example Destructuring with defaults
+ * ```typescript
+ * const { pools = [] } = extractResponseData(response) || {};
+ * // Safe even if response.data is undefined
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare function extractResponseData<T = unknown>(response: HasData<T> | null | undefined): T | undefined;
+/**
+ * Strictly extract data from response, throwing if missing
+ *
+ * Extracts response.data and throws a descriptive error if not present.
+ * Use this when data is REQUIRED for the operation.
+ *
+ * @typeParam T - Type of data being extracted
+ * @param response Response object that should contain data
+ * @param errorMessage Optional custom error message (default: generic message)
+ * @returns The extracted data (never undefined due to throw)
+ * @throws Error if response is null/undefined or response.data is missing
+ *
+ * @example With default error message
+ * ```typescript
+ * const pools = getResponseDataOrThrow(response);
+ * // Throws: "No data found in response" if response.data is missing
+ * ```
+ *
+ * @example With custom error message
+ * ```typescript
+ * const userData = getResponseDataOrThrow(response, 'Failed to fetch user profile');
+ * // Throws custom message if data is missing
+ * ```
+ *
+ * @example Type-safe extraction
+ * ```typescript
+ * interface UserProfile {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * const profile = getResponseDataOrThrow<UserProfile>(response, 'User profile not found');
+ * // profile is definitely UserProfile (or throws)
+ * console.log(profile.id);
+ * ```
+ *
+ * @since 6.5.0
+ */
+export declare function getResponseDataOrThrow<T = unknown>(response: HasData<T> | null | undefined, errorMessage?: string): T;
+export {};
+//# sourceMappingURL=response-handlers.d.ts.map

package/dist/utils/response-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-handlers.d.ts","sourceRoot":"","sources":["../../src/utils/response-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;GAEG;AACH,UAAU,eAAe,CAAC,CAAC,GAAG,OAAO;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;CACV;AAED;;;GAGG;AACH,UAAU,OAAO,CAAC,CAAC,GAAG,OAAO;IAC3B,IAAI,CAAC,EAAE,CAAC,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EACzC,QAAQ,EAAE,OAAO,GAChB,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,CAOxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAC5B,mBAAmB,EAAE,MAAM,EAC3B,WAAW,GAAE,OAAe,GAC3B,IAAI,CAmBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAC7C,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GACtC,CAAC,GAAG,SAAS,CAKf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAChD,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EACvC,YAAY,GAAE,MAAoC,GACjD,CAAC,CAYH"}

package/dist/utils/response-helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * HTTP Response Helpers
+ *
+ * Utility functions for handling Fetch API Response objects.
+ * Provides concise assertion and validation for HTTP responses.
+ *
+ * @category Utilities
+ * @since 5.12.0
+ */
+/**
+ * Asserts that a Fetch API HTTP response is successful (status 2xx).
+ *
+ * Throws an error if the response status indicates failure.
+ * Useful for DRY response validation in HTTP clients.
+ *
+ * @param response Fetch API Response object to validate
+ * @param message Optional custom error message context
+ * @throws Error if response.ok is false
+ *
+ * @example Basic usage
+ * ```typescript
+ * const response = await fetch(url);
+ * assertFetchResponseSuccess(response, 'Failed to fetch data');
+ * // Continue processing response
+ * ```
+ */
+export declare function assertFetchResponseSuccess(response: Response, message?: string): void;
+//# sourceMappingURL=response-helpers.d.ts.map

package/dist/utils/response-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/response-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAMrF"}

package/dist/utils/response-normalizers.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Response Normalization Utilities
+ *
+ * Utilities for normalizing backend API responses into consistent formats.
+ * Handles the various response structure variations from the backend API,
+ * reducing complexity in service methods.
+ *
+ * @category Utilities
+ * @since 3.6.0
+ */
+import type { BackendPoolResponse } from '../types/backend-responses';
+import type { PoolData } from '../types/launchpad.dto';
+/**
+ * Generic helper to normalize API responses that may be arrays or wrapped objects.
+ *
+ * Handles common backend response patterns where data may be returned as:
+ * - Direct array: [item1, item2]
+ * - Wrapped object: { arrayKey: [item1, item2] }
+ *
+ * @param data Raw response data (array, object with array property, or nullish)
+ * @param arrayKey The property name containing the array when data is an object
+ * @returns Normalized array of items, empty array if data is nullish
+ *
+ * @example
+ * ```typescript
+ * // Direct array input
+ * normalizeArrayResponse([1, 2, 3], 'items'); // [1, 2, 3]
+ *
+ * // Wrapped object input
+ * normalizeArrayResponse({ items: [1, 2, 3] }, 'items'); // [1, 2, 3]
+ *
+ * // Nullish input
+ * normalizeArrayResponse(null, 'items'); // []
+ * ```
+ *
+ * @since 3.6.0
+ */
+export declare function normalizeArrayResponse<T>(data: unknown, arrayKey: string): T[];
+/**
+ * Normalizes pool response data into consistent array format
+ *
+ * The backend API returns pools in different formats depending on the query:
+ * - Single token: { tokens: {pool data} }
+ * - Multiple tokens: { tokens: [{pool data}] }
+ * - Legacy format: { pools: [{pool data}] }
+ *
+ * This normalizer ensures we always get an array of pools with proper Date objects.
+ *
+ * @param data Raw response data from backend
+ * @returns Normalized array of pools with Date objects
+ *
+ * @example
+ * ```typescript
+ * // Single token response
+ * const normalized = normalizePoolResponse({
+ *   tokens: { id: 1, created_at: '2024-01-01' }
+ * });
+ * // Result: [{ id: 1, createdAt: Date('2024-01-01') }]
+ *
+ * // Multiple tokens response
+ * const normalized = normalizePoolResponse({
+ *   tokens: [{ id: 1, created_at: '2024-01-01' }, { id: 2, created_at: '2024-01-02' }]
+ * });
+ * // Result: [{ id: 1, createdAt: Date('2024-01-01') }, { id: 2, createdAt: Date('2024-01-02') }]
+ * ```
+ */
+export declare function normalizePoolResponse(data: BackendPoolResponse | null | undefined): PoolData[];
+/**
+ * Extracts pagination metadata from backend response
+ *
+ * Safely extracts page, limit, and total from various response formats,
+ * providing defaults when fields are missing.
+ *
+ * @param response Raw backend response
+ * @param defaults Default values for page and limit
+ * @returns Normalized pagination metadata
+ *
+ * @example
+ * ```typescript
+ * const pagination = extractPaginationMetadata(
+ *   { page: '2', limit: '10', total: '100' },
+ *   { page: 1, limit: 10 }
+ * );
+ * // Result: { page: 2, limit: 10, total: 100, totalPages: 10 }
+ * ```
+ */
+export declare function extractPaginationMetadata(response: unknown, defaults: {
+    page: number;
+    limit: number;
+}): {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+};
+/**
+ * Creates pagination helper flags
+ *
+ * Calculates hasNext and hasPrevious flags based on current page and total pages.
+ *
+ * @param page Current page number
+ * @param totalPages Total number of pages
+ * @returns Pagination navigation flags
+ *
+ * @example
+ * ```typescript
+ * const flags = createPaginationFlags(2, 5);
+ * // Result: { hasNext: true, hasPrevious: true }
+ * ```
+ */
+export declare function createPaginationFlags(page: number, totalPages: number): {
+    hasNext: boolean;
+    hasPrevious: boolean;
+};
+//# sourceMappingURL=response-normalizers.d.ts.map

package/dist/utils/response-normalizers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-normalizers.d.ts","sourceRoot":"","sources":["../../src/utils/response-normalizers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,EAAE,CAM9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,EAAE,CAkC9F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAaA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB;IACD,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB,CAKA"}