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

Bitbucket integration for Claude via Model Context Protocol

/**
 * @fileoverview Common types and schemas shared across all domain modules.
 *
 * This module contains:
 * - Error classes for different failure scenarios
 * - Pagination interfaces used by all API responses
 * - Configuration schemas for server and OAuth settings
 * - Utility functions for validation and sanitization
 * - Common validation patterns used across domains
 *
 */
import { z } from 'zod';
/**
 * 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 tokens are invalid.
 * Indicates that the user needs to re-authenticate or refresh tokens.
 */
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);
}
/**
 * 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;
}
/**
 * Schema for logging configuration parameters.
 * Defines options for multiple output destinations and logging behavior.
 */
export declare const LoggingConfigSchema: z.ZodObject<{
    /** Enable real-time web log viewer */
    enableLogViewer: z.ZodDefault<z.ZodBoolean>;
    /** 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>;
    /** Maximum number of log entries to keep in memory for web viewer */
    logViewerMaxEntries: z.ZodDefault<z.ZodNumber>;
    /** Enable structured logging with additional metadata */
    enableStructuredLogging: z.ZodDefault<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
    enableConsoleLogging: boolean;
    enableFileLogging: boolean;
    logFilePath: string;
    enableStructuredLogging: boolean;
    enableLogViewer: boolean;
    logViewerMaxEntries: number;
}, {
    enableConsoleLogging?: boolean | undefined;
    enableFileLogging?: boolean | undefined;
    logFilePath?: string | undefined;
    enableStructuredLogging?: boolean | undefined;
    enableLogViewer?: boolean | undefined;
    logViewerMaxEntries?: number | 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>;
    /** Server port number (1-65535) */
    port: 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 real-time web log viewer */
        enableLogViewer: z.ZodDefault<z.ZodBoolean>;
        /** 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>;
        /** Maximum number of log entries to keep in memory for web viewer */
        logViewerMaxEntries: z.ZodDefault<z.ZodNumber>;
        /** Enable structured logging with additional metadata */
        enableStructuredLogging: z.ZodDefault<z.ZodBoolean>;
    }, "strip", z.ZodTypeAny, {
        enableConsoleLogging: boolean;
        enableFileLogging: boolean;
        logFilePath: string;
        enableStructuredLogging: boolean;
        enableLogViewer: boolean;
        logViewerMaxEntries: number;
    }, {
        enableConsoleLogging?: boolean | undefined;
        enableFileLogging?: boolean | undefined;
        logFilePath?: string | undefined;
        enableStructuredLogging?: boolean | undefined;
        enableLogViewer?: boolean | undefined;
        logViewerMaxEntries?: number | 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;
    }>>;
    /** Optional encrypted token storage configuration */
    tokenStorage: z.ZodOptional<z.ZodObject<{
        /** Encryption key (minimum 32 characters for security) */
        encryptionKey: z.ZodString;
        /** File path for encrypted token storage */
        filePath: z.ZodDefault<z.ZodString>;
    }, "strip", z.ZodTypeAny, {
        encryptionKey: string;
        filePath: string;
    }, {
        encryptionKey: string;
        filePath?: string | undefined;
    }>>;
    /** 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;
    port: number;
    logLevel: "error" | "warn" | "info" | "debug";
    logging: {
        enableConsoleLogging: boolean;
        enableFileLogging: boolean;
        logFilePath: string;
        enableStructuredLogging: boolean;
        enableLogViewer: boolean;
        logViewerMaxEntries: number;
    };
    rateLimit: {
        maxConcurrent: number;
        minTime: number;
        reservoir: number;
        reservoirRefreshAmount: number;
        reservoirRefreshInterval: number;
    };
    pullRequest: {
        autoCloseBranchOnMerge: boolean;
    };
    tokenStorage?: {
        encryptionKey: string;
        filePath: string;
    } | 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;
        enableLogViewer?: boolean | undefined;
        logViewerMaxEntries?: number | undefined;
    } | undefined;
    rateLimit?: {
        maxConcurrent?: number | undefined;
        minTime?: number | undefined;
        reservoir?: number | undefined;
        reservoirRefreshAmount?: number | undefined;
        reservoirRefreshInterval?: number | undefined;
    } | undefined;
    pullRequest?: {
        autoCloseBranchOnMerge?: boolean | undefined;
    } | undefined;
    tokenStorage?: {
        encryptionKey: string;
        filePath?: string | 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>;
/**
 * Common regex patterns for validating Bitbucket identifiers.
 */
export declare const ValidationPatterns: {
    /** Workspace slug validation (alphanumeric, hyphens, underscores) */
    readonly workspace: RegExp;
    /** Repository slug validation (alphanumeric, hyphens, underscores, dots) */
    readonly repository: RegExp;
    /** Commit hash validation (40 character hexadecimal) */
    readonly commitHash: RegExp;
    /** Branch name validation (general git branch naming rules) */
    readonly branchName: RegExp;
};
/**
 * Base schema for workspace-related operations.
 */
export declare const WorkspaceBaseSchema: z.ZodObject<{
    workspace: z.ZodString;
}, "strip", z.ZodTypeAny, {
    workspace: string;
}, {
    workspace: string;
}>;
/**
 * Base schema for repository-related operations.
 */
export declare const RepositoryBaseSchema: z.ZodObject<{
    workspace: z.ZodString;
} & {
    repo_slug: z.ZodString;
}, "strip", z.ZodTypeAny, {
    workspace: string;
    repo_slug: string;
}, {
    workspace: string;
    repo_slug: string;
}>;
/**
 * Validates input against a Zod schema and throws detailed error on failure.
 *
 * @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.
 *
 * @param input - String to sanitize
 * @returns Sanitized string safe for processing
 */
export declare function sanitizeString(input: string): string;
/**
 * Type guard to check if input matches workspace input schema.
 */
export declare function isWorkspaceInput(input: unknown): input is z.infer<typeof WorkspaceBaseSchema>;
/**
 * Type guard to check if input matches repository input schema.
 */
export declare function isRepositoryInput(input: unknown): input is z.infer<typeof RepositoryBaseSchema>;
//# sourceMappingURL=common.d.ts.map