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

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

@@ -1,11 +1,15 @@
 /**
  * Response Handlers
  *
- * Standardized response validation and error handling for API calls.
- * Eliminates duplicate error checking patterns across services.
+ * 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
@@ -16,6 +20,48 @@ interface BackendResponse<T = unknown> {
     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.
  *
@@ -26,8 +72,11 @@ interface BackendResponse<T = unknown> {
  *
  * A response is considered **failed** if any of these conditions are true:
  * 1. `response.error === true` - Explicit error flag from backend
- * 2. `response.status !== 200` - Non-success HTTP status code
- * 3. `requireData === true && !response.data` - Data is required but missing
+ * 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
  *
@@ -35,9 +84,12 @@ interface BackendResponse<T = unknown> {
  *
  * ### Before (Duplicate Pattern in Every Service):
  * ```typescript
- * // PoolService.ts
- * if (response.error === true || response.status !== 200 || !response.data) {
- *   throw new Error(response.message || 'Failed to fetch pools');
+ * // 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
@@ -45,25 +97,17 @@ interface BackendResponse<T = unknown> {
  *   throw new Error(response.message || 'Failed to execute trade');
  * }
  *
- * // UserService.ts
- * if (response.error || response.status !== 200) {
- *   throw new Error(response.message || 'User operation failed');
- * }
- *
  * // ... more duplicate instances across different services
  * ```
  *
  * ### After (Single Source of Truth):
  * ```typescript
- * // PoolService.ts
- * assertResponseSuccess(response, 'Failed to fetch pools', true);
+ * // StreamTokenServiceBase.ts
+ * assertResponseSuccess(response, 'Backend request failed', true);
  *
  * // TradeService.ts
  * assertResponseSuccess(response, 'Failed to execute trade');
  *
- * // UserService.ts
- * assertResponseSuccess(response, 'User operation failed');
- *
  * // All services use the same consistent error handling
  * ```
  *
@@ -75,15 +119,15 @@ interface BackendResponse<T = unknown> {
  *
  * @example
  * ```typescript
- * // Basic usage - check status and error flag only
+ * // Basic usage - check error flag only
  * const response = await http.post('/api/endpoint', data);
  * assertResponseSuccess(response, 'Operation failed');
- * // No return value - throws if response is invalid
+ * // 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, status !== 200, OR !response.data
+ * // Throws if response.error OR !response.data
  *
  * // Custom error message context
  * assertResponseSuccess(response, 'Token creation failed');
@@ -92,5 +136,90 @@ interface BackendResponse<T = unknown> {
  * ```
  */
 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/src/utils/response-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-handlers.d.ts","sourceRoot":"","sources":["../../../src/utils/response-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;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,CAQN"}
+{"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,CAWN;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/src/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/src/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/src/utils/response-normalizers.d.ts

@@ -8,10 +8,34 @@
  * @category Utilities
  * @since 3.6.0
  */
-import { BackendPoolResponse, BackendTradeResponse, BackendTokenListResponse } from '../types/backend-responses';
+import { BackendPoolResponse } from '../types/backend-responses';
 import { PoolData } from '../types/launchpad.dto';
-import { TradeInfo } from '../types/trade.dto';
-import { UserTokenInfo } from '../types/user.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
  *
@@ -41,52 +65,6 @@ import { UserTokenInfo } from '../types/user.dto';
  * ```
  */
 export declare function normalizePoolResponse(data: BackendPoolResponse | null | undefined): PoolData[];
-/**
- * Normalizes trade response data into consistent array format
- *
- * The backend API returns trades in different formats:
- * - Direct array: [trade1, trade2]
- * - Wrapped object: { trades: [trade1, trade2] }
- *
- * This normalizer ensures we always get an array of trades.
- *
- * @param data Raw response data from backend
- * @returns Normalized array of trades
- *
- * @example
- * ```typescript
- * const normalized = normalizeTradeResponse({
- *   trades: [
- *     { id: 1, createdAt: '2024-01-01', updatedAt: '2024-01-01' }
- *   ]
- * });
- * // Result: [{ id: 1, createdAt: '2024-01-01', updatedAt: '2024-01-01' }]
- * ```
- */
-export declare function normalizeTradeResponse(data: BackendTradeResponse | null | undefined): TradeInfo[];
-/**
- * Normalizes token list response data into consistent array format
- *
- * The backend API returns token lists in different formats:
- * - Direct array: [token1, token2]
- * - Wrapped object: { token: [token1, token2] }
- *
- * This normalizer ensures we always get an array of tokens.
- *
- * @param data Raw response data from backend
- * @returns Normalized array of tokens
- *
- * @example
- * ```typescript
- * const normalized = normalizeTokenListResponse({
- *   token: [
- *     { id: 1, createdAt: '2024-01-01', updatedAt: '2024-01-01' }
- *   ]
- * });
- * // Result: [{ id: 1, createdAt: '2024-01-01', updatedAt: '2024-01-01' }]
- * ```
- */
-export declare function normalizeTokenListResponse(data: BackendTokenListResponse | null | undefined): UserTokenInfo[];
 /**
  * Extracts pagination metadata from backend response
  *

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

@@ -1 +1 @@
-{"version":3,"file":"response-normalizers.d.ts","sourceRoot":"","sources":["../../../src/utils/response-normalizers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,EAAE,CAiC9F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,EAAE,CAGjG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,EAAE,CAG7G;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,CASA;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"}
+{"version":3,"file":"response-normalizers.d.ts","sourceRoot":"","sources":["../../../src/utils/response-normalizers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlD;;;;;;;;;;;;;;;;;;;;;;;;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,CAiC9F;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"}