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

package/dist/src/utils/validation-helpers.d.ts

@@ -7,6 +7,18 @@
  * @category Utilities
  * @since 3.6.2
  */
+import { type TokenNameConstraint } from '../types/constraints';
+/**
+ * Pagination bounds structure (required fields)
+ *
+ * This interface defines the required pagination bounds.
+ */
+export interface PaginationBounds {
+    MIN_PAGE: number;
+    MAX_PAGE: number;
+    MIN_LIMIT: number;
+    MAX_LIMIT: number;
+}
 /**
  * Pagination constraints structure
  *
@@ -14,56 +26,11 @@
  * used across the SDK (e.g., USER_CONSTRAINTS, TRADE_CONSTRAINTS).
  */
 export interface PaginationConstraints {
-    PAGINATION: {
-        MIN_PAGE: number;
-        MAX_PAGE: number;
-        MIN_LIMIT: number;
-        MAX_LIMIT: number;
-    };
+    PAGINATION: PaginationBounds;
 }
 /**
  * Validates pagination parameters against constraint bounds
  *
- * This utility consolidates the duplicate pagination validation logic found across
- * multiple services (UserService, TradeService).
- *
- * ## Replaces Patterns
- *
- * This function replaces duplicate pagination validation across services:
- *
- * ### Before (Duplicate Private Methods):
- * ```typescript
- * // UserService.ts (lines 403-427)
- * private validateUserPagination(options: { page: number; limit: number }): void {
- *   if (typeof options.page !== 'number' ||
- *       options.page < USER_CONSTRAINTS.PAGINATION.MIN_PAGE ||
- *       options.page > USER_CONSTRAINTS.PAGINATION.MAX_PAGE) {
- *     throw new ValidationError(...);
- *   }
- *   if (typeof options.limit !== 'number' ||
- *       options.limit < USER_CONSTRAINTS.PAGINATION.MIN_LIMIT ||
- *       options.limit > USER_CONSTRAINTS.PAGINATION.MAX_LIMIT) {
- *     throw new ValidationError(...);
- *   }
- * }
- *
- * // TradeService.ts (lines 121-145) - IDENTICAL STRUCTURE
- * private validateTradePagination(options: { page: number; limit: number }): void {
- *   // Same pattern, different constraints
- * }
- * ```
- *
- * ### After (Single Source of Truth):
- * ```typescript
- * // UserService.ts
- * import { assertValidPagination } from '../utils/validation-helpers';
- * assertValidPagination(page, limit, USER_CONSTRAINTS);
- *
- * // TradeService.ts
- * import { assertValidPagination } from '../utils/validation-helpers';
- * assertValidPagination(page, limit, TRADE_CONSTRAINTS);
- * ```
- *
  * @param page - Page number to validate (1-based)
  * @param limit - Results per page limit to validate
  * @param constraints - Constraint object with PAGINATION bounds
@@ -115,33 +82,12 @@ export declare const ADDRESS_PATTERNS: {
     readonly ETH_ADDRESS: RegExp;
     /** Backend address format: eth| followed by optional 0x and 40 hexadecimal characters */
     readonly BACKEND_ADDRESS: RegExp;
-    /** Client address format: client| followed by alphanumeric characters (variable length) */
+    /** Client address format: client| followed by alphanumeric characters, hyphens, underscores (variable length) */
     readonly CLIENT_ADDRESS: RegExp;
 };
 /**
  * Type guard to check if a value is a non-empty string
  *
- * This utility consolidates the common validation pattern found across the SDK:
- * checking if a value exists, is a string, and is not empty after trimming.
- *
- * ## Replaces Pattern
- *
- * ### Before (Repeated ~40 times):
- * ```typescript
- * if (!value || typeof value !== 'string' || value.trim().length === 0) {
- *   throw new ValidationError('Value required', 'fieldName');
- * }
- * ```
- *
- * ### After (Single Source of Truth):
- * ```typescript
- * import { isNonEmptyString } from '../utils/validation-helpers';
- *
- * if (!isNonEmptyString(value)) {
- *   throw new ValidationError('Value required', 'fieldName');
- * }
- * ```
- *
  * @param value - Value to check
  * @returns True if value is a string with non-whitespace content
  *
@@ -172,98 +118,87 @@ export declare const ADDRESS_PATTERNS: {
  */
 export declare function isNonEmptyString(value: unknown): value is string;
 /**
- * Validates if a string is a valid address in either Ethereum or backend format
+ * Check if a value is "empty" (null, undefined, or empty string)
  *
- * This utility consolidates address validation logic that was duplicated across
- * services, particularly in GalaChainService.
+ * This is a common check used across parsers and validators to determine
+ * if a value should be treated as "not provided". Consolidates the pattern:
+ * `value === null || value === undefined || value === ''`
  *
- * ## Replaces Patterns
+ * @param value - Value to check
+ * @returns True if value is null, undefined, or empty string
  *
- * ### Before (Duplicate Private Method):
+ * @example Basic usage
  * ```typescript
- * // GalaChainService.ts (lines 698-703)
- * private isValidAddress(address: string): boolean {
- *   return (
- *     TRANSFER_CONSTRAINTS.ETH_ADDRESS_PATTERN.test(address) ||
- *     TRANSFER_CONSTRAINTS.BACKEND_ADDRESS_PATTERN.test(address)
- *   );
- * }
+ * isEmptyValue(null);      // true
+ * isEmptyValue(undefined); // true
+ * isEmptyValue('');        // true
+ * isEmptyValue('hello');   // false
+ * isEmptyValue(0);         // false (0 is a valid value)
+ * isEmptyValue(false);     // false (false is a valid value)
  * ```
  *
- * ### After (Single Source of Truth):
+ * @example In parser functions
  * ```typescript
- * import { isValidAddress } from '../utils/validation-helpers';
- *
- * if (!isValidAddress(data.recipientAddress)) {
- *   throw new ValidationError(...);
+ * function safeParseFloat(value: unknown, fallback: number = 0): number {
+ *   if (isEmptyValue(value)) {
+ *     return fallback;
+ *   }
+ *   // ... parsing logic
  * }
  * ```
  *
- * @param address - Address string to validate
- * @returns True if address matches either Ethereum (0x...) or backend (eth|...) format
+ * @since 6.17.0
+ */
+export declare function isEmptyValue(value: unknown): value is null | undefined | '';
+/**
+ * Check if a value is nullish (null or undefined, but NOT empty string)
  *
- * @example Ethereum address validation
- * ```typescript
- * isValidAddress('0x1234567890abcdef1234567890abcdef12345678'); // true
- * isValidAddress('0x123'); // false (too short)
- * ```
+ * Use this when you want to distinguish between "not provided" (null/undefined)
+ * and "explicitly empty" (empty string). For most parsing scenarios, use
+ * `isEmptyValue()` instead which treats empty string as equivalent to null.
  *
- * @example Backend address validation
- * ```typescript
- * isValidAddress('eth|1234567890abcdef1234567890abcdef12345678'); // true
- * isValidAddress('eth|123'); // false (too short)
- * ```
+ * @param value - Value to check
+ * @returns True if value is null or undefined
  *
- * @example Client address validation
+ * @example Basic usage
  * ```typescript
- * isValidAddress('client|abc123def456'); // true
- * isValidAddress('client|'); // false (empty after prefix)
+ * isNullish(null);      // true
+ * isNullish(undefined); // true
+ * isNullish('');        // false (empty string is NOT nullish)
+ * isNullish('hello');   // false
+ * isNullish(0);         // false
  * ```
+ *
+ * @since 6.17.0
  */
