@gohcltech/bitbucket-mcp/dist/clients/pull-request-client.d.ts

Bitbucket integration for Claude via Model Context Protocol

/**
 * @fileoverview Pull request-specific HTTP client for Bitbucket API operations.
 *
 * This module provides pull request-related functionality including:
 * - Listing pull requests with state filtering
 * - Getting detailed pull request information
 * - Creating new pull requests for code review
 * - Managing pull request approvals and workflow
 * - Merging and declining pull requests
 * - Adding and retrieving comments for code review discussions
 *
 * Pull requests are the primary mechanism for code review and collaboration
 * in Bitbucket. They allow developers to propose changes, discuss code,
 * and manage the integration of new features and fixes.
 */
import { BaseClient, BitbucketApiResponse } from './base-client.js';
import { PullRequest, Comment } from '../types/pull-request/index.js';
/**
 * HTTP client for Bitbucket pull request operations.
 *
 * Provides comprehensive methods for managing pull requests including
 * creation, approval workflows, merging, and comment management.
 * Pull requests support various states and approval mechanisms for
 * different team collaboration patterns.
 *
 * @example
 * ```typescript
 * const client = new PullRequestClient(oauthService);
 *
 * // List open pull requests
 * const openPRs = await client.getPullRequests('workspace', 'repo', { state: 'OPEN' });
 *
 * // Create a new pull request
 * const newPR = await client.createPullRequest('workspace', 'repo', {
 *   title: 'Feature: Add authentication',
 *   source: { branch: { name: 'feature/auth' } },
 *   destination: { branch: { name: 'develop' } },
 *   description: 'Implements OAuth 2.0 authentication'
 * });
 *
 * // Approve and merge the pull request
 * await client.approvePullRequest('workspace', 'repo', newPR.id);
 * await client.mergePullRequest('workspace', 'repo', newPR.id);
 * ```
 */
