@gohcltech/bitbucket-mcp/dist/types.d.ts

Bitbucket integration for Claude via Model Context Protocol

/**
 * @fileoverview Core TypeScript types and configuration schemas for Bitbucket MCP server.
 *
 * This module provides essential infrastructure types including:
 * - Server and OAuth configuration schemas
 * - Custom error classes for different failure scenarios
 * - Generic API response interfaces
 * - Utility functions for validation and sanitization
 *
 * Domain-specific types and schemas are located in their respective modules:
 * - Workspace types: src/types/workspace/
 * - Repository types: src/types/repository/
 * - Branch types: src/types/branch/
 * - Pull Request types: src/types/pull-request/
 * - Commit types: src/types/commit/
 * - Issue types: src/types/issue/
 *
 */
import { z } from 'zod';
/**
 * Schema for logging configuration parameters.
 * Defines options for multiple output destinations and logging behavior.
 */
export declare const LoggingConfigSchema: z.ZodObject<{
    /** Enable console logging output */
    enableConsoleLogging: z.ZodDefault<z.ZodBoolean>;
    /** Enable file logging output */
    enableFileLogging: z.ZodDefault<z.ZodBoolean>;
    /** Path for log file when file logging is enabled */
    logFilePath: z.ZodDefault<z.ZodString>;
    /** Enable structured logging with additional metadata */
    enableStructuredLogging: z.ZodDefault<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
    enableConsoleLogging: boolean;
    enableFileLogging: boolean;
    logFilePath: string;
    enableStructuredLogging: boolean;
}, {
    enableConsoleLogging?: boolean | undefined;
    enableFileLogging?: boolean | undefined;
    logFilePath?: string | undefined;
    enableStructuredLogging?: boolean | undefined;
}>;
/** Inferred TypeScript type for logging configuration */
export type LoggingConfig = z.infer<typeof LoggingConfigSchema>;
/**
 * Schema for server configuration parameters.
 * Defines valid ranges and defaults for server operation settings.
 */
export declare const ServerConfigSchema: z.ZodObject<{
    /** Application version (loaded dynamically from package.json) */
    version: z.ZodDefault<z.ZodString>;
    /** Note: port field removed in v2.0 (no persistent web server) */
    port: z.ZodReadonly<z.ZodOptional<z.ZodDefault<z.ZodNumber>>>;
    /** Logging level for server operations */
    logLevel: z.ZodDefault<z.ZodEnum<["error", "warn", "info", "debug"]>>;
    /** Logging configuration for multiple output destinations */
    logging: z.ZodDefault<z.ZodObject<{
        /** Enable console logging output */
        enableConsoleLogging: z.ZodDefault<z.ZodBoolean>;
        /** Enable file logging output */
        enableFileLogging: z.ZodDefault<z.ZodBoolean>;
        /** Path for log file when file logging is enabled */
        logFilePath: z.ZodDefault<z.ZodString>;
        /** Enable structured logging with additional metadata */
        enableStructuredLogging: z.ZodDefault<z.ZodBoolean>;
    }, "strip", z.ZodTypeAny, {
        enableConsoleLogging: boolean;
        enableFileLogging: boolean;
        logFilePath: string;
        enableStructuredLogging: boolean;
    }, {
        enableConsoleLogging?: boolean | undefined;
        enableFileLogging?: boolean | undefined;
        logFilePath?: string | undefined;
        enableStructuredLogging?: boolean | undefined;
    }>>;
    /** Rate limiting configuration to respect API quotas using token bucket algorithm */
    rateLimit: z.ZodDefault<z.ZodObject<{
        /** Maximum concurrent requests to prevent overwhelming the API */
        maxConcurrent: z.ZodDefault<z.ZodNumber>;
        /** Minimum time between requests in milliseconds to throttle request rate */
        minTime: z.ZodDefault<z.ZodNumber>;
        /** Request reservoir size - initial number of tokens available for burst requests */
        reservoir: z.ZodDefault<z.ZodNumber>;
        /** Amount to refill reservoir - tokens added during each refresh interval */
        reservoirRefreshAmount: z.ZodDefault<z.ZodNumber>;
        /** Reservoir refresh interval in milliseconds - how often tokens are replenished */
        reservoirRefreshInterval: z.ZodDefault<z.ZodNumber>;
    }, "strip", z.ZodTypeAny, {
        maxConcurrent: number;
        minTime: number;
        reservoir: number;
        reservoirRefreshAmount: number;
        reservoirRefreshInterval: number;
    }, {
        maxConcurrent?: number | undefined;
        minTime?: number | undefined;
        reservoir?: number | undefined;
        reservoirRefreshAmount?: number | undefined;
        reservoirRefreshInterval?: number | undefined;
    }>>;
    /** Note: tokenStorage field removed in v2.0 (no encrypted token persistence needed) */
    /** Pull request configuration options */
    pullRequest: z.ZodDefault<z.ZodObject<{
        /** Automatically close source branch when PR is merged (default: true) */
        autoCloseBranchOnMerge: z.ZodDefault<z.ZodBoolean>;
    }, "strip", z.ZodTypeAny, {
        autoCloseBranchOnMerge: boolean;
    }, {
        autoCloseBranchOnMerge?: boolean | undefined;
    }>>;
}, "strip", z.ZodTypeAny, {
    version: string;
    logLevel: "error" | "warn" | "info" | "debug";
    logging: {
        enableConsoleLogging: boolean;
        enableFileLogging: boolean;
        logFilePath: string;
        enableStructuredLogging: boolean;
    };
    rateLimit: {
        maxConcurrent: number;
        minTime: number;
        reservoir: number;
        reservoirRefreshAmount: number;
        reservoirRefreshInterval: number;
    };
    pullRequest: {
        autoCloseBranchOnMerge: boolean;
    };
    port?: number | undefined;
}, {
    version?: string | undefined;
    port?: number | undefined;
    logLevel?: "error" | "warn" | "info" | "debug" | undefined;
    logging?: {
        enableConsoleLogging?: boolean | undefined;
        enableFileLogging?: boolean | undefined;
        logFilePath?: string | undefined;
        enableStructuredLogging?: boolean | undefined;
    } | undefined;
    rateLimit?: {
        maxConcurrent?: number | undefined;
        minTime?: number | undefined;
        reservoir?: number | undefined;
        reservoirRefreshAmount?: number | undefined;
        reservoirRefreshInterval?: number | undefined;
    } | undefined;
    pullRequest?: {
        autoCloseBranchOnMerge?: boolean | undefined;
    } | undefined;
}>;
/** Inferred TypeScript type for server configuration */
export type ServerConfig = z.infer<typeof ServerConfigSchema>;
/**
 * Schema for OAuth token data persistence.
 * Defines the structure for storing authentication tokens securely.
 */
