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

package/dist/utils/trade-transformers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Trade Result Transformers
+ *
+ * Shared utilities for transforming WebSocket trade responses into TradeResult objects.
+ * Eliminates duplicate transformation logic between buy() and sell() operations.
+ *
+ * @category Utilities
+ * @since 3.7.2
+ */
+import type { BuyTokenOptions, SellTokenOptions } from '../types/options.dto';
+import type { TradeResult } from '../types/result.types';
+/**
+ * Transform WebSocket trade response into TradeResult
+ *
+ * This function consolidates the duplicate transformation logic from buy() and sell() methods.
+ * The only difference between buy and sell transformations is the 'type' field.
+ *
+ * @param wsResponse Raw WebSocket response
+ * @param transactionId Transaction ID for validation
+ * @param tradeType Type of trade ('buy' or 'sell')
+ * @param options Original trade options (buy or sell)
+ * @returns Transformed TradeResult object
+ *
+ * @throws {WebSocketError} If response structure is invalid
+ * @throws {WebSocketError} If trade data validation fails
+ */
+export declare function transformTradeResult(wsResponse: unknown, transactionId: string, tradeType: 'buy' | 'sell', options: BuyTokenOptions | SellTokenOptions): TradeResult;
+//# sourceMappingURL=trade-transformers.d.ts.map

package/dist/utils/trade-transformers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trade-transformers.d.ts","sourceRoot":"","sources":["../../src/utils/trade-transformers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,OAAO,EACnB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,KAAK,GAAG,MAAM,EACzB,OAAO,EAAE,eAAe,GAAG,gBAAgB,GAC1C,WAAW,CAqCb"}

package/dist/utils/transfer-validation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Transfer Validation Helper
+ *
+ * Centralized validation logic for transfer operations (GALA and token transfers).
+ * Eliminates duplication between validateTransferGalaData and validateTransferTokenData
+ * in GalaChainService.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Transfer validation helper for common validation patterns
+ *
+ * Provides reusable validation methods for amount and uniqueKey fields
+ * used in both GALA and token transfer operations.
+ */
+export declare class TransferValidationHelper {
+    /**
+     * Validate transfer amount is positive
+     *
+     * @param amount - Amount string to validate
+     * @throws {TransferError} If amount is not positive
+     *
+     * @example
+     * ```typescript
+     * TransferValidationHelper.validateAmount('100');
+     * // OK: No error thrown
+     *
+     * TransferValidationHelper.validateAmount('0');
+     * // Throws: TransferError with INVALID_AMOUNT type
+     * ```
+     */
+    static validateAmount(amount: string): void;
+    /**
+     * Validate unique key format and length
+     *
+     * Checks that uniqueKey (if provided) meets constraints:
+     * - Maximum length: UNIQUE_KEY_CONSTRAINT.MAX_LENGTH
+     * - Format pattern: Must start with "galaswap-operation-" or "galaconnect-operation-"
+     *
+     * @param uniqueKey - Optional unique key to validate
+     * @throws {ValidationError} If unique key exceeds maximum length
+     * @throws {TransferError} If unique key format is invalid
+     *
+     * @example
+     * ```typescript
+     * TransferValidationHelper.validateUniqueKey('galaconnect-operation-12345');
+     * // OK: Valid format
+     *
+     * TransferValidationHelper.validateUniqueKey('invalid-format');
+     * // Throws: TransferError with invalid format message
+     *
+     * TransferValidationHelper.validateUniqueKey(undefined);
+     * // OK: undefined is allowed (validation skipped)
+     * ```
+     */
+    static validateUniqueKey(uniqueKey: string | undefined): void;
+}
+//# sourceMappingURL=transfer-validation.d.ts.map

package/dist/utils/transfer-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-validation.d.ts","sourceRoot":"","sources":["../../src/utils/transfer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAqB9D"}

