import type { PaginatedResponse, RestLinks, RestPath } from './common.js'; import type { RestRepository, RestRepositoryWithProject } from './repository.js'; import type { RestUser } from './user.js'; /** * Pull request state values from Bitbucket Server. */ export type PullRequestState = 'OPEN' | 'MERGED' | 'DECLINED'; /** * Change type for file changes in pull requests. */ export type ChangeType = 'ADD' | 'COPY' | 'DELETE' | 'MODIFY' | 'MOVE' | 'UNKNOWN'; /** * Diff type values. */ export type DiffType = 'COMMIT' | 'EFFECTIVE' | 'RANGE'; /** * File side in diff (FROM = source, TO = destination). */ export type FileType = 'FROM' | 'TO'; /** * Line type in diff segments. */ export type LineType = 'ADDED' | 'CONTEXT' | 'REMOVED'; /** * Whitespace handling for diff endpoints. */ export type WhitespaceHandling = 'show' | 'ignore-all'; /** * Response format for diff endpoints. */ export type DiffResponseFormat = 'text' | 'json'; /** * Repository visibility filter. */ export type RepoVisibility = 'public' | 'private'; /** * Repository archive-state filter. */ export type RepoArchiveState = 'ACTIVE' | 'ARCHIVED' | 'ALL'; /** * Activity action types from Bitbucket Server. */ export type ActivityAction = 'APPROVED' | 'AUTO_MERGE_CANCELLED' | 'AUTO_MERGE_REQUESTED' | 'COMMENTED' | 'DECLINED' | 'DELETED' | 'MERGED' | 'OPENED' | 'REOPENED' | 'RESCOPED' | 'REVIEW_COMMENTED' | 'REVIEW_DISCARDED' | 'REVIEW_FINISHED' | 'REVIEWED' | 'UNAPPROVED' | 'UPDATED'; /** * Participant role in a pull request. */ export type ParticipantRole = 'AUTHOR' | 'REVIEWER' | 'PARTICIPANT'; /** * Participant status in a pull request (review status). */ export type ParticipantStatus = 'UNAPPROVED' | 'NEEDS_WORK' | 'APPROVED'; /** * Minimal ref for branch references (RestMinimalRef schema from Swagger). */ export interface RestMinimalRef { /** Display ID (e.g., "main") */ displayId: string; /** Ref ID (e.g., "refs/heads/main") */ id: string; /** Latest commit hash */ latestCommit?: string; /** Repository this ref belongs to */ repository?: RestRepository; } /** * Minimal ref with required repository and project (for inbox PRs). */ export interface RestMinimalRefWithRepository extends Omit { /** Repository with project (required for inbox PRs) */ repository: RestRepositoryWithProject; } /** * Comment anchor - specifies where a comment is attached (RestCommentAnchor schema from Swagger). */ export interface RestCommentAnchor { /** Diff type */ diffType?: DiffType; /** File side (FROM/TO) */ fileType?: FileType; /** Line number */ line?: number; /** Line type */ lineType?: LineType; /** Whether this is an orphaned comment */ orphaned?: boolean; /** File path */ path?: RestPath | string; /** Source path (for moves) */ srcPath?: RestPath | string; } /** * Bitbucket Server comment object (RestComment schema from Swagger). * Represents the raw API response structure. */ export interface RestComment { /** Comment ID */ id: number; /** Comment text */ text: string; /** Comment author */ author: RestUser; /** Creation timestamp */ createdDate: number; /** Last update timestamp */ updatedDate?: number; /** Version number */ version: number; /** Nested replies */ comments?: RestComment[]; /** Comment anchor (file/line location) */ anchor?: RestCommentAnchor; /** Permitted operations */ permittedOperations?: unknown; /** Comment properties (reactions, likes) */ properties?: { /** Reactions with full user arrays */ reactions?: { emoticon: string; users?: unknown[]; }[]; /** Like information */ likedBy?: { total?: number; }; }; /** Parent comment (for replies) */ parent?: { id: number; }; } /** * Comment object as returned by Bitbucket API. * Alias for RestComment since base type now matches full API response. */ export type RestCommentApiResponse = RestComment; /** * Request body for adding a comment to a pull request. */ export interface AddCommentBody { /** Comment text */ text: string; /** Parent comment ID for replies */ parent?: { id: number; }; /** Comment anchor for file/line comments */ anchor?: { path: string; diffType: DiffType; line?: number; lineType?: LineType; fileType?: FileType; }; } /** * Supported emoticon identifiers for comment reactions (via the comment-likes * plugin API). These are the only values Bitbucket Server accepts on the * reaction endpoint. */ export type BitbucketEmoticon = 'thumbsup' | 'thumbsdown' | 'heart' | 'thinking_face' | 'laughing'; /** * Emoticon object from Bitbucket Server (RestEmoticon schema from Swagger). * Represents an emoticon reaction that can be added to comments. */ export interface RestEmoticon { /** Emoticon shortcut (e.g., "thumbsup") */ shortcut: string; /** URL to the emoticon image/SVG */ url: string; /** Emoticon value/identifier (optional) */ value?: string; } /** * User reaction to a comment (RestUserReaction schema from Swagger). * Returned when adding a reaction to a comment. */ export interface RestUserReaction { /** The comment that was reacted to */ comment: RestComment; /** The emoticon that was added */ emoticon: RestEmoticon; /** The user who reacted */ user: RestUser; } /** * Pull request participant (RestPullRequestParticipant schema from Swagger). * Represents a user's participation in a pull request with their role and review status. */ export interface RestPullRequestParticipant { /** User information */ user: RestUser; /** Participant role */ role?: ParticipantRole; /** Whether the participant approved the PR */ approved?: boolean; /** Review status */ status?: ParticipantStatus; /** Last commit hash reviewed by this participant */ lastReviewedCommit?: string; } /** * Full pull request object (RestPullRequest schema from Swagger). * Includes all fields for reference, but most tools use MinimalPullRequest. */ export interface RestPullRequest { /** Pull request ID */ id: number; /** Pull request version */ version: number; /** Pull request title */ title: string; /** Pull request description */ description?: string; /** Pull request state */ state: PullRequestState; /** Whether PR is open */ open: boolean; /** Whether PR is closed */ closed: boolean; /** Creation timestamp */ createdDate: number; /** Last update timestamp */ updatedDate: number; /** Source branch ref */ fromRef: RestMinimalRef; /** Target branch ref */ toRef: RestMinimalRef; /** Whether PR is locked */ locked?: boolean; /** Pull request author */ author?: { user: RestUser; role: string; approved: boolean; status: string; }; /** Pull request reviewers */ reviewers?: { user: RestUser; role: string; approved: boolean; status: string; }[]; /** Pull request participants */ participants?: { user: RestUser; role: string; approved: boolean; status: string; }[]; /** Links */ links?: RestLinks; } /** * Pull request from inbox endpoint (author and toRef.repository are required). */ export interface InboxPullRequest extends Omit { /** Pull request author (required for inbox PRs) */ author: { user: RestUser; role: string; approved: boolean; status: string; }; /** Target branch ref with required repository */ toRef: RestMinimalRefWithRepository; } /** * Request body for creating a pull request. * Matches the Bitbucket Server API structure for POST /pull-requests. */ export interface CreatePullRequestBody { /** Pull request title */ title: string; /** Pull request description */ description?: string; /** Source branch reference */ fromRef: { /** Full ref ID (e.g., "refs/heads/feature-branch") */ id: string; /** Repository (required for cross-repo PRs) */ repository?: { /** Repository slug */ slug: string; /** Project */ project: { /** Project key */ key: string; }; }; }; /** Target branch reference */ toRef: { /** Full ref ID (e.g., "refs/heads/main") */ id: string; }; /** Reviewers to assign to the PR */ reviewers?: { /** User information */ user: { /** Username */ name: string; }; }[]; /** Whether this is a draft PR */ draft?: boolean; } /** * File change in a pull request (RestChange schema from Swagger). */ export interface RestChange { /** Content ID for the file */ contentId?: string; /** Source content ID (for moves/copies) */ srcContentId?: string; /** Whether executable bit changed */ executable?: boolean; /** Percentage similarity (for moves/copies) */ percentUnchanged?: number; /** Change type */ type: ChangeType; /** Node type */ nodeType?: string; /** Source path (for moves) */ srcPath?: RestPath; /** Destination path */ path?: RestPath; /** Whether file is a link */ link?: boolean; /** Number of comments on this file */ comments?: number; } /** * Response type for pull request changes endpoint. */ export type ChangesResponse = PaginatedResponse; /** * Line in a diff (RestDiffLine schema from Swagger). */ export interface RestDiffLine { /** Source (FROM) line number */ source?: number; /** Destination (TO) line number */ destination?: number; /** Line content */ line?: string; /** Whether line is truncated */ truncated?: boolean; /** Inline comments on this line */ commentIds?: number[]; /** Whether line has conflicts */ conflictMarker?: string; } /** * Segment in a diff hunk (RestDiffSegment schema from Swagger). */ export interface RestDiffSegment { /** Segment type */ type: LineType; /** Lines in this segment */ lines: RestDiffLine[]; /** Whether segment is truncated */ truncated?: boolean; } /** * Hunk in a diff (RestDiffHunk schema from Swagger). */ export interface RestDiffHunk { /** Source (FROM) line number */ sourceLine: number; /** Source span */ sourceSpan: number; /** Destination (TO) line number */ destinationLine: number; /** Destination span */ destinationSpan: number; /** Segments in this hunk */ segments: RestDiffSegment[]; /** Whether hunk is truncated */ truncated?: boolean; /** Context lines */ context?: string; } /** * Diff for a file (RestDiff schema from Swagger). */ export interface RestDiff { /** Source path */ source?: RestPath | null; /** Destination path */ destination?: RestPath | null; /** Hunks in this diff */ hunks?: RestDiffHunk[]; /** Whether diff is truncated */ truncated?: boolean; /** Source properties */ properties?: { fromHash?: string; }; /** Destination properties */ toHash?: string; /** Whether file is binary */ binary?: boolean; /** Line comments */ lineComments?: RestComment[]; /** File comments */ fileComments?: RestComment[]; } /** * Response type for pull request file diff endpoint. */ export interface DiffResponse { /** Diff data */ diffs: RestDiff[]; /** Source commit hash */ fromHash?: string; /** Destination commit hash */ toHash?: string; /** Context lines setting */ contextLines?: number; /** Whitespace setting */ whitespace?: string; } /** * Commit person object (author or committer) from Bitbucket Server API. * Part of RestCommit schema from Swagger. */ export interface RestCommitPerson { /** Person's full name */ name: string; /** Person's email address */ emailAddress?: string; /** Avatar URL (writeOnly in Swagger, included for completeness) */ avatarUrl?: string; } /** * Minimal commit reference (RestMinimalCommit schema from Swagger). * Used in parent commit references. */ export interface RestMinimalCommit { /** Commit hash */ id: string; /** Short commit hash (first 11 chars) */ displayId: string; } /** * Complete commit object (RestCommit schema from Swagger). * Used in RESCOPED activity's added/removed commits arrays. */ export interface RestCommit { /** Commit hash */ id: string; /** Short commit hash (first 11 chars) */ displayId: string; /** Commit author information */ author: RestCommitPerson; /** Timestamp when commit was authored */ authorTimestamp: number; /** Commit committer information */ committer: RestCommitPerson; /** Timestamp when commit was committed */ committerTimestamp: number; /** Commit message */ message: string; /** Parent commits */ parents: RestMinimalCommit[]; } /** * Pull request activity (RestPullRequestActivity schema from Swagger). * Base activity structure without diff field (diff is in RestPullRequestActivityApiResponse). */ export interface RestPullRequestActivity { /** Activity ID */ id: number; /** Creation timestamp */ createdDate: number; /** User who performed the action */ user: RestUser; /** Activity action type */ action: ActivityAction; /** Comment (for comment activities) */ comment?: RestComment; /** Comment action (for comment activities) */ commentAction?: string; /** Comment anchor (location in code where comment was made) */ commentAnchor?: RestCommentAnchor; /** Commit ID (for commit activities) */ commit?: { id: string; displayId: string; }; /** Added reviewers (for reviewer change activities) */ addedReviewers?: RestUser[]; /** Removed reviewers (for reviewer change activities) */ removedReviewers?: RestUser[]; /** Added commits (for RESCOPED activities) */ added?: { commits?: RestCommit[]; }; /** Removed commits (for RESCOPED activities) */ removed?: { commits?: RestCommit[]; }; } /** * Response type for pull request activities endpoint. */ export type ActivitiesResponse = PaginatedResponse; /** * Pull request activity as returned by Bitbucket API. * Includes diff field and full user/comment structures. */ export interface RestPullRequestActivityApiResponse extends Omit { /** User with links */ user: RestUser; /** Comment with API structure */ comment?: RestCommentApiResponse; /** Diff field (contains code changes context) */ diff?: unknown; } /** * Options for {@link diffPullRequestActivities}. */ export interface ActivityDiffOptions { /** * Cutoff timestamp. Items strictly newer than `since` are considered new. * If omitted, every item in `activities` is treated as new (useful for * first-look bootstrap). */ since?: Date; } /** * A new top-level comment or a reply, in flat form. * * `parentId` is `undefined` for the top-level comment of a COMMENTED activity * and populated for every nested reply (with the immediate parent's id). * * `rootCommentId` is `undefined` for top-level comments (they are the root) and * populated for every reply at any depth with the id of the thread's top-level * comment. Bitbucket DC has no upward link on a comment record — given only a * leaf reply id, you cannot discover its parent — so the helper surfaces the * thread root as a navigable handle. A consumer that wants full thread context * (root + every reply in the subtree) calls * `client.pullRequests.getComment({ commentId: rootCommentId })`, which returns * the comment plus its entire descendant tree. * * `anchor` carries the file/line location for inline comments. Bitbucket stores * the anchor on the activity (not on the comment) for top-level comments, but * exposes a per-comment `anchor` on nested replies. We inherit the activity-level * anchor down to every reply in the tree so consumers can render * "alex replied on src/foo.ts:42" without correlating to the parent thread. */ export interface NewPullRequestComment { id: number; text: string; /** Epoch milliseconds — same units Bitbucket returns. */ createdAt: number; author: RestUser; parentId?: number; rootCommentId?: number; anchor?: RestCommentAnchor; } /** * A new commit pushed to the source branch (extracted from a RESCOPED activity's * `added.commits`). Times are epoch milliseconds. */ export interface NewPullRequestCommit { id: string; displayId: string; message: string; authoredAt: number; author: RestCommitPerson; } /** * Result of a `diffPullRequestActivities` call. * * - `newComments` includes both new top-level comments and new replies on * existing comment threads (Bitbucket DC does not mint a new top-level * activity when someone replies, so naively filtering activities by * `createdDate` misses replies — this is the bug this helper solves). * Reply entries carry `rootCommentId` so consumers can fetch the whole * thread on demand via `client.pullRequests.getComment(...)`. * - `newCommits` is flattened across every RESCOPED activity's `added.commits`. * - `otherActivities` contains the raw activities for everything that isn't * COMMENTED/REVIEW_COMMENTED/RESCOPED (MERGED, DECLINED, OPENED, APPROVED, * REVIEWED, …) — surfaced as-is so the caller can format them however it * needs. * - `latestActivityAt` is the max timestamp observed across the entire walk * (top-level activities, every comment in the tree, every commit) regardless * of `since`. Use it as the next bookmark; if `activities` is empty it is * `undefined`. * - `hasNewActivity` is `true` iff at least one of the three arrays is non-empty. * * Notes: * - The helper does **not** filter by author. Callers that want to ignore an * agent's own activity should filter `newComments` / `newCommits` / * `otherActivities` themselves. * - Comment edits are not detected. Bitbucket exposes `updatedDate` on a comment * but doesn't change `createdDate`; the helper bookmarks on creation only. */ export interface PullRequestActivityDiff { newComments: NewPullRequestComment[]; newCommits: NewPullRequestCommit[]; otherActivities: RestPullRequestActivityApiResponse[]; latestActivityAt: Date | undefined; hasNewActivity: boolean; } /** * Parameters for getInboxPullRequests method */ export interface GetInboxPullRequestsParams { /** Starting index for pagination (default: 0) */ start?: number; /** Maximum number of pull requests to return (default: 25) */ limit?: number; } /** * Parameters for getDashboardPullRequests method. */ export interface GetDashboardPullRequestsParams { /** Filter by role: AUTHOR, REVIEWER, or PARTICIPANT */ role?: 'AUTHOR' | 'REVIEWER' | 'PARTICIPANT'; /** Filter by state: OPEN, DECLINED, or MERGED */ state?: 'OPEN' | 'DECLINED' | 'MERGED'; /** Filter by participant status (comma-separated): UNAPPROVED, NEEDS_WORK, APPROVED */ participantStatus?: string; /** Sort order: OLDEST, NEWEST, DRAFT_STATUS, PARTICIPANT_STATUS, CLOSED_DATE */ order?: 'OLDEST' | 'NEWEST' | 'DRAFT_STATUS' | 'PARTICIPANT_STATUS' | 'CLOSED_DATE'; /** Only return PRs closed within N seconds */ closedSince?: number; /** Specify a different user (defaults to authenticated user) */ user?: string; /** Starting index for pagination */ start?: number; /** Number of results to return */ limit?: number; } /** * Parameters for getting pull request details. */ export interface GetPullRequestParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; } /** * Parameters for createPullRequest method */ export interface CreatePullRequestParams { /** The Bitbucket project key (for the target repository) */ projectKey: string; /** The repository slug (target repository) */ repositorySlug: string; /** Pull request title */ title: string; /** Pull request description (optional) */ description?: string; /** Source branch name (e.g., "feature-branch" or "refs/heads/feature-branch") */ fromBranch: string; /** Target branch name (e.g., "main" or "refs/heads/main") */ toBranch: string; /** Source repository slug (for cross-repo PRs, defaults to repositorySlug) */ fromRepositorySlug?: string; /** Source project key (for cross-repo PRs, defaults to projectKey) */ fromProjectKey?: string; /** Array of usernames to assign as reviewers */ reviewers?: string[]; /** Whether to create as a draft PR */ draft?: boolean; } /** * Parameters for getPullRequestChanges method */ export interface GetPullRequestChangesParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** Number of items to return (default: 25, note: endpoint is not paged) */ limit?: number; } /** * Parameters for getting pull request diff. */ export interface GetPullRequestDiffParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** Path to file (optional - empty for full PR diff) */ path?: string; /** The since commit hash to get diff from a specific commit */ sinceId?: string; /** The until commit hash to get diff up to a specific commit */ untilId?: string; /** Number of context lines around changes (default: 10) */ contextLines?: number; /** Whitespace handling: 'show' or 'ignore-all' */ whitespace?: WhitespaceHandling; /** Response format: 'text' for raw diff, 'json' for structured (default: 'text') */ format?: DiffResponseFormat; } /** * Parameters for getPullRequestActivities method */ export interface GetPullRequestActivitiesParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** Filter activities by type (e.g., ["COMMENTED", "REVIEW_COMMENTED"]) */ activityTypes?: string[]; /** Starting index for pagination (default: 0) */ start?: number; /** Maximum number of items to return (default: 25) */ limit?: number; } /** * Parameters for addPullRequestComment method */ export interface AddPullRequestCommentParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** The comment text */ text: string; /** Parent comment ID for replies */ parentId?: number; /** File path for file-specific comments */ path?: string; /** Line number for inline comments */ line?: number; /** Type of line (default: CONTEXT) */ lineType?: LineType; /** Side of diff (default: TO) */ fileType?: FileType; } /** * Parameters for deleting a pull request comment. */ export interface DeletePullRequestCommentParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** The comment ID to delete */ commentId: number; /** The expected version of the comment (prevents concurrent modification conflicts) */ version: number; } /** * Parameters for editPullRequestComment method. * Edits the text of an existing comment on a pull request. */ export interface EditPullRequestCommentParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** The comment ID to edit */ commentId: number; /** The new comment text */ text: string; /** The expected version of the comment (for optimistic locking) */ version: number; } /** * Parameters for updateReviewStatus method */ export interface UpdateReviewStatusParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** The review status: APPROVED (approve), NEEDS_WORK (request changes), or UNAPPROVED (neutral/remove approval) */ status: ParticipantStatus; } /** * Parameters for addPullRequestCommentReaction method */ export interface AddPullRequestCommentReactionParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** The comment ID */ commentId: number; /** The emoticon identifier (thumbsup, thumbsdown, heart, thinking_face, laughing) */ emoticon: BitbucketEmoticon; } /** * Parameters for removePullRequestCommentReaction method */ export interface RemovePullRequestCommentReactionParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** The comment ID */ commentId: number; /** The emoticon identifier to remove */ emoticon: BitbucketEmoticon; } /** * Parameters for updatePullRequest method. * Updates the title and/or description of a pull request. */ export interface UpdatePullRequestParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** New title (optional — keeps current if not provided) */ title?: string; /** New description (optional — keeps current if not provided) */ description?: string; /** New target branch, e.g. "main" or "refs/heads/main" (optional — keeps current if not provided) */ toBranch?: string; } /** * Parameters for declinePullRequest method. */ export interface DeclinePullRequestParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; } /** * Parameters for mergePullRequest method. */ export interface MergePullRequestParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; /** Merge strategy (e.g., 'squash', 'no-ff', 'ff', 'ff-only', 'rebase-no-ff', 'rebase-ff-only') */ strategyId?: string; /** Custom merge commit message */ message?: string; } /** * Parameters for canMergePullRequest method. */ export interface CanMergePullRequestParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; } /** * Result of a merge check (canMerge endpoint). */ export interface MergeCheckResult { /** Whether the PR can be merged */ canMerge: boolean; /** Whether the PR has conflicts */ conflicted?: boolean; /** Vetoes preventing merge */ vetoes?: { /** Summary of the veto reason */ summaryMessage: string; /** Detailed veto message */ detailedMessage: string; }[]; } /** * Parameters for deletePullRequest method. */ export interface DeletePullRequestParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** The pull request ID */ pullRequestId: number; } /** * Parameters for getRequiredReviewers method. * Gets the list of users who are required/default reviewers for a PR from a source to target branch. */ export interface GetRequiredReviewersParams { /** The Bitbucket project key */ projectKey: string; /** The repository slug */ repositorySlug: string; /** Repository ID - use getRepository() to obtain this */ repositoryId: number; /** Source branch name (e.g., "feature-branch" or "refs/heads/feature-branch") */ sourceBranch: string; /** Target branch name (e.g., "main" or "refs/heads/main") */ targetBranch: string; } //# sourceMappingURL=pull-request.d.ts.map