export declare const TokenDataSchema: z.ZodObject<{
    /** OAuth 2.0 access token */
    accessToken: z.ZodString;
    /** Optional refresh token for automatic renewal */
    refreshToken: z.ZodOptional<z.ZodString>;
    /** Token expiration timestamp (milliseconds since epoch) */
    expiresAt: z.ZodOptional<z.ZodNumber>;
    /** Token type (typically 'Bearer') */
    tokenType: z.ZodDefault<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    accessToken: string;
    tokenType: string;
    refreshToken?: string | undefined;
    expiresAt?: number | undefined;
}, {
    accessToken: string;
    refreshToken?: string | undefined;
    expiresAt?: number | undefined;
    tokenType?: string | undefined;
}>;
/** Inferred TypeScript type for token data */
export type TokenData = z.infer<typeof TokenDataSchema>;
/**
 * Error thrown when input validation fails.
 * Contains detailed information about validation failures for debugging.
 */
export declare class ValidationError extends Error {
    details?: any | undefined;
    constructor(message: string, details?: any | undefined);
}
/**
 * Error thrown when authentication fails or credentials are invalid.
 *
 * Indicates problems with authentication including:
 * - Invalid or malformed tokens
 * - Missing required credentials
 * - Expired or revoked tokens
 * - Invalid token format
 * - Authentication validation failures
 *
 * In v2.0, this replaces OAuth-related errors with token-based auth errors.
 * Users need to verify their token configuration in environment variables.
 */
export declare class AuthenticationError extends Error {
    constructor(message: string);
}
/**
 * Error thrown when API rate limits are exceeded.
 * Includes retry-after information when available from the API.
 */
export declare class RateLimitError extends Error {
    retryAfter?: number | undefined;
    constructor(message: string, retryAfter?: number | undefined);
}
/**
 * Error thrown when Bitbucket API requests fail.
 * Contains HTTP status code and response data for debugging.
 */