package/dist/utils/type-guard-factory.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Type Guard Factory
+ *
+ * Factory function for creating type guards that validate object shapes.
+ * Eliminates 50+ duplicate type guard implementations across DTOs by providing
+ * a declarative, configuration-based approach.
+ *
+ * ## Problem Solved
+ *
+ * Before this factory, every DTO file contained 5-15 nearly identical type guards:
+ *
+ * ```typescript
+ * // Repeated pattern in 50+ type guards
+ * export function isBuyTokensData(obj: unknown): obj is BuyTokensData {
+ *   if (!obj || typeof obj !== 'object') return false;
+ *   const o = obj as Record<string, unknown>;
+ *   return (
+ *     typeof o.tokenSymbol === 'string' &&
+ *     typeof o.nativeTokenQuantity === 'string' &&
+ *     typeof o.expectedToken === 'string' &&
+ *     (o.maxAcceptableReverseBondingCurveFee === undefined ||
+ *       typeof o.maxAcceptableReverseBondingCurveFee === 'string')
+ *   );
+ * }
+ * ```
+ *
+ * ## Solution
+ *
+ * ```typescript
+ * // Before: 10+ lines of boilerplate per type guard
+ * // After: 1-2 lines of declarative configuration
+ * const isBuyTokensData = createTypeGuard<BuyTokensData>({
+ *   tokenSymbol: 'string',
+ *   nativeTokenQuantity: 'string',
+ *   expectedToken: 'string',
+ *   maxAcceptableReverseBondingCurveFee: 'optional-string'
+ * });
+ * ```
+ *
+ * @category Utilities
+ * @since 3.33.0
+ */
+/**
+ * Type field specification - defines the expected type and optionality
+ * of a field in an object being validated.
+ *
+ * Examples:
+ * - 'string' - Required string field
+ * - 'number' - Required number field
+ * - 'boolean' - Required boolean field
+ * - 'object' - Required object field (nested object)
+ * - 'array' - Required array field
+ * - 'optional-string' - Optional string field (undefined allowed)
+ * - 'optional-number' - Optional number field (undefined allowed)
+ * - 'optional-boolean' - Optional boolean field (undefined allowed)
+ * - 'optional-object' - Optional object field (undefined allowed)
+ * - 'optional-array' - Optional array field (undefined allowed)
+ */
+export type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'optional-string' | 'optional-number' | 'optional-boolean' | 'optional-object' | 'optional-array';
+/**
+ * Field specification for type guard validation
+ *
+ * Maps field names to their expected types. Used to declare the shape
+ * of an object that the type guard will validate.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'string',
+ *   age: 'number',
+ *   active: 'boolean',
+ *   metadata: 'optional-object',
+ *   tags: 'optional-array'
+ * }
+ * ```
+ */
+export type FieldSpec = Record<string, FieldType>;
+/**
+ * Creates a type guard function from a field specification
+ *
+ * This factory generates reusable type guard functions that validate object shapes
+ * based on a declarative configuration. Eliminates the need for manual type guard
+ * implementations while maintaining full type safety.
+ *
+ * ## Key Features
+ *
+ * - **Declarative Configuration**: Define object shape once, type guard generated
+ * - **Optional Fields**: Handle optional/undefined fields with `optional-*` types
+ * - **Nested Objects**: Support for object and array fields
+ * - **Type Narrowing**: Generated guards properly narrow TypeScript types
+ * - **Reusable**: Create once, use in multiple validation contexts
+ *
+ * ## Usage Patterns
+ *
+ * ### Basic Usage (Simple Types)
+ * ```typescript
+ * interface CreateTradeData {
+ *   tradeType: string;
+ *   tokenAmount: string;
+ *   vaultAddress: string;
+ *   userAddress: string;
+ *   slippageTolerance?: string;
+ *   deadline?: number;
+ * }
+ *
+ * const isCreateTradeData = createTypeGuard<CreateTradeData>({
+ *   tradeType: 'string',
+ *   tokenAmount: 'string',
+ *   vaultAddress: 'string',
+ *   userAddress: 'string',
+ *   slippageTolerance: 'optional-string',
+ *   deadline: 'optional-number'
+ * });
+ *
+ * // Usage
+ * if (isCreateTradeData(data)) {
+ *   // data is typed as CreateTradeData
+ *   console.log(data.tradeType);
+ * }
+ * ```
+ *
+ * ### With Objects and Arrays
+ * ```typescript
+ * interface PoolData {
+ *   tokenName: string;
+ *   price: number;
+ *   metadata: {
+ *     tags: string[];
+ *   };
+ *   extra?: Record<string, unknown>;
+ * }
+ *
+ * const isPoolData = createTypeGuard<PoolData>({
+ *   tokenName: 'string',
+ *   price: 'number',
+ *   metadata: 'object',
+ *   extra: 'optional-object'
+ * });
+ * ```
+ *
+ * ### In Validation Workflows
+ * ```typescript
+ * import { createValidator } from './validation-helpers';
+ *
+ * const isCreateTradeData = createTypeGuard<CreateTradeData>({
+ *   tradeType: 'string',
+ *   tokenAmount: 'string',
+ *   vaultAddress: 'string',
+ *   userAddress: 'string'
+ * });
+ *
+ * // Create validator that throws on invalid data
+ * const validateCreateTradeData = createValidator(
+ *   isCreateTradeData,
+ *   'create trade data'
+ * );
+ *
+ * function createTrade(data: unknown) {
+ *   validateCreateTradeData(data); // Throws ValidationError if invalid
+ *   // data is now typed as CreateTradeData
+ *   return tradingService.create(data);
+ * }
+ * ```
+ *
+ * ## Migration from Manual Type Guards
+ *
+ * ### Before (Manual Implementation)
+ * ```typescript
+ * export function isBuyTokensData(obj: unknown): obj is BuyTokensData {
+ *   if (!obj || typeof obj !== 'object') return false;
+ *   const o = obj as Record<string, unknown>;
+ *   return (
+ *     typeof o.tokenSymbol === 'string' &&
+ *     typeof o.nativeTokenQuantity === 'string' &&
+ *     typeof o.expectedToken === 'string' &&
+ *     (o.maxAcceptableReverseBondingCurveFee === undefined ||
+ *       typeof o.maxAcceptableReverseBondingCurveFee === 'string')
+ *   );
+ * }
+ * ```
+ *
+ * ### After (Using Factory)
+ * ```typescript
+ * export const isBuyTokensData = createTypeGuard<BuyTokensData>({
+ *   tokenSymbol: 'string',
+ *   nativeTokenQuantity: 'string',
+ *   expectedToken: 'string',
+ *   maxAcceptableReverseBondingCurveFee: 'optional-string'
+ * });
+ * ```
+ *
+ * Benefits:
+ * - 50% less code (3 lines vs 10+ lines)
+ * - No manual type checking logic
+ * - Easier to maintain and update
+ * - Consistent pattern across all DTOs
+ * - Self-documenting (field spec shows exact contract)
+ *
+ * @template T - The interface type this guard validates
+ * @param fields - Field specification mapping field names to their expected types
+ * @returns A type guard function that checks if a value matches the field specification
+ *
+ * @throws Never - Type guards never throw, they return boolean
+ *
+ * @example Email configuration type guard
+ * ```typescript
+ * interface EmailConfig {
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ *   cc?: string;
+ *   bcc?: string;
+ *   attachments?: Array<unknown>;
+ * }
+ *
+ * const isEmailConfig = createTypeGuard<EmailConfig>({
+ *   to: 'string',
+ *   subject: 'string',
+ *   body: 'string',
+ *   cc: 'optional-string',
+ *   bcc: 'optional-string',
+ *   attachments: 'optional-array'
+ * });
+ *
+ * // Use in conditional
+ * if (isEmailConfig(config)) {
+ *   await sendEmail(config); // config is EmailConfig
+ * }
+ * ```
+ *
+ * @example Trade options type guard
+ * ```typescript
+ * interface TradeOptions {
+ *   tokenName: string;
+ *   amount: string;
+ *   slippage?: number;
+ *   deadline?: number;
+ * }
+ *
+ * const isTradeOptions = createTypeGuard<TradeOptions>({
+ *   tokenName: 'string',
+ *   amount: 'string',
+ *   slippage: 'optional-number',
+ *   deadline: 'optional-number'
+ * });
+ *
+ * // Use in validation function
+ * function executeTradeIfValid(options: unknown): void {
+ *   if (isTradeOptions(options)) {
+ *     executeTradeInternal(options);
+ *   } else {
+ *     throw new Error('Invalid trade options');
+ *   }
+ * }
+ * ```
+ *
+ * @since 3.33.0
+ */
+export declare function createTypeGuard<T>(fields: FieldSpec): (obj: unknown) => obj is T;
+//# sourceMappingURL=type-guard-factory.d.ts.map