-export declare function isValidAddress(address: string): boolean;
+export declare function isNullish(value: unknown): value is null | undefined;
 /**
- * Converts an address to backend format (eth|40hex)
+ * Validates optional pagination parameters (page and limit)
  *
- * This utility consolidates address formatting logic that was duplicated across
- * services, particularly in GalaChainService. Matches the transformation logic
- * in the flexibleAddressSchema Zod schema (primitives.ts).
- *
- * ## Replaces Patterns
- *
- * ### Before (Duplicate Private Method):
- * ```typescript
- * // GalaChainService.ts (lines 708-713)
- * private formatAddressForBackend(address: string): string {
- *   if (address.startsWith('0x')) {
- *     return `eth|${address.slice(2)}`;
- *   }
- *   return address;
- * }
- * ```
+ * @param page - Optional page number to validate (1-based)
+ * @param limit - Optional results per page to validate
+ * @param maxLimit - Maximum allowed limit (default: 100)
+ * @throws ValidationError if page or limit is invalid
  *
- * ### After (Single Source of Truth):
+ * @example Basic usage
  * ```typescript
- * import { formatAddressForBackend } from '../utils/validation-helpers';
+ * import { validatePaginationOptions } from '../utils/validation-helpers';
  *
- * const recipientAddress = formatAddressForBackend(data.to);
+ * function validateListOptions(options: ListOptions): void {
+ *   validatePaginationOptions(options.page, options.limit);
+ *   // Validation passed - proceed with fetch
+ * }
  * ```
  *
- * @param address - Address in either Ethereum (0x...) or backend (eth|...) format
- * @returns Address in backend format (eth|40hex)
- *
- * @example Ethereum address conversion
+ * @example With custom max limit
  * ```typescript
- * formatAddressForBackend('0x1234567890abcdef1234567890abcdef12345678');
- * // Returns: 'eth|1234567890abcdef1234567890abcdef12345678'
+ * // For endpoints with smaller page sizes
+ * validatePaginationOptions(options.page, options.limit, 50);
  * ```
  *
- * @example Backend address passthrough
- * ```typescript
- * formatAddressForBackend('eth|1234567890abcdef1234567890abcdef12345678');
- * // Returns: 'eth|1234567890abcdef1234567890abcdef12345678' (unchanged)
- * ```
+ * @since 6.4.0
  */
