@theholocron/github-client 1.31.0 → 1.32.1

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import "@theholocron/http-client";
 import { ErrorSink, Logger } from "@theholocron/observability/core";
-//#region src/utils.d.ts
+//#region ../../../../../src/utils.d.ts
 interface GitHubClientOptions {
   token: string;
   baseUrl?: string;
@@ -11,7 +11,7 @@ interface GitHubClientOptions {
   errors?: ErrorSink;
 }
 //#endregion
-//#region src/checks/checks.d.ts
+//#region ../../../../../src/checks/checks.d.ts
 type CheckRunStatus = "queued" | "in_progress" | "completed";
 type CheckRunConclusion = "success" | "failure" | "neutral" | "cancelled" | "timed_out" | "action_required" | "skipped";
 type CheckRunAnnotationLevel = "notice" | "warning" | "failure";
@@ -72,7 +72,7 @@ interface UpdateCheckRunInput {
   details_url?: string;
 }
 //#endregion
-//#region src/environments/environments.d.ts
+//#region ../../../../../src/environments/environments.d.ts
 interface GitHubEnvironment {
   name: string;
   wait_timer?: number;
@@ -88,7 +88,7 @@ interface GitHubEnvironment {
   }>;
 }
 //#endregion
-//#region src/git/git.d.ts
+//#region ../../../../../src/git/git.d.ts
 interface GitRef {
   object: {
     sha: string;
@@ -140,7 +140,7 @@ interface CreatePullInput {
   body?: string;
 }
 //#endregion
-//#region src/issues/issues.d.ts
+//#region ../../../../../src/issues/issues.d.ts
 interface GitHubIssue {
   id: number;
   number: number;
@@ -172,14 +172,14 @@ interface IssueSearchParams {
   assignee?: string;
 }
 //#endregion
-//#region src/labels/labels.d.ts
+//#region ../../../../../src/labels/labels.d.ts
 interface GitHubLabel {
   name: string;
   color: string;
   description: string | null;
 }
 //#endregion
-//#region src/pages/pages.d.ts
+//#region ../../../../../src/pages/pages.d.ts
 type PagesBuildType = "workflow" | "legacy";
 type PagesBuildStatus = "built" | "building" | "errored" | "unknown";
 interface GitHubPages {
@@ -210,7 +210,7 @@ interface UpdatePagesPayload {
   https_enforced?: boolean;
 }
 //#endregion
-//#region src/pulls/pulls.d.ts
+//#region ../../../../../src/pulls/pulls.d.ts
 interface GitHubPullRequest {
   number: number;
   title: string;
@@ -235,8 +235,50 @@ interface GitHubPullRequestFile {
   /** Set only when `status === "renamed"`. */
   previous_filename?: string;
 }
+/** One inline comment in a `POST /pulls/{pull_number}/reviews` request body. */
+interface CreateReviewComment {
+  /** File path relative to the repo root. */
+  path: string;
+  /** 1-indexed line in the file's current (`RIGHT`) version — GitHub anchors a review comment to a line, not a column. */
+  line: number;
+  /** Almost always `"RIGHT"` (the PR's own new content) — `"LEFT"` targets the base/pre-PR version instead. */
+  side: "LEFT" | "RIGHT";
+  body: string;
+}
+interface CreateReviewInput {
+  /** The PR's head SHA the review attaches to. */
+  commit_id: string;
+  /** The review's own top-level summary, shown above its inline comments. */
+  body: string;
+  /**
+   * `"COMMENT"` never blocks a merge by itself — the right choice for an
+   * advisory bot review. `"REQUEST_CHANGES"`/`"APPROVE"` carry the same
+   * real weight as a human reviewer's own review state, affecting
+   * required-approval counts and dismissal.
+   */
+  event: "COMMENT" | "REQUEST_CHANGES" | "APPROVE";
+  comments?: CreateReviewComment[];
+}
+/** `POST /pulls/{pull_number}/reviews`'s response — only the fields any known consumer needs. */
+interface GitHubPullRequestReview {
+  id: number;
+  html_url: string;
+}
+/**
+ * One review thread — GraphQL-only (`resolveReviewThread`, the mutation
+ * this exists to support, has no REST equivalent at all). `id` here is a
+ * GraphQL node ID (`PRRT_...`), not the same numeric ID space as REST's
+ * review-comment `id` — pass it straight through to `resolveReviewThread()`,
+ * never compare it against a REST-sourced ID.
+ */
+interface ReviewThread {
+  id: string;
+  isResolved: boolean;
+  /** The thread's first comment's author login (e.g. `"the-holocron-sentinel[bot]"`) — `undefined` if GitHub ever returns a thread with no comments, which shouldn't happen in practice. Callers filter on this before resolving anything, so a bot never touches a human reviewer's own thread. */
+  authorLogin: string | undefined;
+}
 //#endregion
-//#region src/repos/repos.d.ts
+//#region ../../../../../src/repos/repos.d.ts
 interface GitHubRepo {
   default_branch: string;
   full_name: string;
@@ -246,14 +288,14 @@ interface GitHubContents {
   encoding: string;
 }
 //#endregion
-//#region src/rulesets/rulesets.d.ts
+//#region ../../../../../src/rulesets/rulesets.d.ts
 interface GitHubRuleset {
   id: number;
   name: string;
   enforcement: string;
 }
 //#endregion
-//#region src/secrets/secrets.d.ts
+//#region ../../../../../src/secrets/secrets.d.ts
 type SecretScope = {
   kind: "repo";
 } | {
@@ -268,23 +310,23 @@ interface GitHubPublicKey {
   key: string;
 }
 //#endregion
-//#region src/security/security.d.ts
+//#region ../../../../../src/security/security.d.ts
 interface CodeScanningSetupResult {
   run_id: number;
   run_url: string;
 }
 //#endregion
-//#region src/teams/teams.d.ts
+//#region ../../../../../src/teams/teams.d.ts
 type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
 //#endregion
-//#region src/user/user.d.ts
+//#region ../../../../../src/user/user.d.ts
 interface GitHubUser {
   login: string;
   name: string | null;
   email: string | null;
 }
 //#endregion
-//#region src/workflows/workflows.d.ts
+//#region ../../../../../src/workflows/workflows.d.ts
 interface GitHubWorkflowRun {
   id: number;
   name: string | null;
@@ -303,7 +345,7 @@ interface WorkflowRunFilter {
   status?: string;
 }
 //#endregion
-//#region src/app-auth/app-auth.d.ts
+//#region ../../../../../src/app-auth/app-auth.d.ts
 interface GitHubAppCredentials {
   /** The App's numeric id (not the client id). */
   appId: string;
@@ -331,7 +373,7 @@ declare function getInstallationAccessToken(creds: GitHubAppCredentials, install
 /** The whole flow in one call — an already-authenticated `GitHubClient` scoped to one installation. */
 declare function createInstallationClient(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubClient>;
 //#endregion
-//#region src/webhooks/webhooks.d.ts
+//#region ../../../../../src/webhooks/webhooks.d.ts
 /**
  * GitHub's own webhook mechanics — signature verification and header/
  * payload shapes. Pure functions, no REST call, no auth token: these
@@ -398,7 +440,7 @@ interface GitHubPullRequestWebhookPayload {
   };
 }
 //#endregion
-//#region src/index.d.ts
+//#region ../../../../../src/index.d.ts
 declare function createGitHubClient(opts: GitHubClientOptions): {
   branches: {
     protectBranch: (repo: string, branch: string, payload: Record<string, unknown>) => Promise<void>;
@@ -466,6 +508,9 @@ declare function createGitHubClient(opts: GitHubClientOptions): {
     getPullRequest: (repo: string, number: number) => Promise<GitHubPullRequest>;
     listCommits: (repo: string, number: number) => Promise<GitHubPullRequestCommit[]>;
     listFiles: (repo: string, number: number) => Promise<GitHubPullRequestFile[]>;
+    createReview: (repo: string, number: number, input: CreateReviewInput) => Promise<GitHubPullRequestReview>;
+    listReviewThreads: (repo: string, number: number) => Promise<ReviewThread[]>;
+    resolveReviewThread: (threadId: string) => Promise<void>;
   };
   repos: {
     getRepo: (repo: string) => Promise<GitHubRepo>;
@@ -509,4 +554,4 @@ declare function createGitHubClient(opts: GitHubClientOptions): {
 };
 type GitHubClient = ReturnType<typeof createGitHubClient>;
 //#endregion
-export { type CheckRunAnnotation, type CheckRunAnnotationLevel, type CheckRunConclusion, type CheckRunOutput, type CheckRunStatus, type CodeScanningSetupResult, type CreateCheckRunInput, type CreatePagesPayload, type CreatePullInput, type GitBlob, type GitCommit, type GitContents, type GitHubAppCredentials, type GitHubCheckRun, GitHubClient, type GitHubClientOptions, type GitHubContents, type GitHubEnvironment, type GitHubInstallationWebhookPayload, type GitHubIssue, type GitHubLabel, type GitHubMilestone, type GitHubPages, type GitHubPublicKey, type GitHubPullRequest, type GitHubPullRequestCommit, type GitHubPullRequestFile, type GitHubPullRequestWebhookPayload, type GitHubPushWebhookPayload, type GitHubRepo, type GitHubRuleset, type GitHubUser, type GitHubWebhookHeaders, type GitHubWorkflowRun, type GitPull, type GitRef, type GitTree, type GitTreeItem, type InstallationAccessToken, type IssueSearchParams, type PagesBuildStatus, type PagesBuildType, type SecretScope, type TeamPermission, type UpdateCheckRunInput, type UpdatePagesPayload, type WorkflowRunFilter, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };
+export { type CheckRunAnnotation, type CheckRunAnnotationLevel, type CheckRunConclusion, type CheckRunOutput, type CheckRunStatus, type CodeScanningSetupResult, type CreateCheckRunInput, type CreatePagesPayload, type CreatePullInput, type CreateReviewComment, type CreateReviewInput, type GitBlob, type GitCommit, type GitContents, type GitHubAppCredentials, type GitHubCheckRun, GitHubClient, type GitHubClientOptions, type GitHubContents, type GitHubEnvironment, type GitHubInstallationWebhookPayload, type GitHubIssue, type GitHubLabel, type GitHubMilestone, type GitHubPages, type GitHubPublicKey, type GitHubPullRequest, type GitHubPullRequestCommit, type GitHubPullRequestFile, type GitHubPullRequestReview, type GitHubPullRequestWebhookPayload, type GitHubPushWebhookPayload, type GitHubRepo, type GitHubRuleset, type GitHubUser, type GitHubWebhookHeaders, type GitHubWorkflowRun, type GitPull, type GitRef, type GitTree, type GitTreeItem, type InstallationAccessToken, type IssueSearchParams, type PagesBuildStatus, type PagesBuildType, type ReviewThread, type SecretScope, type TeamPermission, type UpdateCheckRunInput, type UpdatePagesPayload, type WorkflowRunFilter, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };

package/dist/index.mjs

@@ -1,6 +1,29 @@
 import { ProviderApiError, createRestClient } from "@theholocron/http-client";
 import { createHmac, timingSafeEqual } from "node:crypto";
-//#region src/utils.ts
+//#region ../../../../../src/graphql/graphql.ts
+function createGitHubGraphQLClient(config) {
+	const rest = createRestClient({
+		baseUrl: config.baseUrl ?? "https://api.github.com",
+		token: config.token,
+		vendor: "GitHub GraphQL",
+		fetch: config.fetch,
+		logger: config.logger,
+		errors: config.errors
+	});
+	return { async query(document, variables) {
+		const result = await rest.request("/graphql", {
+			method: "POST",
+			body: {
+				query: document,
+				variables
+			}
+		});
+		if (result.errors && result.errors.length > 0) throw new ProviderApiError(`GitHub GraphQL → ${result.errors.map((e) => e.message).join("; ")}`, 200, result.errors);
+		return result.data;
+	} };
+}
+//#endregion
+//#region ../../../../../src/utils.ts
 function createGitHubRestClient(opts) {
 	return createRestClient({
 		baseUrl: opts.baseUrl ?? "https://api.github.com",
@@ -15,13 +38,28 @@ function createGitHubRestClient(opts) {
 		errors: opts.errors
 	});
 }
+/** GitHub's GraphQL endpoint — a distinct client from `createGitHubRestClient()`'s REST one; see `graphql/graphql.ts` for why a shared transport still needed its own response-error handling. */
+function createGitHubGraphQLApiClient(opts) {
+	return createGitHubGraphQLClient({
+		baseUrl: opts.baseUrl,
+		token: opts.token,
+		fetch: opts.fetch,
+		logger: opts.logger,
+		errors: opts.errors
+	});
+}
 /** `/repos/owner/name` prefix from a `"owner/name"` repo string. */
 function repoBase(repo) {
 	const [owner, name] = repo.split("/", 2);
 	return `/repos/${owner}/${name}`;
 }
+/** `["owner", "name"]` from a `"owner/name"` repo string — GraphQL's `repository(owner:, name:)` args take them separately, unlike REST's single path segment. */
+function splitRepo(repo) {
+	const [owner, name] = repo.split("/", 2);
+	return [owner ?? "", name ?? ""];
+}
 //#endregion
-//#region src/branches/branches.ts
+//#region ../../../../../src/branches/branches.ts
 function branches(rest) {
 	return { protectBranch: (repo, branch, payload) => rest.request(`${repoBase(repo)}/branches/${encodeURIComponent(branch)}/protection`, {
 		method: "PUT",
@@ -29,7 +67,7 @@ function branches(rest) {
 	}) };
 }
 //#endregion
-//#region src/checks/checks.ts
+//#region ../../../../../src/checks/checks.ts
 function checks(rest) {
 	return {
 		createCheckRun: (repo, input) => rest.request(`${repoBase(repo)}/check-runs`, {
@@ -44,7 +82,7 @@ function checks(rest) {
 	};
 }
 //#endregion
-//#region src/environments/environments.ts
+//#region ../../../../../src/environments/environments.ts
 function environments(rest) {
 	return {
 		listEnvironments: (repo) => rest.request(`${repoBase(repo)}/environments`).then((r) => r.environments),
@@ -59,7 +97,7 @@ function environments(rest) {
 	};
 }
 //#endregion
-//#region src/git/git.ts
+//#region ../../../../../src/git/git.ts
 function git(rest) {
 	return {
 		getRef: (repo, branch) => rest.request(`${repoBase(repo)}/git/ref/heads/${branch}`),
@@ -117,7 +155,7 @@ function git(rest) {
 	};
 }
 //#endregion
-//#region src/issues/issues.ts
+//#region ../../../../../src/issues/issues.ts
 function issues(rest) {
 	return {
 		listIssues: (repo, params = {}) => {
@@ -158,7 +196,7 @@ function issues(rest) {
 	};
 }
 //#endregion
-//#region src/labels/labels.ts
+//#region ../../../../../src/labels/labels.ts
 function labels(rest) {
 	return {
 		listLabels: (repo) => rest.request(`${repoBase(repo)}/labels?per_page=100`),
@@ -174,7 +212,7 @@ function labels(rest) {
 	};
 }
 //#endregion
-//#region src/pages/pages.ts
+//#region ../../../../../src/pages/pages.ts
 function pages(rest) {
 	return {
 		/** Returns null when Pages is not yet enabled (404). */
@@ -206,7 +244,7 @@ function pages(rest) {
 	};
 }
 //#endregion
-//#region src/properties/properties.ts
+//#region ../../../../../src/properties/properties.ts
 function properties(rest) {
 	return { 
 	/**
@@ -229,8 +267,34 @@ setProperties: (repo, values) => {
 	} };
 }
 //#endregion
-//#region src/pulls/pulls.ts
-function pulls(rest) {
+//#region ../../../../../src/pulls/pulls.ts
+const LIST_REVIEW_THREADS_QUERY = `
+	query($owner: String!, $name: String!, $number: Int!) {
+		repository(owner: $owner, name: $name) {
+			pullRequest(number: $number) {
+				reviewThreads(first: 100) {
+					nodes {
+						id
+						isResolved
+						comments(first: 1) {
+							nodes {
+								author { login }
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+`;
+const RESOLVE_REVIEW_THREAD_MUTATION = `
+	mutation($threadId: ID!) {
+		resolveReviewThread(input: { threadId: $threadId }) {
+			thread { id isResolved }
+		}
+	}
+`;
+function pulls(rest, graphql) {
 	return {
 		getPullRequest: (repo, number) => rest.request(`${repoBase(repo)}/pulls/${number}`),
 		/**
@@ -246,11 +310,42 @@ function pulls(rest) {
 		* files (GitHub caps this endpoint at 3000 regardless of pagination)
 		* 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`)
+		listFiles: (repo, number) => rest.request(`${repoBase(repo)}/pulls/${number}/files?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
+		* `PENDING` review flow exists for the web UI's own draft-comments
+		* experience, not needed here).
+		*/
+		createReview: (repo, number, input) => rest.request(`${repoBase(repo)}/pulls/${number}/reviews`, {
+			method: "POST",
+			body: input
+		}),
+		/** Every review thread on a PR, resolved or not — GraphQL-only, `first: 100` covers every real PR's review-thread count in this org today; no consumer needs pagination yet. */
+		listReviewThreads: async (repo, number) => {
+			const [owner, name] = splitRepo(repo);
+			return (await graphql.query(LIST_REVIEW_THREADS_QUERY, {
+				owner,
+				name,
+				number
+			})).repository.pullRequest.reviewThreads.nodes.map((node) => ({
+				id: node.id,
+				isResolved: node.isResolved,
+				authorLogin: node.comments.nodes[0]?.author?.login
+			}));
+		},
+		/**
+		* Marks one review thread resolved. Requires `Contents: Write` —
+		* confirmed directly against GitHub's own behavior (surprising, since
+		* resolving a thread creates no commit, touches no file, moves no
+		* ref — it only toggles a boolean on PR conversation metadata), not
+		* `Pull requests: Write` the way `createReview()` needs.
+		*/
+		resolveReviewThread: (threadId) => graphql.query(RESOLVE_REVIEW_THREAD_MUTATION, { threadId })
 	};
 }
 //#endregion
-//#region src/repos/repos.ts
+//#region ../../../../../src/repos/repos.ts
 function repos(rest) {
 	return {
 		getRepo: (repo) => rest.request(repoBase(repo)),
@@ -262,7 +357,7 @@ function repos(rest) {
 	};
 }
 //#endregion
-//#region src/rulesets/rulesets.ts
+//#region ../../../../../src/rulesets/rulesets.ts
 function rulesets(rest) {
 	return {
 		listRulesets: (repo) => rest.request(`${repoBase(repo)}/rulesets`),
@@ -277,7 +372,7 @@ function rulesets(rest) {
 	};
 }
 //#endregion
-//#region src/secrets/secrets.ts
+//#region ../../../../../src/secrets/secrets.ts
 function scopeBase(repo, scope) {
 	switch (scope.kind) {
 		case "repo": return `${repoBase(repo)}/actions`;
@@ -301,7 +396,7 @@ function secrets(rest) {
 	};
 }
 //#endregion
-//#region src/security/security.ts
+//#region ../../../../../src/security/security.ts
 function security(rest) {
 	return {
 		enableVulnerabilityAlerts: (repo) => rest.request(`${repoBase(repo)}/vulnerability-alerts`, {
@@ -347,7 +442,7 @@ function security(rest) {
 	};
 }
 //#endregion
-//#region src/teams/teams.ts
+//#region ../../../../../src/teams/teams.ts
 function teams(rest) {
 	return { addRepo: (org, teamSlug, owner, repo, permission) => rest.request(`/orgs/${org}/teams/${teamSlug}/repos/${owner}/${repo}`, {
 		method: "PUT",
@@ -355,7 +450,7 @@ function teams(rest) {
 	}) };
 }
 //#endregion
-//#region src/topics/topics.ts
+//#region ../../../../../src/topics/topics.ts
 function topics(rest) {
 	return { setTopics: (repo, names) => rest.request(`${repoBase(repo)}/topics`, {
 		method: "PUT",
@@ -363,12 +458,12 @@ function topics(rest) {
 	}) };
 }
 //#endregion
-//#region src/user/user.ts
+//#region ../../../../../src/user/user.ts
 function user(rest) {
 	return { getCurrentUser: () => rest.request("/user") };
 }
 //#endregion
-//#region src/workflows/workflows.ts
+//#region ../../../../../src/workflows/workflows.ts
 function workflows(rest) {
 	return {
 		listRuns: (repo, filter) => {
@@ -400,7 +495,7 @@ function workflows(rest) {
 	};
 }
 //#endregion
-//#region src/app-auth/pem.ts
+//#region ../../../../../src/app-auth/pem.ts
 /**
 * PEM/DER handling for GitHub App private keys — Web Crypto only (no
 * `node:crypto`), so this runs unchanged on Cloudflare Workers (no
@@ -487,7 +582,7 @@ function base64UrlEncode(bytes) {
 	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 //#endregion
-//#region src/app-auth/app-auth.ts
+//#region ../../../../../src/app-auth/app-auth.ts
 /**
 * GitHub App authentication — a signed App JWT, exchanged for a
 * short-lived installation access token, exchanged for a ready-to-use
@@ -558,7 +653,7 @@ async function createInstallationClient(creds, installationId, opts = {}) {
 	});
 }
 //#endregion
-//#region src/webhooks/webhooks.ts
+//#region ../../../../../src/webhooks/webhooks.ts
 /**
 * GitHub's own webhook mechanics — signature verification and header/
 * payload shapes. Pure functions, no REST call, no auth token: these
@@ -604,9 +699,10 @@ function parseGitHubWebhookHeaders(headers) {
 	};
 }
 //#endregion
-//#region src/index.ts
+//#region ../../../../../src/index.ts
 function createGitHubClient(opts) {
 	const rest = createGitHubRestClient(opts);
+	const graphql = createGitHubGraphQLApiClient(opts);
 	return {
 		branches: branches(rest),
 		checks: checks(rest),
@@ -616,7 +712,7 @@ function createGitHubClient(opts) {
 		labels: labels(rest),
 		pages: pages(rest),
 		properties: properties(rest),
-		pulls: pulls(rest),
+		pulls: pulls(rest, graphql),
 		repos: repos(rest),
 		rulesets: rulesets(rest),
 		secrets: secrets(rest),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -33,13 +33,13 @@
   ],
   "dependencies": {
     "@theholocron/observability": "^0.3.0",
-    "@theholocron/http-client": "^1.31.0"
+    "@theholocron/http-client": "^1.32.1"
   },
   "devDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.33",
+    "@theholocron/cli": "5.0.0-alpha.79",
     "@theholocron/eslint-config": "^8.4.3",
     "@theholocron/tsconfig": "^8.2.0",
-    "@theholocron/tsdown-config": "^8.2.0",
+    "@theholocron/tsdown-config": "^8.6.1",
     "@theholocron/vitest-config": "^8.2.0",
     "@types/node": "^26.4.1",
     "@vitest/coverage-v8": "^5.0.0",
@@ -61,7 +61,7 @@
   "releases": "https://github.com/theholocron/clients/releases",
   "wiki": "https://github.com/theholocron/clients/wiki",
   "scripts": {
-    "delivery.build": "tsdown",
+    "delivery.build": "holocron run delivery.build -- && node ../../scripts/check-bundle-size.mjs",
     "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
     "test:watch": "vitest",
     "verification.typeSafety": "holocron run verification.typeSafety --",