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

package/dist/src/utils/date-utils.d.ts

@@ -36,4 +36,170 @@ export declare function isValidDateString(dateString: string | Date | null | und
  * @returns Valid Date object with debug information
  */
 export declare function safeParseWithContext(dateString: string | Date | null | undefined, context: string, fallback?: Date): Date;
+/**
+ * Calculate elapsed time in milliseconds since a start timestamp
+ *
+ * Replaces the common pattern: `Date.now() - startTimeMs`
+ *
+ * @param startTimeMs - Start timestamp in milliseconds (from Date.now())
+ * @returns Elapsed milliseconds between start and now
+ *
+ * @example
+ * ```typescript
+ * const startTime = Date.now();
+ * // ... perform operation ...
+ * const elapsed = calculateElapsedTime(startTime);
+ * console.log(`Operation took ${elapsed}ms`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Measuring performance of async operations
+ * const start = Date.now();
+ * const result = await fetchData();
+ * const duration = calculateElapsedTime(start);
+ * metrics.record('fetch_duration_ms', duration);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Timeout checking
+ * const timeout = 5000;
+ * const start = Date.now();
+ * while (!completed) {
+ *   if (calculateElapsedTime(start) > timeout) {
+ *     throw new TimeoutError('Operation exceeded 5 second limit');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Rate limiting with time windows
+ * const requestTime = Date.now();
+ * const timeSinceLastRequest = calculateElapsedTime(lastRequestTime);
+ * if (timeSinceLastRequest < minIntervalMs) {
+ *   throw new RateLimitError(`Must wait ${minIntervalMs - timeSinceLastRequest}ms`);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Always use the same timestamp source (Date.now()) for accurate calculations
+ * - Results are in milliseconds, divide by 1000 for seconds
+ * - Useful for performance monitoring, timeout checking, and rate limiting
+ * - Simpler and more readable than inline Date.now() subtraction
+ */
+export declare function calculateElapsedTime(startTimeMs: number): number;
+/**
+ * Check if a timestamp has expired
+ *
+ * Replaces the common pattern: `Date.now() > expiresAt`
+ * Used for cache expiration, JWT validation, token expiry checks.
+ *
+ * @param expiresAt - Expiration timestamp in milliseconds
+ * @returns True if the current time is past the expiration time
+ *
+ * @example
+ * ```typescript
+ * if (isExpired(cacheEntry.expiresAt)) {
+ *   cache.delete(key);
+ * }
+ * ```
+ */
+export declare function isExpired(expiresAt: number): boolean;
+/**
+ * Set an expiry time by adding TTL (time-to-live) to current time
+ *
+ * Replaces the common pattern: `Date.now() + ttl`
+ * Used for cache timestamps, token expiry, session validity.
+ *
+ * @param ttl - Time-to-live in milliseconds
+ * @returns Expiration timestamp in milliseconds
+ *
+ * @example
+ * ```typescript
+ * const expiresAt = setExpiryTime(3600000); // 1 hour from now
+ * ```
+ */
+export declare function setExpiryTime(ttl: number): number;
+/**
+ * Convert timestamp to ISO 8601 string
+ *
+ * Replaces the common pattern: `new Date(ts).toISOString()`
+ * Used for API responses, logging, date serialization.
+ *
+ * @param timestamp - Timestamp in milliseconds (from Date.now())
+ * @returns ISO 8601 formatted string
+ *
+ * @example
+ * ```typescript
+ * const isoString = timestampToISOString(Date.now());
+ * // "2025-01-09T15:30:45.123Z"
+ * ```
+ */
+export declare function timestampToISOString(timestamp: number): string;
+/**
+ * Time constant helper: convert minutes to milliseconds
+ *
+ * Replaces the common pattern: `n * 60 * 1000`
+ * Used for timeout values, cache TTLs, polling intervals.
+ *
+ * @param n - Number of minutes
+ * @returns Milliseconds equivalent
+ *
+ * @example
+ * ```typescript
+ * const timeout = minutes(5); // 300000ms
+ * const cacheTtl = minutes(30); // 1800000ms
+ * ```
+ */
+export declare function minutes(n: number): number;
+/**
+ * Time constant helper: convert hours to milliseconds
+ *
+ * Replaces the common pattern: `n * 60 * 60 * 1000`
+ * Used for long-lived cache entries, session durations.
+ *
+ * @param n - Number of hours
+ * @returns Milliseconds equivalent
+ *
+ * @example
+ * ```typescript
+ * const sessionTtl = hours(24); // 86400000ms (1 day)
+ * ```
+ */
+export declare function hours(n: number): number;
+/**
+ * Time constant helper: convert days to milliseconds
+ *
+ * Replaces the common pattern: `n * 24 * 60 * 60 * 1000`
+ * Used for date calculations, expiry windows.
+ *
+ * @param n - Number of days
+ * @returns Milliseconds equivalent
+ *
+ * @example
+ * ```typescript
+ * const tokenExpiry = days(365); // 1 year
+ * const archiveThreshold = days(30);
+ * ```
+ */
+export declare function days(n: number): number;
+/**
+ * Normalize various date formats to milliseconds timestamp
+ *
+ * Handles Date objects, numeric timestamps, and ISO string dates.
+ * Consolidates the common pattern: `value instanceof Date ? value.getTime() : value`
+ *
+ * @param value - Date object, timestamp in milliseconds, or ISO date string
+ * @returns Timestamp in milliseconds (or current time if invalid)
+ *
+ * @example
+ * ```typescript
+ * const ts1 = dateToMilliseconds(new Date());        // Date object
+ * const ts2 = dateToMilliseconds(1609459200000);      // Already milliseconds
+ * const ts3 = dateToMilliseconds('2021-01-01T00:00:00Z'); // ISO string
+ * ```
+ */
+export declare function dateToMilliseconds(value: Date | number | string | null | undefined): number;
 //# sourceMappingURL=date-utils.d.ts.map

package/dist/src/utils/date-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/date-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,EAC5C,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,CA2BN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACjD,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,EAAE,CAER;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAiBT;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,CAiCN"}
+{"version":3,"file":"date-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/date-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,EAC5C,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,CA2BN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACjD,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,EAAE,CAER;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAiBT;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,CAiCN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/C,MAAM,CAmBR"}

package/dist/src/utils/delimiter-parser.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Delimiter Parser - Unified Token Delimiter Parsing
+ *
+ * Consolidates common delimiter parsing patterns used across:
+ * - tokenNormalizer.ts: Vault address parsing ($ delimiter)
+ * - token-format-converter.ts: Dollar-delimited token parsing
+ * - token-parser.ts: Pipe and dollar-delimited parsing
+ *
+ * This module provides low-level parsing primitives that are used
+ * by higher-level token utilities.
+ *
+ * @internal
+ * @category Utilities
+ * @since 6.16.0
+ */
+/**
+ * Parsed token parts from a delimited string
+ */
+export interface DelimitedTokenParts {
+    collection: string;
+    category: string;
+    type: string;
+    additionalKey: string;
+}
+/**
+ * Delimiter type for token formats
+ */
+export type TokenDelimiter = '|' | '$';
+/**
+ * Parse a delimited token string into its component parts (LEFT-TO-RIGHT)
+ *
+ * This is a low-level parsing function that extracts the four standard token
+ * components from a delimited string. It handles additionalKey that may contain
+ * the delimiter character by joining all remaining parts after the first three.
+ *
+ * **WARNING:** This function parses LEFT-TO-RIGHT which does NOT handle the edge case
+ * where the collection name contains the delimiter (e.g., "$MUSIC$Unit$none$none").
+ * For tokens that may have $ in the collection, use `parseDelimitedTokenFromEnd`.
+ *
+ * @param input - The delimited string to parse
+ * @param delimiter - The delimiter character ('|' or '$')
+ * @param errorContext - Optional context for error messages (e.g., "vault address")
+ * @returns Parsed token parts
+ * @throws ValidationError if the format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Pipe-delimited
+ * const result = parseDelimitedToken('GALA|Unit|none|none', '|');
+ * // { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }
+ *
+ * // Dollar-delimited
+ * const result = parseDelimitedToken('GUSDC$Unit$none$eth:0x...', '$');
+ * // { collection: 'GUSDC', category: 'Unit', type: 'none', additionalKey: 'eth:0x...' }
+ *
+ * // With complex additionalKey containing delimiter
+ * const result = parseDelimitedToken('Token|Unit|SYM|eth:0x|suffix', '|');
+ * // { collection: 'Token', category: 'Unit', type: 'SYM', additionalKey: 'eth:0x|suffix' }
+ * ```
+ *
+ * @internal
+ */
+export declare function parseDelimitedToken(input: string, delimiter: TokenDelimiter, errorContext?: string): DelimitedTokenParts;
+/**
+ * Parse a delimited token string from the END (RIGHT-TO-LEFT)
+ *
+ * This handles the edge case where the collection name contains the delimiter.
+ * Example: "$MUSIC$Unit$none$none" -> collection: "$MUSIC"
+ *
+ * Algorithm:
+ * 1. Split by delimiter
+ * 2. Take last 3 parts (from right): category, type, additionalKey
+ * 3. Everything before those 3 parts = collection (rejoin with delimiter)
+ *
+ * @param input - The delimited string to parse
+ * @param delimiter - The delimiter character ('|' or '$')
+ * @param errorContext - Optional context for error messages
+ * @returns Parsed token parts
+ * @throws ValidationError if the format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Handles $ in collection name
+ * const result = parseDelimitedTokenFromEnd('$MUSIC$Unit$none$none', '$');
+ * // { collection: '$MUSIC', category: 'Unit', type: 'none', additionalKey: 'none' }
+ *
+ * // Normal case also works
+ * const result = parseDelimitedTokenFromEnd('GALA$Unit$none$none', '$');
+ * // { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' }
+ * ```
+ *
+ * @internal
+ */
+export declare function parseDelimitedTokenFromEnd(input: string, delimiter: TokenDelimiter, errorContext?: string): DelimitedTokenParts;
+/**
+ * Validate that all required token parts are non-empty strings
+ *
+ * @param parts - Token parts to validate
+ * @param errorContext - Optional context for error messages
+ * @throws ValidationError if any part is empty
+ *
+ * @internal
+ */
+export declare function validateTokenParts(parts: Partial<DelimitedTokenParts>, errorContext?: string): asserts parts is DelimitedTokenParts;
+/**
+ * Validate that an object conforms to the TokenClassKey-like interface
+ *
+ * This is a more detailed validator that provides specific error messages
+ * including the actual type received for debugging purposes.
+ *
+ * @param obj - Object to validate
+ * @returns Validated token parts
+ * @throws ValidationError if object is invalid or missing required fields
+ *
+ * @internal
+ */
+export declare function validateTokenObject(obj: any): DelimitedTokenParts;
+/**
+ * Parse a vault address into token parts
+ *
+ * Vault address format: "service|Token$Unit$SYMBOL$additionalKey$launchpad"
+ * - First split by '|' to extract service prefix and token part
+ * - Then split token part by '$' to extract components
+ * - Handle additionalKey that may contain $ by excluding the 'launchpad' suffix
+ *
+ * @param vaultAddress - The vault address string to parse
+ * @returns Parsed token parts
+ * @throws ValidationError if the format is invalid
+ *
+ * @example
+ * ```typescript
+ * const result = parseVaultAddress('service|Token$Unit$DRAGNRKTI$eth:0x...$launchpad');
+ * // { collection: 'Token', category: 'Unit', type: 'DRAGNRKTI', additionalKey: 'eth:0x...' }
+ * ```
+ *
+ * @internal
+ */
+export declare function parseVaultAddress(vaultAddress: string): DelimitedTokenParts;
+//# sourceMappingURL=delimiter-parser.d.ts.map

package/dist/src/utils/delimiter-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delimiter-parser.d.ts","sourceRoot":"","sources":["../../../src/utils/delimiter-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,cAAc,EACzB,YAAY,CAAC,EAAE,MAAM,GACpB,mBAAmB,CA8CrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,cAAc,EACzB,YAAY,CAAC,EAAE,MAAM,GACpB,mBAAmB,CAiDrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,EACnC,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAkBtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAEjC,GAAG,EAAE,GAAG,GACP,mBAAmB,CAiDrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,mBAAmB,CAqD3E"}

package/dist/src/utils/error-factories.d.ts

@@ -314,7 +314,7 @@ export declare function createTransactionError(message: string, transactionId?:
  *   throw createNetworkError(
  *     `Failed to fetch tokens: ${getErrorMessage(error)}`,
  *     undefined,
- *     error instanceof Error ? error : undefined
+ *     isError(error) ? error : undefined
  *   );
  * }
  * ```
@@ -353,4 +353,349 @@ export declare function createTransactionError(message: string, transactionId?:
  * @since 5.0.2
  */
 export declare function handleNetworkError(error: unknown, operation: string, logger?: Logger, statusCode?: number): NetworkError;
+/**
+ * Creates a standardized "value out of range" validation error
+ *
+ * Consolidates duplicate range validation error patterns.
+ *
+ * @param fieldName The field name that is out of range
+ * @param min Minimum allowed value
+ * @param max Maximum allowed value
+ * @param actualValue The actual value that was out of range
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (page < 1 || page > 1000) {
+ *   throw createRangeError('page', 1, 1000, page);
+ * }
+ * // Throws: "Page must be between 1 and 1000, received: 0"
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createRangeError(fieldName: string, min: number | string, max: number | string, actualValue?: number | string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "value too small" validation error
+ *
+ * @param fieldName The field name
+ * @param min Minimum allowed value
+ * @param actualValue The actual value
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (amount.isLessThan(minAmount)) {
+ *   throw createTooSmallError('amount', minAmount, amount.toString());
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createTooSmallError(fieldName: string, min: number | string, actualValue?: number | string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "value too large" validation error
+ *
+ * @param fieldName The field name
+ * @param max Maximum allowed value
+ * @param actualValue The actual value
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (limit > MAX_LIMIT) {
+ *   throw createTooLargeError('limit', MAX_LIMIT, limit);
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createTooLargeError(fieldName: string, max: number | string, actualValue?: number | string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "invalid type" validation error
+ *
+ * @param fieldName The field name
+ * @param expectedType Expected type description
+ * @param actualValue Optional actual value received
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (typeof value !== 'string') {
+ *   throw createInvalidTypeError('tokenName', 'string', typeof value);
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createInvalidTypeError(fieldName: string, expectedType: string, actualValue?: unknown, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "invalid number" validation error
+ *
+ * Specialized error for numeric parsing failures.
+ *
+ * @param fieldName The field name
+ * @param actualValue The invalid value
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (isNaN(parsedValue)) {
+ *   throw createInvalidNumberError('amount', rawValue);
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createInvalidNumberError(fieldName: string, actualValue?: string | number, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "parse error" validation error
+ *
+ * Used when parsing operations fail (JSON, token formats, etc.)
+ *
+ * @param fieldName The field being parsed
+ * @param format Expected format description
+ * @param actualValue The value that failed to parse
+ * @param parseError Optional underlying parse error message
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = JSON.parse(jsonString);
+ * } catch (e) {
+ *   throw createParseError('config', 'valid JSON', jsonString, e.message);
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createParseError(fieldName: string, format: string, actualValue?: string, parseError?: string): ValidationError;
+/**
+ * Creates a standardized "pool not found" validation error
+ *
+ * Consolidates duplicate pool error messages.
+ *
+ * @param token0 First token identifier
+ * @param token1 Second token identifier
+ * @param fee Optional fee tier
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (!pool) {
+ *   throw createPoolNotFoundError('GALA', 'GUSDC', 3000);
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createPoolNotFoundError(token0: string, token1: string, fee?: number): ValidationError;
+/**
+ * Creates a standardized "position not found" validation error
+ *
+ * @param positionId The position identifier
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (!position) {
+ *   throw createPositionNotFoundError(positionId);
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createPositionNotFoundError(positionId: string | number): ValidationError;
+/**
+ * Creates a standardized "operation failed" validation error
+ *
+ * Generic factory for operation failures with context.
+ *
+ * @param operation Description of the operation that failed
+ * @param reason Reason for failure
+ * @param fieldName Optional field related to the failure
+ * @param code Optional error code (defaults to 'OPERATION_FAILED')
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * throw createOperationError('Token swap', 'insufficient liquidity', 'amount');
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createOperationError(operation: string, reason: string, fieldName?: string, code?: string): ValidationError;
+/**
+ * Creates a standardized "insufficient balance" validation error
+ *
+ * @param tokenName Token with insufficient balance
+ * @param required Required amount
+ * @param available Available amount
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (balance.isLessThan(required)) {
+ *   throw createInsufficientBalanceError('GALA', required.toString(), balance.toString());
+ * }
+ * ```
+ *
+ * @since 6.13.0
+ */
+export declare function createInsufficientBalanceError(tokenName: string, required: string, available: string): ValidationError;
+/**
+ * Creates a standardized "invalid enum value" validation error
+ *
+ * Consolidates duplicate enum validation error patterns.
+ *
+ * @param fieldName The field name with invalid enum value
+ * @param actualValue The actual value that was invalid
+ * @param validValues Array of valid enum values
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * const validStatuses = ['PENDING', 'CLAIMED', 'REVOKED'];
+ * if (!validStatuses.includes(status)) {
+ *   throw createInvalidEnumError('status', status, validStatuses);
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createInvalidEnumError(fieldName: string, actualValue: unknown, validValues: readonly string[], displayName?: string): ValidationError;
+/**
+ * Creates a standardized "mutual exclusivity" validation error
+ *
+ * Used when at least one of multiple fields must be provided.
+ *
+ * @param fieldNames Names of the mutually inclusive fields
+ * @param code Optional error code (defaults to 'MUTUAL_REQUIREMENT')
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (!options.tokenName && !options.userAddress) {
+ *   throw createMutualRequirementError(['tokenName', 'userAddress']);
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createMutualRequirementError(fieldNames: string[], code?: string): ValidationError;
+/**
+ * Creates a standardized "string too long" validation error
+ *
+ * @param fieldName The field name
+ * @param maxLength Maximum allowed length
+ * @param actualLength The actual length received
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (description.length > 255) {
+ *   throw createStringTooLongError('description', 255, description.length);
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createStringTooLongError(fieldName: string, maxLength: number, actualLength?: number, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "empty string" validation error
+ *
+ * @param fieldName The field name
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (code.trim().length === 0) {
+ *   throw createEmptyStringError('code');
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createEmptyStringError(fieldName: string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "invalid array" validation error
+ *
+ * @param fieldName The field name
+ * @param expectedElementType Expected element type description (e.g., 'strings', 'numbers')
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (!Array.isArray(tokens) || !tokens.every((t) => typeof t === 'string')) {
+ *   throw createInvalidArrayError('tokens', 'strings');
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createInvalidArrayError(fieldName: string, expectedElementType?: string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "empty array" validation error
+ *
+ * @param fieldName The field name
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (tokens.length === 0) {
+ *   throw createEmptyArrayError('tokens');
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createEmptyArrayError(fieldName: string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "invalid date" validation error
+ *
+ * @param fieldName The field name
+ * @param format Expected date format description
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (isNaN(new Date(expiresAt).getTime())) {
+ *   throw createInvalidDateError('expiresAt', 'ISO 8601 format');
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createInvalidDateError(fieldName: string, format?: string, displayName?: string): ValidationError;
+/**
+ * Creates a standardized "date in past" validation error
+ *
+ * Used for expiration dates, deadlines, or future-date requirements.
+ *
+ * @param fieldName The field name
+ * @param displayName Optional human-readable field name
+ * @returns ValidationError with standardized message
+ *
+ * @example
+ * ```typescript
+ * if (expiryDate <= new Date()) {
+ *   throw createDateInPastError('expiresAt');
+ * }
+ * ```
+ *
+ * @since 6.14.0
+ */
+export declare function createDateInPastError(fieldName: string, displayName?: string): ValidationError;
 //# sourceMappingURL=error-factories.d.ts.map

package/dist/src/utils/error-factories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-factories.d.ts","sourceRoot":"","sources":["../../../src/utils/error-factories.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,UAAU,GACnB,eAAe,CAOjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,eAAe,CAOjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,eAAe,CAOjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,KAAK,GACpB,YAAY,CAEd;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,kBAAkB,CAEpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,MAAM,GACZ,gBAAgB,CAElB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAYd"}
+{"version":3,"file":"error-factories.d.ts","sourceRoot":"","sources":["../../../src/utils/error-factories.ts"],"names":[],"mappings":"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"}