-export declare function formatAddressForBackend(address: string): string;
+export declare function validatePaginationOptions(page?: number, limit?: number, maxLimit?: number): void;
 /**
  * Type guard function signature
  * A function that checks if a value matches a specific type and narrows the type accordingly
@@ -272,56 +207,6 @@ export type TypeGuard<T> = (value: unknown) => value is T;
 /**
  * Creates a validation function from a type guard
  *
- * This utility eliminates the need for boilerplate validation wrapper methods
- * that simply call a type guard and throw an error. Common pattern across services.
- *
- * ## Replaces Patterns
- *
- * ### Before (Multiple Duplicate Wrapper Methods):
- * ```typescript
- * // GalaChainService.ts - 3 separate validation methods (~30 lines total)
- * private validateFetchPoolDetailsData(data: FetchPoolDetailsData): void {
- *   if (!isFetchPoolDetailsData(data)) {
- *     throw new ValidationError(
- *       'Invalid fetch pool details data',
- *       'data',
- *       'INVALID_DATA'
- *     );
- *   }
- * }
- *
- * private validateTransferGalaData(data: TransferGalaData): void {
- *   if (!isTransferGalaData(data)) {
- *     throw new ValidationError(
- *       'Invalid transfer GALA data',
- *       'data',
- *       'INVALID_DATA'
- *     );
- *   }
- * }
- *
- * private validateTransferTokenData(data: TransferTokenData): void {
- *   if (!isTransferTokenData(data)) {
- *     throw new ValidationError(
- *       'Invalid transfer token data',
- *       'data',
- *       'INVALID_DATA'
- *     );
- *   }
- * }
- * ```
- *
- * ### After (Single Factory Function):
- * ```typescript
- * import { createValidator } from '../utils/validation-helpers';
- *
- * // Create validators inline
- * const data = req.body;
- * createValidator(isFetchPoolDetailsData, 'fetch pool details data')(data);
- * createValidator(isTransferGalaData, 'transfer GALA data')(data);
- * createValidator(isTransferTokenData, 'transfer token data')(data);
- * ```
- *
  * @param typeGuard - Type guard function that validates the data type
  * @param dataTypeName - Human-readable name for error messages (e.g., 'transfer data', 'pool details')
  * @param fieldName - Optional field name for error context (defaults to 'data')
@@ -365,6 +250,109 @@ export type TypeGuard<T> = (value: unknown) => value is T;
  * ```
  */
 export declare function createValidator<T>(typeGuard: TypeGuard<T>, dataTypeName: string, fieldName?: string, errorCode?: string): (value: unknown) => asserts value is T;
+/**
+ * Creates a type guard function for string enums
+ *
+ * This utility eliminates boilerplate for enum validation functions that follow the pattern:
+ * ```typescript
+ * function isEnumValue(value: unknown): value is MyEnum {
+ *   return typeof value === 'string' && Object.values(MyEnum).includes(value as MyEnum);
+ * }
+ * ```
+ *
+ * ## Replaces Patterns
+ *
+ * ### Before (Duplicate across DTOs):
+ * ```typescript
+ * // content-flag.dto.ts
+ * export function isContentType(value: unknown): value is ContentType {
+ *   return typeof value === 'string' && Object.values(ContentType).includes(value as ContentType);
+ * }
+ * export function isFlagReason(value: unknown): value is FlagReason {
+ *   return typeof value === 'string' && Object.values(FlagReason).includes(value as FlagReason);
+ * }
+ * // ... repeated for each enum
+ * ```
+ *
+ * ### After (Single Source of Truth):
+ * ```typescript
+ * import { createEnumTypeGuard } from '../utils/validation-helpers';
+ * export const isContentType = createEnumTypeGuard(ContentType);
+ * export const isFlagReason = createEnumTypeGuard(FlagReason);
+ * ```
+ *
+ * @param enumObj - The TypeScript enum object to create a type guard for
+ * @returns A type guard function that checks if a value is a member of the enum
+ *
+ * @example Basic usage with ContentType enum
+ * ```typescript
+ * import { createEnumTypeGuard } from '../utils/validation-helpers';
+ *
+ * enum ContentType {
+ *   CHAT_MESSAGE = 'CHAT_MESSAGE',
+ *   COMMENT = 'COMMENT',
+ *   STREAM = 'STREAM',
+ * }
+ *
+ * export const isContentType = createEnumTypeGuard(ContentType);
+ *
+ * // Usage
+ * if (isContentType(value)) {
+ *   // value is narrowed to ContentType
+ * }
+ * ```
+ *
+ * @since 6.0.0
+ */
+export declare function createEnumTypeGuard<T extends Record<string, string>>(enumObj: T): (value: unknown) => value is T[keyof T];
+/**
+ * Derives an array of values from a const object
+ *
+ * This utility eliminates the repetitive pattern of creating parallel arrays
+ * from const objects using `Object.values()`.
+ *
+ * ## Replaces Patterns
+ *
+ * ### Before (Duplicate across DTOs):
+ * ```typescript
+ * // api-key.dto.ts
+ * export const API_KEY_ROLE = { MODERATOR: 'MODERATOR', MANAGER: 'MANAGER' } as const;
+ * export type ApiKeyRole = (typeof API_KEY_ROLE)[keyof typeof API_KEY_ROLE];
+ * export const API_KEY_ROLES: ApiKeyRole[] = Object.values(API_KEY_ROLE);
+ *
+ * // moderator.dto.ts
+ * export const MODERATOR_ROLE = { ... } as const;
+ * export type ModeratorRole = (typeof MODERATOR_ROLE)[keyof typeof MODERATOR_ROLE];
+ * export const MODERATOR_ROLES: ModeratorRole[] = Object.values(MODERATOR_ROLE);
+ * ```
+ *
+ * ### After (Single Source of Truth):
+ * ```typescript
+ * import { enumValues } from '../utils/validation-helpers';
+ * export const API_KEY_ROLES = enumValues(API_KEY_ROLE);
+ * export const MODERATOR_ROLES = enumValues(MODERATOR_ROLE);
+ * ```
+ *
+ * @param enumObj - The const object to extract values from
+ * @returns A typed array of all values in the const object
+ *
+ * @example Basic usage with role const
+ * ```typescript
+ * import { enumValues } from '../utils/validation-helpers';
+ *
+ * const API_KEY_ROLE = {
+ *   MODERATOR: 'MODERATOR',
+ *   MANAGER: 'MANAGER',
+ * } as const;
+ *
+ * type ApiKeyRole = (typeof API_KEY_ROLE)[keyof typeof API_KEY_ROLE];
+ * const API_KEY_ROLES = enumValues(API_KEY_ROLE); // ['MODERATOR', 'MANAGER']
+ * // Type: ApiKeyRole[]
+ * ```
+ *
+ * @since 6.11.0
+ */
+export declare function enumValues<T extends Record<string, string>>(enumObj: T): T[keyof T][];
 /**
  * Result of mutual exclusivity validation
  */