export declare class PullRequestClient extends BaseClient {
    /**
     * Retrieves all pull requests for a repository with optional filtering.
     *
     * Supports filtering by state, author, reviewer, and other criteria.
     * Common filters include state (OPEN, MERGED, DECLINED, SUPERSEDED)
     * and specific branch targets.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param params - Optional query parameters for filtering pull requests
     * @param params.state - Filter by pull request state (OPEN, MERGED, DECLINED, SUPERSEDED)
     * @param params.sort - Sort order for results (created_on, updated_on, etc.)
     * @returns Promise resolving to paginated pull request list
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If repository not found or request fails
     *
     * @example
     * ```typescript
     * // Get all open pull requests
     * const openPRs = await client.getPullRequests('workspace', 'repo', { state: 'OPEN' });
     *
     * // Get pull requests sorted by creation date
     * const recentPRs = await client.getPullRequests('workspace', 'repo', {
     *   sort: '-created_on'
     * });
     * ```
     */
    getPullRequests(workspaceSlug: string, repoSlug: string, params?: Record<string, string>): Promise<BitbucketApiResponse<PullRequest>>;
    /**
     * Retrieves all pull requests for a repository (all pages) with optional filtering.
     *
     * This method automatically handles pagination to return all pull requests
     * across multiple pages. Use this when you need a complete list of pull requests
     * matching your filter criteria.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param params - Optional query parameters for filtering pull requests
     * @returns Promise resolving to array of all matching pull requests
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If repository not found or request fails
     *
     * @example
     * ```typescript
     * // Get all pull requests for analysis
     * const allPRs = await client.getAllPullRequests('workspace', 'repo');
     *
     * // Get all merged pull requests for reporting
     * const mergedPRs = await client.getAllPullRequests('workspace', 'repo', {
     *   state: 'MERGED'
     * });
     * ```
     */
    getAllPullRequests(workspaceSlug: string, repoSlug: string, params?: Record<string, string>): Promise<PullRequest[]>;
    /**
     * Retrieves detailed information for a specific pull request.
     *
     * Returns comprehensive pull request data including source and destination
     * branches, approval status, merge commit details, and reviewer information.
     * This is useful for displaying pull request details or making decisions
     * about merge readiness.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @returns Promise resolving to detailed pull request information
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or request fails
     *
     * @example
     * ```typescript
     * // Get pull request details for review
     * const pr = await client.getPullRequest('workspace', 'repo', 42);
     * console.log(`PR #${pr.id}: ${pr.title}`);
     * console.log(`State: ${pr.state}, Approvals: ${pr.participants.filter(p => p.approved).length}`);
     * ```
     */
    getPullRequest(workspaceSlug: string, repoSlug: string, pullRequestId: number): Promise<PullRequest>;
    /**
     * Creates a new pull request between two branches.
     *
     * Creates a pull request for code review and collaboration. The pull request
     * will compare changes between the source and destination branches and allow
     * team members to review, comment, and approve the changes.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param payload - Pull request creation data
     * @param payload.title - Title for the pull request (required)
     * @param payload.source - Source branch information ({ branch: { name: 'branch-name' } })
     * @param payload.destination - Destination branch information ({ branch: { name: 'target-branch' } })
     * @param payload.description - Optional description in markdown format
     * @param payload.close_source_branch - Whether to close source branch after merge
     * @param payload.reviewers - Optional array of reviewers ({ username: 'user' })
     * @returns Promise resolving to the created pull request details
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If creation fails or branches are invalid
     *
     * @example
     * ```typescript
     * // Create a feature pull request
     * const pr = await client.createPullRequest('workspace', 'repo', {
     *   title: 'Feature: Add user authentication',
     *   source: { branch: { name: 'feature/auth' } },
     *   destination: { branch: { name: 'develop' } },
     *   description: 'Implements OAuth 2.0 authentication with JWT tokens',
     *   close_source_branch: true,
     *   reviewers: [{ username: 'tech-lead' }, { username: 'security-reviewer' }]
     * });
     * ```
     */
    createPullRequest(workspaceSlug: string, repoSlug: string, payload: any): Promise<PullRequest>;
    /**
     * Updates an existing pull request.
     *
     * Modifies the title, description, or other properties of an open pull request.
     * Useful for updating PR information based on feedback or completed work.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @param payload - Update payload containing fields to update (title, description, etc.)
     * @returns Promise resolving to the updated pull request details
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or update fails
     *
     * @example
     * ```typescript
     * // Update PR title and description
     * const updated = await client.updatePullRequest('workspace', 'repo', 42, {
     *   title: 'Updated: Fix authentication bug',
     *   description: 'Updated description with test verification'
     * });
     * ```
     */
    updatePullRequest(workspaceSlug: string, repoSlug: string, pullRequestId: number, payload: any): Promise<PullRequest>;
    /**
     * Approves a pull request to indicate readiness for merge.
     *
     * Adds the authenticated user's approval to the pull request. This approval
     * may be required for merge depending on the repository's branch restrictions
     * and merge requirements. Multiple approvals may be needed based on the
     * repository's configuration.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @returns Promise that resolves when approval is recorded
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or approval fails
     *
     * @example
     * ```typescript
     * // Approve a pull request after code review
     * await client.approvePullRequest('workspace', 'repo', 42);
     * console.log('Pull request approved successfully');
     * ```
     */
    approvePullRequest(workspaceSlug: string, repoSlug: string, pullRequestId: number): Promise<void>;
    /**
     * Removes approval from a pull request.
     *
     * Withdraws the authenticated user's approval from the pull request.
     * This is useful when additional changes are needed or when concerns
     * are discovered after initial approval.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @returns Promise that resolves when approval is removed
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or unapproval fails
     *
     * @example
     * ```typescript
     * // Remove approval if additional changes are needed
     * await client.unapprovePullRequest('workspace', 'repo', 42);
     * console.log('Approval removed - requesting additional changes');
     * ```
     */
    unapprovePullRequest(workspaceSlug: string, repoSlug: string, pullRequestId: number): Promise<void>;
    /**
     * Merges an approved pull request into the destination branch.
     *
     * Integrates the changes from the source branch into the destination branch.
     * The merge strategy can be configured (merge commit, squash, fast-forward)
     * based on repository settings and the optional payload parameters.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @param payload - Optional merge configuration
     * @param payload.type - Merge strategy ('merge_commit', 'squash', 'fast_forward')
     * @param payload.message - Custom merge commit message
     * @param payload.close_source_branch - Whether to delete source branch after merge
     * @returns Promise resolving to the updated pull request with merge details
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If merge fails due to conflicts or insufficient approvals
     *
     * @example
     * ```typescript
     * // Merge with default settings
     * const mergedPR = await client.mergePullRequest('workspace', 'repo', 42);
     *
     * // Merge with squash and custom message
     * const squashedPR = await client.mergePullRequest('workspace', 'repo', 42, {
     *   type: 'squash',
     *   message: 'Feature: Add authentication system\n\nImplements OAuth 2.0 with JWT tokens',
     *   close_source_branch: true
     * });
     * ```
     */
    mergePullRequest(workspaceSlug: string, repoSlug: string, pullRequestId: number, payload?: any): Promise<PullRequest>;
    /**
     * Declines a pull request, preventing it from being merged.
     *
     * Marks the pull request as declined, indicating that the proposed changes
     * will not be integrated. This action can be taken when changes are no longer
     * needed, don't meet quality standards, or conflict with project direction.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @returns Promise resolving to the updated pull request with declined status
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or decline fails
     *
     * @example
     * ```typescript
     * // Decline a pull request that's no longer needed
     * const declinedPR = await client.declinePullRequest('workspace', 'repo', 42);
     * console.log(`Pull request #${declinedPR.id} has been declined`);
     * ```
     */
    declinePullRequest(workspaceSlug: string, repoSlug: string, pullRequestId: number): Promise<PullRequest>;
    /**
     * Adds a comment to a pull request for code review discussion.
     *
     * Creates a new comment on the pull request for team communication,
     * code review feedback, or general discussion. Comments support
     * markdown formatting and can reference specific lines of code.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @param payload - Comment data
     * @param payload.content - Comment content in markdown format
     * @param payload.inline - Optional inline comment configuration for specific code lines
     * @returns Promise resolving to the created comment details
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or comment creation fails
     *
     * @example
     * ```typescript
     * // Add a general comment
     * const comment = await client.addComment('workspace', 'repo', 42, {
     *   content: {
     *     raw: 'Great work on this feature! The error handling looks robust.',
     *     markup: 'markdown'
     *   }
     * });
     *
     * // Add an inline comment on specific code
     * const inlineComment = await client.addComment('workspace', 'repo', 42, {
     *   content: {
     *     raw: 'Consider using const instead of let here for immutability.',
     *     markup: 'markdown'
     *   },
     *   inline: {
     *     to: 15,
     *     path: 'src/auth.ts'
     *   }
     * });
     * ```
     */
    addComment(workspaceSlug: string, repoSlug: string, pullRequestId: number, payload: any): Promise<Comment>;
    /**
     * Retrieves all comments for a pull request.
     *
     * Returns all comments associated with the pull request including
     * general comments and inline code review comments. Comments are
     * ordered chronologically to maintain conversation flow.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @returns Promise resolving to paginated comment list
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or request fails
     *
     * @example
     * ```typescript
     * // Get all comments for review
     * const comments = await client.getComments('workspace', 'repo', 42);
     * console.log(`Found ${comments.values.length} comments`);
     *
     * // Display comment authors and content
     * comments.values.forEach(comment => {
     *   console.log(`${comment.user.display_name}: ${comment.content.raw}`);
     * });
     * ```
     */
    getComments(workspaceSlug: string, repoSlug: string, pullRequestId: number): Promise<BitbucketApiResponse<Comment>>;
    /**
     * Retrieves all comments for a pull request (all pages).
     *
     * This method automatically handles pagination to return all comments
     * across multiple pages. Use this when you need a complete list of all
     * comments for analysis or display purposes.
     *
     * @param workspaceSlug - Unique identifier for the workspace
     * @param repoSlug - Unique identifier for the repository
     * @param pullRequestId - Unique numeric identifier for the pull request
     * @returns Promise resolving to array of all comments
     * @throws {AuthenticationError} If not authenticated
     * @throws {BitbucketApiError} If pull request not found or request fails
     *
     * @example
     * ```typescript
     * // Get all comments for analysis
     * const allComments = await client.getAllComments('workspace', 'repo', 42);
     *
     * // Count comments by author
     * const commentCounts = allComments.reduce((counts, comment) => {
     *   const author = comment.user.display_name;
     *   counts[author] = (counts[author] || 0) + 1;
     *   return counts;
     * }, {});
     * ```
     */
    getAllComments(workspaceSlug: string, repoSlug: string, pullRequestId: number): Promise<Comment[]>;
}
//# sourceMappingURL=pull-request-client.d.ts.map