@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
410 lines • 13.2 kB
TypeScript
/**
* @fileoverview TypeScript types for Bitbucket commit operations.
*
* This module contains TypeScript interfaces that correspond to commit-related
* entities returned by the Bitbucket API v2.0. Commits represent individual
* changes to the repository, containing metadata about what changed, who made
* the change, and when it was made.
*
* These types cover:
* - Individual commit information and metadata
* - Commit diffs showing file changes
* - Author information and attribution
* - Parent commit relationships
* - Links to related resources and views
*
* These types are used throughout the MCP server for:
* - Parsing Bitbucket commit API responses
* - Ensuring type safety in commit analysis operations
* - Supporting commit history and diff viewing
* - Managing code change tracking and attribution
*/
/**
* Bitbucket commit entity representing a single code change.
*
* A commit represents an atomic set of changes to the repository, including
* file modifications, additions, deletions, and renames. Each commit contains
* comprehensive metadata about the changes, author information, timestamps,
* and relationships to other commits in the repository history.
*
* @example
* ```typescript
* const commit: Commit = {
* hash: "a1b2c3d4e5f6789012345678901234567890abcd",
* date: "2025-09-23T14:22:33.456Z",
* message: "Add OAuth 2.0 authentication support\n\nImplements secure authentication flow with token refresh",
* author: {
* raw: "Kurt Wolf <kurt@example.com>",
* user: {
* display_name: "Kurt Wolf",
* uuid: "{user-uuid}",
* links: {
* avatar: {
* href: "https://secure.gravatar.com/avatar/..."
* }
* }
* }
* },
* parents: [
* {
* hash: "b2c3d4e5f6789012345678901234567890abcde1",
* links: {
* self: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/commit/b2c3d4e5..."
* }
* }
* }
* ],
* repository: {
* name: "bitbucket-mcp",
* full_name: "gohcl/bitbucket-mcp",
* uuid: "{repo-uuid}"
* },
* links: {
* self: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/commit/a1b2c3d4..."
* },
* html: {
* href: "https://bitbucket.org/gohcl/bitbucket-mcp/commits/a1b2c3d4..."
* },
* diff: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/diff/a1b2c3d4..."
* },
* patch: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/patch/a1b2c3d4..."
* }
* }
* };
* ```
*/
export interface Commit {
/**
* SHA-1 hash uniquely identifying this commit.
*
* This is the 40-character hexadecimal string that uniquely identifies
* the commit across all git repositories. Used for referencing the
* commit in API calls, git operations, and links.
*/
hash: string;
/**
* ISO 8601 timestamp when the commit was created.
*
* Represents the commit date (when the commit was created) rather than
* the author date (when the changes were originally made). Includes
* timezone information for accurate temporal ordering.
*/
date: string;
/**
* Commit message describing the changes.
*
* Contains the full commit message including title and optional body.
* The first line is typically a brief summary, followed by an optional
* blank line and detailed description. May include multiple lines and
* conventional commit formatting.
*/
message: string;
/**
* Author information for the commit.
*
* Contains both the raw git author string and optional Bitbucket user
* information if the author email matches a registered account.
*/
author: {
/**
* Raw git author string from the commit.
*
* Contains the original author information as stored in git,
* typically in the format "Name <email@domain.com>". This is
* the authoritative source for author attribution.
*/
raw: string;
/**
* Optional Bitbucket user information for the author.
*
* Present only if the commit author's email address matches
* a registered Bitbucket user account. Provides additional
* context and links to the user's profile.
*/
user?: {
/** Display name of the author's Bitbucket account */
display_name: string;
/** Unique UUID identifier for the author's account */
uuid: string;
/**
* Links related to the author's account.
*/
links: {
/**
* Link to the author's avatar image.
*/
avatar: {
/** URL to the author's profile picture */
href: string;
};
};
};
};
/**
* Array of parent commits.
*
* Most commits have exactly one parent (the previous commit in the
* branch). Merge commits have multiple parents (the commits being
* merged together). The first commit in a repository has no parents.
*/
parents: Array<{
/**
* SHA-1 hash of the parent commit.
* References another commit in the repository history.
*/
hash: string;
/**
* Links related to the parent commit.
*/
links: {
/**
* API endpoint for the parent commit.
*/
self: {
/** Full URL to the parent commit's API endpoint */
href: string;
};
};
}>;
/**
* Repository information for this commit.
*
* Contains metadata about the repository where this commit exists,
* providing context for the commit within the larger codebase.
*/
repository: {
/** Repository name within the workspace */
name: string;
/** Full repository name including workspace prefix */
full_name: string;
/** Unique UUID identifier for the repository */
uuid: string;
};
/**
* Collection of related URLs and endpoints for the commit.
*
* Provides direct access to various representations and views of
* the commit data through different interfaces and formats.
*/
links: {
/**
* API endpoint for this commit.
*/
self: {
/** Full URL to this commit's API endpoint */
href: string;
};
/**
* Web interface link to the commit page.
*/
html: {
/** Full URL to the commit page in Bitbucket */
href: string;
};
/**
* API endpoint for the commit's diff.
*/
diff: {
/** Full URL to the commit's diff API endpoint */
href: string;
};
/**
* API endpoint for the commit's patch.
*/
patch: {
/** Full URL to the commit's patch API endpoint */
href: string;
};
};
/**
* Optional formatted summary of the commit message.
*
* Contains the commit message in various formats for display purposes.
* Present when the commit message contains rich formatting or when
* specifically requested through API parameters.
*/
summary?: {
/** Raw commit message as entered */
raw: string;
/** Commit message with markup processing applied */
markup: string;
/** Commit message rendered as HTML */
html: string;
/** Type of markup used in the message */
type: string;
};
}
/**
* Bitbucket commit diff entity representing file changes in a commit.
*
* A commit diff shows the specific changes made to files in a commit,
* including additions, modifications, deletions, and renames. It provides
* detailed information about what files were affected and optionally
* includes the actual diff content showing line-by-line changes.
*
* @example
* ```typescript
* const commitDiff: CommitDiff = {
* values: [
* {
* type: "modify",
* old: {
* path: "src/oauth-service.ts",
* type: "commit_file",
* links: {
* self: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/src/abc123/oauth-service.ts"
* }
* }
* },
* new: {
* path: "src/oauth-service.ts",
* type: "commit_file",
* links: {
* self: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/src/def456/oauth-service.ts"
* }
* }
* },
* diff: "@@ -1,4 +1,6 @@\n import { OAuth } from 'oauth';\n+import { TokenStorage } from './token-storage';\n..."
* },
* {
* type: "add",
* new: {
* path: "src/token-storage.ts",
* type: "commit_file",
* links: {
* self: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/src/def456/token-storage.ts"
* }
* }
* }
* }
* ],
* page: 1,
* pagelen: 10,
* size: 2
* };
* ```
*/
export interface CommitDiff {
/**
* Array of file changes in the commit.
*
* Each entry represents a single file or directory that was affected
* by the commit, with details about the type of change and the
* before/after states of the file.
*/
values: Array<{
/**
* Type of change made to the file.
*
* - 'add': File was newly created
* - 'modify': Existing file was changed
* - 'delete': File was removed
* - 'rename': File was moved or renamed
*/
type: 'add' | 'modify' | 'delete' | 'rename';
/**
* Information about the file before the change.
*
* Present for 'modify', 'delete', and 'rename' operations.
* Undefined for 'add' operations since the file didn't exist before.
*/
old?: {
/**
* File path before the change.
* Relative to the repository root.
*/
path: string;
/**
* Type of filesystem object.
* Indicates whether this is a file or directory.
*/
type: 'commit_file' | 'commit_directory';
/**
* Links related to the old file version.
*/
links: {
/**
* API endpoint for the old file content.
*/
self: {
/** Full URL to access the old file content */
href: string;
};
};
};
/**
* Information about the file after the change.
*
* Present for 'add', 'modify', and 'rename' operations.
* Undefined for 'delete' operations since the file no longer exists.
*/
new?: {
/**
* File path after the change.
* Relative to the repository root.
*/
path: string;
/**
* Type of filesystem object.
* Indicates whether this is a file or directory.
*/
type: 'commit_file' | 'commit_directory';
/**
* Links related to the new file version.
*/
links: {
/**
* API endpoint for the new file content.
*/
self: {
/** Full URL to access the new file content */
href: string;
};
};
};
/**
* Optional unified diff showing line-by-line changes.
*
* Contains the actual diff content in unified diff format,
* showing added lines (prefixed with +), removed lines (prefixed with -),
* and context lines. Only present for text files and when requested.
*/
diff?: string;
}>;
/**
* Current page number in paginated results.
*
* Used when the diff contains many files and results are paginated.
* Page numbering typically starts at 1.
*/
page?: number;
/**
* Number of items per page in paginated results.
*
* Indicates how many file changes are included in each page
* of the response. Default is usually 10 or 25.
*/
pagelen?: number;
/**
* Total number of file changes across all pages.
*
* Provides the complete count of files affected by the commit,
* useful for calculating total pages and progress indicators.
*/
size?: number;
/**
* URL for the next page of results.
*
* Only present when there are additional pages of file changes
* available. Used for pagination through large commit diffs.
*/
next?: string;
}
//# sourceMappingURL=types.d.ts.map