package/dist/utils/type-guard-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guard-factory.d.ts","sourceRoot":"","sources":["../../src/utils/type-guard-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAuClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoLG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,GAAG,IAAI,CAAC,CAqBhF"}

package/dist/utils/unique-key-generator.d.ts

@@ -0,0 +1,148 @@
+/**
+ * GalaChain Unique Operation Key Generator
+ *
+ * Generates unique identifiers for GalaChain bundle transactions and operations
+ * that require idempotency keys. Consolidated from 14+ duplicated patterns across
+ * transfer and lock/unlock operations.
+ *
+ * @category Utilities
+ * @since 6.14.0
+ */
+/**
+ * Generate a unique operation key for GalaChain bundle transactions.
+ *
+ * Creates a deterministic yet unique identifier combining:
+ * - Timestamp (millisecond precision)
+ * - Random suffix (base36 encoded for compact representation)
+ *
+ * Format: `galaconnect-operation-{timestamp}_{randomSuffix}`
+ *
+ * Used for idempotency across:
+ * - Token transfers (uniqueKey parameter)
+ * - Token locks/unlocks (uniqueKey parameter)
+ * - Token burns (uniqueKey parameter)
+ * - Any operation requiring request deduplication
+ *
+ * @returns Unique operation key in format `galaconnect-operation-{timestamp}_{randomSuffix}`
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { generateUniqueKey } from '@gala-chain/launchpad-sdk';
+ *
+ * const key = generateUniqueKey();
+ * console.log(key); // 'galaconnect-operation-1735857234567_abc123'
+ *
+ * // Use in transfer operation
+ * await sdk.transferGala({
+ *   recipientAddress: 'eth|0x...',
+ *   amount: '100',
+ *   uniqueKey: generateUniqueKey()
+ * });
+ * ```
+ *
+ * @example With explicit key
+ * ```typescript
+ * // For operations where you control the idempotency key
+ * const operationKey = `my-operation-${Date.now()}`;
+ * await sdk.transferToken({
+ *   to: 'eth|0x...',
+ *   tokenName: 'anime',
+ *   amount: '1000',
+ *   uniqueKey: operationKey
+ * });
+ * ```
+ *
+ * @see {@link https://docs.galachain.com/idempotency GalaChain Idempotency}
+ */
+export declare function generateUniqueKey(): string;
+/**
+ * Generate unique operation key with UUID, timestamp, and wallet address
+ *
+ * Creates a unique identifier for GalaSwap operations combining:
+ * - Prefix (customizable, defaults to 'galaswap-operation')
+ * - UUID v4 for global uniqueness
+ * - Timestamp (millisecond precision)
+ * - Wallet address for context
+ *
+ * Format: `{prefix}-${uuid}-${timestamp}-${walletAddress}`
+ *
+ * Used for idempotent GalaSwap operations including:
+ * - Liquidity additions (add/remove)
+ * - Swap executions
+ * - Fee collections
+ * - Bundle transactions
+ *
+ * @param walletAddress The wallet address associated with the operation (required)
+ * @param prefix Optional custom prefix (defaults to 'galaswap-operation')
+ * @returns Unique operation key combining UUID, timestamp, and wallet address
+ *
+ * @example Basic usage with default prefix
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * const operationKey = generateOperationKey('eth|0x1234567890abcdef...');
+ * console.log(operationKey);
+ * // 'galaswap-operation-550e8400-e29b-41d4-a716-446655440000-1735857234567-eth|0x1234...'
+ * ```
+ *
+ * @example With custom prefix
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * const operationKey = generateOperationKey(
+ *   'eth|0x1234567890abcdef...',
+ *   'custom-swap'
+ * );
+ * console.log(operationKey);
+ * // 'custom-swap-550e8400-e29b-41d4-a716-446655440000-1735857234567-eth|0x1234...'
+ * ```
+ *
+ * @example In GalaSwap operations
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * // Use in add liquidity operation
+ * const result = await sdk.addSwapLiquidityByPrice({
+ *   token0: 'GALA',
+ *   token1: 'GUSDC',
+ *   fee: 3000,
+ *   minPrice: '0.95',
+ *   maxPrice: '1.05',
+ *   amount0Desired: '100',
+ *   amount1Desired: '100',
+ *   uniqueKey: generateOperationKey(walletAddress)
+ * });
+ * ```
+ *
+ * @example Handling operation idempotency
+ * ```typescript
+ * import { generateOperationKey } from '@gala-chain/launchpad-sdk';
+ *
+ * // Store the key for retry scenarios
+ * const operationKey = generateOperationKey(userAddress);
+ * try {
+ *   await sdk.executeSwap({
+ *     fromToken: 'GALA',
+ *     toToken: 'GUSDC',
+ *     inputAmount: '100',
+ *     expectedOutput: '95',
+ *     feeTier: 3000,
+ *     uniqueKey: operationKey
+ *   });
+ * } catch (error) {
+ *   // Retry with same key - ensures idempotency
+ *   await sdk.executeSwap({
+ *     fromToken: 'GALA',
+ *     toToken: 'GUSDC',
+ *     inputAmount: '100',
+ *     expectedOutput: '95',
+ *     feeTier: 3000,
+ *     uniqueKey: operationKey // Same key prevents duplicate execution
+ *   });
+ * }
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function generateOperationKey(walletAddress: string, prefix?: string): string;
+//# sourceMappingURL=unique-key-generator.d.ts.map

package/dist/utils/unique-key-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-key-generator.d.ts","sourceRoot":"","sources":["../../src/utils/unique-key-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,MAA6B,GACpC,MAAM,CAIR"}