@theholocron/github-client 1.46.0 → 1.47.0

package/README.md

@@ -50,7 +50,7 @@ const blob = await client.git.createBlob("owner/name", "file contents");
 | `labels`       | `listLabels`, `createLabel`, `updateLabel`, `deleteLabel`                                                                                                                                               |
 | `topics`       | `setTopics`                                                                                                                                                                                             |
 | `properties`   | `setProperties`                                                                                                                                                                                         |
-| `git`          | `getRef`, `getCommit`, `getTree`, `getContents`, `createBlob`, `createTree`, `createCommit`, `createRef`, `updateRef`, `createPull`                                                                     |
+| `git`          | `getRef`, `getCommit`, `getTree`, `getContents`, `putContents`, `createBlob`, `createTree`, `createCommit`, `createRef`, `updateRef`, `createPull`                                                      |
 | `checks`       | `createCheckRun`                                                                                                                                                                                        |
 
 GitHub accepts at most 50 annotations per check-run request. Slice with the

package/dist/index.d.mts

@@ -131,6 +131,29 @@ interface GitContents {
   name: string;
   path: string;
 }
+/** What `git.putContents` returns: the file's new blob sha (the `sha` to pass next time) and the commit it made. */
+interface PutContentsResult {
+  content: {
+    sha: string;
+    path: string;
+  };
+  commit: {
+    sha: string;
+  };
+}
+interface PutContentsInput {
+  message: string;
+  /** The new file text (UTF-8); the client encodes it. */
+  content: string;
+  /**
+   * The blob `sha` of the file being replaced, from `getContents`. Required to update an existing file,
+   * and omitted to create one. This is what makes the write safe: if someone changed the file since it was
+   * read, GitHub refuses (409) instead of overwriting, so the caller can read again and retry.
+   */
+  sha?: string;
+  /** Defaults to the repo's default branch. */
+  branch?: string;
+}
 interface GitBlob {
   sha: string;
   url: string;
@@ -361,6 +384,12 @@ interface CodeScanningSetupResult {
 //#endregion
 //#region ../../../../../src/teams/teams.d.ts
 type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
+/** A member of a team, as GitHub lists it. `id` is the numeric user id, which survives a rename; `login` does not. */
+interface TeamMember {
+  id: number;
+  login: string;
+  type?: string;
+}
 //#endregion
 //#region ../../../../../src/user/user.d.ts
 interface GitHubUser {
@@ -502,6 +531,7 @@ declare function createGitHubClient(opts: GitHubClientOptions): {
     getCommit: (repo: string, sha: string) => Promise<GitCommit>;
     getTree: (repo: string, sha: string, recursive?: boolean) => Promise<GitTree>;
     getContents: (repo: string, path: string, ref?: string) => Promise<GitContents>;
+    putContents: (repo: string, path: string, input: PutContentsInput) => Promise<PutContentsResult>;
     createBlob: (repo: string, content: string, encoding?: string) => Promise<GitBlob>;
     createTree: (repo: string, tree: Array<{
       path: string;
@@ -581,6 +611,7 @@ declare function createGitHubClient(opts: GitHubClientOptions): {
     disableDefaultCodeScanning: (repo: string) => Promise<void>;
   };
   teams: {
+    members: (org: string, teamSlug: string) => Promise<TeamMember[]>;
     addRepo: (org: string, teamSlug: string, owner: string, repo: string, permission: TeamPermission) => Promise<void>;
   };
   topics: {
@@ -597,4 +628,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 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, MAX_CHECK_RUN_ANNOTATIONS, type PagesBuildStatus, type PagesBuildType, type ReviewThread, 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, MAX_CHECK_RUN_ANNOTATIONS, type PagesBuildStatus, type PagesBuildType, type PutContentsInput, type PutContentsResult, type ReviewThread, type SecretScope, type TeamMember, type TeamPermission, type UpdateCheckRunInput, type UpdatePagesPayload, type WorkflowRunFilter, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };

package/dist/index.mjs

@@ -58,6 +58,24 @@ function splitRepo(repo) {
 	const [owner, name] = repo.split("/", 2);
 	return [owner ?? "", name ?? ""];
 }
+/**
+* One URL path segment from a caller-supplied name (an org, a team slug). `.` and `..` are refused because
+* `new URL` would resolve them, sending the authenticated request to a different resource.
+*/
+function segment(value) {
+	if (value === "" || value === "." || value === "..") throw new Error(`invalid path segment: ${JSON.stringify(value)}`);
+	return encodeURIComponent(value);
+}
+/** A repo file path with each segment encoded, so `?` and `#` stay part of the name and `..` cannot climb out. */
+function filePath(path) {
+	return path.split("/").map(segment).join("/");
+}
+/** UTF-8 text as base64 without `Buffer`, so it runs in Workers and browsers as well as Node. */
+function toBase64(text) {
+	let binary = "";
+	for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
 //#endregion
 //#region ../../../../../src/branches/branches.ts
 function branches(rest) {
@@ -119,6 +137,19 @@ function git(rest) {
 		* (D6-amended, `tech-sentinel-ci-runner.spec.md`), just never a fork's.
 		*/
 		getContents: (repo, path, ref) => rest.request(`${repoBase(repo)}/contents/${path}`, ref ? { query: { ref } } : void 0),
+		/**
+		* `PUT /repos/:repo/contents/:path` — creates or updates one file in a single commit. Pass `sha` when
+		* updating so a concurrent change is refused (409) and not silently overwritten.
+		*/
+		putContents: (repo, path, input) => rest.request(`${repoBase(repo)}/contents/${filePath(path)}`, {
+			method: "PUT",
+			body: {
+				message: input.message,
+				content: toBase64(input.content),
+				...input.sha ? { sha: input.sha } : {},
+				...input.branch ? { branch: input.branch } : {}
+			}
+		}),
 		createBlob: (repo, content, encoding = "utf-8") => rest.request(`${repoBase(repo)}/git/blobs`, {
 			method: "POST",
 			body: {
@@ -456,11 +487,35 @@ function security(rest) {
 }
 //#endregion
 //#region ../../../../../src/teams/teams.ts
+const PAGE = 100;
+/** A guard so a runaway listing cannot loop forever: 50 pages of 100 is far more than any team. */
+const MAX_PAGES = 50;
 function teams(rest) {
-	return { addRepo: (org, teamSlug, owner, repo, permission) => rest.request(`/orgs/${org}/teams/${teamSlug}/repos/${owner}/${repo}`, {
-		method: "PUT",
-		body: { permission }
-	}) };
+	return {
+		/**
+		* Every member of a team (maintainers included), read page by page. Members of child teams are
+		* included, as GitHub does. A 404 means the team does not exist or the token cannot see it.
+		*/
+		members: async (org, teamSlug) => {
+			const path = `/orgs/${segment(org)}/teams/${segment(teamSlug)}/members`;
+			const read = (page) => rest.request(path, { query: {
+				per_page: String(PAGE),
+				page: String(page)
+			} });
+			const all = [];
+			for (let page = 1; page <= MAX_PAGES; page++) {
+				const batch = await read(page);
+				all.push(...batch);
+				if (batch.length < PAGE) return all;
+			}
+			if ((await read(51)).length > 0) throw new Error(`team ${org}/${teamSlug} has more than 5000 members; refusing to read them all`);
+			return all;
+		},
+		addRepo: (org, teamSlug, owner, repo, permission) => rest.request(`/orgs/${org}/teams/${teamSlug}/repos/${owner}/${repo}`, {
+			method: "PUT",
+			body: { permission }
+		})
+	};
 }
 //#endregion
 //#region ../../../../../src/topics/topics.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@theholocron/observability": "^0.3.0",
-    "@theholocron/http-client": "^1.46.0"
+    "@theholocron/http-client": "^1.47.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.79",