/**
 * Action Router - Generic routing for consolidated MCP tools
 *
 * TIER 1 Token Efficiency Optimization
 *
 * Provides a generic framework for routing action-based tools:
 * - Parses action parameter with fuzzy matching
 * - Routes to appropriate handler based on action
 * - Handles common patterns (CRUD, domain-specific)
 * - Provides consistent response formatting
 *
 * Usage:
 *   const router = createActionRouter(ACTIONS, commonSchema, handlers);
 *   const result = await router(args);
 */
import { z } from 'zod';
import { MatchResult } from './fuzzy-enum.js';
/**
 * Handler function for a specific action
 */
export type ActionHandler<TArgs = unknown, TResult = unknown> = (args: TArgs) => Promise<TResult> | TResult;
/**
 * Definition for a single action within a consolidated tool
 *
 * Note: Handler uses 'any' for flexibility since Zod schema validates at runtime.
 * This allows typed handlers to be assigned without explicit casts.
 */
export interface ActionDefinition {
    /** Zod schema for action-specific parameters */
    schema: z.ZodType<any>;
    /** Handler function for this action (validated args from schema) */
    handler: (args: any) => Promise<unknown> | unknown;
    /** Optional aliases for this action (e.g., 'new' -> 'create') */
    aliases?: string[];
    /** Description for documentation */
    description?: string;
}
/**
 * Configuration for the action router
 */
export interface ActionRouterConfig<TActions extends string> {
    /** Valid action names */
    actions: readonly TActions[];
    /** Action definitions with handlers */
    definitions: Record<TActions, ActionDefinition>;
    /** Global alias map (optional, built from definitions if not provided) */
    aliases?: Record<string, TActions>;
    /** Minimum similarity for fuzzy matching (default: 0.6) */
    threshold?: number;
}
/**
 * MCP-formatted response
 */
export interface McpResponse {
    content: Array<{
        type: 'text';
        text: string;
    }>;
}
/**
 * Enhanced result with fuzzy match metadata
 */
export interface EnhancedResult<T> {
    result: T;
    _meta?: {
        fuzzyMatch?: {
            requested: string;
            resolved: string;
            similarity: number;
        };
    };
}
/**
 * Create an action router for a consolidated tool
 *
 * @example
 * const router = createActionRouter({
 *     actions: ['create', 'get', 'update', 'delete', 'list'] as const,
 *     definitions: {
 *         create: {
 *             schema: z.object({ name: z.string() }),
 *             handler: async (args) => createEntity(args),
 *             aliases: ['new', 'add']
 *         },
 *         get: {
 *             schema: z.object({ id: z.string() }),
 *             handler: async (args) => getEntity(args.id)
 *         },
 *         // ...
 *     }
 * });
 *
 * // Later in tool handler:
 * const result = await router({ action: 'new', name: 'Test' });
 */
export declare function createActionRouter<TActions extends string>(config: ActionRouterConfig<TActions>): (args: Record<string, unknown>) => Promise<McpResponse>;
/**
 * Create a router using Zod discriminated unions
 *
 * This approach uses Zod's discriminatedUnion for compile-time type safety.
 * Better for complex tools where each action has very different schemas.
 *
 * @example
 * const schema = z.discriminatedUnion('action', [
 *     z.object({ action: z.literal('create'), name: z.string() }),
 *     z.object({ action: z.literal('get'), id: z.string() }),
 * ]);
 *
 * const router = createDiscriminatedRouter(schema, {
 *     create: async (args) => { ... },
 *     get: async (args) => { ... },
 * });
 */
export declare function createDiscriminatedRouter<TSchema extends z.ZodSchema>(schema: TSchema, handlers: Record<string, ActionHandler>): (args: unknown) => Promise<McpResponse>;
/**
 * Format a successful result as MCP response
 */
export declare function formatMcpSuccess(result: unknown, matchInfo?: MatchResult<string>): McpResponse;
/**
 * Format an error as MCP response
 */
export declare function formatMcpError(message: string, details: Record<string, unknown>): McpResponse;
/**
 * Format a Zod validation error as MCP response with helpful details
 */
export declare function formatValidationError(action: string, error: z.ZodError): McpResponse;
/**
 * Generate description text for the 'action' parameter
 * Includes all valid actions and their aliases
 */
export declare function buildActionDescription<TActions extends string>(actions: readonly TActions[], definitions: Record<TActions, ActionDefinition>): string;
/**
 * Create the base schema for a consolidated tool
 * Includes the action parameter with description
 */
export declare function createConsolidatedSchema<TActions extends string>(actions: readonly TActions[], definitions: Record<TActions, ActionDefinition>): z.ZodObject<{
    action: z.ZodString;
}>;
/**
 * Merge common schema with action-specific schema
 * Useful for building the full input schema for documentation
 */
export declare function mergeSchemas(common: z.AnyZodObject, specific: z.AnyZodObject): z.AnyZodObject;
//# sourceMappingURL=action-router.d.ts.map