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

package/dist/src/utils/error-handling-patterns.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Advanced Error Handling Patterns
+ *
+ * Higher-level error handling utilities built on top of error-utils.ts.
+ * Consolidates 8 duplicated error handling patterns found across 39+ service files.
+ *
+ * @category Utilities
+ * @since 5.16.0
+ */
+/**
+ * Rethrow if error is instance of specific type, otherwise return null
+ *
+ * Used to conditionally rethrow custom errors while handling other types.
+ * Consolidates 8 occurrences across auth and signature services.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await operation();
+ * } catch (error: unknown) {
+ *   throw rethrowIfType(error, AuthError) || new AuthError(
+ *     AuthErrorType.SIGNATURE_FAILED,
+ *     `Operation failed: ${getErrorMessage(error)}`,
+ *     extractErrorIfInstanceOf(error)
+ *   );
+ * }
+ * ```
+ */
+export declare function rethrowIfType<T extends Error>(error: unknown, errorClass: new (...args: any[]) => T): T | null;
+/**
+ * Extract Error instance from unknown value (type guard helper)
+ *
+ * Consolidates the pattern: `isError(error) ? error : undefined`.
+ * Used in 11 occurrences across services for error wrapping.
+ *
+ * @example
+ * ```typescript
+ * throw createNetworkError(
+ *   `Failed: ${getErrorMessage(error)}`,
+ *   undefined,
+ *   extractErrorIfInstanceOf(error)
+ * );
+ * ```
+ */
+export declare function extractErrorIfInstanceOf(value: unknown): Error | undefined;
+/**
+ * Check if error is instance of class by constructor.name
+ *
+ * Used when instanceof checks fail due to module boundaries.
+ * Consolidates 2 occurrences in GalaChain services.
+ *
+ * @example
+ * ```typescript
+ * if (isInstanceOfByName(error, 'ValidationError')) {
+ *   throw error; // Re-throw validation errors as-is
+ * }
+ * ```
+ */
+export declare function isInstanceOfByName(error: unknown, className: string): error is Error;
+/**
+ * Check if error is axios error with specific HTTP status code
+ *
+ * Consolidates 2 occurrences in GalaChain services for 404 handling.
+ *
+ * @example
+ * ```typescript
+ * if (hasAxiosStatusCode(error, 404)) {
+ *   throw createNetworkError(
+ *     'Not found on GalaChain',
+ *     404,
+ *     extractErrorIfInstanceOf(error)
+ *   );
+ * }
+ * ```
+ */
+export declare function hasAxiosStatusCode(error: unknown, statusCode: number): boolean;
+/**
+ * Check if error is Error with name === 'Error' and message contains substring
+ *
+ * Used for GalaChain Status failure detection.
+ * Consolidates 2 occurrences in GalaChain services.
+ *
+ * @example
+ * ```typescript
+ * if (isErrorWithMessageContaining(error, 'status indicates failure')) {
+ *   throw createNetworkError(getErrorMessage(error), 400, extractErrorIfInstanceOf(error));
+ * }
+ * ```
+ */
+export declare function isErrorWithMessageContaining(error: unknown, substring: string): boolean;
+/**
+ * Throw NetworkError from response validation failure
+ *
+ * Consolidates 2 occurrences in GalaChain services.
+ * Used as wrapper around assertResponseSuccess failures.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   assertResponseSuccess(response, 'Failed to fetch pool details');
+ * } catch (error: unknown) {
+ *   throwNetworkErrorFromResponse(error, 500);
+ * }
+ * ```
+ */
+export declare function throwNetworkErrorFromResponse(error: unknown, defaultStatus?: number): never;
+/**
+ * Extract message from axios error response data
+ *
+ * Consolidates 3+ occurrences in transfer service error handling.
+ *
+ * @example
+ * ```typescript
+ * if (isAxiosError(error) && error.response) {
+ *   const responseMsg = extractAxiosResponseMessage(error.response);
+ *   if (responseMsg) {
+ *     return new TransferError(responseMsg, TransferErrorType.INVALID_AMOUNT);
+ *   }
+ * }
+ * ```
+ */
+export declare function extractAxiosResponseMessage(response: {
+    data?: Record<string, unknown>;
+} | unknown): string | undefined;
+/**
+ * Throw NetworkError with context prefix (most common pattern: 9 occurrences)
+ *
+ * Consolidates the pattern: `${context}: ${getErrorMessage(error)}`.
+ * Used across 9 services for consistent error messaging.
+ *
+ * @example
+ * ```typescript
+ * } catch (error: unknown) {
+ *   throwNetworkErrorWithContext(error, 'Failed to fetch pool');
+ * }
+ * ```
+ */
+export declare function throwNetworkErrorWithContext(error: unknown, context: string, statusCode?: number): never;
+/**
+ * Throw NetworkError with original error attached
+ *
+ * Consolidates 6 occurrences of pattern: `throw new NetworkError(..., { originalError })`.
+ * Provides structured error wrapping with explicit originalError property.
+ *
+ * Used for preserving complete error chain when wrapping exceptions.
+ *
+ * @param message Human-readable error message
+ * @param originalError The error that caused this failure (preserved for debugging)
+ * @param errorCode Optional HTTP status code or error code
+ * @returns Never (function always throws)
+ *
+ * @example HTTP error with original exception
+ * ```typescript
+ * try {
+ *   const response = await http.post('/api/trade');
+ * } catch (error: unknown) {
+ *   throwNetworkErrorWithOriginal(
+ *     'Trade execution failed',
+ *     error,
+ *     500
+ *   );
+ * }
+ * ```
+ *
+ * @example Nested error handling
+ * ```typescript
+ * try {
+ *   await fetchPoolData();
+ * } catch (innerError: unknown) {
+ *   try {
+ *     await fallbackFetch();
+ *   } catch (fallbackError: unknown) {
+ *     throwNetworkErrorWithOriginal(
+ *       'Failed: both primary and fallback requests',
+ *       fallbackError
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @since 6.16.0
+ */
+export declare function throwNetworkErrorWithOriginal(message: string, originalError: unknown, errorCode?: string | number): never;
+/**
+ * Check if error has specific HTTP status code
+ *
+ * Consolidates 4 occurrences of pattern: `error.response?.status === statusCode`.
+ * Type-safe HTTP status code checking with null/undefined safety.
+ *
+ * @param error Unknown error (should be axios error)
+ * @param statusCode HTTP status code to check (e.g., 404, 500)
+ * @returns True if error is axios error with matching status code
+ *
+ * @example Check for 404 Not Found
+ * ```typescript
+ * try {
+ *   await api.get('/resource');
+ * } catch (error: unknown) {
+ *   if (checkHttpStatusCode(error, 404)) {
+ *     console.log('Resource not found');
+ *   }
+ * }
+ * ```
+ *
+ * @example Check for rate limit
+ * ```typescript
+ * if (checkHttpStatusCode(error, 429)) {
+ *   console.log('Rate limited, retry after delay');
+ *   await delay(30000);
+ *   return retry();
+ * }
+ * ```
+ *
+ * @example Check for server errors
+ * ```typescript
+ * if (checkHttpStatusCode(error, 500) || checkHttpStatusCode(error, 503)) {
+ *   console.log('Server error, please try again later');
+ * }
+ * ```
+ *
+ * @since 6.16.0
+ */
+export declare function checkHttpStatusCode(error: unknown, statusCode: number): boolean;
+/**
+ * Type-safe extraction of HTTP response from unknown error
+ *
+ * Consolidates 3 occurrences of pattern: extract error.response?.data safely.
+ * Returns structured response object with status and data, or null if not HTTP error.
+ *
+ * @param error Unknown error value
+ * @returns Object with status and data if HTTP error, null otherwise
+ *
+ * @example Extract and handle HTTP error response
+ * ```typescript
+ * try {
+ *   await api.post('/trade');
+ * } catch (error: unknown) {
+ *   const httpError = checkAndExtractHttpError(error);
+ *   if (httpError) {
+ *     console.log(`HTTP ${httpError.status}: ${JSON.stringify(httpError.data)}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Handle both HTTP and non-HTTP errors
+ * ```typescript
+ * try {
+ *   const result = await sdk.executeTransaction();
+ * } catch (error: unknown) {
+ *   const httpError = checkAndExtractHttpError(error);
+ *   if (httpError?.status === 400) {
+ *     // Handle bad request
+ *     console.log('Bad request:', httpError.data);
+ *   } else if (httpError?.status === 500) {
+ *     // Handle server error
+ *     console.log('Server error, retry later');
+ *   } else {
+ *     // Handle non-HTTP error
+ *     console.log('Network error:', getErrorMessage(error));
+ *   }
+ * }
+ * ```
+ *
+ * @since 6.16.0
+ */
+export declare function checkAndExtractHttpError(error: unknown): {
+    status: number;
+    data: unknown;
+} | null;
+/**
+ * Extract error message from axios response.data with GalaChain Message field support
+ *
+ * Consolidates 2 occurrences of pattern: extract message from response.data.Message or response.data.message.
+ * GalaChain API uses capitalized 'Message' field, standard APIs use 'message'.
+ *
+ * @param responseData Unknown response data object
+ * @returns Error message string if found, null if no message available
+ *
+ * @example Extract from GalaChain response
+ * ```typescript
+ * try {
+ *   const response = await galachain.post('/api/data');
+ * } catch (error: unknown) {
+ *   const httpError = checkAndExtractHttpError(error);
+ *   if (httpError) {
+ *     const msg = extractResponseDataMessage(httpError.data);
+ *     console.log(msg || 'Unknown error');
+ *   }
+ * }
+ * ```
+ *
+ * @example Use with fallback message
+ * ```typescript
+ * if (isAxiosError(error) && error.response) {
+ *   const errorMsg = extractResponseDataMessage(error.response.data)
+ *     || 'Request failed';
+ *   throw createNetworkError(errorMsg, error.response.status);
+ * }
+ * ```
+ *
+ * @example GalaChain transfer error handling
+ * ```typescript
+ * try {
+ *   await galachain.transferToken(data);
+ * } catch (error: unknown) {
+ *   const httpError = checkAndExtractHttpError(error);
+ *   if (httpError) {
+ *     const galachainMsg = extractResponseDataMessage(httpError.data);
+ *     if (galachainMsg?.includes('insufficient')) {
+ *       throw createInsufficientBalanceError('GALA', requested, available);
+ *     }
+ *     throw createNetworkError(galachainMsg || 'Transfer failed');
+ *   }
+ * }
+ * ```
+ *
+ * @since 6.16.0
+ */
+export declare function extractResponseDataMessage(responseData: unknown): string | null;
+/**
+ * Map error message substrings to error types/handlers
+ *
+ * Consolidates 3 occurrences of pattern: match error message substrings to specific error conditions.
+ * Useful for classifying API errors based on response message content.
+ *
+ * @param message Error message to check
+ * @param patterns Record mapping search string → result value
+ * @returns Matching pattern value if substring found, null otherwise
+ *
+ * @example Map GalaChain error messages to error types
+ * ```typescript
+ * const patterns = {
+ *   'insufficient': 'INSUFFICIENT_BALANCE',
+ *   'not found': 'TOKEN_NOT_FOUND',
+ *   'invalid amount': 'INVALID_AMOUNT',
+ *   'rate limit': 'RATE_LIMIT',
+ * };
+ *
+ * try {
+ *   await galachain.transferToken(data);
+ * } catch (error: unknown) {
+ *   const httpError = checkAndExtractHttpError(error);
+ *   if (httpError) {
+ *     const msg = extractResponseDataMessage(httpError.data) || '';
+ *     const errorType = matchErrorMessagePatterns(msg, patterns);
+ *
+ *     if (errorType === 'INSUFFICIENT_BALANCE') {
+ *       throw createInsufficientBalanceError('GALA', required, available);
+ *     } else if (errorType === 'TOKEN_NOT_FOUND') {
+ *       throw createTokenNotFoundError(tokenName);
+ *     } else if (errorType === 'RATE_LIMIT') {
+ *       console.log('Rate limited, retry after 60s');
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Case-insensitive error classification
+ * ```typescript
+ * const patterns = {
+ *   'unauthorized': 'AUTH_FAILED',
+ *   'forbidden': 'PERMISSION_DENIED',
+ *   'timeout': 'REQUEST_TIMEOUT',
+ * };
+ *
+ * const errorMsg = 'Request timeout after 30s'.toLowerCase();
+ * const classified = matchErrorMessagePatterns(errorMsg, patterns);
+ * // → 'REQUEST_TIMEOUT'
+ * ```
+ *
+ * @example Complex error pattern matching
+ * ```typescript
+ * const patterns: Record<string, string> = {
+ *   'pool not found': 'POOL_ERROR',
+ *   'slippage': 'SLIPPAGE_ERROR',
+ *   'liquidity': 'LIQUIDITY_ERROR',
+ *   'invalid price': 'PRICE_ERROR',
+ * };
+ *
+ * const result = matchErrorMessagePatterns(
+ *   `Swap failed: Slippage tolerance exceeded`,
+ *   patterns
+ * );
+ * // → 'SLIPPAGE_ERROR'
+ * ```
+ *
+ * @since 6.16.0
+ */
+export declare function matchErrorMessagePatterns(message: string, patterns: Record<string, string>): string | null;
+//# sourceMappingURL=error-handling-patterns.d.ts.map

package/dist/src/utils/error-handling-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling-patterns.d.ts","sourceRoot":"","sources":["../../../src/utils/error-handling-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,KAAK,EAC3C,KAAK,EAAE,OAAO,EAEd,UAAU,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GACpC,CAAC,GAAG,IAAI,CAGV;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAE1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,CAEpF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAMvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,aAAa,GAAE,MAAY,GAC1B,KAAK,CAEP;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,OAAO,GACrD,MAAM,GAAG,SAAS,CAIpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,KAAK,CAMP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,OAAO,EACtB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAC1B,KAAK,CAMP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,GACb;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAS1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAsB/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,MAAM,GAAG,IAAI,CAYf"}