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

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";
@@ -241,8 +248,12 @@ interface GitHubPullRequest {
   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). */
@@ -400,6 +411,18 @@ interface GitHubUser {
   name: string | null;
   email: string | null;
 }
+/** The authenticated user and, for a token that expires, when. */
+interface GitHubUserWithExpiry {
+  /** The authenticated user. */
+  user: GitHubUser;
+  /** When the token stops working, ISO 8601 in UTC. Absent for a token that never expires. */
+  expiresAt?: string;
+}
+/**
+ * The expiry GitHub reports in the `github-authentication-token-expiration` header (`2026-11-19 03:46:04 UTC`) as
+ * ISO 8601, or `undefined` when the header is missing or is not a date.
+ */
+export declare function parseTokenExpiration(header: string | null): string | undefined;
 interface GitHubWorkflowRun {
   id: number;
   name: string | null;
@@ -511,6 +534,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>;
@@ -575,6 +600,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
   };
   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>;
@@ -622,6 +648,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
   };
   user: {
     getCurrentUser: () => Promise<GitHubUser>;
+    getCurrentUserWithExpiry(): Promise<GitHubUserWithExpiry>;
   };
   workflows: {
     listRuns: (repo: string, filter?: WorkflowRunFilter) => Promise<GitHubWorkflowRun[]>;
@@ -630,4 +657,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, OrgProperty, 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, GitHubUserWithExpiry, 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
 /**
@@ -331,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)
@@ -516,8 +549,31 @@ function topics(rest) {
 	}) };
 }
 // src/user/user.ts
+/**
+* The expiry GitHub reports in the `github-authentication-token-expiration` header (`2026-11-19 03:46:04 UTC`) as
+* ISO 8601, or `undefined` when the header is missing or is not a date.
+*/
+function parseTokenExpiration(header) {
+	if (!header) return void 0;
+	const time = Date.parse(header.replace(/ UTC$/, "Z").replace(" ", "T"));
+	return Number.isNaN(time) ? void 0 : new Date(time).toISOString();
+}
 function user(rest) {
-	return { getCurrentUser: () => rest.request("/user") };
+	return {
+		getCurrentUser: () => rest.request("/user"),
+		/** The authenticated user plus when the token expires, read from the response header on the same call. */
+		async getCurrentUserWithExpiry() {
+			let header = null;
+			const me = await rest.request("/user", { onResponse: (headers) => {
+				header = headers.get("github-authentication-token-expiration");
+			} });
+			const expiresAt = parseTokenExpiration(header);
+			return expiresAt ? {
+				user: me,
+				expiresAt
+			} : { user: me };
+		}
+	};
 }
 // src/variables/variables.ts
 /** GitHub's maximum page size for this listing is 30, not the usual 100. */
@@ -838,4 +894,4 @@ function createGitHubClient(opts) {
 		workflows: workflows(rest)
 	};
 }
-export { MAX_CHECK_RUN_ANNOTATIONS, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };
+export { MAX_CHECK_RUN_ANNOTATIONS, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, parseTokenExpiration, verifyGitHubWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.57.1-alpha.2",
+  "version": "1.58.0-alpha.2",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -32,7 +32,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.57.1-alpha.2",
+    "@theholocron/http-client": "^1.58.0-alpha.2",
     "@theholocron/observability": "^0.6.1-alpha.1"
   },
   "devDependencies": {
@@ -45,8 +45,8 @@
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3",
     "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/tsconfig": "^8.9.0-alpha.3",
     "@theholocron/tsdown-config": "^8.9.0-alpha.3",
     "@theholocron/vitest-config": "^8.9.0-alpha.3"
   },