@theholocron/github-client 1.58.0-alpha.12 → 1.58.0-alpha.14

package/dist/index.d.mts

@@ -15,6 +15,10 @@ import { ErrorSink, Logger } from "@theholocron/observability/core";
  * which transport they're talking to.
  */
 interface GraphQLClient {
+  /**
+   * Sends one query or mutation to `POST /graphql` and returns its `data`. Throws a `ProviderApiError` (status `200`, with the
+   * response's `errors` array) when GitHub answers with errors, and the transport's own `ProviderApiError` for a network or HTTP failure.
+   */
   query<T>(document: string, variables?: Record<string, unknown>): Promise<T>;
 }
 /** Options for creating a GitHub client. */
@@ -115,6 +119,8 @@ interface GitHubCheckRun {
   conclusion: CheckRunConclusion | null;
   /** The URL of the check run's page on GitHub. */
   html_url: string;
+  /** The check's own "Details" link, when it set one. */
+  details_url?: string | null;
 }
 /** The body of an `updateCheckRun()` request; every field is optional. */
 interface UpdateCheckRunInput {
@@ -433,6 +439,40 @@ interface GitHubPullRequest {
     /** The head commit. */
     sha: string;
   };
+  /** Whether the pull request is a draft. */
+  draft?: boolean;
+  /** When the pull request was opened, as an ISO 8601 timestamp. */
+  created_at?: string;
+  /** The author. */
+  user?: {
+    /** The author's login. */
+    login: string;
+    /** The account type: `User` or `Bot` (Dependabot is a `Bot`). */
+    type: string;
+  };
+  /** Who merged it; `null` for a pull request that is not merged. */
+  merged_by?: {
+    login: string;
+  } | null;
+  /** The base branch. */
+  base?: {
+    /** The base branch's name, e.g. `alpha`. */
+    ref: string;
+  };
+  /** The people whose review is still asked for. */
+  requested_reviewers?: {
+    login: string;
+  }[];
+  /** Lines added, as the single-pull-request endpoint returns it (the list endpoint omits it). */
+  additions?: number;
+  /** Lines removed; see `additions`. */
+  deletions?: number;
+  /** Files changed; see `additions`. */
+  changed_files?: number;
+  /** Whether it merges cleanly; `null` while GitHub is still working it out. */
+  mergeable?: boolean | null;
+  /** `dirty` means it conflicts with its base; see `mergeable`. */
+  mergeable_state?: string;
 }
 /** A commit's name/email as git itself recorded it — `commit.author`/`commit.committer`, distinct from the GitHub-account `author` below (a commit can carry any email, linked to a GitHub account or not). */
 interface GitHubCommitIdentity {
@@ -511,6 +551,12 @@ interface GitHubPullRequestReview {
   id: number;
   /** The URL of the review on GitHub. */
   html_url: string;
+  /** `APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `DISMISSED` or `PENDING`; set on a review read back. */
+  state?: string;
+  /** The reviewer; set on a review read back. */
+  user?: {
+    login: string;
+  } | null;
 }
 /**
  * One review thread — GraphQL-only (`resolveReviewThread`, the mutation
@@ -546,6 +592,8 @@ interface GitHubRepo {
   default_branch: string;
   /** The repository's `owner/name`. */
   full_name: string;
+  /** Whether the repository is archived (read-only). */
+  archived?: boolean;
   /** The repository description. */
   description?: string | null;
   /** The repository homepage URL. */
@@ -751,6 +799,41 @@ export declare function createAppJWT(creds: GitHubAppCredentials, now?: number):
 export declare function getInstallationAccessToken(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<InstallationAccessToken>;
 /** The whole flow in one call — an already-authenticated `GitHubClient` scoped to one installation. */
 export declare function createInstallationClient(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubClient>;
+/** The account an App or one of its installations belongs to. */
+interface GitHubAppAccount {
+  /** The user or organization login. */
+  login: string;
+  /** `User` or `Organization` (GitHub also reports `Enterprise` for an enterprise-owned App). */
+  type: string;
+}
+/** An App as `GET /app` reports it. */
+interface GitHubApp {
+  /** The App's URL name, as in `github.com/apps/<slug>`. */
+  slug: string;
+  /** The App's display name. */
+  name: string;
+  /** Who owns the App: decides which settings page its permissions live on. */
+  owner: GitHubAppAccount | null;
+  /** The permissions the App asks for now: name to `read`, `write` or `admin`. */
+  permissions: Record<string, string>;
+  /** The webhook events the App is subscribed to now. */
+  events: string[];
+}
+/** One installation of an App as `GET /app/installations` reports it. */
+interface GitHubAppInstallation {
+  /** The installation id. */
+  id: number;
+  /** The account the App is installed on. */
+  account: GitHubAppAccount | null;
+  /** What this installation has accepted: it lags the App's own list until an owner accepts a new request. */
+  permissions: Record<string, string>;
+  /** The events delivered to this installation. */
+  events: string[];
+}
+/** The App this JWT identifies: its slug, owner and the permissions and events it asks for now. */
+export declare function getApp(creds: GitHubAppCredentials, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubApp>;
+/** Every installation of the App this JWT identifies, with what each has accepted. Reads all pages. */
+export declare function listAppInstallations(creds: GitHubAppCredentials, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubAppInstallation[]>;
 /**
  * GitHub's own webhook mechanics — signature verification and header/
  * payload shapes. Pure functions, no REST call, no auth token: these
@@ -855,6 +938,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     removeBranch: (repo: string, branch: string) => Promise<void>;
   };
   checks: {
+    listCheckRunsForRef: (repo: string, ref: string) => Promise<GitHubCheckRun[]>;
     createCheckRun: (repo: string, input: CreateCheckRunInput) => Promise<GitHubCheckRun>;
     updateCheckRun: (repo: string, checkRunId: number, input: UpdateCheckRunInput) => Promise<GitHubCheckRun>;
   };
@@ -924,6 +1008,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     listPullRequests: (repo: string, state: "open" | "closed") => Promise<GitHubPullRequest[]>;
     listCommits: (repo: string, number: number) => Promise<GitHubPullRequestCommit[]>;
     listFiles: (repo: string, number: number) => Promise<GitHubPullRequestFile[]>;
+    listReviews: (repo: string, number: number) => Promise<GitHubPullRequestReview[]>;
     createReview: (repo: string, number: number, input: CreateReviewInput) => Promise<GitHubPullRequestReview>;
     listReviewThreads: (repo: string, number: number) => Promise<ReviewThread[]>;
     resolveReviewThread: (threadId: string) => Promise<void>;
@@ -985,4 +1070,4 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
 };
 /** The client returned by `createGitHubClient()`: one group of methods per GitHub API area. */
 export type GitHubClient = ReturnType<typeof createGitHubClient>;
-export type { CheckRunAnnotation, CheckRunAnnotationLevel, CheckRunConclusion, CheckRunOutput, CheckRunStatus, CodeScanningSetupResult, CreateCheckRunInput, CreatePagesPayload, CreatePullInput, CreateReviewComment, CreateReviewInput, GitBlob, GitCommit, GitContents, GitDirectoryEntry, GitHubAppCredentials, GitHubCheckRun, GitHubClientOptions, GitHubContents, GitHubEnvironment, GitHubInstallationWebhookPayload, GitHubIssue, GitHubLabel, GitHubMilestone, GitHubPages, GitHubPublicKey, GitHubPullRequest, GitHubPullRequestCommit, GitHubPullRequestFile, GitHubPullRequestReview, GitHubPullRequestWebhookPayload, GitHubPushWebhookPayload, GitHubRepo, GitHubRuleset, GitHubRulesetDetail, GitHubUser, GitHubUserWithExpiry, GitHubVariable, GitHubWebhookHeaders, GitHubWorkflowRun, GitPull, GitRef, GitTree, GitTreeItem, GraphQLClient, InstallationAccessToken, IssueSearchParams, ListDirectoryOptions, OrgProperty, PagesBuildStatus, PagesBuildType, PutContentsInput, PutContentsResult, RepoPropertyValue, RepoTeam, ReviewThread, SecretScope, TeamMember, TeamPermission, UpdateCheckRunInput, UpdatePagesPayload, VariableScope, VariableVisibility, WorkflowRunFilter };
+export type { CheckRunAnnotation, CheckRunAnnotationLevel, CheckRunConclusion, CheckRunOutput, CheckRunStatus, CodeScanningSetupResult, CreateCheckRunInput, CreatePagesPayload, CreatePullInput, CreateReviewComment, CreateReviewInput, GitBlob, GitCommit, GitContents, GitDirectoryEntry, GitHubApp, GitHubAppAccount, GitHubAppCredentials, GitHubAppInstallation, GitHubCheckRun, GitHubClientOptions, GitHubContents, GitHubEnvironment, GitHubInstallationWebhookPayload, GitHubIssue, GitHubLabel, GitHubMilestone, GitHubPages, GitHubPublicKey, GitHubPullRequest, GitHubPullRequestCommit, GitHubPullRequestFile, GitHubPullRequestReview, GitHubPullRequestWebhookPayload, GitHubPushWebhookPayload, GitHubRepo, GitHubRuleset, GitHubRulesetDetail, GitHubUser, GitHubUserWithExpiry, GitHubVariable, GitHubWebhookHeaders, GitHubWorkflowRun, GitPull, GitRef, GitTree, GitTreeItem, GraphQLClient, InstallationAccessToken, IssueSearchParams, ListDirectoryOptions, OrgProperty, PagesBuildStatus, PagesBuildType, PutContentsInput, PutContentsResult, RepoPropertyValue, RepoTeam, ReviewThread, SecretScope, TeamMember, TeamPermission, UpdateCheckRunInput, UpdatePagesPayload, VariableScope, VariableVisibility, WorkflowRunFilter };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { ProviderApiError, createRestClient } from "@theholocron/http-client";
 import { createHmac, timingSafeEqual } from "node:crypto";
 // src/graphql/graphql.ts
+/** A {@link GraphQLClient} for GitHub's GraphQL API, built on the shared REST transport. */
 function createGitHubGraphQLClient(config) {
 	const rest = createRestClient({
 		baseUrl: config.baseUrl ?? "https://api.github.com",
@@ -107,8 +108,21 @@ function branches(rest) {
 * do for you; slice with it rather than hardcoding the number.
 */
 const MAX_CHECK_RUN_ANNOTATIONS = 50;
+/** Page size and the most pages {@link checks}`.listCheckRunsForRef` reads: 100 a page over 10 pages, so 1,000 check runs. */
+const CHECK_RUN_PAGE_SIZE = 100;
+const CHECK_RUN_MAX_PAGES = 10;
 function checks(rest) {
 	return {
+		/** Every check run on a commit, read a page at a time until a page comes back short. */
+		listCheckRunsForRef: async (repo, ref) => {
+			const all = [];
+			for (let page = 1; page <= CHECK_RUN_MAX_PAGES; page++) {
+				const batch = await rest.request(`${repoBase(repo)}/commits/${ref}/check-runs?per_page=${CHECK_RUN_PAGE_SIZE}&page=${page}`);
+				all.push(...batch.check_runs);
+				if (batch.check_runs.length < CHECK_RUN_PAGE_SIZE) break;
+			}
+			return all;
+		},
 		createCheckRun: (repo, input) => rest.request(`${repoBase(repo)}/check-runs`, {
 			method: "POST",
 			body: input
@@ -413,6 +427,8 @@ function pulls(rest, graphql) {
 		* is an edge case no consumer here needs to paginate for today.
 		*/
 		listFiles: (repo, number) => rest.request(`${repoBase(repo)}/pulls/${number}/files?per_page=100`),
+		/** A PR's reviews, oldest first. `per_page=100` covers every real PR in this org. */
+		listReviews: (repo, number) => rest.request(`${repoBase(repo)}/pulls/${number}/reviews?per_page=100`),
 		/**
 		* Submits a review in one call — GitHub has no separate "create draft,
 		* then submit" step when `event` is provided directly (the multi-step
@@ -875,6 +891,62 @@ async function createInstallationClient(creds, installationId, opts = {}) {
 		fetch: opts.fetch
 	});
 }
+// src/app-info/app-info.ts
+/**
+* What a GitHub App is right now, read with the App's own JWT (`GET /app`, `GET /app/installations`). GitHub has no
+* endpoint that changes an existing App's permissions or event subscriptions, so these reads are how a caller
+* checks the settings page was done by hand.
+*
+* https://docs.github.com/en/rest/apps/apps#get-the-authenticated-app
+* https://docs.github.com/en/rest/apps/apps#list-installations-for-the-authenticated-app
+*/
+const PAGE_SIZE = 100;
+const account = (value) => {
+	const { login, type } = value ?? {};
+	return typeof login === "string" ? {
+		login,
+		type: typeof type === "string" ? type : ""
+	} : null;
+};
+async function appGet(creds, path, opts) {
+	const jwt = await createAppJWT(creds);
+	const baseUrl = opts.baseUrl ?? "https://api.github.com";
+	const res = await (opts.fetch ?? globalThis.fetch)(`${baseUrl}${path}`, { headers: {
+		authorization: `Bearer ${jwt}`,
+		accept: "application/vnd.github+json",
+		"x-github-api-version": "2022-11-28"
+	} });
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new ProviderApiError(`GitHub GET ${path} → ${res.status}`, res.status, body);
+	}
+	return res.json();
+}
+/** The App this JWT identifies: its slug, owner and the permissions and events it asks for now. */
+async function getApp(creds, opts = {}) {
+	const raw = await appGet(creds, "/app", opts);
+	return {
+		slug: String(raw.slug),
+		name: String(raw.name),
+		owner: account(raw.owner),
+		permissions: raw.permissions ?? {},
+		events: raw.events ?? []
+	};
+}
+/** Every installation of the App this JWT identifies, with what each has accepted. Reads all pages. */
+async function listAppInstallations(creds, opts = {}) {
+	const installations = [];
+	for (let page = 1;; page++) {
+		const raws = await appGet(creds, `/app/installations?per_page=${PAGE_SIZE}&page=${page}`, opts);
+		for (const raw of raws) installations.push({
+			id: Number(raw.id),
+			account: account(raw.account),
+			permissions: raw.permissions ?? {},
+			events: raw.events ?? []
+		});
+		if (raws.length < PAGE_SIZE) return installations;
+	}
+}
 // src/webhooks/webhooks.ts
 /**
 * GitHub's own webhook mechanics — signature verification and header/
@@ -948,4 +1020,4 @@ function createGitHubClient(opts) {
 		workflows: workflows(rest)
 	};
 }
-export { MAX_CHECK_RUN_ANNOTATIONS, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, parseTokenExpiration, verifyGitHubWebhookSignature };
+export { MAX_CHECK_RUN_ANNOTATIONS, createAppJWT, createGitHubClient, createInstallationClient, getApp, getInstallationAccessToken, listAppInstallations, parseGitHubWebhookHeaders, parseTokenExpiration, verifyGitHubWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.58.0-alpha.12",
+  "version": "1.58.0-alpha.14",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -32,7 +32,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.58.0-alpha.12",
+    "@theholocron/http-client": "^1.58.0-alpha.14",
     "@theholocron/observability": "^0.7.0-alpha.1"
   },
   "devDependencies": {
@@ -45,10 +45,10 @@
     "tsdown": "^0.23.4",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "^8.9.0-alpha.8",
-    "@theholocron/eslint-config": "^8.9.0-alpha.8",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
-    "@theholocron/vitest-config": "^8.9.0-alpha.8"
+    "@theholocron/eslint-config": "^8.9.0-alpha.9",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.9",
+    "@theholocron/tsconfig": "^8.9.0-alpha.9",
+    "@theholocron/vitest-config": "^8.9.0-alpha.9"
   },
   "engines": {
     "node": ">=22.0.0"