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

package/dist/utils/service-validators.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Service-Layer Validation Utilities
+ *
+ * Consolidated validators for service methods. Eliminates 927+ duplicate validation patterns:
+ * - 352+ string type checks
+ * - 210+ range/boundary checks
+ * - 127+ string length checks
+ * - 89+ number type checks
+ * - 69+ Array.isArray() checks
+ * - 21+ Number.isInteger() checks
+ *
+ * These validators are designed for service methods where validation failure should throw.
+ * For conditional validation, use validation-helpers.ts instead.
+ *
+ * @category Utilities
+ * @since 6.18.0
+ */
+import type { TokenNameConstraint } from '../types/constraints';
+/**
+ * Validates that a value is a required non-empty string
+ *
+ * Consolidates 352+ instances of:
+ * ```typescript
+ * if (typeof value !== 'string' || value.trim().length === 0) {
+ *   throw new ValidationError('...');
+ * }
+ * ```
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is not a non-empty string
+ *
+ * @example
+ * ```typescript
+ * validateRequiredString(options.tokenName, 'tokenName');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateRequiredString(value: unknown, field: string): asserts value is string;
+/**
+ * Validates that a value is an optional string with optional max length constraint
+ *
+ * Consolidates 127+ instances of string length checking and type validation.
+ * Allows undefined/null for optional fields.
+ *
+ * @param value Value to validate (may be undefined/null)
+ * @param field Field name for error messages
+ * @param maxLength Optional maximum length (no limit if not provided)
+ * @throws {ValidationError} If value is provided but invalid
+ *
+ * @example No length constraint
+ * ```typescript
+ * validateOptionalString(options.description, 'description');
+ * ```
+ *
+ * @example With length constraint
+ * ```typescript
+ * validateOptionalString(options.reason, 'reason', 255);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateOptionalString(value: unknown, field: string, maxLength?: number): void;
+/**
+ * Validates that a value is a positive integer
+ *
+ * Consolidates 21+ instances of:
+ * ```typescript
+ * if (!Number.isInteger(value) || value < 1) {
+ *   throw new ValidationError('...');
+ * }
+ * ```
+ *
+ * Delegates to positiveIntegerValidation from validation-patterns.ts.
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is not a positive integer
+ *
+ * @example
+ * ```typescript
+ * validatePositiveInteger(options.limit, 'limit');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validatePositiveInteger(value: unknown, field: string): asserts value is number;
+/**
+ * Validates that a value is a number within a range (optional field)
+ *
+ * Consolidates 210+ instances of range checking:
+ * ```typescript
+ * if (typeof value !== 'number' || value < min || value > max) {
+ *   throw createRangeError(...);
+ * }
+ * ```
+ *
+ * Allows undefined/null for optional fields.
+ *
+ * @param value Value to validate (may be undefined/null)
+ * @param field Field name for error messages
+ * @param min Minimum allowed value (inclusive)
+ * @param max Maximum allowed value (inclusive)
+ * @throws {ValidationError} If value is provided but outside range
+ *
+ * @example
+ * ```typescript
+ * validateOptionalNumber(options.slippage, 'slippage', 0.001, 0.5);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateOptionalNumber(value: unknown, field: string, min?: number, max?: number): void;
+/**
+ * Validates token name with constraints (required field)
+ *
+ * Consolidates duplicate token name validation across multiple services.
+ * Validates token name is 3-20 alphanumeric characters by default.
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages (default: 'tokenName')
+ * @param constraint Token name constraint (default: LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @throws {ValidationError} If token name is invalid
+ *
+ * @example
+ * ```typescript
+ * validateTokenNameWithConstraints(options.tokenName, 'tokenName');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateTokenNameWithConstraints(value: unknown, field?: string, constraint?: TokenNameConstraint): asserts value is string;
+/**
+ * Validates a status filter value (optional)
+ *
+ * Used in services that have status filtering options.
+ * Allows undefined/null and validates against allowed values.
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @param allowedValues Array of allowed status values
+ * @throws {ValidationError} If value is provided but not in allowed values
+ *
+ * @example
+ * ```typescript
+ * validateStatusFilter(options.status, 'status', ['active', 'inactive', 'pending']);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateStatusFilter(value: unknown, field: string, allowedValues: readonly string[]): void;
+/**
+ * Validates that a value is a non-empty array (required field)
+ *
+ * Consolidates 69+ instances of Array.isArray() checks with additional validation.
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is not a non-empty array
+ *
+ * @example
+ * ```typescript
+ * validateNonEmptyArray(options.tokens, 'tokens');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateNonEmptyArray(value: unknown, field: string): asserts value is unknown[];
+/**
+ * Validates that an array length is within bounds (optional field)
+ *
+ * Allows undefined/null for optional array fields.
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @param maxLength Maximum allowed array length
+ * @throws {ValidationError} If array exceeds max length
+ *
+ * @example
+ * ```typescript
+ * validateArrayLength(options.tags, 'tags', 10);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateArrayLength(value: unknown, field: string, maxLength: number): void;
+/**
+ * Validates that a value is an optional non-null object (excluding arrays)
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is provided but not an object
+ *
+ * @example
+ * ```typescript
+ * validateOptionalObject(options.metadata, 'metadata');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateOptionalObject(value: unknown, field: string): asserts value is object | undefined | null;
+/**
+ * Validates that a value is a required non-null object (excluding arrays)
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is not an object
+ *
+ * @example
+ * ```typescript
+ * validateRequiredObject(options.config, 'config');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateRequiredObject(value: unknown, field: string): asserts value is object;
+/**
+ * Validates that a value is an optional date
+ *
+ * Accepts Date objects, ISO 8601 date strings, or numeric timestamps.
+ * Allows undefined/null for optional fields.
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is provided but not a valid date
+ *
+ * @example
+ * ```typescript
+ * validateOptionalDate(options.expiresAt, 'expiresAt');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateOptionalDate(value: unknown, field: string): void;
+/**
+ * Validates a required date (Date object, ISO 8601 string, or numeric timestamp)
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @throws {ValidationError} If value is not a valid date
+ *
+ * @example
+ * ```typescript
+ * validateRequiredDate(options.startDate, 'startDate');
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateRequiredDate(value: unknown, field: string): asserts value is Date | string | number;
+/**
+ * Validates that a value is within a string length range (required field)
+ *
+ * @param value Value to validate
+ * @param field Field name for error messages
+ * @param minLength Minimum allowed length
+ * @param maxLength Maximum allowed length
+ * @throws {ValidationError} If string is outside the length range
+ *
+ * @example
+ * ```typescript
+ * validateStringLength(options.reason, 'reason', 1, 500);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateStringLength(value: unknown, field: string, minLength: number, maxLength: number): asserts value is string;
+//# sourceMappingURL=service-validators.d.ts.map

package/dist/utils/service-validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-validators.d.ts","sourceRoot":"","sources":["../../src/utils/service-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAWhE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAO7F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAmB9F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAE9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM,GACX,IAAI,CAeN;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,MAAoB,EAC3B,UAAU,GAAE,mBAAqD,GAChE,OAAO,CAAC,KAAK,IAAI,MAAM,CAgCzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,IAAI,CAmBN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,EAAE,CAW/F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAmB1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,GAAG,SAAS,GAAG,IAAI,CAM5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,CAIzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA0BxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,GAAG,MAAM,GAAG,MAAM,CA0B3G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,IAAI,MAAM,CAQzB"}

package/dist/utils/slippage-utils.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Slippage tolerance utilities for trading operations
+ *
+ * Provides precise slippage calculations for buy and sell operations to protect
+ * against price movement between quote calculation and transaction execution.
+ *
+ * @category Utilities
+ * @since 2.0.0
+ */
+/**
+ * Operation types for slippage calculation
+ */
+export type SlippageOperationType = 'buy-native' | 'buy-exact' | 'sell-exact' | 'sell-native';
+/**
+ * Apply slippage tolerance to an expected amount for trading operations
+ *
+ * Slippage tolerance protects against price movement by adjusting the minimum/maximum
+ * acceptable amounts in the direction that favors the user:
+ *
+ * **Buy Operations:**
+ * - buy-native: Reduce minimum tokens expected (accept receiving less)
+ * - buy-exact: Increase maximum GALA cost (accept paying more)
+ *
+ * **Sell Operations:**
+ * - sell-exact: Reduce minimum GALA expected (accept receiving less)
+ * - sell-native: Increase maximum tokens to sell (accept selling more)
+ *
+ * @param expectedAmount The calculated expected amount from bonding curve
+ * @param slippageToleranceFactor Slippage tolerance as decimal (e.g., 0.05 = 5%)
+ * @param operationType The specific trading operation type
+ * @returns Adjusted amount with slippage protection applied
+ *
+ * @example
+ * ```typescript
+ * // Buy native: Accept receiving 5% fewer tokens
+ * const protectedTokens = applySlippageTolerance("1000", 0.05, "buy-native");
+ * // Returns "950" (5% less tokens acceptable)
+ *
+ * // Buy exact: Accept paying 5% more GALA
+ * const protectedGala = applySlippageTolerance("100", 0.05, "buy-exact");
+ * // Returns "105" (5% more GALA acceptable)
+ *
+ * // Sell exact: Accept receiving 5% less GALA
+ * const protectedGala = applySlippageTolerance("100", 0.05, "sell-exact");
+ * // Returns "95" (5% less GALA acceptable)
+ * ```
+ *
+ * @throws {Error} If slippageToleranceFactor is negative or greater than 1
+ * @throws {Error} If expectedAmount is not a valid number
+ */
+export declare function applySlippageTolerance(expectedAmount: string, slippageToleranceFactor: number, operationType: SlippageOperationType): string;
+/**
+ * Calculate the effective slippage percentage between two amounts
+ *
+ * Useful for debugging and logging to show the actual slippage applied.
+ *
+ * @param originalAmount The original expected amount
+ * @param adjustedAmount The slippage-adjusted amount
+ * @returns The effective slippage percentage as a decimal (e.g., 0.05 = 5%)
+ *
+ * @example
+ * ```typescript
+ * const original = "1000";
+ * const adjusted = "950";
+ * const slippage = calculateEffectiveSlippage(original, adjusted);
+ * console.log(`Applied ${slippage * 100}% slippage`); // "Applied 5% slippage"
+ * ```
+ */
+export declare function calculateEffectiveSlippage(originalAmount: string, adjustedAmount: string): number;
+//# sourceMappingURL=slippage-utils.d.ts.map

package/dist/utils/slippage-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slippage-utils.d.ts","sourceRoot":"","sources":["../../src/utils/slippage-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,aAAa,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,MAAM,EACtB,uBAAuB,EAAE,MAAM,EAC/B,aAAa,EAAE,qBAAqB,GACnC,MAAM,CAsDR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR"}