@cursor/bdk 0.2.1

package/src/channels/bitbucket/api.ts

@@ -0,0 +1,891 @@
+/**
+ * Bitbucket REST client for the Bitbucket channel — the `createGitLabClient`
+ * analogue, with one `BitbucketApi` facade implemented twice: Cloud 2.0
+ * (`https://api.bitbucket.org/2.0/repositories/{workspace}/{slug}/…`) and
+ * Data Center 1.0 (`<host>/rest/api/1.0/projects/{KEY}/repos/{slug}/…`).
+ * The dialect comes from the delivery payload shape, never a round trip.
+ *
+ * Two transports:
+ *
+ * - **Direct**: `Authorization: Bearer` with a repository / workspace /
+ *   HTTP access token from options or `BITBUCKET_TOKEN`. The base defaults
+ *   to `BITBUCKET_API_BASE_URL`, else api.bitbucket.org (Cloud). Data Center
+ *   deploys must configure one; `ctx.bitbucket` never derives the host from
+ *   the webhook payload — only the replay CLI passes a user-supplied repo URL.
+ * - **Proxy** (`--cursor-scm-proxy` with `cursorAccount`): the backend
+ *   forwarder at `/v0/bitbucket-proxy`. Calls carry the Cursor API key as
+ *   the bearer plus `x-cursor-bitbucket-repos` naming the repo the call is
+ *   scoped to; the backend swaps in the tenant's Bitbucket credential and
+ *   picks the upstream (Cloud 2.0 or the DC host's 1.0) per tenant.
+ */
+
+import type { BitbucketDialect, BitbucketRepositoryRef } from "./types.js";
+
+export const DEFAULT_BITBUCKET_CLOUD_API_BASE_URL = "https://api.bitbucket.org/2.0";
+
+/** Header the SCM proxy reads to scope a Bitbucket call to one repo. */
+export const CURSOR_BITBUCKET_REPOS_HEADER = "x-cursor-bitbucket-repos";
+
+export type BitbucketApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+
+/** Normalized Bitbucket REST failure — the `GitLabApiError` analogue. */
+export class BitbucketApiError extends Error {
+  readonly body: unknown;
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+
+  constructor(input: { body: unknown; method: string; path: string; status: number }) {
+    super(`Bitbucket ${input.method} ${input.path} failed with HTTP ${input.status}.`);
+    this.name = "BitbucketApiError";
+    this.body = input.body;
+    this.method = input.method;
+    this.path = input.path;
+    this.status = input.status;
+  }
+}
+
+export type BitbucketTokenProvider = () => Promise<string> | string;
+
+/** Backend SCM-proxy transport bound by the serve host in proxy mode. */
+export interface BitbucketProxyTransport {
+  /** `/v0/bitbucket-proxy` base, see `resolveCursorBitbucketProxyUrl`. */
+  apiBaseUrl: string;
+  /** Cursor API key sent as the bearer; the proxy swaps in the Bitbucket token. */
+  getApiKey: () => Promise<string>;
+  /** Static headers added to every call (repo scope when declared). */
+  headers?: Readonly<Record<string, string>>;
+}
+
+export interface BitbucketClientOptions {
+  /**
+   * REST base, e.g. `https://bitbucket.example.com/rest/api/1.0`. Falls back
+   * to `BITBUCKET_API_BASE_URL`.
+   */
+  apiBaseUrl?: string;
+  /** Access token or provider for direct calls. Falls back to `BITBUCKET_TOKEN`. */
+  token?: string | BitbucketTokenProvider;
+  /** Route through the Cursor SCM proxy instead of calling Bitbucket directly. */
+  proxy?: BitbucketProxyTransport;
+  /**
+   * Repo (`workspace/slug` or `PROJECT/slug`) every call is scoped to.
+   * Proxy mode sends it as `x-cursor-bitbucket-repos` when no static header
+   * names one.
+   */
+  repo?: string;
+  /** Injectable fetch for tests. */
+  fetch?: typeof fetch;
+}
+
+export interface BitbucketRequestInput {
+  method: BitbucketApiMethod;
+  /** Path under the API base, e.g. `/repositories/acme/widgets/pullrequests/7`. */
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  /**
+   * `Accept` header. `application/json` (default) parses the body; anything
+   * else (`text/plain` for diffs and raw files) returns the body text.
+   */
+  accept?: string;
+}
+
+/** Minimal authenticated Bitbucket REST client. */
+export interface BitbucketClient {
+  readonly apiBaseUrl: string;
+  /** Call a Bitbucket REST path. Throws {@link BitbucketApiError} on non-2xx. */
+  request<T = unknown>(input: BitbucketRequestInput): Promise<T>;
+}
+
+function envValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+
+/** `BITBUCKET_TOKEN` when set. */
+export function envBitbucketToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return envValue(env.BITBUCKET_TOKEN);
+}
+
+/**
+ * REST base for direct calls: `BITBUCKET_API_BASE_URL`, else api.bitbucket.org
+ * 2.0 for Cloud, else `/rest/api/1.0` on `repoHtmlUrl`'s origin. Callers must
+ * only pass a `repoHtmlUrl` the operator supplied (the replay CLI), never one
+ * read from a delivery payload.
+ */
+export function bitbucketApiBaseUrl(input: {
+  dialect: BitbucketDialect;
+  repoHtmlUrl?: string;
+  env?: NodeJS.ProcessEnv;
+}): string | undefined {
+  const fromEnv = envValue((input.env ?? process.env).BITBUCKET_API_BASE_URL);
+  if (fromEnv !== undefined) {
+    return fromEnv.replace(/\/+$/, "");
+  }
+  if (input.dialect === "cloud") {
+    return DEFAULT_BITBUCKET_CLOUD_API_BASE_URL;
+  }
+  if (input.repoHtmlUrl !== undefined) {
+    try {
+      return `${new URL(input.repoHtmlUrl).origin}/rest/api/1.0`;
+    } catch {
+      // no usable host
+    }
+  }
+  return undefined;
+}
+
+function buildQuery(query: BitbucketRequestInput["query"]): string {
+  if (query === undefined) {
+    return "";
+  }
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) {
+      params.set(key, String(value));
+    }
+  }
+  const encoded = params.toString();
+  return encoded === "" ? "" : `?${encoded}`;
+}
+
+export function createBitbucketClient(options: BitbucketClientOptions = {}): BitbucketClient {
+  const fetchImpl = options.fetch ?? fetch;
+  const apiBaseUrl =
+    options.proxy?.apiBaseUrl ?? options.apiBaseUrl ?? envValue(process.env.BITBUCKET_API_BASE_URL);
+  if (apiBaseUrl === undefined || apiBaseUrl.trim() === "") {
+    throw new Error(
+      "bitbucketChannel: no Bitbucket API base URL (pass apiBaseUrl, set BITBUCKET_API_BASE_URL, or serve with --cursor-scm-proxy and cursorAccount).",
+    );
+  }
+  const base = apiBaseUrl.replace(/\/+$/, "");
+  const repo = options.repo?.trim().replace(/^\/+|\/+$/g, "");
+
+  const authHeaders = async (): Promise<Record<string, string>> => {
+    if (options.proxy !== undefined) {
+      const headers: Record<string, string> = {
+        authorization: `Bearer ${await options.proxy.getApiKey()}`,
+        ...options.proxy.headers,
+      };
+      if (
+        (headers[CURSOR_BITBUCKET_REPOS_HEADER] ?? "").trim() === "" &&
+        repo !== undefined &&
+        repo !== ""
+      ) {
+        headers[CURSOR_BITBUCKET_REPOS_HEADER] = repo.toLowerCase();
+      }
+      return headers;
+    }
+    const token =
+      typeof options.token === "function"
+        ? await options.token()
+        : (options.token ?? envBitbucketToken());
+    if (token === undefined || token === "") {
+      throw new Error(
+        "bitbucketChannel: no Bitbucket credential available (pass token, set BITBUCKET_TOKEN, or serve with --cursor-scm-proxy and cursorAccount).",
+      );
+    }
+    return { authorization: `Bearer ${token}` };
+  };
+
+  return {
+    apiBaseUrl: base,
+    async request<T = unknown>(input: BitbucketRequestInput): Promise<T> {
+      const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
+      const accept = input.accept ?? "application/json";
+      const response = await fetchImpl(`${base}${path}${buildQuery(input.query)}`, {
+        method: input.method,
+        headers: {
+          ...(await authHeaders()),
+          accept,
+          ...(input.body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        body: input.body === undefined ? undefined : JSON.stringify(input.body),
+      });
+      const text = await response.text();
+      let parsed: unknown = text;
+      if (accept === "application/json") {
+        try {
+          parsed = text === "" ? undefined : JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+      }
+      if (!response.ok) {
+        throw new BitbucketApiError({
+          body: parsed,
+          method: input.method,
+          path,
+          status: response.status,
+        });
+      }
+      return parsed as T;
+    },
+  };
+}
+
+// --- BitbucketApi facade -----------------------------------------------------
+
+/** Build-status states shared by both dialects (DC `STOPPED` → `CANCELLED`). */
+export type BitbucketBuildStatusState = "INPROGRESS" | "SUCCESSFUL" | "FAILED" | "STOPPED";
+
+export interface BitbucketBuildStatusInput {
+  sha: string;
+  /** Stable key per status row (`cursor/security-review`). */
+  key: string;
+  state: BitbucketBuildStatusState;
+  /** Display name; defaults to {@link key}. */
+  name?: string;
+  /** "Details" link. Both dialects require one; falls back to the repo URL. */
+  url?: string;
+  description?: string;
+}
+
+export interface BitbucketPullRequestCommentInput {
+  body: string;
+  /**
+   * Anchor the comment to a file line. Cloud posts `inline`; Data Center
+   * posts an `anchor` on the destination side. Omit for a top-level comment.
+   */
+  inline?: { path: string; line?: number };
+}
+
+/** Comment as returned by either dialect, minimally normalized. */
+export interface BitbucketApiComment {
+  id: number;
+  body: string;
+  authorId?: string;
+  path?: string;
+  line?: number;
+  raw: unknown;
+}
+
+/** Pull request as returned by either dialect, minimally normalized. */
+export interface BitbucketApiPullRequest {
+  id: number;
+  title?: string;
+  description?: string;
+  state?: string;
+  draft?: boolean;
+  authorUsername?: string;
+  sourceBranch?: string;
+  targetBranch?: string;
+  headSha?: string;
+  baseSha?: string;
+  htmlUrl?: string;
+  raw: unknown;
+}
+
+export interface BitbucketApiChangedFile {
+  path: string;
+  previousPath?: string;
+  status: "added" | "modified" | "removed" | "renamed";
+  patch?: string;
+}
+
+export interface BitbucketPullRequestDiffInput {
+  headSha?: string;
+  baseSha?: string;
+  mergeBaseSha?: string;
+  mergeBaseResolved?: boolean;
+}
+
+/**
+ * The handful of operations review products need, implemented once per
+ * dialect. `ctx.bitbucket.api` is the repo-bound instance.
+ */
+export interface BitbucketApi {
+  readonly dialect: BitbucketDialect;
+  readonly repository: BitbucketRepositoryRef;
+  getPullRequest(id: number): Promise<BitbucketApiPullRequest>;
+  /** Unified diff of the pull request (`text/plain`). */
+  getPullRequestDiff(id: number): Promise<string>;
+  listPullRequestComments(id: number): Promise<BitbucketApiComment[]>;
+  postPullRequestComment(
+    id: number,
+    input: BitbucketPullRequestCommentInput,
+  ): Promise<BitbucketApiComment>;
+  setBuildStatus(input: BitbucketBuildStatusInput): Promise<unknown>;
+  /** Raw file contents at `ref` (branch, tag, or SHA). */
+  getFileAtRef(path: string, ref: string): Promise<string>;
+}
+
+export interface BitbucketPullRequestReadApi {
+  getPullRequest(id: number): Promise<BitbucketApiPullRequest>;
+  getMergeBaseSha(id: number, base: string, headSha: string): Promise<string | undefined>;
+  listChangedFiles(
+    id: number,
+    input?: BitbucketPullRequestDiffInput,
+  ): Promise<BitbucketApiChangedFile[]>;
+}
+
+export interface BitbucketPullRequestReadClient {
+  readonly repository: BitbucketRepositoryRef;
+  readonly api: Pick<BitbucketApi, "getPullRequest" | "getPullRequestDiff">;
+  request<T = unknown>(input: BitbucketRequestInput): Promise<T>;
+}
+
+export type BitbucketPullRequestReadDiagnostic =
+  | { kind: "commit-expansion-failed"; sha: string; error: unknown }
+  | { kind: "diff-fallback"; status: number }
+  | { kind: "metadata-fallback"; status: number };
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function errorStatus(error: unknown): number | undefined {
+  return num(asRecord(error)?.status);
+}
+
+function bitbucketAuthorUsername(raw: unknown): string | undefined {
+  const author = asRecord(asRecord(raw)?.author);
+  const user = asRecord(author?.user);
+  return (
+    str(author?.nickname) ??
+    str(user?.name) ??
+    str(user?.slug) ??
+    str(author?.display_name) ??
+    str(user?.displayName)
+  );
+}
+
+const GIT_PATH_ESCAPES: Readonly<Record<string, string>> = {
+  a: "\u0007",
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  v: "\v",
+  "\\": "\\",
+  '"': '"',
+};
+
+function unescapeGitPath(path: string, quoted: boolean): string {
+  if (!quoted) {
+    return path;
+  }
+  const bytes: number[] = [];
+  let output = "";
+  const flush = () => {
+    if (bytes.length > 0) {
+      output += Buffer.from(bytes).toString("utf8");
+      bytes.length = 0;
+    }
+  };
+  for (let index = 0; index < path.length; index += 1) {
+    const character = path[index] as string;
+    if (character !== "\\") {
+      flush();
+      output += character;
+      continue;
+    }
+    const octal = /^[0-7]{1,3}/.exec(path.slice(index + 1));
+    if (octal !== null) {
+      bytes.push(Number.parseInt(octal[0], 8));
+      index += octal[0].length;
+      continue;
+    }
+    flush();
+    const next = path[index + 1] ?? "";
+    output += GIT_PATH_ESCAPES[next] ?? next;
+    index += 1;
+  }
+  flush();
+  return output;
+}
+
+/** Split a Git-style unified diff into normalized changed files. */
+export function splitBitbucketUnifiedDiff(diff: string): BitbucketApiChangedFile[] {
+  const files: BitbucketApiChangedFile[] = [];
+  const sections = diff.split(/^(?=diff --git )/m).filter(Boolean);
+  for (const section of sections) {
+    const lines = section.replace(/\n$/, "").split("\n");
+    const header = /^diff --git ("?)a\/(.+?)\1 ("?)b\/(.+?)\3$/.exec(lines[0] ?? "");
+    if (header === null) {
+      continue;
+    }
+    const oldPath = unescapeGitPath(header[2] ?? "", header[1] !== "");
+    const newPath = unescapeGitPath(header[4] ?? "", header[3] !== "");
+    let status: BitbucketApiChangedFile["status"] = "modified";
+    let bodyStart = 1;
+    for (; bodyStart < lines.length; bodyStart += 1) {
+      const line = lines[bodyStart] ?? "";
+      if (line.startsWith("@@")) {
+        break;
+      }
+      if (line === "--- /dev/null") {
+        status = "added";
+      } else if (line === "+++ /dev/null") {
+        status = "removed";
+      }
+    }
+    if (status === "modified" && oldPath !== newPath) {
+      status = "renamed";
+    }
+    const patch = lines.slice(bodyStart).join("\n");
+    files.push({
+      path: newPath,
+      previousPath: status === "renamed" ? oldPath : undefined,
+      status,
+      patch: patch === "" ? undefined : patch,
+    });
+  }
+  return files;
+}
+
+function encodePath(path: string): string {
+  return path
+    .split("/")
+    .filter(segment => segment !== "")
+    .map(segment => encodeURIComponent(segment))
+    .join("/");
+}
+
+function fallbackUrl(repository: BitbucketRepositoryRef): string {
+  return (
+    repository.htmlUrl ??
+    (repository.dialect === "cloud"
+      ? `https://bitbucket.org/${repository.fullName}`
+      : "https://cursor.com")
+  );
+}
+
+/** `/repositories/{workspace}/{slug}` — Bitbucket Cloud 2.0. */
+export function bitbucketCloudRepoPath(repository: { owner: string; slug: string }): string {
+  return `/repositories/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.slug)}`;
+}
+
+/** `/projects/{KEY}/repos/{slug}` — Bitbucket Data Center 1.0. */
+export function bitbucketDataCenterRepoPath(repository: { owner: string; slug: string }): string {
+  return `/projects/${encodeURIComponent(repository.owner)}/repos/${encodeURIComponent(repository.slug)}`;
+}
+
+export async function expandBitbucketCloudCommitSha(
+  bitbucket: Pick<BitbucketClient, "request">,
+  repository: Pick<BitbucketRepositoryRef, "owner" | "slug">,
+  sha: string | undefined,
+  onError?: (error: unknown) => void,
+): Promise<string | undefined> {
+  if (sha === undefined || !/^[0-9a-f]{7,39}$/i.test(sha)) {
+    return sha;
+  }
+  try {
+    const commit = await bitbucket.request<{ hash?: string }>({
+      method: "GET",
+      path: `${bitbucketCloudRepoPath(repository)}/commit/${encodeURIComponent(sha)}`,
+    });
+    return /^[0-9a-f]{40}$/i.test(commit.hash ?? "") ? commit.hash : sha;
+  } catch (error) {
+    onError?.(error);
+    return sha;
+  }
+}
+
+function bitbucketPullRequestFromRaw(
+  raw: Record<string, unknown>,
+  id: number,
+  htmlUrl?: string,
+): BitbucketApiPullRequest {
+  const source = asRecord(raw.source);
+  const destination = asRecord(raw.destination);
+  return {
+    id,
+    title: str(raw.title),
+    description: str(raw.description),
+    state: str(raw.state),
+    draft: typeof raw.draft === "boolean" ? raw.draft : undefined,
+    authorUsername: bitbucketAuthorUsername(raw),
+    sourceBranch: str(asRecord(source?.branch)?.name) ?? str(asRecord(raw.fromRef)?.displayId),
+    targetBranch: str(asRecord(destination?.branch)?.name) ?? str(asRecord(raw.toRef)?.displayId),
+    headSha: str(asRecord(source?.commit)?.hash) ?? str(asRecord(raw.fromRef)?.latestCommit),
+    baseSha: str(asRecord(destination?.commit)?.hash) ?? str(asRecord(raw.toRef)?.latestCommit),
+    htmlUrl,
+    raw,
+  };
+}
+
+export function createBitbucketPullRequestReadApi(
+  bitbucket: BitbucketPullRequestReadClient,
+  options: {
+    onDiagnostic?: (diagnostic: BitbucketPullRequestReadDiagnostic) => void;
+  } = {},
+): BitbucketPullRequestReadApi {
+  const { repository } = bitbucket;
+  const repo =
+    repository.dialect === "cloud"
+      ? bitbucketCloudRepoPath(repository)
+      : bitbucketDataCenterRepoPath(repository);
+  const cloudPullRequestFromActivity = async (
+    id: number,
+  ): Promise<BitbucketApiPullRequest | undefined> => {
+    let path = `${repo}/pullrequests/${id}/activity`;
+    let query: Record<string, string | number> | undefined = { pagelen: 50 };
+    for (let page = 0; page < 20; page += 1) {
+      const response = await bitbucket.request<Record<string, unknown>>({
+        method: "GET",
+        path,
+        query,
+      });
+      for (const value of Array.isArray(response.values) ? response.values : []) {
+        const update = asRecord(asRecord(value)?.update);
+        if (update !== undefined) {
+          return bitbucketPullRequestFromRaw(update, id);
+        }
+      }
+      const next = str(response.next);
+      if (next === undefined) {
+        return undefined;
+      }
+      const nextUrl = new URL(next);
+      const marker = nextUrl.pathname.indexOf("/repositories/");
+      path = marker === -1 ? nextUrl.pathname : nextUrl.pathname.slice(marker);
+      query = Object.fromEntries(nextUrl.searchParams.entries());
+    }
+    return undefined;
+  };
+  return {
+    async getPullRequest(id) {
+      let pullRequest: BitbucketApiPullRequest;
+      try {
+        pullRequest = await bitbucket.api.getPullRequest(id);
+      } catch (error) {
+        const status = errorStatus(error);
+        if (repository.dialect !== "cloud" || status === undefined || status < 500) {
+          throw error;
+        }
+        options.onDiagnostic?.({ kind: "metadata-fallback", status });
+        const fallback = await cloudPullRequestFromActivity(id);
+        if (fallback === undefined) {
+          throw error;
+        }
+        pullRequest = fallback;
+      }
+      const normalized = {
+        ...pullRequest,
+        draft: asRecord(pullRequest.raw)?.draft === true,
+        authorUsername: bitbucketAuthorUsername(pullRequest.raw),
+      };
+      if (repository.dialect !== "cloud") {
+        return normalized;
+      }
+      const [headSha, baseSha] = await Promise.all([
+        expandBitbucketCloudCommitSha(bitbucket, repository, pullRequest.headSha, error =>
+          pullRequest.headSha === undefined
+            ? undefined
+            : options.onDiagnostic?.({
+                kind: "commit-expansion-failed",
+                sha: pullRequest.headSha,
+                error,
+              }),
+        ),
+        expandBitbucketCloudCommitSha(bitbucket, repository, pullRequest.baseSha, error =>
+          pullRequest.baseSha === undefined
+            ? undefined
+            : options.onDiagnostic?.({
+                kind: "commit-expansion-failed",
+                sha: pullRequest.baseSha,
+                error,
+              }),
+        ),
+      ]);
+      return { ...normalized, headSha, baseSha };
+    },
+    async getMergeBaseSha(id, base, headSha) {
+      if (repository.dialect === "cloud") {
+        const commit = await bitbucket.request<{ hash?: string }>({
+          method: "GET",
+          path: `${repo}/merge-base/${encodeURIComponent(headSha)}..${encodeURIComponent(base)}`,
+        });
+        return str(commit.hash);
+      }
+      const commit = await bitbucket.request<{ id?: string }>({
+        method: "GET",
+        path: `${repo}/pull-requests/${id}/merge-base`,
+      });
+      return str(commit.id);
+    },
+    async listChangedFiles(id, input) {
+      try {
+        return splitBitbucketUnifiedDiff(await bitbucket.api.getPullRequestDiff(id));
+      } catch (error) {
+        const status = errorStatus(error);
+        const comparisonBase = input?.mergeBaseSha ?? input?.baseSha;
+        if (
+          repository.dialect !== "cloud" ||
+          status === undefined ||
+          status < 500 ||
+          input?.headSha === undefined ||
+          comparisonBase === undefined
+        ) {
+          throw error;
+        }
+        options.onDiagnostic?.({ kind: "diff-fallback", status });
+        const diff = await bitbucket.request<string>({
+          method: "GET",
+          path: `${repo}/diff/${encodeURIComponent(input.headSha)}..${encodeURIComponent(comparisonBase)}`,
+          query: { topic: input.mergeBaseResolved === true ? "false" : "true" },
+          accept: "text/plain",
+        });
+        return splitBitbucketUnifiedDiff(diff);
+      }
+    },
+  };
+}
+
+export function cloudBitbucketApi(
+  client: BitbucketClient,
+  repository: BitbucketRepositoryRef,
+): BitbucketApi {
+  const repo = bitbucketCloudRepoPath(repository);
+  const mapComment = (raw: unknown): BitbucketApiComment => {
+    const record = asRecord(raw) ?? {};
+    const inline = asRecord(record.inline);
+    return {
+      id: num(record.id) ?? 0,
+      body: str(asRecord(record.content)?.raw) ?? "",
+      authorId: str(asRecord(record.user)?.uuid),
+      path: str(inline?.path),
+      line: num(inline?.to) ?? num(inline?.from),
+      raw,
+    };
+  };
+  return {
+    dialect: "cloud",
+    repository,
+    async getPullRequest(id) {
+      const raw = await client.request<Record<string, unknown>>({
+        method: "GET",
+        path: `${repo}/pullrequests/${id}`,
+      });
+      const source = asRecord(raw.source);
+      const destination = asRecord(raw.destination);
+      return {
+        id: num(raw.id) ?? id,
+        title: str(raw.title),
+        description: str(raw.description),
+        state: str(raw.state),
+        sourceBranch: str(asRecord(source?.branch)?.name),
+        targetBranch: str(asRecord(destination?.branch)?.name),
+        headSha: str(asRecord(source?.commit)?.hash),
+        baseSha: str(asRecord(destination?.commit)?.hash),
+        htmlUrl: str(asRecord(asRecord(raw.links)?.html)?.href),
+        raw,
+      };
+    },
+    getPullRequestDiff: id =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/pullrequests/${id}/diff`,
+        accept: "text/plain",
+      }),
+    async listPullRequestComments(id) {
+      const comments: BitbucketApiComment[] = [];
+      let page: string | undefined = `${repo}/pullrequests/${id}/comments`;
+      let query: Record<string, string | number> | undefined = { pagelen: 100 };
+      while (page !== undefined) {
+        const raw: Record<string, unknown> = await client.request({
+          method: "GET",
+          path: page,
+          query,
+        });
+        for (const value of Array.isArray(raw.values) ? raw.values : []) {
+          comments.push(mapComment(value));
+        }
+        const next = str(raw.next);
+        if (next === undefined) {
+          break;
+        }
+        // `next` is absolute; re-root it under the client base so the proxy
+        // (which only forwards paths) keeps working.
+        const nextUrl = new URL(next);
+        const baseUrl = new URL(`${client.apiBaseUrl}/`);
+        page = nextUrl.pathname.startsWith(baseUrl.pathname)
+          ? nextUrl.pathname.slice(baseUrl.pathname.length - 1)
+          : nextUrl.pathname;
+        query = Object.fromEntries(nextUrl.searchParams.entries());
+      }
+      return comments;
+    },
+    async postPullRequestComment(id, input) {
+      const raw = await client.request({
+        method: "POST",
+        path: `${repo}/pullrequests/${id}/comments`,
+        body: {
+          content: { raw: input.body },
+          ...(input.inline === undefined
+            ? {}
+            : {
+                inline: {
+                  path: input.inline.path,
+                  ...(input.inline.line === undefined ? {} : { to: input.inline.line }),
+                },
+              }),
+        },
+      });
+      return mapComment(raw);
+    },
+    setBuildStatus: input =>
+      client.request({
+        method: "POST",
+        path: `${repo}/commit/${encodeURIComponent(input.sha)}/statuses/build`,
+        body: {
+          key: input.key,
+          state: input.state,
+          name: input.name ?? input.key,
+          url: input.url ?? fallbackUrl(repository),
+          ...(input.description === undefined ? {} : { description: input.description }),
+        },
+      }),
+    getFileAtRef: (path, ref) =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/src/${encodeURIComponent(ref)}/${encodePath(path)}`,
+        accept: "text/plain",
+      }),
+  };
+}
+
+export function dcBitbucketApi(
+  client: BitbucketClient,
+  repository: BitbucketRepositoryRef,
+): BitbucketApi {
+  const repo = bitbucketDataCenterRepoPath(repository);
+  const mapComment = (raw: unknown): BitbucketApiComment => {
+    const record = asRecord(raw) ?? {};
+    const anchor = asRecord(record.anchor);
+    const authorId = num(asRecord(record.author)?.id);
+    return {
+      id: num(record.id) ?? 0,
+      body: str(record.text) ?? "",
+      authorId: authorId === undefined ? undefined : String(authorId),
+      path: str(anchor?.path),
+      line: num(anchor?.line),
+      raw,
+    };
+  };
+  return {
+    dialect: "data-center",
+    repository,
+    async getPullRequest(id) {
+      const raw = await client.request<Record<string, unknown>>({
+        method: "GET",
+        path: `${repo}/pull-requests/${id}`,
+      });
+      const fromRef = asRecord(raw.fromRef);
+      const toRef = asRecord(raw.toRef);
+      const self = asRecord(raw.links)?.self;
+      return {
+        id: num(raw.id) ?? id,
+        title: str(raw.title),
+        description: str(raw.description),
+        state: str(raw.state),
+        sourceBranch: str(fromRef?.displayId),
+        targetBranch: str(toRef?.displayId),
+        headSha: str(fromRef?.latestCommit),
+        baseSha: str(toRef?.latestCommit),
+        htmlUrl: Array.isArray(self) ? str(asRecord(self[0])?.href) : undefined,
+        raw,
+      };
+    },
+    // `/pull-requests/{id}.diff` streams the raw unified diff; the sibling
+    // `/pull-requests/{id}/diff` route returns a JSON `RestDiff` instead.
+    getPullRequestDiff: id =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/pull-requests/${id}.diff`,
+        accept: "text/plain",
+      }),
+    async listPullRequestComments(id) {
+      const comments: BitbucketApiComment[] = [];
+      let start = 0;
+      for (;;) {
+        const raw = await client.request<Record<string, unknown>>({
+          method: "GET",
+          path: `${repo}/pull-requests/${id}/activities`,
+          query: { limit: 100, start },
+        });
+        for (const value of Array.isArray(raw.values) ? raw.values : []) {
+          const activity = asRecord(value);
+          if (activity?.action === "COMMENTED" && activity.comment !== undefined) {
+            comments.push(mapComment(activity.comment));
+          }
+        }
+        const nextStart = num(raw.nextPageStart);
+        if (raw.isLastPage !== false || nextStart === undefined) {
+          break;
+        }
+        start = nextStart;
+      }
+      return comments;
+    },
+    async postPullRequestComment(id, input) {
+      const raw = await client.request({
+        method: "POST",
+        path: `${repo}/pull-requests/${id}/comments`,
+        body: {
+          text: input.body,
+          ...(input.inline === undefined
+            ? {}
+            : {
+                anchor: {
+                  path: input.inline.path,
+                  diffType: "EFFECTIVE",
+                  ...(input.inline.line === undefined
+                    ? { fileType: "TO" }
+                    : {
+                        line: input.inline.line,
+                        lineType: "CONTEXT",
+                        fileType: "TO",
+                      }),
+                },
+              }),
+        },
+      });
+      return mapComment(raw);
+    },
+    // Repository-scoped build status (DC 7.14+), which lives under
+    // `rest/api/1.0` so the proxy's single upstream base reaches it; the
+    // older `rest/build-status/1.0/commits/{sha}` sits outside that base.
+    setBuildStatus: input =>
+      client.request({
+        method: "POST",
+        path: `${repo}/commits/${encodeURIComponent(input.sha)}/builds`,
+        body: {
+          key: input.key,
+          state: input.state === "STOPPED" ? "CANCELLED" : input.state,
+          name: input.name ?? input.key,
+          url: input.url ?? fallbackUrl(repository),
+          ...(input.description === undefined ? {} : { description: input.description }),
+        },
+      }),
+    getFileAtRef: (path, ref) =>
+      client.request<string>({
+        method: "GET",
+        path: `${repo}/raw/${encodePath(path)}`,
+        query: { at: ref },
+        accept: "text/plain",
+      }),
+  };
+}
+
+/** Pick the dialect implementation for `repository.dialect`. */
+export function createBitbucketApi(
+  client: BitbucketClient,
+  repository: BitbucketRepositoryRef,
+): BitbucketApi {
+  return repository.dialect === "cloud"
+    ? cloudBitbucketApi(client, repository)
+    : dcBitbucketApi(client, repository);
+}