@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
210 lines • 10.1 kB
JavaScript
/**
* @fileoverview Branch-specific HTTP client for Bitbucket API operations.
*
* This module provides branch-related functionality including:
* - Listing branches in a repository
* - Getting detailed branch information
* - Creating new branches
* - Deleting branches
* - Managing branching models and permissions
* - Configuring default reviewers
*
*/
import { BaseClient } from './base-client.js';
/**
* HTTP client for Bitbucket branch operations.
*
* Provides methods for managing branches within repositories including
* CRUD operations, branch protection rules, and Git Flow configuration.
*/
export class BranchClient extends BaseClient {
// =============================================================================
// BRANCH API METHODS
// =============================================================================
/**
* Retrieves all branches in a repository.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @returns Promise resolving to paginated branch list
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getBranches(workspaceSlug, repoSlug) {
return this.get(`/repositories/${workspaceSlug}/${repoSlug}/refs/branches`, undefined, {
operationName: 'get_branches',
});
}
/**
* Retrieves all branches in a repository (all pages).
*
* This method automatically handles pagination to return all branches
* across multiple pages. Use this when you need a complete list of branches.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @returns Promise resolving to array of all branches
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getAllBranches(workspaceSlug, repoSlug) {
return this.getAllPages(`/repositories/${workspaceSlug}/${repoSlug}/refs/branches`, undefined, {
operationName: 'get_all_branches',
});
}
/**
* Retrieves details for a specific branch.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param branchName - Name of the branch to retrieve
* @returns Promise resolving to branch details including latest commit info
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If branch not found or request fails
*/
async getBranch(workspaceSlug, repoSlug, branchName) {
return this.get(`/repositories/${workspaceSlug}/${repoSlug}/refs/branches/${encodeURIComponent(branchName)}`, undefined, {
operationName: 'get_branch',
});
}
/**
* Creates a new branch in the repository.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param payload - Branch creation data including name and target commit
* @returns Promise resolving to created branch details
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If creation fails or branch name conflicts exist
*/
async createBranch(workspaceSlug, repoSlug, payload) {
return this.post(`/repositories/${workspaceSlug}/${repoSlug}/refs/branches`, payload, {
operationName: 'create_branch',
priority: 3,
});
}
/**
* Deletes a branch from the repository.
*
* WARNING: This operation is irreversible. Ensure the branch is merged
* or no longer needed before deletion.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param branchName - Name of the branch to delete
* @returns Promise that resolves when deletion is complete
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If branch not found, is protected, or deletion fails
*/
async deleteBranch(workspaceSlug, repoSlug, branchName) {
return this.delete(`/repositories/${workspaceSlug}/${repoSlug}/refs/branches/${encodeURIComponent(branchName)}`, {
operationName: 'delete_branch',
priority: 2,
});
}
// =============================================================================
// BRANCHING MODEL API METHODS
// =============================================================================
/**
* Retrieves the branching model configuration for a repository.
*
* Returns the repository's branching model settings including development and
* production branches, branch type configurations, and naming conventions.
* This information is useful for understanding how the repository is organized
* and what branching strategy is being used (Git Flow, GitHub Flow, etc.).
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @returns Promise resolving to branching model configuration
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getBranchingModel(workspaceSlug, repoSlug) {
return this.get(`/repositories/${workspaceSlug}/${repoSlug}/branching-model`, undefined, {
operationName: 'get_branching_model',
});
}
/**
* Retrieves branch restrictions and permissions for a repository.
*
* Returns all branch protection rules including push restrictions, merge requirements,
* delete restrictions, and force push policies. This information helps understand
* what actions are allowed on different branches and who can perform them.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param params - Optional query parameters for filtering restrictions
* @returns Promise resolving to paginated branch permissions list
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getBranchPermissions(workspaceSlug, repoSlug, params) {
return this.get(`/repositories/${workspaceSlug}/${repoSlug}/branch-restrictions`, params, {
operationName: 'get_branch_permissions',
});
}
/**
* Retrieves all branch restrictions and permissions for a repository (all pages).
*
* This method automatically handles pagination to return all branch restrictions
* across multiple pages. Use this when you need a complete list of all branch
* protection rules and permissions.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param params - Optional query parameters for filtering restrictions
* @returns Promise resolving to complete branch permissions data
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getAllBranchPermissions(workspaceSlug, repoSlug, params) {
const response = await this.get(`/repositories/${workspaceSlug}/${repoSlug}/branch-restrictions`, params, {
operationName: 'get_all_branch_permissions',
});
// Since branch restrictions are typically not heavily paginated, we'll start with single page
// but can extend to full pagination if needed
return response.values;
}
/**
* Retrieves default reviewer assignments for a repository.
*
* Returns the configuration for automatic reviewer assignment based on branch
* patterns. This includes which users are automatically added as reviewers
* for pull requests targeting specific branches or branch patterns.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param params - Optional query parameters for filtering default reviewers
* @returns Promise resolving to paginated default reviewers list
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getDefaultReviewers(workspaceSlug, repoSlug, params) {
return this.get(`/repositories/${workspaceSlug}/${repoSlug}/default-reviewers`, params, {
operationName: 'get_default_reviewers',
});
}
/**
* Retrieves all default reviewer assignments for a repository (all pages).
*
* This method automatically handles pagination to return all default reviewer
* configurations across multiple pages. Use this when you need a complete list
* of all automatic reviewer assignments.
*
* @param workspaceSlug - Unique identifier for the workspace
* @param repoSlug - Unique identifier for the repository
* @param params - Optional query parameters for filtering default reviewers
* @returns Promise resolving to array of all default reviewer configurations
* @throws {AuthenticationError} If not authenticated
* @throws {BitbucketApiError} If repository not found or request fails
*/
async getAllDefaultReviewers(workspaceSlug, repoSlug, params) {
const response = await this.get(`/repositories/${workspaceSlug}/${repoSlug}/default-reviewers`, params, {
operationName: 'get_all_default_reviewers',
});
// Since default reviewers are typically not heavily paginated, we'll start with single page
// but can extend to full pagination if needed
return response.values;
}
}
//# sourceMappingURL=branch-client.js.map