@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/github/api.ts

@@ -1,526 +0,0 @@
-/**
- * GitHub REST helpers backed by `@octokit/rest`.
- *
- * Channel hooks should prefer `ctx.github` / `ctx.thread`. Use
- * {@link createGitHubOctokit} (or `ctx.github.getOctokit()`) when you need
- * typed Octokit methods directly.
- */
-
-import { createAppAuth } from "@octokit/auth-app";
-import { Octokit } from "@octokit/rest";
-import {
-  type GitHubAuthApiOptions,
-  hasGitHubAppCredentials,
-  resolveCredentialValue,
-  resolveGitHubAccessToken,
-  resolveGitHubAppId,
-  resolveGitHubInstallationId,
-  resolveGitHubPrivateKey,
-} from "./auth.js";
-import {
-  type CursorAccountGithubTokenResolver,
-  getCursorAccountGithubProxyTransport,
-  githubRepoFromOctokitRequest,
-  isCursorAccountGithubTokenResolver,
-} from "./cursor-account.js";
-import type { GitHubChannelCredentials } from "./types.js";
-
-export type GitHubJsonObject = Record<string, unknown>;
-export type GitHubApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
-
-export interface GitHubApiOptions extends GitHubAuthApiOptions {}
-
-export interface GitHubApiResponse<T = unknown> {
-  body: T;
-  ok: boolean;
-  status: number;
-}
-
-export class GitHubApiError 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(`GitHub ${input.method} ${input.path} failed with HTTP ${input.status}.`);
-    this.name = "GitHubApiError";
-    this.body = input.body;
-    this.method = input.method;
-    this.path = input.path;
-    this.status = input.status;
-  }
-}
-
-export interface GitHubPostedComment {
-  htmlUrl: string | undefined;
-  id: number;
-  raw: unknown;
-  url: string | undefined;
-}
-
-export type GitHubReactionContent =
-  | "+1"
-  | "-1"
-  | "confused"
-  | "eyes"
-  | "heart"
-  | "hooray"
-  | "laugh"
-  | "rocket";
-
-interface GitHubResourceInput {
-  api?: GitHubApiOptions;
-  credentials?: GitHubChannelCredentials;
-  installationId?: number;
-  owner: string;
-  repo: string;
-}
-
-/**
- * Build an authenticated Octokit client.
- *
- * Prefer explicit bearer tokens, then GitHub App installation auth (when App
- * credentials + an installation id are available), then local PAT /
- * `gh auth token`. App auth uses `@octokit/auth-app` so Octokit refreshes
- * installation tokens itself.
- */
-export async function createGitHubOctokit(input: {
-  api?: GitHubApiOptions;
-  credentials?: GitHubChannelCredentials;
-  installationId?: number;
-}): Promise<Octokit> {
-  const transport = githubOctokitTransport(input.api);
-
-  const dynamicToken: CursorAccountGithubTokenResolver | undefined =
-    isCursorAccountGithubTokenResolver(input.credentials?.token)
-      ? input.credentials.token
-      : isCursorAccountGithubTokenResolver(input.credentials?.installationToken)
-        ? input.credentials.installationToken
-        : undefined;
-  if (dynamicToken !== undefined) {
-    // Host-bound backend proxy: target the forwarder and attach the repo
-    // scope headers; the resolved token is the Cursor API key, not a raw
-    // GitHub credential. Authored `api.apiBaseUrl` still wins (test seam).
-    const proxyTransport = getCursorAccountGithubProxyTransport(dynamicToken);
-    const octokit = new Octokit({
-      ...transport,
-      baseUrl: transport.baseUrl ?? proxyTransport?.apiBaseUrl,
-    });
-    octokit.hook.before("request", async request => {
-      const token = await resolveCredentialValue(dynamicToken);
-      if (token === undefined) {
-        throw new Error("githubChannel: dynamic GitHub token is unavailable.");
-      }
-      request.headers.authorization = `Bearer ${token}`;
-      if (proxyTransport !== undefined) {
-        Object.assign(request.headers, proxyTransport.headers);
-        const existingRepos = request.headers["x-cursor-github-repos"];
-        if (typeof existingRepos !== "string" || existingRepos.trim() === "") {
-          const repo = githubRepoFromOctokitRequest(request);
-          if (repo !== undefined) {
-            request.headers["x-cursor-github-repos"] = repo;
-          }
-        }
-      }
-    });
-    return octokit;
-  }
-
-  const explicit =
-    (await resolveCredentialValue(input.credentials?.token)) ??
-    (await resolveCredentialValue(input.credentials?.installationToken));
-  if (explicit !== undefined) {
-    return new Octokit({ ...transport, auth: explicit });
-  }
-
-  const installationId = await resolveGitHubInstallationId(input.installationId);
-  if (installationId !== undefined && (await hasGitHubAppCredentials(input.credentials))) {
-    const appId = await resolveGitHubAppId(input.credentials?.appId);
-    const privateKey = await resolveGitHubPrivateKey(input.credentials?.privateKey);
-    return new Octokit({
-      ...transport,
-      authStrategy: createAppAuth,
-      auth: {
-        appId,
-        privateKey,
-        installationId,
-      },
-    });
-  }
-
-  // Local testing: ambient PAT / `gh auth token` when App creds are unset.
-  return new Octokit({
-    ...transport,
-    auth: await resolveGitHubAccessToken(input),
-  });
-}
-
-/** Shared `baseUrl` / custom `fetch` for every Octokit constructed here. */
-function githubOctokitTransport(api: GitHubApiOptions | undefined): {
-  baseUrl?: string;
-  request?: { fetch: typeof fetch };
-} {
-  return {
-    baseUrl: api?.apiBaseUrl,
-    request: api?.fetch === undefined ? undefined : { fetch: api.fetch },
-  };
-}
-
-/**
- * Call a GitHub REST path with channel auth. Prefer typed Octokit methods via
- * {@link createGitHubOctokit} / `ctx.github.getOctokit()` when possible.
- */
-export async function callGitHubApi<T = unknown>(input: {
-  api?: GitHubApiOptions;
-  body?: GitHubJsonObject;
-  credentials?: GitHubChannelCredentials;
-  installationId?: number;
-  method: GitHubApiMethod;
-  path: string;
-  options?: { auth?: boolean; headers?: Readonly<Record<string, string>> };
-}): Promise<GitHubApiResponse<T>> {
-  if (input.options?.auth === false) {
-    return requestWithOctokit(new Octokit(githubOctokitTransport(input.api)), input);
-  }
-
-  const octokit = await createGitHubOctokit({
-    api: input.api,
-    credentials: input.credentials,
-    installationId: input.installationId,
-  });
-  return requestWithOctokit(octokit, input);
-}
-
-async function requestWithOctokit<T>(
-  octokit: Octokit,
-  input: {
-    body?: GitHubJsonObject;
-    method: GitHubApiMethod;
-    path: string;
-    options?: { headers?: Readonly<Record<string, string>> };
-  },
-): Promise<GitHubApiResponse<T>> {
-  try {
-    const route = `${input.method} ${normalizeRequestPath(input.path)}`;
-    const response = await octokit.request(route, {
-      ...(input.body ?? {}),
-      ...(input.options?.headers === undefined ? {} : { headers: input.options.headers }),
-    });
-    return {
-      body: response.data as T,
-      ok: true,
-      status: response.status,
-    };
-  } catch (error) {
-    if (isOctokitRequestError(error)) {
-      throw new GitHubApiError({
-        body: error.response?.data,
-        method: input.method,
-        path: input.path,
-        status: error.status,
-      });
-    }
-    throw error;
-  }
-}
-
-/** Create an issue or PR timeline comment. */
-export async function createGitHubIssueComment(
-  input: GitHubResourceInput & { body: string; issueNumber: number },
-): Promise<GitHubPostedComment> {
-  const octokit = await createGitHubOctokit(input);
-  try {
-    const response = await octokit.rest.issues.createComment({
-      owner: input.owner,
-      repo: input.repo,
-      issue_number: input.issueNumber,
-      body: input.body,
-    });
-    return toPostedComment(response.data);
-  } catch (error) {
-    throw wrapOctokitError(
-      error,
-      "POST",
-      `/repos/${input.owner}/${input.repo}/issues/${input.issueNumber}/comments`,
-    );
-  }
-}
-
-/** Update an issue or PR timeline comment by id. */
-export async function updateGitHubIssueComment(
-  input: GitHubResourceInput & { body: string; commentId: number },
-): Promise<GitHubPostedComment> {
-  const octokit = await createGitHubOctokit(input);
-  try {
-    const response = await octokit.rest.issues.updateComment({
-      owner: input.owner,
-      repo: input.repo,
-      comment_id: input.commentId,
-      body: input.body,
-    });
-    return toPostedComment(response.data);
-  } catch (error) {
-    throw wrapOctokitError(
-      error,
-      "PATCH",
-      `/repos/${input.owner}/${input.repo}/issues/comments/${input.commentId}`,
-    );
-  }
-}
-
-/** Reply to an inline pull-request review comment thread. */
-export async function createGitHubReviewCommentReply(
-  input: GitHubResourceInput & {
-    body: string;
-    commentId: number;
-    pullRequestNumber: number;
-  },
-): Promise<GitHubPostedComment> {
-  const octokit = await createGitHubOctokit(input);
-  try {
-    const response = await octokit.rest.pulls.createReplyForReviewComment({
-      owner: input.owner,
-      repo: input.repo,
-      pull_number: input.pullRequestNumber,
-      comment_id: input.commentId,
-      body: input.body,
-    });
-    return toPostedComment(response.data);
-  } catch (error) {
-    throw wrapOctokitError(
-      error,
-      "POST",
-      `/repos/${input.owner}/${input.repo}/pulls/${input.pullRequestNumber}/comments/${input.commentId}/replies`,
-    );
-  }
-}
-
-/** Create a reaction on an issue or review comment. */
-export async function createGitHubReaction(
-  input: GitHubResourceInput & {
-    commentId: number;
-    content: GitHubReactionContent;
-    subject: "issue_comment" | "pull_request_review_comment";
-  },
-): Promise<GitHubApiResponse> {
-  const octokit = await createGitHubOctokit(input);
-  try {
-    const response =
-      input.subject === "issue_comment"
-        ? await octokit.rest.reactions.createForIssueComment({
-            owner: input.owner,
-            repo: input.repo,
-            comment_id: input.commentId,
-            content: input.content,
-          })
-        : await octokit.rest.reactions.createForPullRequestReviewComment({
-            owner: input.owner,
-            repo: input.repo,
-            comment_id: input.commentId,
-            content: input.content,
-          });
-    return {
-      body: response.data,
-      ok: true,
-      status: response.status,
-    };
-  } catch (error) {
-    const segment = input.subject === "issue_comment" ? "issues/comments" : "pulls/comments";
-    throw wrapOctokitError(
-      error,
-      "POST",
-      `/repos/${input.owner}/${input.repo}/${segment}/${input.commentId}/reactions`,
-    );
-  }
-}
-
-/** Create a commit status (legacy `statuses` API). */
-export async function createGitHubCommitStatus(
-  input: GitHubResourceInput & {
-    sha: string;
-    state: "error" | "failure" | "pending" | "success";
-    context?: string;
-    description?: string;
-    targetUrl?: string;
-  },
-): Promise<GitHubApiResponse> {
-  const octokit = await createGitHubOctokit(input);
-  try {
-    const response = await octokit.rest.repos.createCommitStatus({
-      owner: input.owner,
-      repo: input.repo,
-      sha: input.sha,
-      state: input.state,
-      ...(input.context === undefined ? {} : { context: input.context }),
-      ...(input.description === undefined ? {} : { description: input.description }),
-      ...(input.targetUrl === undefined ? {} : { target_url: input.targetUrl }),
-    });
-    return {
-      body: response.data,
-      ok: true,
-      status: response.status,
-    };
-  } catch (error) {
-    throw wrapOctokitError(
-      error,
-      "POST",
-      `/repos/${input.owner}/${input.repo}/statuses/${input.sha}`,
-    );
-  }
-}
-
-export type GitHubCheckRunStatus = "queued" | "in_progress" | "completed";
-export type GitHubCheckRunConclusion =
-  | "action_required"
-  | "cancelled"
-  | "failure"
-  | "neutral"
-  | "skipped"
-  | "success"
-  | "timed_out";
-
-export interface GitHubCheckRun {
-  htmlUrl: string | undefined;
-  id: number;
-  raw: unknown;
-}
-
-export interface GitHubCheckRunWriteInput {
-  conclusion?: GitHubCheckRunConclusion;
-  detailsUrl?: string;
-  name: string;
-  output?: { summary: string; title: string };
-  status: GitHubCheckRunStatus;
-}
-
-/** Create a check run (Checks API). */
-export async function createGitHubCheckRun(
-  input: GitHubResourceInput &
-    GitHubCheckRunWriteInput & {
-      sha: string;
-    },
-): Promise<GitHubCheckRun> {
-  const octokit = await createGitHubOctokit(input);
-  const now = new Date().toISOString();
-  try {
-    const response = await octokit.rest.checks.create({
-      owner: input.owner,
-      repo: input.repo,
-      name: input.name,
-      head_sha: input.sha,
-      status: input.status,
-      started_at: now,
-      ...checkRunCompletionFields(input, now),
-      ...checkRunDetailsUrl(input),
-      ...checkRunOutput(input),
-    });
-    return toCheckRun(response.data);
-  } catch (error) {
-    throw wrapOctokitError(error, "POST", `/repos/${input.owner}/${input.repo}/check-runs`);
-  }
-}
-
-/** Update a check run (Checks API). */
-export async function updateGitHubCheckRun(
-  input: GitHubResourceInput &
-    GitHubCheckRunWriteInput & {
-      checkRunId: number;
-    },
-): Promise<GitHubCheckRun> {
-  const octokit = await createGitHubOctokit(input);
-  try {
-    const response = await octokit.rest.checks.update({
-      owner: input.owner,
-      repo: input.repo,
-      check_run_id: input.checkRunId,
-      name: input.name,
-      status: input.status,
-      ...checkRunCompletionFields(input, new Date().toISOString()),
-      ...checkRunDetailsUrl(input),
-      ...checkRunOutput(input),
-    });
-    return toCheckRun(response.data);
-  } catch (error) {
-    throw wrapOctokitError(
-      error,
-      "PATCH",
-      `/repos/${input.owner}/${input.repo}/check-runs/${input.checkRunId}`,
-    );
-  }
-}
-
-function checkRunCompletionFields(
-  input: GitHubCheckRunWriteInput,
-  completedAt: string,
-): {
-  completed_at?: string;
-  conclusion?: GitHubCheckRunConclusion;
-} {
-  if (input.status !== "completed" || input.conclusion === undefined) {
-    return {};
-  }
-  return { completed_at: completedAt, conclusion: input.conclusion };
-}
-
-function checkRunDetailsUrl(input: GitHubCheckRunWriteInput): {
-  details_url?: string;
-} {
-  return input.detailsUrl === undefined ? {} : { details_url: input.detailsUrl };
-}
-
-function checkRunOutput(input: GitHubCheckRunWriteInput): {
-  output?: { summary: string; title: string };
-} {
-  return input.output === undefined ? {} : { output: input.output };
-}
-
-function toCheckRun(raw: { html_url?: string | null; id?: number }): GitHubCheckRun {
-  return {
-    htmlUrl: typeof raw.html_url === "string" ? raw.html_url : undefined,
-    id: typeof raw.id === "number" ? raw.id : 0,
-    raw,
-  };
-}
-
-function toPostedComment(raw: {
-  html_url?: string;
-  id?: number;
-  url?: string;
-}): GitHubPostedComment {
-  return {
-    htmlUrl: typeof raw.html_url === "string" ? raw.html_url : undefined,
-    id: typeof raw.id === "number" ? raw.id : 0,
-    raw,
-    url: typeof raw.url === "string" ? raw.url : undefined,
-  };
-}
-
-function normalizeRequestPath(path: string): string {
-  return path.startsWith("/") ? path : `/${path}`;
-}
-
-function isOctokitRequestError(error: unknown): error is {
-  status: number;
-  response?: { data?: unknown };
-} {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "status" in error &&
-    typeof (error as { status: unknown }).status === "number"
-  );
-}
-
-/** Normalize an Octokit request failure into {@link GitHubApiError}. */
-export function wrapOctokitError(error: unknown, method: string, path: string): Error {
-  if (isOctokitRequestError(error)) {
-    return new GitHubApiError({
-      body: error.response?.data,
-      method,
-      path,
-      status: error.status,
-    });
-  }
-  return error instanceof Error ? error : new Error(String(error));
-}