export declare class BitbucketApiError extends Error {
    statusCode?: number | undefined;
    response?: any | undefined;
    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
}
/**
 * Authentication method enumeration for v2.0 token-based authentication.
 * Supports two methods: API Tokens (with username) or Repository Tokens (standalone).
 */
export declare enum AuthMethod {
    /** API Token authentication using HTTP Basic Auth (username + token) */
    API_TOKEN = "api_token",
    /** Repository Token authentication using Bearer token */
    REPOSITORY_TOKEN = "repository_token"
}
/**
 * API Token authentication configuration (v2.0).
 * Uses HTTP Basic Auth with username and API token.
 * API Tokens are user-account level tokens valid across all repositories.
 */
export declare const ApiTokenAuthSchema: z.ZodObject<{
    method: z.ZodLiteral<AuthMethod.API_TOKEN>;
    username: z.ZodString;
    apiToken: z.ZodString;
    workspace: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    method: AuthMethod.API_TOKEN;
    username: string;
    apiToken: string;
    workspace?: string | undefined;
}, {
    method: AuthMethod.API_TOKEN;
    username: string;
    apiToken: string;
    workspace?: string | undefined;
}>;
export type ApiTokenAuth = z.infer<typeof ApiTokenAuthSchema>;
/**
 * Repository Token authentication configuration (v2.0).
 * Uses Bearer token authentication with a repository-scoped token.
 * Repository tokens are limited to a single repository.
 */
export declare const RepositoryTokenAuthSchema: z.ZodObject<{
    method: z.ZodLiteral<AuthMethod.REPOSITORY_TOKEN>;
    repositoryToken: z.ZodString;
    workspace: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    method: AuthMethod.REPOSITORY_TOKEN;
    repositoryToken: string;
    workspace?: string | undefined;
}, {
    method: AuthMethod.REPOSITORY_TOKEN;
    repositoryToken: string;
    workspace?: string | undefined;
}>;
export type RepositoryTokenAuth = z.infer<typeof RepositoryTokenAuthSchema>;
/**
 * Combined authentication configuration schema (v2.0).
 * Supports dual authentication methods using discriminated union:
 * - API Token: For user-account level access with username + token
 * - Repository Token: For single-repository access with token only
 */
export declare const AuthConfigSchema: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
    method: z.ZodLiteral<AuthMethod.API_TOKEN>;
    username: z.ZodString;
    apiToken: z.ZodString;
    workspace: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    method: AuthMethod.API_TOKEN;
    username: string;
    apiToken: string;
    workspace?: string | undefined;
}, {
    method: AuthMethod.API_TOKEN;
    username: string;
    apiToken: string;
    workspace?: string | undefined;
}>, z.ZodObject<{
    method: z.ZodLiteral<AuthMethod.REPOSITORY_TOKEN>;
    repositoryToken: z.ZodString;
    workspace: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    method: AuthMethod.REPOSITORY_TOKEN;
    repositoryToken: string;
    workspace?: string | undefined;
}, {
    method: AuthMethod.REPOSITORY_TOKEN;
    repositoryToken: string;
    workspace?: string | undefined;
}>]>;
export type AuthConfig = z.infer<typeof AuthConfigSchema>;
/**
 * Generic interface for paginated Bitbucket API responses.
 * Used for endpoints that return lists of resources with pagination.
 *
 * @template T - The type of items in the response array
 */
export interface BitbucketApiResponse<T> {
    /** Array of items for the current page */
    values: T[];
    /** Current page number (optional) */
    page?: number;
    /** Number of items per page (optional) */
    pagelen?: number;
    /** Total number of items across all pages (optional) */
    size?: number;
    /** URL for the next page of results (optional) */
    next?: string;
}
/**
 * Validates input against a Zod schema and throws detailed error on failure.
 *
 * This helper function provides standardized input validation with detailed
 * error messages that can be used for debugging and user feedback.
 *
 * @template T - The expected type after validation
 * @param schema - Zod schema to validate against
 * @param input - Input data to validate
 * @returns Validated and typed data
 * @throws {ValidationError} If validation fails with detailed error information
 */
export declare function validateInput<T>(schema: z.ZodSchema<T>, input: unknown): T;
/**
 * Sanitizes string input to prevent injection attacks and limit length.
 *
 * Removes potentially dangerous characters and enforces reasonable length limits
 * for user-provided string data.
 *
 * @param input - String to sanitize
 * @returns Sanitized string safe for processing
 */
export declare function sanitizeString(input: string): string;
//# sourceMappingURL=types.d.ts.map