@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
147 lines • 6.4 kB
TypeScript
/**
* @fileoverview Base HTTP client for Bitbucket Cloud API integration.
*
* This module provides the foundational HTTP client functionality that all
* domain-specific clients inherit from. It handles common concerns like:
* - Token-based authentication (API Token or Repository Token)
* - Request/response interceptors for logging and debugging
* - Rate limiting to respect API quotas
* - Error handling with retry logic
* - Pagination utilities for multi-page responses
*
*/
import { AxiosInstance } from 'axios';
import { AuthService } from '../auth-service.js';
/**
* Context information for API requests used in logging and rate limiting.
*/
export interface RequestContext {
/** HTTP method for the request (GET, POST, PUT, DELETE) */
method: string;
/** API endpoint path being accessed */
endpoint: string;
/** Human-readable operation name for logging */
operationName: string;
/** Priority level for rate limiting (1=highest, 10=lowest) */
priority?: number;
}
/**
* Generic interface for paginated Bitbucket API responses.
* @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;
}
/**
* Abstract base client for Bitbucket API operations.
*
* This class provides the core HTTP functionality that all domain-specific
* clients extend. It handles authentication, rate limiting, error handling,
* and pagination in a consistent manner across all API operations.
*/
export declare abstract class BaseClient {
/** Axios HTTP client instance configured for Bitbucket API */
protected client: AxiosInstance;
/** Authentication service for token management */
protected authService: AuthService;
/** Logger instance for API request/response tracking */
protected logger: import("../logger.js").Logger;
/** Error handler with retry logic for failed requests */
protected errorHandler: import("../error-handler.js").ErrorHandler;
/** Rate limiter to respect Bitbucket API quotas */
protected rateLimiter: import("../rate-limiter.js").RateLimiter;
/**
* Creates a new base Bitbucket API client.
*
* @param authService - Authentication service for handling tokens
*/
constructor(authService: AuthService);
/**
* Sets up request and response interceptors for the HTTP client.
* @private
*/
private setupInterceptors;
/**
* Makes a GET request to the specified endpoint.
*
* @template T - Expected response type
* @param endpoint - API endpoint path (relative to base URL)
* @param params - Optional query parameters
* @param context - Optional request context for logging and rate limiting
* @returns Promise resolving to the response data
*/
protected get<T>(endpoint: string, params?: Record<string, any>, context?: Partial<RequestContext>): Promise<T>;
/**
* Makes a POST request to the specified endpoint.
*
* @template T - Expected response type
* @param endpoint - API endpoint path (relative to base URL)
* @param data - Optional request body data
* @param context - Optional request context for logging and rate limiting
* @returns Promise resolving to the response data
*/
protected post<T>(endpoint: string, data?: any, context?: Partial<RequestContext>): Promise<T>;
/**
* Makes a PUT request to the specified endpoint.
*
* @template T - Expected response type
* @param endpoint - API endpoint path (relative to base URL)
* @param data - Optional request body data
* @param context - Optional request context for logging and rate limiting
* @returns Promise resolving to the response data
*/
protected put<T>(endpoint: string, data?: any, context?: Partial<RequestContext>): Promise<T>;
/**
* Makes a DELETE request to the specified endpoint.
*
* @template T - Expected response type
* @param endpoint - API endpoint path (relative to base URL)
* @param context - Optional request context for logging and rate limiting
* @returns Promise resolving to the response data
*/
protected delete<T>(endpoint: string, context?: Partial<RequestContext>): Promise<T>;
/**
* Executes an HTTP request with comprehensive error handling and rate limiting.
* @private
*/
private executeRequest;
/**
* Fetches all pages of a paginated API endpoint and returns combined results.
*
* @template T - The type of items being paginated
* @param endpoint - Initial API endpoint path (relative to base URL)
* @param params - Optional query parameters for the first request
* @param context - Optional request context for logging and rate limiting
* @param maxPages - Maximum number of pages to fetch (default: 50)
* @param maxItems - Maximum total items to fetch (default: 5000)
* @returns Promise resolving to array of all items across all pages
*/
protected getAllPages<T>(endpoint: string, params?: Record<string, any>, context?: Partial<RequestContext>, maxPages?: number, maxItems?: number): Promise<T[]>;
/**
* Fetches a single page with optional page size control.
*
* @template T - The type of items being paginated
* @param endpoint - API endpoint path (relative to base URL)
* @param page - Page number to fetch (1-based indexing)
* @param pageSize - Number of items per page (typically 10-100)
* @param params - Optional additional query parameters
* @param context - Optional request context for logging and rate limiting
* @returns Promise resolving to paginated response for the specified page
*/
protected getPage<T>(endpoint: string, page?: number, pageSize?: number, params?: Record<string, any>, context?: Partial<RequestContext>): Promise<BitbucketApiResponse<T>>;
/**
* Extracts retry-after delay from HTTP response headers.
* @private
*/
private extractRetryAfter;
}
//# sourceMappingURL=base-client.d.ts.map