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

package/dist/tools/handler-factories.js

@@ -0,0 +1,1680 @@
+"use strict";
+/**
+ * Handler Factory Utilities
+ *
+ * Provides reusable factory functions for creating MCP tool handlers with common patterns.
+ * Reduces boilerplate and ensures consistent error handling across all tools.
+ *
+ * @example
+ * // Simple single-arg handler
+ * const handler = createSimpleHandler('fetchGalaBalance', (args) => args.address);
+ *
+ * @example
+ * // Toggle enable/disable pattern
+ * const handler = createToggleHandler('enableChat', 'disableChat');
+ *
+ * @example
+ * // Transaction status handler
+ * const handler = createTransactionStatusHandler('getSolanaTransactionStatus', 'Solana');
+ *
+ * @example
+ * // No-arg convenience fetcher
+ * const handler = createConvenienceFetcher('getGlobalChatStatus');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_DESCRIPTIONS = exports.extractBatchTokenOperationArgs = exports.extractSearchFilterArgs = exports.extractOffsetPaginationArgs = exports.extractPaginationArgs = exports.EXTERNAL_CHAIN_CONFIG = void 0;
+exports.invokeSdkMethod = invokeSdkMethod;
+exports.createSimpleHandler = createSimpleHandler;
+exports.createToggleHandler = createToggleHandler;
+exports.createTransactionStatusHandler = createTransactionStatusHandler;
+exports.createConvenienceFetcher = createConvenienceFetcher;
+exports.createBooleanHandler = createBooleanHandler;
+exports.createTransformingHandler = createTransformingHandler;
+exports.createReactionHandler = createReactionHandler;
+exports.createWebSocketActionHandler = createWebSocketActionHandler;
+exports.createTypingIndicatorHandler = createTypingIndicatorHandler;
+exports.createContentListHandler = createContentListHandler;
+exports.createContentCreateHandler = createContentCreateHandler;
+exports.createContentUpdateHandler = createContentUpdateHandler;
+exports.createContentDeleteHandler = createContentDeleteHandler;
+exports.createContentCrudHandlers = createContentCrudHandlers;
+exports.createStreamingListHandler = createStreamingListHandler;
+exports.createStreamingGetHandler = createStreamingGetHandler;
+exports.createStreamingDeleteHandler = createStreamingDeleteHandler;
+exports.createTokenUserHandler = createTokenUserHandler;
+exports.createNoArgActionHandler = createNoArgActionHandler;
+exports.createWrapUnwrapHandler = createWrapUnwrapHandler;
+exports.createExternalTokenBalanceHandler = createExternalTokenBalanceHandler;
+exports.createExternalNativeBalanceHandler = createExternalNativeBalanceHandler;
+exports.createExternalAllBalancesHandler = createExternalAllBalancesHandler;
+exports.createArgumentExtractor = createArgumentExtractor;
+exports.createOptionalAddressFetcher = createOptionalAddressFetcher;
+exports.createTokenAddressHandler = createTokenAddressHandler;
+exports.extractStatusArg = extractStatusArg;
+exports.createPaginatedListHandler = createPaginatedListHandler;
+exports.createBatchTokenOperationHandler = createBatchTokenOperationHandler;
+exports.extractTransferArgs = extractTransferArgs;
+exports.extractTokenTransferArgs = extractTokenTransferArgs;
+exports.createGalaTransferHandler = createGalaTransferHandler;
+exports.createTokenTransferHandler = createTokenTransferHandler;
+exports.createTokenNameFetcher = createTokenNameFetcher;
+exports.createTokenNameHandler = createTokenNameHandler;
+exports.createTokenNameBooleanHandler = createTokenNameBooleanHandler;
+exports.createCustomMessageHandler = createCustomMessageHandler;
+exports.createWalletRequiredHandler = createWalletRequiredHandler;
+exports.createNotFoundHandler = createNotFoundHandler;
+exports.createNoArgResultHandler = createNoArgResultHandler;
+exports.createSyncBooleanHandler = createSyncBooleanHandler;
+exports.extractFlexibleTokenId = extractFlexibleTokenId;
+exports.createConditionalResponseHandler = createConditionalResponseHandler;
+exports.createOptionResultHandler = createOptionResultHandler;
+exports.createWalletRequiredMethodHandler = createWalletRequiredMethodHandler;
+exports.createOptionalParamsHandler = createOptionalParamsHandler;
+exports.createPositionEnrichmentHandler = createPositionEnrichmentHandler;
+const response_formatter_js_1 = require("../utils/response-formatter.js");
+const error_handler_js_1 = require("../utils/error-handler.js");
+/**
+ * Core helper: Looks up and invokes an SDK method with the given arguments.
+ *
+ * This is the core primitive that all handler factories use. It handles:
+ * - Method lookup on the SDK instance
+ * - Method existence validation
+ * - Argument handling (no args, single arg, spread array)
+ * - Proper `this` binding via call/apply
+ *
+ * @param options - Invocation configuration
+ * @returns Promise resolving to the SDK method result
+ * @throws Error if the SDK method doesn't exist
+ *
+ * @internal Exported for use by pagination-handler-factory; not part of public API.
+ */
+async function invokeSdkMethod(options) {
+    const { sdk, methodName, extractedArgs, errorContext } = options;
+    const contextLabel = errorContext ?? methodName;
+    const method = sdk[methodName];
+    if (!method || typeof method !== 'function') {
+        throw new Error(`SDK method "${methodName}" not found${errorContext ? ` for ${contextLabel}` : ''}`);
+    }
+    let result;
+    if (extractedArgs === undefined) {
+        // No args case
+        result = (await method.call(sdk));
+    }
+    else if (Array.isArray(extractedArgs)) {
+        // Spread array of args
+        result = (await method.apply(sdk, extractedArgs));
+    }
+    else {
+        // Single arg
+        result = (await method.call(sdk, extractedArgs));
+    }
+    return { result };
+}
+/**
+ * Creates a simple handler that calls an SDK method with extracted arguments.
+ *
+ * Handles single or multi-argument SDK methods, with optional custom argument extraction.
+ *
+ * @param sdkMethodName - Name of the SDK method to call (must exist on LaunchpadSDK)
+ * @param argExtractor - Optional function to extract/transform args before calling SDK method
+ * @returns Handler that calls the SDK method and returns formatted success response
+ *
+ * @example
+ * // Simple single-arg extraction
+ * const handler = createSimpleHandler('fetchGalaBalance', (args) => args.address);
+ *
+ * @example
+ * // Multi-arg extraction
+ * const handler = createSimpleHandler('fetchTokenBalance', (args) => [
+ *   args.tokenName,
+ *   args.address
+ * ]);
+ *
+ * @example
+ * // No extraction (uses entire args object)
+ * const handler = createSimpleHandler('registerAccount');
+ */
+function createSimpleHandler(sdkMethodName, argExtractor) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor ? argExtractor(args) : args;
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(result);
+    });
+}
+/**
+ * Creates a toggle handler for enable/disable patterns.
+ *
+ * Returns a handler that calls the appropriate enable or disable SDK method
+ * based on the `enabled` argument value.
+ *
+ * @param enableMethod - Name of the SDK method to enable (called when enabled=true)
+ * @param disableMethod - Name of the SDK method to disable (called when enabled=false)
+ * @param argExtractor - Optional function to extract arguments for the SDK methods
+ * @returns Handler that toggles between enable and disable methods
+ *
+ * @example
+ * const handler = createToggleHandler('enableChat', 'disableChat', (args) => args.tokenName);
+ *
+ * // When args = { enabled: true, tokenName: 'mytoken' }
+ * // Calls: sdk.enableChat('mytoken')
+ *
+ * // When args = { enabled: false, tokenName: 'mytoken' }
+ * // Calls: sdk.disableChat('mytoken')
+ */
+function createToggleHandler(enableMethod, disableMethod, argExtractor) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const enabled = args.enabled;
+        // Validate enabled is a boolean
+        if (typeof enabled !== 'boolean') {
+            throw new Error(`enabled must be a boolean, received: ${typeof enabled}`);
+        }
+        const methodName = enabled ? enableMethod : disableMethod;
+        const extractedArgs = argExtractor ? argExtractor(args) : args;
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(result);
+    });
+}
+/**
+ * Creates a transaction status handler for blockchain transaction queries.
+ *
+ * Handles transaction status patterns like getSolanaTransactionStatus and getEthereumTransactionStatus.
+ * These methods typically require a transaction hash and optional chain hint.
+ *
+ * @param sdkMethod - Name of the SDK method to call (e.g., 'getSolanaTransactionStatus')
+ * @param chainName - Name of the chain for context in error messages
+ * @returns Handler that queries transaction status
+ *
+ * @example
+ * const handler = createTransactionStatusHandler('getSolanaTransactionStatus', 'Solana');
+ *
+ * // Args expected: { transactionHash, chainHint? }
+ */
+function createTransactionStatusHandler(sdkMethod, chainName) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const transactionHash = args.transactionHash;
+        const chainHint = args.chainHint;
+        // Validate transactionHash is a non-empty string
+        if (typeof transactionHash !== 'string' || transactionHash.trim() === '') {
+            throw new Error(`transactionHash must be a non-empty string for ${chainName} transaction status`);
+        }
+        // Validate chainHint is undefined or a string
+        if (chainHint !== undefined && typeof chainHint !== 'string') {
+            throw new Error(`chainHint must be a string if provided, received: ${typeof chainHint}`);
+        }
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethod,
+            extractedArgs: [transactionHash, chainHint],
+            errorContext: chainName,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(result);
+    });
+}
+/**
+ * Creates a convenience fetcher handler for simple no-arg or single-arg SDK methods.
+ *
+ * Ideal for read-only queries that don't require complex argument extraction.
+ * Automatically formats the result as JSON.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @param argExtractor - Optional function to extract single argument
+ * @returns Handler that fetches data from SDK
+ *
+ * @example
+ * // No-arg fetcher
+ * const handler = createConvenienceFetcher('getGlobalChatStatus');
+ *
+ * // Single-arg fetcher
+ * const handler = createConvenienceFetcher('fetchProfile', (args) => args.address);
+ */
+function createConvenienceFetcher(sdkMethod, argExtractor) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor ? argExtractor(args) : undefined;
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethod,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(result);
+    });
+}
+/**
+ * Creates a simple handler that returns a boolean success result.
+ *
+ * Use this for handlers that call SDK methods and just need to report success/failure,
+ * rather than returning the full SDK result.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param argExtractor - Optional function to extract/transform args before calling SDK method
+ * @param successMessage - Optional custom success message (defaults to "Operation completed successfully")
+ * @returns Handler that calls the SDK method and returns formatted boolean response
+ *
+ * @example
+ * const handler = createBooleanHandler('updateProfile', (args) => [
+ *   { fullName: args.fullName, profileImage: args.profileImage },
+ *   args.address,
+ *   args.privateKey
+ * ], 'Profile updated successfully');
+ */
+function createBooleanHandler(sdkMethodName, argExtractor, successMessage) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor ? argExtractor(args) : args;
+        await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatBoolean)(true, successMessage ?? 'Operation completed successfully');
+    });
+}
+/**
+ * Creates a handler with custom result transformation.
+ *
+ * Use this for handlers that need to post-process SDK results before formatting.
+ * The resultTransformer receives the raw SDK result and args, and returns the
+ * transformed data to be formatted.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param argExtractor - Optional function to extract/transform args before calling SDK method
+ * @param resultTransformer - Function to transform the SDK result before formatting
+ * @returns Handler that calls the SDK method and returns formatted transformed response
+ *
+ * @example
+ * const handler = createTransformingHandler(
+ *   'getSupportedBridgeTokens',
+ *   undefined,
+ *   (result, args) => {
+ *     if (args.chain) {
+ *       return result.tokens.filter(t => t.supportedChains.includes(args.chain));
+ *     }
+ *     return result;
+ *   }
+ * );
+ */
+function createTransformingHandler(sdkMethodName, argExtractor, resultTransformer) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor ? argExtractor(args) : undefined;
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        const transformed = resultTransformer(result, args);
+        return (0, response_formatter_js_1.formatSuccess)(transformed);
+    });
+}
+/**
+ * Creates a reaction handler for add/remove reaction operations.
+ *
+ * This factory handles the common pattern of reaction operations that take
+ * tokenName, messageId, and reactionType parameters. Consolidates add/remove
+ * into a single factory with operation type parameter.
+ *
+ * Note: The `operation` parameter is intentionally kept for API clarity and
+ * future extensibility (e.g., logging, metrics). The actual SDK method
+ * determines the operation semantics.
+ *
+ * @param _operation - Either 'add' or 'remove' (documents intent, used for API clarity)
+ * @param sdkMethodName - Name of the SDK method to call
+ * @returns Handler that calls the SDK method with reaction parameters
+ *
+ * @example
+ * // Create add reaction handler
+ * const handler = createReactionHandler('add', 'addContentReaction');
+ *
+ * // Create remove reaction handler
+ * const handler = createReactionHandler('remove', 'removeContentReaction');
+ *
+ * @since 5.13.0
+ */
+function createReactionHandler(operation, sdkMethodName) {
+    return createSimpleHandler(sdkMethodName, (args) => {
+        // Runtime validation for required string fields
+        const tokenName = args.tokenName;
+        const messageId = args.messageId;
+        const reactionType = args.reactionType;
+        if (typeof tokenName !== 'string' || !tokenName) {
+            throw new Error(`tokenName is required to ${operation} reaction`);
+        }
+        if (typeof messageId !== 'string' || !messageId) {
+            throw new Error(`messageId is required to ${operation} reaction`);
+        }
+        if (typeof reactionType !== 'string' || !reactionType) {
+            throw new Error(`reactionType is required to ${operation} reaction`);
+        }
+        return { tokenName, messageId, reactionType };
+    });
+}
+/**
+ * Creates a WebSocket action handler with custom response formatting.
+ *
+ * This factory handles WebSocket operations that don't return meaningful
+ * SDK responses but need to return a custom success response.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param argExtractor - Function to extract arguments from input
+ * @param responseBuilder - Function to build the success response from args
+ * @returns Handler that calls SDK method and returns custom response
+ *
+ * @example
+ * const handler = createWebSocketActionHandler(
+ *   'sendStreamChatViaWebSocket',
+ *   (args) => [args.tokenName, args.content],
+ *   (args) => ({ sent: true, tokenName: args.tokenName, content: args.content })
+ * );
+ *
+ * @since 5.13.0
+ */
+function createWebSocketActionHandler(sdkMethodName, argExtractor, responseBuilder) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor(args);
+        await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(responseBuilder(args));
+    });
+}
+/**
+ * Creates a typing indicator handler for start/stop typing operations.
+ *
+ * This factory handles the typing indicator pattern where a boolean
+ * determines which SDK method to call (sendTypingStart or sendTypingStop).
+ *
+ * Note: This handler uses synchronous SDK methods, which is why it doesn't
+ * use the shared invokeSdkMethod helper (designed for async methods).
+ *
+ * @param startMethod - SDK method name for start typing (sync method)
+ * @param stopMethod - SDK method name for stop typing (sync method)
+ * @returns Handler that calls appropriate method based on isTyping flag
+ *
+ * @example
+ * const handler = createTypingIndicatorHandler('sendTypingStart', 'sendTypingStop');
+ *
+ * @since 5.13.0
+ */
+function createTypingIndicatorHandler(startMethod, stopMethod) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const tokenName = args.tokenName;
+        const isTyping = args.isTyping;
+        const methodName = isTyping ? startMethod : stopMethod;
+        const method = sdk[methodName];
+        if (!method || typeof method !== 'function') {
+            throw new Error(`SDK method "${methodName}" not found`);
+        }
+        method.call(sdk, tokenName);
+        return (0, response_formatter_js_1.formatSuccess)({
+            sent: true,
+            tokenName,
+            isTyping,
+        });
+    });
+}
+/**
+ * Creates a list handler for content with tokenName/userAddress filters and pagination.
+ *
+ * This factory handles the common pattern of listing content (comments, chat messages)
+ * with optional tokenName and/or userAddress filters plus pagination.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @param options - Configuration options
+ * @returns Handler that lists content with filters and pagination
+ *
+ * @example
+ * const handler = createContentListHandler('getComments', {
+ *   requireAtLeastOneFilter: true,
+ *   resourceName: 'comments'
+ * });
+ *
+ * @since 6.3.0
+ */
+function createContentListHandler(sdkMethod, options = {}) {
+    const { requireAtLeastOneFilter = true, resourceName = 'content' } = options;
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        if (requireAtLeastOneFilter && !args.tokenName && !args.userAddress) {
+            throw new Error(`At least one of tokenName or userAddress is required to list ${resourceName}`);
+        }
+        const extractedArgs = {
+            tokenName: args.tokenName,
+            userAddress: args.userAddress,
+            page: args.page,
+            limit: args.limit,
+        };
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethod,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(result);
+    });
+}
+/**
+ * Creates a create handler for content with tokenName and content fields.
+ *
+ * This factory handles the common pattern of creating content (comments, chat messages)
+ * with tokenName and content as required fields.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @returns Handler that creates content
+ *
+ * @example
+ * const handler = createContentCreateHandler('createComment');
+ *
+ * @since 6.3.0
+ */
+function createContentCreateHandler(sdkMethod) {
+    return createSimpleHandler(sdkMethod, (args) => ({
+        tokenName: args.tokenName,
+        content: args.content,
+    }));
+}
+/**
+ * Creates an update handler for content with id and content fields.
+ *
+ * This factory handles the common pattern of updating content (comments, chat messages)
+ * with id and content wrapped in an update object.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @returns Handler that updates content
+ *
+ * @example
+ * const handler = createContentUpdateHandler('updateComment');
+ *
+ * @since 6.3.0
+ */
+function createContentUpdateHandler(sdkMethod) {
+    return createSimpleHandler(sdkMethod, (args) => [
+        args.id,
+        { content: args.content },
+    ]);
+}
+/**
+ * Creates a delete handler for content with just an id field.
+ *
+ * This factory handles the common pattern of deleting content (comments, chat messages)
+ * by id, returning a boolean success response.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @param successMessage - Optional custom success message
+ * @returns Handler that deletes content
+ *
+ * @example
+ * const handler = createContentDeleteHandler('deleteComment', 'Comment deleted');
+ *
+ * @since 6.3.0
+ */
+function createContentDeleteHandler(sdkMethod, successMessage) {
+    return createBooleanHandler(sdkMethod, (args) => args.id, successMessage ?? 'Content deleted successfully');
+}
+/**
+ * Creates all four CRUD handlers for a content resource.
+ *
+ * Returns an object with list, create, update, and delete handlers configured
+ * for the specified SDK methods. This is a convenience factory for resources
+ * that implement the full CRUD pattern.
+ *
+ * @param config - Configuration specifying SDK methods and resource name
+ * @returns Object containing all four CRUD handlers
+ *
+ * @example
+ * const { list, create, update, delete: remove } = createContentCrudHandlers({
+ *   listMethod: 'getComments',
+ *   createMethod: 'createComment',
+ *   updateMethod: 'updateComment',
+ *   deleteMethod: 'deleteComment',
+ *   resourceName: 'Comment'
+ * });
+ *
+ * @since 6.3.0
+ */
+function createContentCrudHandlers(config) {
+    return {
+        list: createContentListHandler(config.listMethod, {
+            requireAtLeastOneFilter: true,
+            resourceName: config.resourceName.toLowerCase() + 's',
+        }),
+        create: createContentCreateHandler(config.createMethod),
+        update: createContentUpdateHandler(config.updateMethod),
+        delete: createContentDeleteHandler(config.deleteMethod, `${config.resourceName} deleted`),
+    };
+}
+/**
+ * Creates a list handler for streaming resources with tokenName and pagination.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @returns Handler that lists streaming resources
+ *
+ * @example
+ * const handler = createStreamingListHandler('getStreamRecordings');
+ *
+ * @since 6.3.0
+ */
+function createStreamingListHandler(sdkMethod) {
+    return createSimpleHandler(sdkMethod, (args) => ({
+        tokenName: args.tokenName,
+        page: args.page,
+        limit: args.limit,
+    }));
+}
+/**
+ * Creates a get/fetch handler for streaming resources with tokenName and resourceId.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @param resourceIdField - Name of the resource ID field in args
+ * @returns Handler that fetches a single streaming resource
+ *
+ * @example
+ * const handler = createStreamingGetHandler('getRecordingDownload', 'assetId');
+ *
+ * @since 6.3.0
+ */
+function createStreamingGetHandler(sdkMethod, resourceIdField) {
+    return createSimpleHandler(sdkMethod, (args) => [
+        args.tokenName,
+        args[resourceIdField],
+    ]);
+}
+/**
+ * Creates a delete handler for streaming resources with tokenName and resourceId.
+ *
+ * @param sdkMethod - Name of the SDK method to call
+ * @param resourceIdField - Name of the resource ID field in args
+ * @param successMessage - Success message to return
+ * @returns Handler that deletes a streaming resource
+ *
+ * @example
+ * const handler = createStreamingDeleteHandler('deleteRecording', 'assetId', 'Recording deleted');
+ *
+ * @since 6.3.0
+ */
+function createStreamingDeleteHandler(sdkMethod, resourceIdField, successMessage) {
+    return createBooleanHandler(sdkMethod, (args) => [args.tokenName, args[resourceIdField]], successMessage);
+}
+// =============================================================================
+// Token + User Handler Factory (Ban/Moderation Operations)
+// =============================================================================
+/**
+ * Creates a handler for operations that take tokenName and userAddress.
+ *
+ * This is a common pattern for ban/moderation operations:
+ * - createBan
+ * - removeBan
+ * - getBanStatus
+ *
+ * Reduces boilerplate by providing consistent argument extraction.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param additionalExtractor - Optional function to extract additional arguments
+ * @returns Handler that calls SDK method with tokenName, userAddress, and optional extras
+ *
+ * @example
+ * // Simple case: tokenName + userAddress only
+ * const handler = createTokenUserHandler('removeBan');
+ *
+ * // With additional args
+ * const handler = createTokenUserHandler('createBan', (args) => ({
+ *   reason: args.reason as string | undefined,
+ *   durationSeconds: args.durationSeconds as number | undefined,
+ * }));
+ *
+ * @since 6.6.0
+ */
+function createTokenUserHandler(sdkMethodName, additionalExtractor) {
+    return createSimpleHandler(sdkMethodName, (args) => {
+        const baseArgs = {
+            tokenName: args.tokenName,
+            userAddress: args.userAddress,
+        };
+        if (additionalExtractor) {
+            return { ...baseArgs, ...additionalExtractor(args) };
+        }
+        return baseArgs;
+    });
+}
+// =============================================================================
+// No-Arg Action Handler Factory
+// =============================================================================
+/**
+ * Creates a handler for no-argument async actions that return a custom response.
+ *
+ * Use this for SDK methods that take no arguments and need a custom success response.
+ * Ideal for WebSocket connection management, initialization operations, etc.
+ *
+ * @param sdkMethodName - Name of the SDK method to call (takes no arguments)
+ * @param successResponse - Static response to return on success
+ * @returns Handler that calls SDK method and returns the custom response
+ *
+ * @example
+ * const handler = createNoArgActionHandler(
+ *   'connectStreamWebSocket',
+ *   { connected: true, message: 'Connected to stream WebSocket' }
+ * );
+ *
+ * @since 6.6.0
+ */
+function createNoArgActionHandler(sdkMethodName, successResponse) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk) => {
+        await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(successResponse);
+    });
+}
+/**
+ * Creates a wrap or unwrap handler for cross-channel bridge operations.
+ *
+ * Both wrap and unwrap operations share identical structure:
+ * - tokenId (flexible format)
+ * - amount (decimal string)
+ * - recipient (optional)
+ * - memo (optional)
+ *
+ * The only difference is the SDK method called.
+ *
+ * @param sdkMethodName - Either 'wrapToken' or 'unwrapToken'
+ * @returns Handler for the wrap/unwrap operation
+ *
+ * @example
+ * const wrapHandler = createWrapUnwrapHandler('wrapToken');
+ * const unwrapHandler = createWrapUnwrapHandler('unwrapToken');
+ *
+ * @since 6.4.0
+ */
+function createWrapUnwrapHandler(sdkMethodName) {
+    return createSimpleHandler(sdkMethodName, (args) => {
+        // Runtime validation for tokenId - must be string or object
+        const tokenId = args.tokenId;
+        if (tokenId === undefined || tokenId === null) {
+            throw new Error('tokenId is required for wrap/unwrap operations');
+        }
+        if (typeof tokenId !== 'string' && typeof tokenId !== 'object') {
+            throw new Error('tokenId must be a string or TokenClassKey object');
+        }
+        return {
+            tokenId,
+            amount: args.amount,
+            recipient: args.recipient,
+            memo: args.memo,
+        };
+    });
+}
+/**
+ * Pre-configured chain settings for Ethereum and Solana.
+ * Single source of truth for chain-specific configuration.
+ */
+exports.EXTERNAL_CHAIN_CONFIG = {
+    Ethereum: {
+        chain: 'Ethereum',
+        addressFormat: '0x format',
+        nativeSymbol: 'ETH',
+        tokenSymbols: ['GALA', 'GWETH', 'GUSDC', 'GUSDT', 'GWTRX', 'GWBTC'],
+        allBalancesRpcCount: 7,
+    },
+    Solana: {
+        chain: 'Solana',
+        addressFormat: 'base58 format',
+        nativeSymbol: 'SOL',
+        tokenSymbols: ['GALA', 'GSOL'],
+        allBalancesRpcCount: 3,
+    },
+};
+/**
+ * Creates a token balance handler for external chains (Ethereum ERC-20, Solana SPL).
+ *
+ * Used for fetching single token balances on external chains.
+ * Takes symbol and optional address, returns token balance.
+ *
+ * @param chain - Target chain ('Ethereum' or 'Solana')
+ * @returns Handler that fetches single token balance
+ *
+ * @example
+ * const handler = createExternalTokenBalanceHandler('Ethereum');
+ * // SDK method: fetchEthereumWalletTokenBalance
+ *
+ * @since 6.5.0
+ */
+function createExternalTokenBalanceHandler(chain) {
+    const sdkMethod = `fetch${chain}WalletTokenBalance`;
+    return createSimpleHandler(sdkMethod, (args) => [
+        args.symbol,
+        args.address,
+    ]);
+}
+/**
+ * Creates a native balance handler for external chains (ETH, SOL).
+ *
+ * Used for fetching native currency balance on external chains.
+ * Takes optional address, returns native balance.
+ *
+ * @param chain - Target chain ('Ethereum' or 'Solana')
+ * @returns Handler that fetches native currency balance
+ *
+ * @example
+ * const handler = createExternalNativeBalanceHandler('Solana');
+ * // SDK method: fetchSolanaWalletNativeBalance
+ *
+ * @since 6.5.0
+ */
+function createExternalNativeBalanceHandler(chain) {
+    const sdkMethod = `fetch${chain}WalletNativeBalance`;
+    return createConvenienceFetcher(sdkMethod, (args) => args.address);
+}
+/**
+ * Creates an all-balances handler for external chains.
+ *
+ * Used for fetching all supported token balances on external chains.
+ * Takes optional address, returns native + all supported token balances.
+ *
+ * @param chain - Target chain ('Ethereum' or 'Solana')
+ * @returns Handler that fetches all balances
+ *
+ * @example
+ * const handler = createExternalAllBalancesHandler('Ethereum');
+ * // SDK method: fetchEthereumWalletAllBalances
+ *
+ * @since 6.5.0
+ */
+function createExternalAllBalancesHandler(chain) {
+    const sdkMethod = `fetch${chain}WalletAllBalances`;
+    return createConvenienceFetcher(sdkMethod, (args) => args.address);
+}
+/**
+ * Creates a type-safe argument extractor function from field definitions.
+ *
+ * This factory eliminates repetitive argument extraction patterns like:
+ * ```typescript
+ * // Before (repeated many times)
+ * function extractFooArgs(args: Record<string, unknown>): FooArgs {
+ *   return {
+ *     page: args.page as number | undefined,
+ *     limit: args.limit as number | undefined,
+ *   };
+ * }
+ *
+ * // After
+ * const extractFooArgs = createArgumentExtractor<FooArgs>(['page', 'limit']);
+ * ```
+ *
+ * @param fields - Array of field names to extract (strings or FieldDefinition objects)
+ * @returns Function that extracts specified fields from MCP args with proper typing
+ *
+ * @example
+ * // Simple field names (all optional)
+ * const extractPaginationArgs = createArgumentExtractor<PaginationArgs>(['page', 'limit']);
+ *
+ * @example
+ * // Mixed required/optional
+ * const extractTransferArgs = createArgumentExtractor<TransferArgs>([
+ *   { name: 'recipientAddress', required: true },
+ *   { name: 'amount', required: true },
+ *   'uniqueKey',  // optional
+ *   'privateKey', // optional
+ * ]);
+ *
+ * @since 6.11.0
+ */
+function createArgumentExtractor(fields) {
+    return (args) => {
+        const result = {};
+        for (const field of fields) {
+            const fieldName = typeof field === 'string' ? field : field.name;
+            result[fieldName] = args[fieldName];
+        }
+        return result;
+    };
+}
+/**
+ * Extracts standard page/limit pagination from MCP args.
+ *
+ * Use this helper to avoid repetitive casting in list handlers.
+ *
+ * @param args - MCP tool arguments
+ * @returns Typed pagination object with page and limit
+ *
+ * @example
+ * handler: createSimpleHandler('listItems', (args) => ({
+ *   tokenName: args.tokenName as string,
+ *   ...extractPaginationArgs(args),
+ * })),
+ *
+ * @since 6.7.0
+ */
+exports.extractPaginationArgs = createArgumentExtractor(['page', 'limit']);
+// =============================================================================
+// GalaChain Balance Handler Factories
+// =============================================================================
+/**
+ * Creates a handler for SDK methods that take an optional wallet address.
+ *
+ * Consolidates the common pattern where an SDK method accepts an optional
+ * address parameter that defaults to the SDK's configured wallet.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @returns Handler that fetches data with optional address
+ *
+ * @example
+ * // For fetchGalaBalance, fetchProfile
+ * const handler = createOptionalAddressFetcher('fetchGalaBalance');
+ *
+ * @since 6.8.0
+ */
+function createOptionalAddressFetcher(sdkMethodName) {
+    return createConvenienceFetcher(sdkMethodName, (args) => args.address);
+}
+/**
+ * Creates a handler for SDK methods that take tokenName and address parameters.
+ *
+ * Consolidates the common pattern for balance queries that need both
+ * a token identifier and a wallet address.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @returns Handler that fetches token-specific data for an address
+ *
+ * @example
+ * // For fetchTokenBalance
+ * const handler = createTokenAddressHandler('fetchTokenBalance');
+ *
+ * @since 6.8.0
+ */
+function createTokenAddressHandler(sdkMethodName) {
+    return createSimpleHandler(sdkMethodName, (args) => [
+        args.tokenName,
+        args.address,
+    ]);
+}
+/**
+ * Extracts offset/limit pagination from MCP args.
+ *
+ * Used for bridgeable token queries that use offset-based pagination.
+ *
+ * @param args - MCP tool arguments
+ * @returns Typed pagination object with offset and limit
+ *
+ * @example
+ * handler: createSimpleHandler('fetchTokens', (args) => ({
+ *   network: args.network as string,
+ *   ...extractOffsetPaginationArgs(args),
+ * })),
+ *
+ * @since 6.7.0
+ */
+exports.extractOffsetPaginationArgs = createArgumentExtractor(['offset', 'limit']);
+/**
+ * Extracts common search/filter parameters from MCP args.
+ *
+ * Used for list operations that support search, name, and userAddress filters.
+ *
+ * @param args - MCP tool arguments
+ * @returns Typed filter object
+ *
+ * @example
+ * handler: createSimpleHandler('listBans', (args) => ({
+ *   tokenName: args.tokenName as string,
+ *   ...extractPaginationArgs(args),
+ *   ...extractSearchFilterArgs(args),
+ * })),
+ *
+ * @since 6.7.0
+ */
+exports.extractSearchFilterArgs = createArgumentExtractor(['search', 'name', 'userAddress']);
+/**
+ * Extracts status filter with typed union constraint.
+ *
+ * @param args - MCP tool arguments
+ * @returns Status string or undefined
+ *
+ * @example
+ * handler: createSimpleHandler('listInvites', (args) => ({
+ *   ...extractPaginationArgs(args),
+ *   status: extractStatusArg<'PENDING' | 'CLAIMED' | 'REVOKED' | 'EXPIRED'>(args),
+ * })),
+ *
+ * @since 6.7.0
+ */
+function extractStatusArg(args) {
+    return args.status;
+}
+/**
+ * Creates a handler for paginated list operations with common patterns.
+ *
+ * This factory reduces boilerplate for handlers that:
+ * - Require tokenName (optional or required)
+ * - Use page/limit pagination
+ * - Optionally include status filter
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param options - Configuration options
+ * @returns Handler that calls SDK method with extracted args
+ *
+ * @example
+ * const handler = createPaginatedListHandler('listModeratorInvites', {
+ *   tokenNameRequired: false,
+ *   includeStatus: true,
+ * });
+ *
+ * @since 6.7.0
+ */
+function createPaginatedListHandler(sdkMethodName, options = {}) {
+    const { tokenNameRequired = false, includeStatus = false } = options;
+    return createSimpleHandler(sdkMethodName, (args) => {
+        const result = {
+            ...(0, exports.extractPaginationArgs)(args),
+        };
+        if (tokenNameRequired) {
+            result.tokenName = args.tokenName;
+        }
+        else {
+            result.tokenName = args.tokenName;
+        }
+        if (includeStatus) {
+            result.status = args.status;
+        }
+        return result;
+    });
+}
+/**
+ * Extracts common batch token operation args from MCP tool args.
+ *
+ * Used by lockTokens and unlockTokens which share identical argument patterns.
+ *
+ * @param args - MCP tool arguments
+ * @returns Typed batch operation arguments
+ *
+ * @since 6.8.0
+ */
+exports.extractBatchTokenOperationArgs = createArgumentExtractor(['tokens', 'uniqueKey', 'privateKey']);
+/**
+ * Creates a handler for batch token operations (lock, unlock).
+ *
+ * Consolidates the common pattern for operations that batch multiple
+ * token amounts with optional uniqueKey and privateKey.
+ *
+ * @param sdkMethodName - Name of the SDK method to call ('lockTokens' or 'unlockTokens')
+ * @returns Handler that processes batch token operations
+ *
+ * @example
+ * const lockHandler = createBatchTokenOperationHandler('lockTokens');
+ * const unlockHandler = createBatchTokenOperationHandler('unlockTokens');
+ *
+ * @since 6.8.0
+ */
+function createBatchTokenOperationHandler(sdkMethodName) {
+    return createSimpleHandler(sdkMethodName, exports.extractBatchTokenOperationArgs);
+}
+/**
+ * Base extractor for common transfer fields (amount, uniqueKey, privateKey).
+ *
+ * @since 6.11.0
+ */
+const extractBaseTransferArgs = createArgumentExtractor(['amount', 'uniqueKey', 'privateKey']);
+/**
+ * Extracts GALA transfer args from MCP tool args.
+ *
+ * Used by transferGala which uses recipientAddress.
+ *
+ * @param args - MCP tool arguments
+ * @returns Typed transfer arguments
+ *
+ * @since 6.8.0
+ */
+function extractTransferArgs(args) {
+    return {
+        recipientAddress: args.recipientAddress,
+        ...extractBaseTransferArgs(args),
+    };
+}
+/**
+ * Extracts token transfer args from MCP tool args.
+ *
+ * Used by transferToken which uses 'to' and tokenName.
+ *
+ * @param args - MCP tool arguments
+ * @returns Typed token transfer arguments
+ *
+ * @since 6.8.0
+ */
+function extractTokenTransferArgs(args) {
+    return {
+        to: args.to,
+        tokenName: args.tokenName,
+        ...extractBaseTransferArgs(args),
+    };
+}
+/**
+ * Creates a handler for GALA transfer operations.
+ *
+ * Consolidates the GALA transfer pattern which uses recipientAddress.
+ *
+ * @returns Handler that processes GALA transfers
+ *
+ * @example
+ * const handler = createGalaTransferHandler();
+ *
+ * @since 6.8.0
+ */
+function createGalaTransferHandler() {
+    return createSimpleHandler('transferGala', extractTransferArgs);
+}
+/**
+ * Creates a handler for token transfer operations.
+ *
+ * Consolidates the token transfer pattern which uses 'to' and tokenName.
+ *
+ * @returns Handler that processes token transfers
+ *
+ * @example
+ * const handler = createTokenTransferHandler();
+ *
+ * @since 6.8.0
+ */
+function createTokenTransferHandler() {
+    return createSimpleHandler('transferToken', extractTokenTransferArgs);
+}
+// =============================================================================
+// Token Name Fetcher Factory (DRY consolidation for status check tools)
+// =============================================================================
+/**
+ * Creates a fetcher handler for SDK methods that take tokenName as the sole argument.
+ *
+ * This is a specialized version of createConvenienceFetcher that eliminates the
+ * repetitive pattern: `(args) => args.tokenName as string`
+ *
+ * Common in streaming/chat status tools:
+ * - getChatStatus
+ * - getStreamInfo
+ * - getSimulcastTargets
+ * - resetStreamKey
+ *
+ * @param sdkMethod - Name of the SDK method that accepts tokenName
+ * @returns Handler that calls SDK method with tokenName extracted from args
+ *
+ * @example
+ * // Before (repetitive)
+ * handler: createConvenienceFetcher('getChatStatus', (args) => args.tokenName as string),
+ * handler: createConvenienceFetcher('getStreamInfo', (args) => args.tokenName as string),
+ *
+ * // After (DRY)
+ * handler: createTokenNameFetcher('getChatStatus'),
+ * handler: createTokenNameFetcher('getStreamInfo'),
+ *
+ * @since 6.8.0
+ */
+function createTokenNameFetcher(sdkMethod) {
+    return createConvenienceFetcher(sdkMethod, (args) => args.tokenName);
+}
+/**
+ * Creates a simple handler for SDK methods that take tokenName as the sole argument.
+ *
+ * Similar to createTokenNameFetcher but uses createSimpleHandler internally.
+ * Use this for write operations that take only tokenName.
+ *
+ * @param sdkMethod - Name of the SDK method that accepts tokenName
+ * @returns Handler that calls SDK method with tokenName extracted from args
+ *
+ * @example
+ * // Before (repetitive)
+ * handler: createSimpleHandler('startStream', (args) => args.tokenName as string),
+ *
+ * // After (DRY)
+ * handler: createTokenNameHandler('startStream'),
+ *
+ * @since 6.8.0
+ */
+function createTokenNameHandler(sdkMethod) {
+    return createSimpleHandler(sdkMethod, (args) => args.tokenName);
+}
+/**
+ * Creates a boolean handler for SDK methods that take tokenName and return success.
+ *
+ * Combines tokenName extraction with boolean success response.
+ * Use for operations like stopStream that return { success: true }.
+ *
+ * @param sdkMethod - Name of the SDK method that accepts tokenName
+ * @param successMessage - Success message to return
+ * @returns Handler that calls SDK method and returns boolean success
+ *
+ * @example
+ * // Before
+ * handler: createBooleanHandler('stopStream', (args) => args.tokenName as string, 'Stream stopped'),
+ *
+ * // After
+ * handler: createTokenNameBooleanHandler('stopStream', 'Stream stopped'),
+ *
+ * @since 6.8.0
+ */
+function createTokenNameBooleanHandler(sdkMethod, successMessage) {
+    return createBooleanHandler(sdkMethod, (args) => args.tokenName, successMessage);
+}
+// =============================================================================
+// Custom Message Handler Factory (DRY for interpolated message responses)
+// =============================================================================
+/**
+ * Creates a handler that calls an SDK method and builds a response with custom message.
+ *
+ * Use this for handlers that need to format a response with an interpolated message
+ * based on the SDK result. This is a common pattern in pool info, quote, and
+ * position query tools.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param argExtractor - Function to extract arguments from MCP args
+ * @param responseBuilder - Function to build the response object from SDK result
+ * @returns Handler that calls SDK method and returns custom formatted response
+ *
+ * @example
+ * const handler = createCustomMessageHandler(
+ *   'getSwapPoolInfo',
+ *   (args) => [args.tokenA as string, args.tokenB as string],
+ *   (result, args) => ({
+ *     ...result,
+ *     message: `Pool ${args.tokenA}/${args.tokenB} has ${result.liquidity} liquidity`,
+ *   })
+ * );
+ *
+ * @since 6.9.0
+ */
+function createCustomMessageHandler(sdkMethodName, argExtractor, responseBuilder) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor(args);
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(responseBuilder(result, args));
+    });
+}
+// =============================================================================
+// Wallet-Required Handler Factory (DRY for operations requiring wallet)
+// =============================================================================
+/**
+ * Creates a handler that validates wallet configuration before calling SDK method.
+ *
+ * Use this for write operations that require a configured wallet (swaps, liquidity
+ * add/remove, transfers, etc.). Fails fast with helpful error if wallet not configured.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param argExtractor - Function to extract arguments from MCP args
+ * @param responseBuilder - Optional function to build custom response (defaults to result)
+ * @param walletValidator - Optional custom wallet validation function
+ * @returns Handler that validates wallet then calls SDK method
+ *
+ * @example
+ * const handler = createWalletRequiredHandler(
+ *   'executeSwap',
+ *   (args) => [args.fromToken, args.toToken, args.amount, args.estimatedOutput, args.feeTier, args.slippageTolerance || 0.01],
+ *   (result) => ({ ...result, message: `Swap completed!` })
+ * );
+ *
+ * @since 6.9.0
+ */
+function createWalletRequiredHandler(sdkMethodName, argExtractor, responseBuilder, walletValidator) {
+    const validateWallet = walletValidator ?? ((sdk) => {
+        try {
+            sdk.getAddress();
+        }
+        catch {
+            throw new Error('Wallet not configured - required for this operation');
+        }
+    });
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        validateWallet(sdk);
+        const extractedArgs = argExtractor(args);
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        const response = responseBuilder ? responseBuilder(result, args) : result;
+        return (0, response_formatter_js_1.formatSuccess)(response);
+    });
+}
+// =============================================================================
+// Not-Found Conditional Handler Factory (DRY for position/resource lookups)
+// =============================================================================
+/**
+ * Creates a handler that returns found: false response if SDK result is null/undefined.
+ *
+ * Use this for position lookups and resource queries that may return null when
+ * the resource doesn't exist. Provides consistent not-found responses.
+ *
+ * @param sdkMethodName - Name of the SDK method to call
+ * @param argExtractor - Function to extract arguments from MCP args
+ * @param notFoundBuilder - Function to build not-found response (receives args)
+ * @param foundBuilder - Function to build found response (receives result and args)
+ * @returns Handler with conditional found/not-found response
+ *
+ * @example
+ * const handler = createNotFoundHandler(
+ *   'getSwapLiquidityPositionById',
+ *   (args) => [args.ownerAddress, args.positionId],
+ *   (args) => ({ found: false, message: `Position ${args.positionId} not found` }),
+ *   (result, args) => ({ found: true, ...result, message: `Found position ${args.positionId}` })
+ * );
+ *
+ * @since 6.9.0
+ */
+function createNotFoundHandler(sdkMethodName, argExtractor, notFoundBuilder, foundBuilder) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const extractedArgs = argExtractor(args);
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+            extractedArgs,
+        });
+        if (!result) {
+            return (0, response_formatter_js_1.formatSuccess)(notFoundBuilder(args));
+        }
+        return (0, response_formatter_js_1.formatSuccess)(foundBuilder(result, args));
+    });
+}
+// =============================================================================
+// Async No-Arg Handler Factory (DRY for session/status tools with custom messages)
+// =============================================================================
+/**
+ * Creates a handler for no-argument SDK methods with custom response formatting.
+ *
+ * Unlike createNoArgActionHandler which returns a static response, this factory
+ * allows building the response from the SDK result. Useful for session info,
+ * status queries, and other async methods that return data.
+ *
+ * @param sdkMethodName - Name of the SDK method to call (takes no arguments)
+ * @param responseBuilder - Function to build response from SDK result
+ * @returns Handler that calls SDK method and formats response
+ *
+ * @example
+ * const handler = createNoArgResultHandler(
+ *   'getSession',
+ *   (session) => ({
+ *     address: session.address,
+ *     expiresAt: session.expiresAt,
+ *     message: `Session for ${session.address}, expires ${new Date(session.expiresAt).toISOString()}`,
+ *   })
+ * );
+ *
+ * @since 6.9.0
+ */
+function createNoArgResultHandler(sdkMethodName, responseBuilder) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk) => {
+        const { result } = await invokeSdkMethod({
+            sdk,
+            methodName: sdkMethodName,
+        });
+        return (0, response_formatter_js_1.formatSuccess)(responseBuilder(result));
+    });
+}
+// =============================================================================
+// Sync Boolean Check Handler Factory (DRY for isAuthenticated, shouldRefresh, etc.)
+// =============================================================================
+/**
+ * Creates a handler for synchronous SDK methods that return boolean with conditional messages.
+ *
+ * Use for sync methods like isAuthenticated(), shouldRefreshToken() that need
+ * different messages based on the boolean result.
+ *
+ * @param syncMethodName - Name of the sync SDK method to call
+ * @param argExtractor - Optional function to extract arguments from MCP args
+ * @param messages - Object with true and false message strings
+ * @returns Handler that calls sync method and returns formatted boolean response
+ *
+ * @example
+ * const handler = createSyncBooleanHandler(
+ *   'isAuthenticated',
+ *   undefined,
+ *   { true: 'Session is valid', false: 'Not authenticated or token expired' }
+ * );
+ *
+ * @since 6.9.0
+ */
+function createSyncBooleanHandler(syncMethodName, argExtractor, messages) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const method = sdk[syncMethodName];
+        if (!method || typeof method !== 'function') {
+            throw new Error(`SDK method "${syncMethodName}" not found`);
+        }
+        const extractedArg = argExtractor ? argExtractor(args) : undefined;
+        const result = extractedArg !== undefined ? method.call(sdk, extractedArg) : method.call(sdk);
+        return (0, response_formatter_js_1.formatBoolean)(result, result ? messages.true : messages.false);
+    });
+}
+/**
+ * Extracts flexible token identifier from MCP args.
+ *
+ * Handles the common pattern where tools accept either tokenName (convenience)
+ * or tokenId (full identifier), but not both. Returns an object with the
+ * appropriate property set based on which was provided.
+ *
+ * Pattern replaced:
+ * ```typescript
+ * // Before (repeated 6+ times)
+ * if (args.tokenName) {
+ *   options.tokenName = args.tokenName;
+ * } else {
+ *   options.tokenId = args.tokenId;
+ * }
+ *
+ * // After
+ * const tokenId = extractFlexibleTokenId(args);
+ * const options = { ...tokenId, ...otherOptions };
+ * ```
+ *
+ * @param args - MCP tool arguments containing tokenName and/or tokenId
+ * @returns Object with either tokenName or tokenId property set
+ *
+ * @example
+ * // In fetchPriceHistory handler:
+ * handler: createSimpleHandler('fetchPriceHistory', (args) => ({
+ *   ...extractFlexibleTokenId(args),
+ *   sortOrder: args.sortOrder,
+ *   page: args.page,
+ *   limit: args.limit,
+ * })),
+ *
+ * @since 6.10.0
+ */
+function extractFlexibleTokenId(args) {
+    if (args.tokenName) {
+        return { tokenName: args.tokenName };
+    }
+    return { tokenId: args.tokenId };
+}
+// =============================================================================
+// Conditional Response Handler Factory (DRY for null-check token responses)
+// =============================================================================
+/**
+ * Creates a handler for SDK methods that may return null with different success responses.
+ *
+ * Use for methods like getAccessToken() that return null when not authenticated,
+ * requiring different response structures for null vs non-null results.
+ *
+ * @param sdkMethodName - Name of the SDK method to call (sync or async)
+ * @param nullResponse - Response to return when result is null/undefined
+ * @param valueBuilder - Function to build response when result has value
+ * @param isSync - Whether the SDK method is synchronous (default: false)
+ * @returns Handler with conditional null/value responses
+ *
+ * @example
+ * const handler = createConditionalResponseHandler(
+ *   'getAccessToken',
+ *   { accessToken: null, message: 'Not authenticated - no token available' },
+ *   (token) => ({ accessToken: token, message: 'Access token retrieved' }),
+ *   true // sync method
+ * );
+ *
+ * @since 6.9.0
+ */
+function createConditionalResponseHandler(sdkMethodName, nullResponse, valueBuilder, isSync = false) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk) => {
+        let result;
+        if (isSync) {
+            const method = sdk[sdkMethodName];
+            if (!method || typeof method !== 'function') {
+                throw new Error(`SDK method "${sdkMethodName}" not found`);
+            }
+            result = method.call(sdk);
+        }
+        else {
+            // Async method via invokeSdkMethod
+            const invocation = await invokeSdkMethod({
+                sdk,
+                methodName: sdkMethodName,
+            });
+            result = invocation.result;
+        }
+        if (result === null || result === undefined) {
+            return (0, response_formatter_js_1.formatSuccess)(nullResponse);
+        }
+        return (0, response_formatter_js_1.formatSuccess)(valueBuilder(result));
+    });
+}
+// =============================================================================
+// Authentication Description Constants (DRY consolidation for tool descriptions)
+// =============================================================================
+/**
+ * Standard authentication requirement descriptions for MCP tool definitions.
+ *
+ * Provides consistent, reusable auth requirement strings to eliminate
+ * repetitive boilerplate in tool descriptions.
+ *
+ * @example
+ * description: `Get chat status for a stream.
+ *
+ * ${AUTH_DESCRIPTIONS.PUBLIC}`,
+ *
+ * @example
+ * description: `Start a stream.
+ *
+ * ${AUTH_DESCRIPTIONS.JWT_SESSION}`,
+ *
+ * @since 6.8.0
+ */
+exports.AUTH_DESCRIPTIONS = {
+    /** No authentication required */
+    PUBLIC: 'Authentication: None required (public endpoint)',
+    /** Requires JWT session (login first) */
+    JWT_SESSION: 'Authentication: Requires JWT session (call gala_launchpad_login first)',
+    /** Requires wallet signature */
+    WALLET_SIGNATURE: 'Authentication: Requires wallet signature',
+    /** Requires stream admin API key */
+    ADMIN_API_KEY: 'Authentication: Requires streamAdminApiKey configuration',
+    /** Requires admin API key OR JWT as token owner */
+    ADMIN_OR_OWNER: 'Authentication: Requires streamAdminApiKey (admin) OR JWT auth (token owner)',
+    /** Requires admin API key OR JWT as moderator */
+    ADMIN_OR_MODERATOR: 'Authentication: Requires streamAdminApiKey (admin) OR JWT auth (token owner/moderator)',
+    /** Requires admin API key OR JWT as overseer */
+    ADMIN_OR_OVERSEER: 'Authentication: Requires streamAdminApiKey (admin) OR JWT auth as Overseer',
+    /** Requires admin API key OR JWT as existing overseer */
+    ADMIN_OR_EXISTING_OVERSEER: 'Authentication: Requires streamAdminApiKey (admin) OR JWT auth as existing Overseer',
+    /** Stream creator only (wallet signature) */
+    STREAM_CREATOR: 'Authentication: Requires wallet signature (stream creator only)',
+    /** Optional JWT - returns null/limited if not authenticated */
+    OPTIONAL_JWT: 'Authentication: Optional JWT - returns limited data if not authenticated',
+    /** Requires JWT or API key with specific permission */
+    JWT_OR_API_KEY: (permission) => `Authentication: Requires JWT session OR API key with ${permission} permission`,
+};
+// =============================================================================
+// Optional Result Handler Factory (DRY for position/resource lookups that may not exist)
+// =============================================================================
+/**
+ * Creates a handler for SDK methods that return optional results (null/undefined if not found).
+ *
+ * Use this for resource lookup operations where not finding the resource is a valid
+ * outcome (not an error). Returns a consistent { found: false } response when
+ * the resource doesn't exist, and { found: true, data: result } when it does.
+ *
+ * @param sdkMethod - Function that calls the SDK method with sdk and args
+ * @param notFoundMessage - Message to return when resource is not found (default: 'Resource not found')
+ * @returns Handler with consistent found/not-found response structure
+ *
+ * @example
+ * const handler = createOptionResultHandler(
+ *   (sdk, args) => sdk.getSwapLiquidityPositionById(args.ownerAddress, args.positionId),
+ *   'Position not found'
+ * );
+ *
+ * @since 6.12.0
+ */
+function createOptionResultHandler(sdkMethod, notFoundMessage = 'Resource not found') {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const result = await sdkMethod(sdk, args);
+        if (result === null || result === undefined) {
+            return (0, response_formatter_js_1.formatSuccess)({ found: false, message: notFoundMessage });
+        }
+        return (0, response_formatter_js_1.formatSuccess)({ found: true, data: result });
+    });
+}
+// =============================================================================
+// Wallet Required Handler Factory (Simplified version for common patterns)
+// =============================================================================
+/**
+ * Creates a handler for SDK methods requiring wallet validation with optional result transformation.
+ *
+ * This is a simplified version of createWalletRequiredHandler that takes the SDK method
+ * directly (as a function) rather than a method name string. Useful for cases where
+ * you need direct SDK method calls with type safety.
+ *
+ * @param sdkMethod - Function that calls the SDK method with sdk and args
+ * @param transformer - Optional function to transform the result before returning
+ * @returns Handler that validates wallet then calls SDK method
+ *
+ * @example
+ * const handler = createWalletRequiredMethodHandler(
+ *   (sdk, args) => sdk.addSwapLiquidityByPrice({
+ *     token0: args.token0, token1: args.token1, fee: args.fee,
+ *     minPrice: args.minPrice, maxPrice: args.maxPrice,
+ *     amount0Desired: args.amount0Desired, amount1Desired: args.amount1Desired,
+ *   }),
+ *   (result) => ({ ...result, message: 'Liquidity added!' })
+ * );
+ *
+ * @since 6.12.0
+ */
+function createWalletRequiredMethodHandler(sdkMethod, transformer) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        // Validate wallet is configured
+        try {
+            sdk.getAddress();
+        }
+        catch {
+            throw new Error('Wallet configuration required for this operation');
+        }
+        const result = await sdkMethod(sdk, args);
+        return (0, response_formatter_js_1.formatSuccess)(transformer ? transformer(result) : result);
+    });
+}
+// =============================================================================
+// Optional Params Handler Factory (DRY for SDK methods with optional parameter objects)
+// =============================================================================
+/**
+ * Creates a handler for SDK methods that accept optional parameter objects.
+ *
+ * This factory handles the common pattern where an SDK method takes an optional
+ * params object, and you want to build those params from the MCP args.
+ *
+ * @param sdkMethod - Function that calls the SDK method with sdk and optional params
+ * @param paramBuilder - Optional function to build params from args (if omitted, passes args directly)
+ * @param resultTransformer - Optional function to transform the result before returning
+ * @returns Handler that builds params and calls SDK method
+ *
+ * @example
+ * const handler = createOptionalParamsHandler(
+ *   (sdk, params) => sdk.getAllSwapUserLiquidityPositions(params?.ownerAddress, params?.options),
+ *   (args) => ({
+ *     ownerAddress: args.ownerAddress,
+ *     options: args.withPrices ? { withPrices: true } : undefined,
+ *   }),
+ *   (result, args) => formatPositionListResponse(parsePositionListResult(result), { ownerAddress: args.ownerAddress })
+ * );
+ *
+ * @since 6.12.0
+ */
+function createOptionalParamsHandler(sdkMethod, paramBuilder, resultTransformer) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        const params = paramBuilder ? paramBuilder(args) : args;
+        const result = await sdkMethod(sdk, params);
+        const transformed = resultTransformer ? resultTransformer(result, args) : result;
+        return (0, response_formatter_js_1.formatSuccess)(transformed);
+    });
+}
+/**
+ * Creates a handler for liquidity position operations that require pre-fetching position details.
+ *
+ * This factory consolidates the common pattern found in removeLiquidity and collectPositionFees:
+ * 1. Validate wallet configured
+ * 2. Extract ownerAddress and positionId from args
+ * 3. Fetch position details via getSwapLiquidityPositionById
+ * 4. Validate position exists
+ * 5. Call the SDK operation with position data
+ * 6. Return enriched response with position token info
+ *
+ * Pattern replaced:
+ * ```typescript
+ * // Before (40+ lines duplicated in 2 handlers)
+ * handler: withErrorHandling(async (sdk, args) => {
+ *   validateWalletConfigured(sdk);
+ *   const ownerAddress = args.ownerAddress as string;
+ *   const positionId = args.positionId as string;
+ *   const position = await sdk.getSwapLiquidityPositionById(ownerAddress, positionId);
+ *   if (!position) throw new Error(`Position ${positionId} not found...`);
+ *   const result = await sdk.someOperation({...});
+ *   return formatSuccess({ transactionId: result.transactionId, token0: position.token0, ... });
+ * })
+ *
+ * // After
+ * handler: createPositionEnrichmentHandler({
+ *   operation: (sdk, position, args) => sdk.removeSwapLiquidity({
+ *     token0: position.token0, token1: position.token1, ...args,
+ *   }),
+ *   responseBuilder: (result, position, args) => ({
+ *     transactionId: result.transactionId,
+ *     token0: position.token0,
+ *     message: `Liquidity removed! Received ${result.amount0} ${position.token0}...`,
+ *   })
+ * })
+ * ```
+ *
+ * @param config - Configuration specifying the SDK operation and response builder
+ * @returns Handler that pre-fetches position, calls operation, and returns enriched response
+ *
+ * @example
+ * // Remove liquidity handler
+ * const handler = createPositionEnrichmentHandler({
+ *   operation: (sdk, position, args) => sdk.removeSwapLiquidity({
+ *     token0: position.token0,
+ *     token1: position.token1,
+ *     fee: position.feeTier,
+ *     tickLower: position.tickLower,
+ *     tickUpper: position.tickUpper,
+ *     liquidity: args.liquidity,
+ *     amount0Min: args.amount0Min,
+ *     amount1Min: args.amount1Min,
+ *     positionId: args.positionId,
+ *   }),
+ *   responseBuilder: (result, position, args) => ({
+ *     transactionId: result.transactionId,
+ *     status: result.status,
+ *     positionId: args.positionId,
+ *     token0: position.token0,
+ *     token1: position.token1,
+ *     amount0: result.amount0,
+ *     amount1: result.amount1,
+ *     message: `Liquidity removed! Received ${result.amount0} ${position.token0} and ${result.amount1} ${position.token1}`,
+ *   })
+ * });
+ *
+ * @since 6.14.0
+ */
+function createPositionEnrichmentHandler(config) {
+    return (0, error_handler_js_1.withErrorHandling)(async (sdk, args) => {
+        // 1. Validate wallet configured
+        try {
+            sdk.getAddress();
+        }
+        catch {
+            throw new Error('Wallet configuration required for this operation');
+        }
+        // 2. Extract position identifiers
+        const ownerAddress = args.ownerAddress;
+        const positionId = args.positionId;
+        // 3. Fetch position details
+        const position = await sdk.getSwapLiquidityPositionById(ownerAddress, positionId);
+        // 4. Validate position exists
+        if (!position) {
+            throw new Error(`Position ${positionId} not found for owner ${ownerAddress}`);
+        }
+        // 5. Call SDK operation with position data
+        const result = await config.operation(sdk, position, args);
+        // 6. Return enriched response
+        return (0, response_formatter_js_1.formatSuccess)(config.responseBuilder(result, position, args));
+    });
+}
+//# sourceMappingURL=handler-factories.js.map