@gohcltech/bitbucket-mcp/dist/utils/parameter-validator.d.ts

Bitbucket integration for Claude via Model Context Protocol

/**
 * @fileoverview Parameter validation utilities for consolidated tools.
 *
 * Provides reusable validation functions for action-specific parameters,
 * including required field checks, enum validation, and Zod schema validation.
 */
import { z } from 'zod';
/**
 * Validates that required parameters are present in the arguments object.
 *
 * Checks if all specified fields are present and are not null or undefined.
 * Throws an error with field names if validation fails.
 *
 * @param args - The arguments object to validate
 * @param fields - Array of required field names
 * @param operation - Name of the operation (used in error message)
 * @throws {Error} If any required fields are missing
 *
 * @example
 * ```typescript
 * validateRequired(
 *   args,
 *   ['workspaceSlug', 'repoSlug', 'issueId'],
 *   'get_issue'
 * );
 * // Throws: "Missing required parameter(s) for get_issue: issueId"
 * ```
 */
export declare function validateRequired(args: Record<string, any>, fields: string[], operation: string): void;
/**
 * Validates that a value is one of the allowed enum values.
 *
 * Throws an error if the value is not in the enumValues array.
 * The error message lists all valid values.
 *
 * @template T - Type of the enum values (inferred from enumValues)
 * @param value - The value to validate
 * @param enumValues - Array or readonly array of allowed values
 * @param paramName - Name of the parameter (for error messages)
 * @throws {Error} If value is not in enumValues
 *
 * @example
 * ```typescript
 * validateEnum(
 *   args.state,
 *   ['OPEN', 'MERGED', 'DECLINED'] as const,
 *   'state'
 * );
 * // Throws: "Invalid value for state: UNKNOWN. Must be one of: OPEN, MERGED, DECLINED"
 * ```
 */
export declare function validateEnum<T extends string>(value: T, enumValues: readonly T[], paramName: string): void;
/**
 * Validates that a value is a positive integer.
 *
 * Useful for validating IDs and counts that must be positive integers.
 *
 * @param value - The value to validate
 * @param paramName - Name of the parameter (for error messages)
 * @throws {Error} If value is not a positive integer
 *
 * @example
 * ```typescript
 * validatePositiveInteger(args.issueId, 'issueId');
 * // Throws: "issueId must be a positive integer"
 * ```
 */
export declare function validatePositiveInteger(value: any, paramName: string): void;
/**
 * Validates that a value is a non-negative integer.
 *
 * Useful for validating indices, limits, and counts that can be zero.
 *
 * @param value - The value to validate
 * @param paramName - Name of the parameter (for error messages)
 * @throws {Error} If value is not a non-negative integer
 *
 * @example
 * ```typescript
 * validateNonNegativeInteger(args.limit, 'limit');
 * ```
 */
export declare function validateNonNegativeInteger(value: any, paramName: string): void;
/**
 * Validates that a value is a non-empty string.
 *
 * @param value - The value to validate
 * @param paramName - Name of the parameter (for error messages)
 * @throws {Error} If value is not a non-empty string
 *
 * @example
 * ```typescript
 * validateNonEmptyString(args.title, 'title');
 * // Throws: "title must be a non-empty string"
 * ```
 */
export declare function validateNonEmptyString(value: any, paramName: string): void;
/**
 * Validates that a value is a valid commit hash (40-character hex string).
 *
 * Git commit hashes are 40 hexadecimal characters (SHA-1).
 *
 * @param value - The value to validate
 * @param paramName - Name of the parameter (for error messages)
 * @throws {Error} If value is not a valid commit hash
 *
 * @example
 * ```typescript
 * validateCommitHash(args.commitHash, 'commitHash');
 * ```
 */
export declare function validateCommitHash(value: any, paramName: string): void;
/**
 * Validates input data against a Zod schema.
 *
 * Safe validation that returns success/error result rather than throwing.
 * Useful for detailed error reporting.
 *
 * @template T - The expected type after validation
 * @param schema - Zod schema to validate against
 * @param data - Data to validate
 * @returns Object with success boolean and either data or error details
 *
 * @example
 * ```typescript
 * const result = validateWithSchema(ManageWorkspacesArgsSchema, args);
 * if (!result.success) {
 *   return createErrorResponse(new Error(result.error), 'manage_workspaces');
 * }
 * const validatedArgs: ManageWorkspacesArgs = result.data;
 * ```
 */
export declare function validateWithSchema<T>(schema: z.ZodSchema<T>, data: unknown): {
    success: true;
    data: T;
} | {
    success: false;
    error: string;
};
/**
 * Validates input data against a Zod schema, throwing on failure.
 *
 * Stricter version that throws an error if validation fails.
 * Useful for early validation in handler functions.
 *
 * @template T - The expected type after validation
 * @param schema - Zod schema to validate against
 * @param data - Data to validate
 * @param context - Optional context for error message
 * @returns Validated data (type-safe)
 * @throws {Error} If validation fails
 *
 * @example
 * ```typescript
 * const args = validateWithSchemaOrThrow(
 *   ManageWorkspacesArgsSchema,
 *   input,
 *   'manage_workspaces'
 * );
 * // args is now type-safe: ManageWorkspacesArgs
 * ```
 */
export declare function validateWithSchemaOrThrow<T>(schema: z.ZodSchema<T>, data: unknown, context?: string): T;
/**
 * Extracts and validates specific parameters from arguments.
 *
 * Type-safe parameter extraction for a subset of parameters.
 * Validates that all required fields are present and correctly typed.
 *
 * @template T - Type of the extracted parameters
 * @param args - The arguments object
 * @param schema - Zod schema for the parameters
 * @returns Extracted and validated parameters
 * @throws {Error} If validation fails
 *
 * @example
 * ```typescript
 * const params = extractAndValidateParams(
 *   args,
 *   z.object({
 *     workspaceSlug: z.string(),
 *     repoSlug: z.string(),
 *   })
 * );
 * // params: { workspaceSlug: string, repoSlug: string }
 * ```
 */
export declare function extractAndValidateParams<T>(args: Record<string, any>, schema: z.ZodSchema<T>): T;
/**
 * Conditionally validates parameters based on a condition.
 *
 * Useful for action-specific validation where different actions
 * require different parameters.
 *
 * @param condition - Boolean condition to check
 * @param args - The arguments object
 * @param fields - Array of required field names
 * @param operation - Name of the operation (for error messages)
 * @throws {Error} If condition is true and required fields are missing
 *
 * @example
 * ```typescript
 * conditionalValidateRequired(
 *   action === 'get',
 *   args,
 *   ['issueId'],
 *   'get_issue'
 * );
 * ```
 */
export declare function conditionalValidateRequired(condition: boolean, args: Record<string, any>, fields: string[], operation: string): void;
/**
 * Creates a validator function for a specific set of required parameters.
 *
 * Returns a reusable validator function for consistent validation
 * of the same parameters across multiple handlers.
 *
 * @param fields - Array of required field names
 * @param operation - Name of the operation (for error messages)
 * @returns Validator function that takes args and validates them
 *
 * @example
 * ```typescript
 * const validateGetParams = createValidator(
 *   ['workspaceSlug', 'repoSlug', 'issueId'],
 *   'get_issue'
 * );
 *
 * // Use in multiple handlers:
 * validateGetParams(args);
 * ```
 */
export declare function createValidator(fields: string[], operation: string): (args: Record<string, any>) => void;
//# sourceMappingURL=parameter-validator.d.ts.map