@theholocron/github-client 1.57.1-alpha.1 → 1.58.0-alpha.1

package/dist/index.d.mts

@@ -9,6 +9,13 @@ interface GitHubClientOptions {
   /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
   errors?: ErrorSink;
 }
+/** One branch as `GET /branches` returns it: its name and the commit it points at. */
+interface GitHubBranch {
+  name: string;
+  commit: {
+    sha: string;
+  };
+}
 type CheckRunStatus = "queued" | "in_progress" | "completed";
 type CheckRunConclusion = "success" | "failure" | "neutral" | "cancelled" | "timed_out" | "action_required" | "skipped";
 type CheckRunAnnotationLevel = "notice" | "warning" | "failure";
@@ -226,14 +233,27 @@ interface UpdatePagesPayload {
   cname?: string | null;
   https_enforced?: boolean;
 }
+/** One custom property of an organization, as its schema defines it. */
+interface OrgProperty {
+  property_name: string;
+  /** `string`, `single_select`, `multi_select`, `true_false` or `url`. */
+  value_type: string;
+  required?: boolean;
+  /** The values a `single_select` or `multi_select` property accepts; `null` for any other type. */
+  allowed_values?: string[] | null;
+}
 interface GitHubPullRequest {
   number: number;
   title: string;
   state: "open" | "closed";
   merged_at: string | null;
   html_url: string;
+  /** The head branch: its name and the commit it pointed at when the PR was read. */
   head: {
+    /** The branch name, e.g. `fix/my-change`. */
     ref: string;
+    /** The head commit. */
+    sha: 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). */
@@ -502,6 +522,8 @@ interface GitHubPullRequestWebhookPayload {
 export declare function createGitHubClient(opts: GitHubClientOptions): {
   branches: {
     protectBranch: (repo: string, branch: string, payload: Record<string, unknown>) => Promise<void>;
+    listBranches: (repo: string) => Promise<GitHubBranch[]>;
+    removeBranch: (repo: string, branch: string) => Promise<void>;
   };
   checks: {
     createCheckRun: (repo: string, input: CreateCheckRunInput) => Promise<GitHubCheckRun>;
@@ -561,10 +583,12 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     updatePages: (repo: string, payload: UpdatePagesPayload) => Promise<void>;
   };
   properties: {
+    orgSchema: (org: string) => Promise<OrgProperty[]>;
     setProperties: (repo: string, values: Record<string, string | string[]>) => Promise<void>;
   };
   pulls: {
     getPullRequest: (repo: string, number: number) => Promise<GitHubPullRequest>;
+    listPullRequests: (repo: string, state: "open" | "closed") => 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>;
@@ -620,4 +644,4 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
   };
 };
 export type GitHubClient = ReturnType<typeof createGitHubClient>;
-export type { CheckRunAnnotation, CheckRunAnnotationLevel, CheckRunConclusion, CheckRunOutput, CheckRunStatus, CodeScanningSetupResult, CreateCheckRunInput, CreatePagesPayload, CreatePullInput, CreateReviewComment, CreateReviewInput, GitBlob, GitCommit, GitContents, GitHubAppCredentials, GitHubCheckRun, GitHubClientOptions, GitHubContents, GitHubEnvironment, GitHubInstallationWebhookPayload, GitHubIssue, GitHubLabel, GitHubMilestone, GitHubPages, GitHubPublicKey, GitHubPullRequest, GitHubPullRequestCommit, GitHubPullRequestFile, GitHubPullRequestReview, GitHubPullRequestWebhookPayload, GitHubPushWebhookPayload, GitHubRepo, GitHubRuleset, GitHubUser, GitHubVariable, GitHubWebhookHeaders, GitHubWorkflowRun, GitPull, GitRef, GitTree, GitTreeItem, InstallationAccessToken, IssueSearchParams, PagesBuildStatus, PagesBuildType, PutContentsInput, PutContentsResult, 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, GitHubAppCredentials, GitHubCheckRun, GitHubClientOptions, GitHubContents, GitHubEnvironment, GitHubInstallationWebhookPayload, GitHubIssue, GitHubLabel, GitHubMilestone, GitHubPages, GitHubPublicKey, GitHubPullRequest, GitHubPullRequestCommit, GitHubPullRequestFile, GitHubPullRequestReview, GitHubPullRequestWebhookPayload, GitHubPushWebhookPayload, GitHubRepo, GitHubRuleset, GitHubUser, GitHubVariable, GitHubWebhookHeaders, GitHubWorkflowRun, GitPull, GitRef, GitTree, GitTreeItem, InstallationAccessToken, IssueSearchParams, OrgProperty, PagesBuildStatus, PagesBuildType, PutContentsInput, PutContentsResult, ReviewThread, SecretScope, TeamMember, TeamPermission, UpdateCheckRunInput, UpdatePagesPayload, VariableScope, VariableVisibility, WorkflowRunFilter };

package/dist/index.mjs

@@ -76,11 +76,28 @@ function toBase64(text) {
 	return btoa(binary);
 }
 // src/branches/branches.ts
+/** Page size and the most pages {@link branches}`.listBranches` reads: 100 a page (GitHub's maximum) over 100 pages. */
+const BRANCH_PAGE_SIZE = 100;
+const BRANCH_MAX_PAGES = 100;
 function branches(rest) {
-	return { protectBranch: (repo, branch, payload) => rest.request(`${repoBase(repo)}/branches/${encodeURIComponent(branch)}/protection`, {
-		method: "PUT",
-		body: payload
-	}) };
+	return {
+		protectBranch: (repo, branch, payload) => rest.request(`${repoBase(repo)}/branches/${encodeURIComponent(branch)}/protection`, {
+			method: "PUT",
+			body: payload
+		}),
+		/** Every branch, read a page at a time until a page comes back short. */
+		listBranches: async (repo) => {
+			const all = [];
+			for (let page = 1; page <= BRANCH_MAX_PAGES; page++) {
+				const batch = await rest.request(`${repoBase(repo)}/branches?per_page=${BRANCH_PAGE_SIZE}&page=${page}`);
+				all.push(...batch);
+				if (batch.length < BRANCH_PAGE_SIZE) break;
+			}
+			return all;
+		},
+		/** Delete one branch's ref. The name keeps its `/`s; each segment is encoded. */
+		removeBranch: (repo, branch) => rest.request(`${repoBase(repo)}/git/refs/heads/${branch.split("/").map(encodeURIComponent).join("/")}`, { method: "DELETE" })
+	};
 }
 // src/checks/checks.ts
 /**
@@ -275,25 +292,31 @@ function pages(rest) {
 }
 // src/properties/properties.ts
 function properties(rest) {
-	return { 
-	/**
-	* `value` is a plain string for `string`/`single_select`/`true_false`
-	* custom properties, or a string array for `multi_select` ones —
-	* GitHub's own PATCH body accepts either per property. A single-string
-	* comma-joined value has no length ceiling GitHub documents, but real
-	* usage hits one in practice (a `string`-type property with enough
-	* joined values 422s as "too long"); `multi_select` has none.
-	*/
-setProperties: (repo, values) => {
-		const propertyList = Object.entries(values).map(([property_name, value]) => ({
-			property_name,
-			value
-		}));
-		return rest.request(`${repoBase(repo)}/properties/values`, {
-			method: "PATCH",
-			body: { properties: propertyList }
-		});
-	} };
+	return {
+		/**
+		* The custom properties an organization defines, with their types and allowed values (read-only).
+		* The token needs read access to the organization's custom properties.
+		*/
+		orgSchema: (org) => rest.request(`/orgs/${segment(org)}/properties/schema`),
+		/**
+		* `value` is a plain string for `string`/`single_select`/`true_false`
+		* custom properties, or a string array for `multi_select` ones —
+		* GitHub's own PATCH body accepts either per property. A single-string
+		* comma-joined value has no length ceiling GitHub documents, but real
+		* usage hits one in practice (a `string`-type property with enough
+		* joined values 422s as "too long"); `multi_select` has none.
+		*/
+		setProperties: (repo, values) => {
+			const propertyList = Object.entries(values).map(([property_name, value]) => ({
+				property_name,
+				value
+			}));
+			return rest.request(`${repoBase(repo)}/properties/values`, {
+				method: "PATCH",
+				body: { properties: propertyList }
+			});
+		}
+	};
 }
 // src/pulls/pulls.ts
 const LIST_REVIEW_THREADS_QUERY = `
@@ -325,10 +348,26 @@ const RESOLVE_REVIEW_THREAD_MUTATION = `
 		}
 	}
 `;
+/** Page size and the most pages {@link pulls}`.listPullRequests` reads: 100 a page (GitHub's maximum) over 100 pages, so 10,000 pull requests. */
+const PULL_REQUEST_PAGE_SIZE = 100;
+const PULL_REQUEST_MAX_PAGES = 100;
 function pulls(rest, graphql) {
 	return {
 		getPullRequest: (repo, number) => rest.request(`${repoBase(repo)}/pulls/${number}`),
 		/**
+		* Every pull request in one state, newest first, read a page at a time until a page comes back short.
+		* `closed` includes the merged ones; tell them apart by `merged_at`.
+		*/
+		listPullRequests: async (repo, state) => {
+			const all = [];
+			for (let page = 1; page <= PULL_REQUEST_MAX_PAGES; page++) {
+				const batch = await rest.request(`${repoBase(repo)}/pulls?state=${state}&sort=created&direction=desc&per_page=${PULL_REQUEST_PAGE_SIZE}&page=${page}`);
+				all.push(...batch);
+				if (batch.length < PULL_REQUEST_PAGE_SIZE) break;
+			}
+			return all;
+		},
+		/**
 		* A PR's own commits, in commit order. `per_page=100` — GitHub's max —
 		* covers every real PR in this org; a PR genuinely exceeding 100
 		* commits (GitHub caps this endpoint at 250 regardless of pagination)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.57.1-alpha.1",
+  "version": "1.58.0-alpha.1",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -32,14 +32,10 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/observability": "^0.6.0",
-    "@theholocron/http-client": "^1.57.1-alpha.1"
+    "@theholocron/http-client": "^1.58.0-alpha.1",
+    "@theholocron/observability": "^0.6.1-alpha.1"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.8.2",
-    "@theholocron/tsconfig": "^8.8.2",
-    "@theholocron/tsdown-config": "^8.8.2",
-    "@theholocron/vitest-config": "^8.8.2",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
     "@vitest/eslint-plugin": "^1.6.27",
@@ -48,7 +44,11 @@
     "globals": "^17.11.0",
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "@theholocron/tsconfig": "^8.9.0-alpha.3",
+    "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
+    "@theholocron/vitest-config": "^8.9.0-alpha.3"
   },
   "engines": {
     "node": ">=22.0.0"