@@ -440,4 +428,739 @@ export declare function validateMutualExclusive(obj: Record<string, unknown>, fi
     /** Whether empty strings should count as "not provided" (default: true) */
     treatEmptyAsNull?: boolean;
 }): MutualExclusivityResult;
+export type { TokenNameConstraint };
+/**
+ * Validates a launchpad token name using configurable constraints
+ *
+ * Consolidates duplicate token name validation logic found across multiple DTO files:
+ * - streaming.dto.ts (validateStreamingTokenName)
+ * - content-flag.dto.ts (validateFlagTokenName)
+ * - comment.dto.ts (inline validation)
+ * - ban.dto.ts (inline validation)
+ * - moderator.dto.ts (inline validation)
+ *
+ * ## Usage
+ *
+ * ### With default constraints (3-20 alphanumeric)
+ * ```typescript
+ * validateLaunchpadTokenName(tokenName); // Uses LAUNCHPAD_TOKEN_NAME_CONSTRAINT
+ * ```
+ *
+ * ### With custom constraints from DTO
+ * ```typescript
+ * import { STREAMING_CONSTRAINTS } from '../types/streaming.dto';
+ * validateLaunchpadTokenName(tokenName, 'tokenName', STREAMING_CONSTRAINTS.TOKEN_NAME);
+ * ```
+ *
+ * ### With custom field name for error messages
+ * ```typescript
+ * validateLaunchpadTokenName(options.tokenName, 'tokenName', BAN_CONSTRAINTS.TOKEN_NAME);
+ * ```
+ *
+ * @param tokenName - Token name to validate
+ * @param field - Field name for error messages (defaults to 'tokenName')
+ * @param constraint - Token name constraint configuration (defaults to LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @throws {ValidationError} If token name is invalid (empty, too short, too long, or invalid format)
+ *
+ * @since 6.4.0
+ */
+export declare function validateLaunchpadTokenName(tokenName: string, field?: string, constraint?: TokenNameConstraint): void;
+/**
+ * Validates an optional token name (allows undefined/null, but validates if present)
+ *
+ * Use this for optional token name fields that should be validated when provided.
+ * Consolidates duplicate logic from tokenNameValidator.ts.
+ *
+ * @param tokenName - The token name to validate (may be undefined/null)
+ * @param field - The field name for error messages (default: 'tokenName')
+ * @param constraint - Token name constraint (default: LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @throws {ValidationError} If token name is provided but invalid
+ *
+ * @example
+ * ```typescript
+ * // No error - undefined is allowed
+ * validateOptionalTokenName(undefined);
+ *
+ * // Throws ValidationError - provided but invalid
+ * validateOptionalTokenName('ab');
+ *
+ * // Success - valid token name
+ * validateOptionalTokenName('myToken123');
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function validateOptionalTokenName(tokenName: unknown, field?: string, constraint?: TokenNameConstraint): void;
+/**
+ * Checks if a token name is valid without throwing
+ *
+ * Use this for conditional checks where you don't want exceptions.
+ * Consolidates duplicate logic from tokenNameValidator.ts.
+ *
+ * @param tokenName - The token name to check
+ * @param constraint - Token name constraint (default: LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isValidTokenName(userInput)) {
+ *   // Proceed with token lookup
+ * } else {
+ *   // Show validation error to user
+ * }
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function isValidTokenName(tokenName: unknown, constraint?: TokenNameConstraint): tokenName is string;
+/**
+ * Validates a token name with constraint-specific error messages
+ *
+ * Enhanced version that provides the exact length constraint in error messages.
+ * This is the recommended function for service methods.
+ *
+ * @param tokenName - Token name to validate
+ * @param field - Field name for error messages (default: 'tokenName')
+ * @param constraint - Token name constraint with MIN_LENGTH, MAX_LENGTH, PATTERN
+ * @throws {ValidationError} If token name is invalid
+ *
+ * @example
+ * ```typescript
+ * // Throws: "tokenName must be 3-20 alphanumeric characters"
+ * validateTokenName('ab', 'tokenName', LAUNCHPAD_TOKEN_NAME_CONSTRAINT);
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function validateTokenName(tokenName: unknown, field?: string, constraint?: TokenNameConstraint): void;
+/**
+ * Field validator configuration for structural type guards
+ *
+ * Specifies how to validate a single field in a type guard.
+ *
+ * @since 6.12.0
+ */
+export interface FieldTypeValidator {
+    /** Field name to validate */
+    field: string;
+    /** Expected type: 'string', 'number', 'boolean', 'object' */
+    type: 'string' | 'number' | 'boolean' | 'object';
+    /** Whether null is an acceptable value (default: false) */
+    nullable?: boolean;
+    /** Whether undefined is acceptable (field may be missing) (default: false) */
+    optional?: boolean;
+    /** Custom validator for complex checks (return true if valid) */
+    validator?: (value: unknown) => boolean;
+}
+/**
+ * Creates a structural type guard function from field specifications
+ *
+ * This factory eliminates repetitive type guard boilerplate found across DTO files.
+ * Each type guard follows the same pattern: check object exists, cast to Record,
+ * then validate each field's type.
+ *
+ * ## Before (Duplicate across DTOs):
+ * ```typescript
+ * export function isBanData(obj: unknown): obj is BanData {
+ *   if (!obj || typeof obj !== 'object') return false;
+ *   const o = obj as Record<string, unknown>;
+ *   return (
+ *     typeof o.id === 'number' &&
+ *     typeof o.userAddress === 'string' &&
+ *     typeof o.bannedBy === 'string' &&
+ *     typeof o.createdAt === 'string' &&
+ *     typeof o.isPermanent === 'boolean' &&
+ *     (o.tokenName === null || typeof o.tokenName === 'string') &&
+ *     (o.reason === null || typeof o.reason === 'string') &&
+ *     (o.expiresAt === null || typeof o.expiresAt === 'string')
+ *   );
+ * }
+ * ```
+ *
+ * ## After (Single declaration):
+ * ```typescript
+ * export const isBanData = createStructuralTypeGuard<BanData>([
+ *   { field: 'id', type: 'number' },
+ *   { field: 'userAddress', type: 'string' },
+ *   { field: 'bannedBy', type: 'string' },
+ *   { field: 'createdAt', type: 'string' },
+ *   { field: 'isPermanent', type: 'boolean' },
+ *   { field: 'tokenName', type: 'string', nullable: true },
+ *   { field: 'reason', type: 'string', nullable: true },
+ *   { field: 'expiresAt', type: 'string', nullable: true },
+ * ]);
+ * ```
+ *
+ * @param fields - Array of field validators specifying required fields and their types
+ * @returns A type guard function that checks if an object matches the specified structure
+ *
+ * @example Basic usage with required fields
+ * ```typescript
+ * const isUser = createStructuralTypeGuard<User>([
+ *   { field: 'id', type: 'number' },
+ *   { field: 'name', type: 'string' },
+ *   { field: 'isActive', type: 'boolean' },
+ * ]);
+ *
+ * if (isUser(data)) {
+ *   console.log(data.name); // data is typed as User
+ * }
+ * ```
+ *
+ * @example With nullable and optional fields
+ * ```typescript
+ * const isComment = createStructuralTypeGuard<Comment>([
+ *   { field: 'id', type: 'number' },
+ *   { field: 'content', type: 'string' },
+ *   { field: 'parentId', type: 'number', nullable: true },
+ *   { field: 'metadata', type: 'object', optional: true },
+ * ]);
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function createStructuralTypeGuard<T>(fields: FieldTypeValidator[]): (obj: unknown) => obj is T;
+import type { FieldValidatorConfig, OptionsValidatorWithErrors } from '../types/common';
+/**
+ * Common field validators for reuse across validation functions
+ *
+ * These validators can be used with `createOptionsValidator` or directly.
+ *
+ * @since 6.12.0
+ */
+export declare const commonValidators: {
+    /**
+     * Creates a validator for required non-empty string fields
+     */
+    requiredString: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for max length string fields
+     */
+    maxLength: (field: string, max: number) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for positive integer fields
+     */
+    positiveInteger: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for required positive integer fields
+     */
+    requiredPositiveInteger: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for enum values
+     */
+    enumValue: <T extends string>(field: string, validValues: readonly T[]) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for required enum values
+     */
+    requiredEnumValue: <T extends string>(field: string, validValues: readonly T[]) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for ISO date strings
+     */
+    isoDate: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for wallet addresses
+     */
+    walletAddress: (field: string, required?: boolean) => (value: unknown) => string | undefined;
+};
+/**
+ * Creates an options validator from field configurations
+ *
+ * This factory eliminates duplicate validation boilerplate across DTO files.
+ * Returns an array of error messages (empty if valid), which aligns with
+ * moderator.dto.ts and api-key.dto.ts validation patterns.
+ *
+ * ## Usage
+ *
+ * ### Basic field validation
+ * ```typescript
+ * import { createOptionsValidator, commonValidators } from '../utils/validation-helpers';
+ *
+ * const validateCreateOptions = createOptionsValidator<CreateOptions>([
+ *   { field: 'name', required: true, type: 'string' },
+ *   { field: 'description', validator: commonValidators.maxLength('description', 255) },
+ *   { field: 'status', validator: commonValidators.enumValue('status', ['active', 'inactive']) },
+ * ]);
+ *
+ * // Usage
+ * const errors = validateCreateOptions(options);
+ * if (errors.length > 0) {
+ *   throw new ValidationError(errors[0], 'options', 'VALIDATION_FAILED');
+ * }
+ * ```
+ *
+ * ### With custom validators
+ * ```typescript
+ * const validateOptions = createOptionsValidator<MyOptions>([
+ *   { field: 'tokenName', validator: (value) => {
+ *     try {
+ *       validateLaunchpadTokenName(value as string, 'tokenName');
+ *       return undefined;
+ *     } catch (e) {
+ *       return (e as Error).message;
+ *     }
+ *   }},
+ * ]);
+ * ```
+ *
+ * @param configs - Array of field validator configurations
+ * @returns Validation function that returns an array of error messages
+ *
+ * @since 6.12.0
+ */
+export declare function createOptionsValidator<T extends Record<string, unknown>>(configs: FieldValidatorConfig[]): OptionsValidatorWithErrors<T>;
+/**
+ * Regular expression pattern for validating decimal amount strings
+ *
+ * Matches positive decimal numbers like "123", "45.67", "0.001"
+ * Does NOT match negative numbers, leading/trailing dots, or scientific notation.
+ *
+ * @since 6.18.0
+ */
+export declare const DECIMAL_AMOUNT_PATTERN: RegExp;
+/**
+ * Validates a decimal amount string
+ *
+ * Used for validating token amounts in transfer, lock, unlock, burn operations.
+ * Consolidates duplicate validation logic from transfer.dto.ts, lock.dto.ts, burn.dto.ts.
+ *
+ * @param amount - Amount string to validate
+ * @param fieldPath - Field path for error messages (e.g., 'amount', 'tokens[0].amount')
+ * @param options - Validation options
+ * @throws {ValidationError} If amount is invalid
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * validateDecimalAmount(data.amount, 'amount');
+ *
+ * // In batch validation
+ * validateDecimalAmount(entry.amount, `tokens[${index}].amount`);
+ *
+ * // Allow zero
+ * validateDecimalAmount(data.amount, 'amount', { allowZero: true });
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateDecimalAmount(amount: unknown, fieldPath: string, options?: {
+    allowZero?: boolean;
+}): void;
+/**
+ * Validates a token name against a regex pattern
+ *
+ * Used for validating token names in batch operations where full launchpad validation
+ * is not appropriate. Consolidates duplicate validation from lock.dto.ts, burn.dto.ts.
+ *
+ * @param tokenName - Token name to validate
+ * @param fieldPath - Field path for error messages (e.g., 'tokenName', 'tokens[0].tokenName')
+ * @param pattern - Regex pattern for validation
+ * @throws {ValidationError} If token name is invalid
+ *
+ * @example
+ * ```typescript
+ * import { TOKEN_NAME_PATTERN } from './constraints';
+ *
+ * // In batch validation
+ * if (entry.tokenName !== undefined) {
+ *   validateTokenNamePattern(entry.tokenName, `tokens[${index}].tokenName`, TOKEN_NAME_PATTERN);
+ * }
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateTokenNamePattern(tokenName: unknown, fieldPath: string, pattern: RegExp): void;
+/**
+ * Validates that a batch array meets size constraints
+ *
+ * Consolidates duplicate validation from lock.dto.ts, burn.dto.ts for batch operations.
+ *
+ * @param array - Array to validate
+ * @param fieldName - Field name for error messages (e.g., 'tokens')
+ * @param maxSize - Maximum allowed array size
+ * @throws {ValidationError} If array is invalid or exceeds max size
+ *
+ * @example
+ * ```typescript
+ * validateBatchArray(data.tokens, 'tokens', MAX_LOCK_BATCH_SIZE);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateBatchArray(array: unknown, fieldName: string, maxSize: number): void;
+/**
+ * Validates an optional unique key string
+ *
+ * Consolidates duplicate validation from transfer.dto.ts, lock.dto.ts, burn.dto.ts.
+ *
+ * @param uniqueKey - Unique key to validate (may be undefined)
+ * @param maxLength - Maximum allowed length
+ * @throws {ValidationError} If unique key is invalid
+ *
+ * @example
+ * ```typescript
+ * import { UNIQUE_KEY_CONSTRAINT } from './constraints';
+ *
+ * validateUniqueKey(data.uniqueKey, UNIQUE_KEY_CONSTRAINT.MAX_LENGTH);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateUniqueKey(uniqueKey: unknown, maxLength: number): void;
+/**
+ * Validates an optional private key string
+ *
+ * Simple type check for optional private key override.
+ * Consolidates duplicate validation from transfer.dto.ts, lock.dto.ts, burn.dto.ts.
+ *
+ * @param privateKey - Private key to validate (may be undefined)
+ * @throws {ValidationError} If private key is not a string
+ *
+ * @since 6.18.0
+ */
+export declare function validateOptionalPrivateKey(privateKey: unknown): void;
+/**
+ * Validates that at least one of two token identifier fields is provided
+ *
+ * Common pattern in batch operations where either tokenId or tokenName is required.
+ * Consolidates duplicate validation from lock.dto.ts, burn.dto.ts.
+ *
+ * @param entry - Object containing tokenId and/or tokenName
+ * @param fieldPath - Base field path for error messages (e.g., 'tokens[0]')
+ * @throws {ValidationError} If neither tokenId nor tokenName is provided
+ *
+ * @example
+ * ```typescript
+ * validateTokenIdentifier(entry, `tokens[${index}]`);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateTokenIdentifier(entry: {
+    tokenId?: unknown;
+    tokenName?: unknown;
+}, fieldPath: string): void;
+/**
+ * NOTE: The primary `isValidAddress()` function is in address-formatter.ts
+ *
+ * Import it from there:
+ * ```typescript
+ * import { isValidAddress } from './address-formatter';
+ * ```
+ *
+ * This consolidation ensures all address validation uses a single,
+ * well-tested implementation with ADDRESS_PATTERNS for consistency.
+ */
+/**
+ * Throws ValidationError if required field is null/undefined with customizable messages
+ *
+ * Use this to validate that required fields are present. Supports generic type
+ * narrowing so TypeScript knows the value is not null/undefined after this check.
+ *
+ * @template T The type of the value being validated
+ * @param value The value to check (can be T, null, or undefined)
+ * @param fieldName Internal field name for error codes (e.g., 'wallet', 'signatureHelper')
+ * @param displayName Optional user-friendly display name for error messages (e.g., 'Wallet instance')
+ * @returns The value if it's not null/undefined (strongly typed as T)
+ * @throws {ValidationError} If value is null or undefined with fieldName and error code REQUIRED
+ *
+ * @example
+ * ```typescript
+ * // Simple validation
+ * const wallet = throwIfMissing(this.wallet, 'wallet', 'Wallet instance');
+ * // wallet is now guaranteed to be non-null by TypeScript
+ *
+ * // Multi-field validation
+ * throwIfMissing(this.wallet, 'wallet', 'Wallet instance');
+ * throwIfMissing(this.signatureHelper, 'signatureHelper', 'Signature helper');
+ * // Both are now guaranteed non-null
+ *
+ * // Generic type preservation
+ * interface Config { apiKey: string }
+ * const config = throwIfMissing<Config>(userConfig, 'config', 'Configuration object');
+ * // config is now Config (not Config | null | undefined)
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function throwIfMissing<T>(value: T | null | undefined, fieldName: string, displayName?: string): T;
+/**
+ * Check if array has no elements (length === 0)
+ *
+ * Provides a readable way to check for empty arrays. Handles null/undefined
+ * gracefully by returning true (treating them as "empty").
+ *
+ * @template T The type of array elements
+ * @param arr The array to check (can be T[], null, or undefined)
+ * @returns True if array is null, undefined, or has length === 0; false otherwise
+ *
+ * @example Basic empty check
+ * ```typescript
+ * import { isEmptyArray } from '@gala-chain/launchpad-sdk';
+ *
+ * const tokens = []; // or null, or undefined
+ *
+ * if (isEmptyArray(tokens)) {
+ *   console.log('No tokens to process');
+ *   return;
+ * }
+ * ```
+ *
+ * @example In conditional logic
+ * ```typescript
+ * import { isEmptyArray } from '@gala-chain/launchpad-sdk';
+ *
+ * if (!symbols || isEmptyArray(symbols)) {
+ *   throw new ValidationError('At least one symbol is required');
+ * }
+ * ```
+ *
+ * @example With different array types
+ * ```typescript
+ * import { isEmptyArray } from '@gala-chain/launchpad-sdk';
+ *
+ * // Works with objects
+ * if (isEmptyArray(this.tokenInstances)) return undefined;
+ *
+ * // Works with strings
+ * if (isEmptyArray(errors)) {
+ *   console.log('Validation passed');
+ * }
+ *
+ * // Works with numbers
+ * const amounts: number[] = [];
+ * if (isEmptyArray(amounts)) {
+ *   console.log('No amounts provided');
+ * }
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function isEmptyArray<T>(arr: T[] | null | undefined): boolean;
+/**
+ * Check if string is empty or contains only whitespace
+ *
+ * A concise alternative to `str.trim().length === 0` or `!str || !str.trim()`.
+ * Returns true if the string is null, undefined, empty, or contains only whitespace characters.
+ * Whitespace includes spaces, tabs, line breaks, carriage returns, form feeds, and non-breaking spaces.
+ *
+ * @param value String to check
+ * @returns true if string is empty or only contains whitespace
+ *
+ * @example Basic check
+ * ```typescript
+ * import { isEmptyOrWhitespace } from '@gala-chain/launchpad-sdk';
+ *
+ * if (isEmptyOrWhitespace(userInput)) {
+ *   console.log('Please provide valid input');
+ * }
+ * ```
+ *
+ * @example Validation in form handlers
+ * ```typescript
+ * const validateReason = (reason: string) => {
+ *   if (isEmptyOrWhitespace(reason)) {
+ *     throw new Error('Reason is required');
+ *   }
+ *   return reason.trim();
+ * };
+ * ```
+ *
+ * @example Filtering whitespace-only values
+ * ```typescript
+ * const values = ['hello', '  ', '', 'world', '\t\n'];
+ * const filtered = values.filter(v => !isEmptyOrWhitespace(v));
+ * // Result: ['hello', 'world']
+ * ```
+ *
+ * @example Conditional logic
+ * ```typescript
+ * const displayName = !isEmptyOrWhitespace(nickname) ? nickname : fullName;
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function isEmptyOrWhitespace(value: string): boolean;
+/**
+ * Supported DEX fee tiers in basis points
+ *
+ * Basis points (bps) are used for precise fee tier representation.
+ * 1 basis point = 0.01% = 1/100th of a percent.
+ *
+ * @constant
+ * @example
+ * ```typescript
+ * import { FEE_TIERS } from '@gala-chain/launchpad-sdk';
+ *
+ * const fees = [FEE_TIERS.LOW, FEE_TIERS.MEDIUM, FEE_TIERS.HIGH];
+ * // [500, 3000, 10000]
+ *
+ * const feeName = {
+ *   [FEE_TIERS.LOW]: '0.05%',
+ *   [FEE_TIERS.MEDIUM]: '0.30%',
+ *   [FEE_TIERS.HIGH]: '1.00%'
+ * };
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare const FEE_TIERS: {
+    readonly LOW: 500;
+    readonly MEDIUM: 3000;
+    readonly HIGH: 10000;
+};
+/**
+ * Type-safe fee tier validation assertion
+ *
+ * Validates that a value is one of the recognized fee tiers (500, 3000, 10000).
+ * Throws ValidationError if the value is not a valid fee tier.
+ *
+ * Uses enumValidationWithObjectValues for consistent enum validation.
+ *
+ * @param value - Value to validate as a fee tier
+ * @param field - Optional field name for error messages (default: 'feeTier')
+ * @throws ValidationError if value is not a recognized fee tier
+ *
+ * @example Basic validation
+ * ```typescript
+ * import { validateFeeTier } from '@gala-chain/launchpad-sdk';
+ *
+ * function createPool(fee: number) {
+ *   validateFeeTier(fee);
+ *   // Safe to use fee
+ * }
+ * ```
+ *
+ * @example With custom field name
+ * ```typescript
+ * try {
+ *   validateFeeTier(5000, 'poolFee');
+ * } catch (error) {
+ *   console.log(error.message); // 'Invalid poolFee: 5000'
+ * }
+ * ```
+ *
+ * @example In form validation
+ * ```typescript
+ * const validatePoolForm = (data: PoolFormData) => {
+ *   try {
+ *     validateFeeTier(data.fee, 'fee');
+ *   } catch (error) {
+ *     return { field: 'fee', error: 'Invalid fee tier' };
+ *   }
+ * };
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare function validateFeeTier(value: unknown, field?: string): void;
+/**
+ * Type guard to check if value is a valid fee tier
+ *
+ * Returns true if value is one of the recognized fee tiers (500, 3000, 10000).
+ * Returns false for any other value including null, undefined, and invalid numbers.
+ *
+ * Use this for conditional logic and filtering without throwing errors.
+ *
+ * @param value - Value to check
+ * @returns true if value is a recognized fee tier
+ *
+ * @example Conditional logic
+ * ```typescript
+ * import { isValidFeeTier } from '@gala-chain/launchpad-sdk';
+ *
+ * const userFee = getUserInput();
+ * if (isValidFeeTier(userFee)) {
+ *   createPool({ fee: userFee });
+ * } else {
+ *   showError('Please select a valid fee tier');
+ * }
+ * ```
+ *
+ * @example Filtering
+ * ```typescript
+ * const fees = [500, 1000, 3000, 5000, 10000];
+ * const validFees = fees.filter(fee => isValidFeeTier(fee));
+ * // Result: [500, 3000, 10000]
+ * ```
+ *
+ * @example Type narrowing
+ * ```typescript
+ * const processFee = (value: unknown) => {
+ *   if (isValidFeeTier(value)) {
+ *     // TypeScript knows value is number here
+ *     const tier = value * 0.0001; // Convert to percentage
+ *     return tier;
+ *   }
+ *   return null;
+ * };
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare function isValidFeeTier(value: unknown): value is number;
+/**
+ * Normalize fee percentage to basis points
+ *
+ * Converts decimal percentage values (0.05, 0.30, 1.0) to basis points (500, 3000, 10000).
+ * Useful for converting user-friendly percentage input to internal fee tier representation.
+ *
+ * Returns null if the percentage doesn't correspond to a standard fee tier.
+ *
+ * @param percentage - Fee percentage in decimal format (0.05 = 0.05%, 0.30 = 0.30%, etc.)
+ * @returns Basis points equivalent (500, 3000, 10000) or null if not a standard tier
+ *
+ * @example Converting percentages
+ * ```typescript
+ * import { normalizeFeeTier } from '@gala-chain/launchpad-sdk';
+ *
+ * normalizeFeeTier(0.05)  // Returns: 500
+ * normalizeFeeTier(0.30)  // Returns: 3000
+ * normalizeFeeTier(1.00)  // Returns: 10000
+ * normalizeFeeTier(0.50)  // Returns: null (not a standard tier)
+ * ```
+ *
+ * @example Form input conversion
+ * ```typescript
+ * const handleFeeInput = (percentageInput: string) => {
+ *   const percentage = parseFloat(percentageInput) / 100;
+ *   const basisPoints = normalizeFeeTier(percentage);
+ *
+ *   if (basisPoints === null) {
+ *     showError('Please select a standard fee tier');
+ *     return;
+ *   }
+ *
+ *   createPool({ fee: basisPoints });
+ * };
+ * ```
+ *
+ * @example With fallback
+ * ```typescript
+ * const feeBasisPoints = normalizeFeeTier(userInput) ?? FEE_TIERS.MEDIUM;
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare function normalizeFeeTier(percentage: number): number | null;
+/**
+ * Extracts and concatenates error messages from Zod validation errors
+ *
+ * Consolidates the pattern of extracting error messages from Zod validation results:
+ * `result.error.errors.map(e => e.message).join('; ')`
+ *
+ * @param errors - Array of Zod validation errors
+ * @returns Array of error message strings
+ *
+ * @example
+ * ```typescript
+ * const result = schema.safeParse(data);
+ * if (!result.success) {
+ *   const messages = collectValidationErrors(result.error.errors);
+ *   // Returns: ['Field is required', 'Must be at least 3 characters']
+ * }
+ * ```
+ *
+ * @since 6.30.0
+ */
+export declare function collectValidationErrors(errors: unknown[]): string[];
 //# sourceMappingURL=validation-helpers.d.ts.map