@theholocron/github-client 0.1.0 → 0.3.2

package/README.md

@@ -0,0 +1,53 @@
+# @theholocron/github-client
+
+TypeScript client for the GitHub REST API, built on `@theholocron/http-client`.
+
+## Install
+
+```bash
+npm i @theholocron/github-client
+```
+
+## Usage
+
+```ts
+import { createGitHubClient } from "@theholocron/github-client";
+
+const client = createGitHubClient({ token: process.env.GITHUB_TOKEN! });
+
+// Repos
+const repo = await client.repos.getRepo("owner/name");
+
+// Labels
+const labels = await client.labels.listLabels("owner/name");
+await client.labels.createLabel("owner/name", {
+  name: "bug",
+  color: "d73a4a",
+  description: "Something isn't working",
+});
+
+// Topics
+await client.topics.setTopics("owner/name", ["cli", "nodejs"]);
+
+// Git plumbing (blobs, trees, commits, refs, PRs)
+const ref = await client.git.getRef("owner/name", "main");
+const blob = await client.git.createBlob("owner/name", "file contents");
+```
+
+## Namespaces
+
+| Namespace      | Methods                                                                                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `user`         | `getCurrentUser`                                                                                                                                                                                        |
+| `repos`        | `getRepo`, `updateRepo`, `getContents`                                                                                                                                                                  |
+| `security`     | `enableVulnerabilityAlerts`, `enableAutomatedSecurityFixes`, `enableSecretScanning`, `enablePrivateVulnerabilityReporting`, `enableDependencyGraph`, `enableCodeScanning`, `disableDefaultCodeScanning` |
+| `rulesets`     | `listRulesets`, `createRuleset`, `updateRuleset`                                                                                                                                                        |
+| `branches`     | `protectBranch`                                                                                                                                                                                         |
+| `workflows`    | `listRuns`, `getRun`                                                                                                                                                                                    |
+| `secrets`      | `listSecrets`, `getPublicKey`, `putSecret`, `deleteSecret`                                                                                                                                              |
+| `environments` | `listEnvironments`, `upsertEnvironment`, `deleteEnvironment`                                                                                                                                            |
+| `issues`       | `listIssues`, `getIssue`, `createIssue`, `updateIssue`, `addLabels`, `removeLabel`, `createComment`, `listMilestones`                                                                                   |
+| `labels`       | `listLabels`, `createLabel`, `updateLabel`, `deleteLabel`                                                                                                                                               |
+| `topics`       | `setTopics`                                                                                                                                                                                             |
+| `properties`   | `setProperties`                                                                                                                                                                                         |
+| `git`          | `getRef`, `getCommit`, `getTree`, `getContents`, `createBlob`, `createTree`, `createCommit`, `createRef`, `updateRef`, `createPull`                                                                     |

package/dist/index.d.mts

@@ -0,0 +1,273 @@
+import "@theholocron/http-client";
+//#region src/utils.d.ts
+interface GitHubClientOptions {
+  token: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+//#endregion
+//#region src/environments/environments.d.ts
+interface GitHubEnvironment {
+  name: string;
+  wait_timer?: number;
+  prevent_self_review?: boolean;
+  protection_rules?: Array<{
+    type: string;
+    reviewers?: Array<{
+      type: "User" | "Team";
+      reviewer: {
+        id: number;
+      };
+    }>;
+  }>;
+}
+//#endregion
+//#region src/git/git.d.ts
+interface GitRef {
+  object: {
+    sha: string;
+    type: string;
+    url: string;
+  };
+  ref: string;
+  url: string;
+}
+interface GitCommit {
+  sha: string;
+  tree: {
+    sha: string;
+    url: string;
+  };
+}
+interface GitTreeItem {
+  path: string;
+  sha: string;
+  type: string;
+  mode?: string;
+  size?: number;
+}
+interface GitTree {
+  sha: string;
+  tree: GitTreeItem[];
+  truncated: boolean;
+}
+interface GitContents {
+  content: string;
+  encoding: string;
+  sha: string;
+  name: string;
+  path: string;
+}
+interface GitBlob {
+  sha: string;
+  url: string;
+}
+interface GitPull {
+  number: number;
+  html_url: string;
+  title: string;
+}
+interface CreatePullInput {
+  title: string;
+  head: string;
+  base: string;
+  body?: string;
+}
+//#endregion
+//#region src/issues/issues.d.ts
+interface GitHubIssue {
+  id: number;
+  number: number;
+  title: string;
+  body?: string | null;
+  state: "open" | "closed";
+  labels: Array<{
+    name: string;
+  }>;
+  assignee: {
+    login: string;
+    name?: string | null;
+    email?: string | null;
+  } | null;
+  updated_at: string;
+  html_url: string;
+  pull_request?: unknown;
+}
+interface GitHubMilestone {
+  number: number;
+  title: string;
+}
+interface IssueSearchParams {
+  state?: "open" | "closed" | "all";
+  sort?: string;
+  direction?: string;
+  per_page?: number;
+  filter?: string;
+  assignee?: string;
+}
+//#endregion
+//#region src/labels/labels.d.ts
+interface GitHubLabel {
+  name: string;
+  color: string;
+  description: string | null;
+}
+//#endregion
+//#region src/repos/repos.d.ts
+interface GitHubRepo {
+  default_branch: string;
+  full_name: string;
+}
+interface GitHubContents {
+  content: string;
+  encoding: string;
+}
+//#endregion
+//#region src/rulesets/rulesets.d.ts
+interface GitHubRuleset {
+  id: number;
+  name: string;
+  enforcement: string;
+}
+//#endregion
+//#region src/secrets/secrets.d.ts
+type SecretScope = {
+  kind: "repo";
+} | {
+  kind: "environment";
+  name: string;
+} | {
+  kind: "organization";
+  org: string;
+};
+interface GitHubPublicKey {
+  key_id: string;
+  key: string;
+}
+//#endregion
+//#region src/security/security.d.ts
+interface CodeScanningSetupResult {
+  run_id: number;
+  run_url: string;
+}
+//#endregion
+//#region src/user/user.d.ts
+interface GitHubUser {
+  login: string;
+  name: string | null;
+  email: string | null;
+}
+//#endregion
+//#region src/workflows/workflows.d.ts
+interface GitHubWorkflowRun {
+  id: number;
+  name: string | null;
+  display_title: string;
+  head_branch: string;
+  head_sha: string;
+  status: string;
+  conclusion: string | null;
+  html_url: string;
+  created_at: string;
+  updated_at: string;
+}
+interface WorkflowRunFilter {
+  branch?: string;
+  limit?: number;
+  status?: string;
+}
+//#endregion
+//#region src/index.d.ts
+declare function createGitHubClient(opts: GitHubClientOptions): {
+  branches: {
+    protectBranch: (repo: string, branch: string, payload: Record<string, unknown>) => Promise<void>;
+  };
+  environments: {
+    listEnvironments: (repo: string) => Promise<GitHubEnvironment[]>;
+    upsertEnvironment: (repo: string, name: string, body: Record<string, unknown>) => Promise<void>;
+    deleteEnvironment: (repo: string, name: string) => Promise<void>;
+  };
+  git: {
+    getRef: (repo: string, branch: string) => Promise<GitRef>;
+    getCommit: (repo: string, sha: string) => Promise<GitCommit>;
+    getTree: (repo: string, sha: string, recursive?: boolean) => Promise<GitTree>;
+    getContents: (repo: string, path: string) => Promise<GitContents>;
+    createBlob: (repo: string, content: string, encoding?: string) => Promise<GitBlob>;
+    createTree: (repo: string, tree: Array<{
+      path: string;
+      mode: string;
+      type: string;
+      sha: string;
+    }>, baseTree?: string) => Promise<GitTree>;
+    createCommit: (repo: string, message: string, tree: string, parents: string[]) => Promise<GitCommit>;
+    createRef: (repo: string, ref: string, sha: string) => Promise<GitRef>;
+    updateRef: (repo: string, ref: string, sha: string, force?: boolean) => Promise<GitRef>;
+    createPull: (repo: string, input: CreatePullInput) => Promise<GitPull>;
+  };
+  issues: {
+    listIssues: (repo: string, params?: IssueSearchParams) => Promise<GitHubIssue[]>;
+    getIssue: (repo: string, number: number) => Promise<GitHubIssue>;
+    createIssue: (repo: string, body: Record<string, unknown>) => Promise<GitHubIssue>;
+    updateIssue: (repo: string, number: number, body: Record<string, unknown>) => Promise<GitHubIssue>;
+    addLabels: (repo: string, number: number, labels: string[]) => Promise<void>;
+    removeLabel: (repo: string, number: number, label: string) => Promise<void>;
+    createComment: (repo: string, number: number, body: string) => Promise<void>;
+    listMilestones: (repo: string, params?: {
+      state?: "open" | "closed" | "all";
+    }) => Promise<GitHubMilestone[]>;
+  };
+  labels: {
+    listLabels: (repo: string) => Promise<GitHubLabel[]>;
+    createLabel: (repo: string, body: {
+      name: string;
+      color: string;
+      description: string;
+    }) => Promise<GitHubLabel>;
+    updateLabel: (repo: string, name: string, body: {
+      color?: string;
+      description?: string;
+    }) => Promise<GitHubLabel>;
+    deleteLabel: (repo: string, name: string) => Promise<void>;
+  };
+  properties: {
+    setProperties: (repo: string, values: Record<string, string>) => Promise<void>;
+  };
+  repos: {
+    getRepo: (repo: string) => Promise<GitHubRepo>;
+    updateRepo: (repo: string, settings: Record<string, unknown>) => Promise<void>;
+    getContents: (repo: string, path: string) => Promise<GitHubContents>;
+  };
+  rulesets: {
+    listRulesets: (repo: string) => Promise<GitHubRuleset[]>;
+    createRuleset: (repo: string, payload: Record<string, unknown>) => Promise<GitHubRuleset>;
+    updateRuleset: (repo: string, id: number, payload: Record<string, unknown>) => Promise<GitHubRuleset>;
+  };
+  secrets: {
+    listSecrets: (repo: string, scope: SecretScope) => Promise<string[]>;
+    getPublicKey: (repo: string, scope: SecretScope) => Promise<GitHubPublicKey>;
+    putSecret: (repo: string, scope: SecretScope, name: string, body: Record<string, unknown>) => Promise<void>;
+    deleteSecret: (repo: string, scope: SecretScope, name: string) => Promise<void>;
+  };
+  security: {
+    enableVulnerabilityAlerts: (repo: string) => Promise<void>;
+    enableAutomatedSecurityFixes: (repo: string) => Promise<void>;
+    enableSecretScanning: (repo: string) => Promise<void>;
+    enablePrivateVulnerabilityReporting: (repo: string) => Promise<void>;
+    enableDependencyGraph: (repo: string) => Promise<void>;
+    enableCodeScanning: (repo: string) => Promise<CodeScanningSetupResult>;
+    disableDefaultCodeScanning: (repo: string) => Promise<void>;
+  };
+  topics: {
+    setTopics: (repo: string, names: string[]) => Promise<void>;
+  };
+  user: {
+    getCurrentUser: () => Promise<GitHubUser>;
+  };
+  workflows: {
+    listRuns: (repo: string, filter?: WorkflowRunFilter) => Promise<GitHubWorkflowRun[]>;
+    getRun: (repo: string, id: string | number) => Promise<GitHubWorkflowRun>;
+  };
+};
+type GitHubClient = ReturnType<typeof createGitHubClient>;
+//#endregion
+export { type CodeScanningSetupResult, type CreatePullInput, type GitBlob, type GitCommit, type GitContents, GitHubClient, type GitHubClientOptions, type GitHubContents, type GitHubEnvironment, type GitHubIssue, type GitHubLabel, type GitHubMilestone, type GitHubPublicKey, type GitHubRepo, type GitHubRuleset, type GitHubUser, type GitHubWorkflowRun, type GitPull, type GitRef, type GitTree, type GitTreeItem, type IssueSearchParams, type SecretScope, type WorkflowRunFilter, createGitHubClient };

package/dist/index.mjs

@@ -0,0 +1,311 @@
+import { createRestClient } from "@theholocron/http-client";
+//#region src/utils.ts
+function createGitHubRestClient(opts) {
+	return createRestClient({
+		baseUrl: opts.baseUrl ?? "https://api.github.com",
+		token: opts.token,
+		extraHeaders: {
+			accept: "application/vnd.github+json",
+			"x-github-api-version": "2022-11-28"
+		},
+		vendor: "GitHub",
+		fetch: opts.fetch
+	});
+}
+/** `/repos/owner/name` prefix from a `"owner/name"` repo string. */
+function repoBase(repo) {
+	const [owner, name] = repo.split("/", 2);
+	return `/repos/${owner}/${name}`;
+}
+//#endregion
+//#region src/branches/branches.ts
+function branches(rest) {
+	return { protectBranch: (repo, branch, payload) => rest.request(`${repoBase(repo)}/branches/${encodeURIComponent(branch)}/protection`, {
+		method: "PUT",
+		body: payload
+	}) };
+}
+//#endregion
+//#region src/environments/environments.ts
+function environments(rest) {
+	return {
+		listEnvironments: (repo) => rest.request(`${repoBase(repo)}/environments`).then((r) => r.environments),
+		upsertEnvironment: (repo, name, body) => rest.request(`${repoBase(repo)}/environments/${encodeURIComponent(name)}`, {
+			method: "PUT",
+			body
+		}),
+		deleteEnvironment: (repo, name) => rest.request(`${repoBase(repo)}/environments/${encodeURIComponent(name)}`, {
+			method: "DELETE",
+			expectNoContent: true
+		})
+	};
+}
+//#endregion
+//#region src/git/git.ts
+function git(rest) {
+	return {
+		getRef: (repo, branch) => rest.request(`${repoBase(repo)}/git/ref/heads/${branch}`),
+		getCommit: (repo, sha) => rest.request(`${repoBase(repo)}/git/commits/${sha}`),
+		getTree: (repo, sha, recursive = false) => rest.request(`${repoBase(repo)}/git/trees/${sha}${recursive ? "?recursive=1" : ""}`),
+		getContents: (repo, path) => rest.request(`${repoBase(repo)}/contents/${path}`),
+		createBlob: (repo, content, encoding = "utf-8") => rest.request(`${repoBase(repo)}/git/blobs`, {
+			method: "POST",
+			body: {
+				content,
+				encoding
+			}
+		}),
+		createTree: (repo, tree, baseTree) => rest.request(`${repoBase(repo)}/git/trees`, {
+			method: "POST",
+			body: {
+				base_tree: baseTree,
+				tree
+			}
+		}),
+		createCommit: (repo, message, tree, parents) => rest.request(`${repoBase(repo)}/git/commits`, {
+			method: "POST",
+			body: {
+				message,
+				tree,
+				parents
+			}
+		}),
+		createRef: (repo, ref, sha) => rest.request(`${repoBase(repo)}/git/refs`, {
+			method: "POST",
+			body: {
+				ref,
+				sha
+			}
+		}),
+		updateRef: (repo, ref, sha, force = false) => rest.request(`${repoBase(repo)}/git/refs/${ref}`, {
+			method: "PATCH",
+			body: {
+				sha,
+				force
+			}
+		}),
+		createPull: (repo, input) => rest.request(`${repoBase(repo)}/pulls`, {
+			method: "POST",
+			body: input
+		})
+	};
+}
+//#endregion
+//#region src/issues/issues.ts
+function issues(rest) {
+	return {
+		listIssues: (repo, params = {}) => {
+			const qs = new URLSearchParams();
+			if (params.state) qs.set("state", params.state);
+			if (params.sort) qs.set("sort", params.sort);
+			if (params.direction) qs.set("direction", params.direction);
+			if (params.per_page) qs.set("per_page", String(params.per_page));
+			if (params.filter) qs.set("filter", params.filter);
+			if (params.assignee) qs.set("assignee", params.assignee);
+			const q = qs.toString();
+			const path = q ? `${repoBase(repo)}/issues?${q}` : `${repoBase(repo)}/issues`;
+			return rest.request(path);
+		},
+		getIssue: (repo, number) => rest.request(`${repoBase(repo)}/issues/${number}`),
+		createIssue: (repo, body) => rest.request(`${repoBase(repo)}/issues`, {
+			method: "POST",
+			body
+		}),
+		updateIssue: (repo, number, body) => rest.request(`${repoBase(repo)}/issues/${number}`, {
+			method: "PATCH",
+			body
+		}),
+		addLabels: (repo, number, labels) => rest.request(`${repoBase(repo)}/issues/${number}/labels`, {
+			method: "POST",
+			body: { labels }
+		}),
+		removeLabel: (repo, number, label) => rest.request(`${repoBase(repo)}/issues/${number}/labels/${encodeURIComponent(label)}`, { method: "DELETE" }),
+		createComment: (repo, number, body) => rest.request(`${repoBase(repo)}/issues/${number}/comments`, {
+			method: "POST",
+			body: { body }
+		}),
+		listMilestones: (repo, params = {}) => {
+			const qs = new URLSearchParams({ per_page: "100" });
+			if (params.state) qs.set("state", params.state);
+			return rest.request(`${repoBase(repo)}/milestones?${qs.toString()}`);
+		}
+	};
+}
+//#endregion
+//#region src/labels/labels.ts
+function labels(rest) {
+	return {
+		listLabels: (repo) => rest.request(`${repoBase(repo)}/labels?per_page=100`),
+		createLabel: (repo, body) => rest.request(`${repoBase(repo)}/labels`, {
+			method: "POST",
+			body
+		}),
+		updateLabel: (repo, name, body) => rest.request(`${repoBase(repo)}/labels/${encodeURIComponent(name)}`, {
+			method: "PATCH",
+			body
+		}),
+		deleteLabel: (repo, name) => rest.request(`${repoBase(repo)}/labels/${encodeURIComponent(name)}`, { method: "DELETE" })
+	};
+}
+//#endregion
+//#region src/properties/properties.ts
+function properties(rest) {
+	return { 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 }
+		});
+	} };
+}
+//#endregion
+//#region src/repos/repos.ts
+function repos(rest) {
+	return {
+		getRepo: (repo) => rest.request(repoBase(repo)),
+		updateRepo: (repo, settings) => rest.request(repoBase(repo), {
+			method: "PATCH",
+			body: settings
+		}),
+		getContents: (repo, path) => rest.request(`${repoBase(repo)}/contents/${path}`)
+	};
+}
+//#endregion
+//#region src/rulesets/rulesets.ts
+function rulesets(rest) {
+	return {
+		listRulesets: (repo) => rest.request(`${repoBase(repo)}/rulesets`),
+		createRuleset: (repo, payload) => rest.request(`${repoBase(repo)}/rulesets`, {
+			method: "POST",
+			body: payload
+		}),
+		updateRuleset: (repo, id, payload) => rest.request(`${repoBase(repo)}/rulesets/${id}`, {
+			method: "PUT",
+			body: payload
+		})
+	};
+}
+//#endregion
+//#region src/secrets/secrets.ts
+function scopeBase(repo, scope) {
+	switch (scope.kind) {
+		case "repo": return `${repoBase(repo)}/actions`;
+		case "environment": return `${repoBase(repo)}/environments/${scope.name}`;
+		case "organization": return `/orgs/${scope.org}/actions`;
+	}
+}
+function secrets(rest) {
+	return {
+		listSecrets: (repo, scope) => rest.request(`${scopeBase(repo, scope)}/secrets`).then((r) => r.secrets.map((s) => s.name)),
+		getPublicKey: (repo, scope) => rest.request(`${scopeBase(repo, scope)}/secrets/public-key`),
+		putSecret: (repo, scope, name, body) => rest.request(`${scopeBase(repo, scope)}/secrets/${name}`, {
+			method: "PUT",
+			body,
+			expectNoContent: true
+		}),
+		deleteSecret: (repo, scope, name) => rest.request(`${scopeBase(repo, scope)}/secrets/${name}`, {
+			method: "DELETE",
+			expectNoContent: true
+		})
+	};
+}
+//#endregion
+//#region src/security/security.ts
+function security(rest) {
+	return {
+		enableVulnerabilityAlerts: (repo) => rest.request(`${repoBase(repo)}/vulnerability-alerts`, {
+			method: "PUT",
+			expectNoContent: true
+		}),
+		enableAutomatedSecurityFixes: (repo) => rest.request(`${repoBase(repo)}/automated-security-fixes`, {
+			method: "PUT",
+			expectNoContent: true
+		}),
+		enableSecretScanning: (repo) => rest.request(repoBase(repo), {
+			method: "PATCH",
+			body: { security_and_analysis: {
+				secret_scanning: { status: "enabled" },
+				secret_scanning_push_protection: { status: "enabled" },
+				secret_scanning_validity_checks: { status: "enabled" },
+				secret_scanning_non_provider_patterns: { status: "enabled" }
+			} }
+		}),
+		enablePrivateVulnerabilityReporting: (repo) => rest.request(`${repoBase(repo)}/private-vulnerability-reporting`, {
+			method: "PUT",
+			expectNoContent: true
+		}),
+		enableDependencyGraph: (repo) => rest.request(repoBase(repo), {
+			method: "PATCH",
+			body: { security_and_analysis: {
+				dependency_graph: { status: "enabled" },
+				dependency_graph_autosubmit_action: { status: "enabled" }
+			} }
+		}),
+		enableCodeScanning: (repo) => rest.request(`${repoBase(repo)}/code-scanning/default-setup`, {
+			method: "PATCH",
+			body: {
+				state: "configured",
+				query_suite: "extended",
+				threat_model: "remote_and_local"
+			}
+		}),
+		disableDefaultCodeScanning: (repo) => rest.request(`${repoBase(repo)}/code-scanning/default-setup`, {
+			method: "PATCH",
+			body: { state: "not-configured" }
+		})
+	};
+}
+//#endregion
+//#region src/topics/topics.ts
+function topics(rest) {
+	return { setTopics: (repo, names) => rest.request(`${repoBase(repo)}/topics`, {
+		method: "PUT",
+		body: { names }
+	}) };
+}
+//#endregion
+//#region src/user/user.ts
+function user(rest) {
+	return { getCurrentUser: () => rest.request("/user") };
+}
+//#endregion
+//#region src/workflows/workflows.ts
+function workflows(rest) {
+	return {
+		listRuns: (repo, filter) => {
+			const params = new URLSearchParams();
+			if (filter?.branch) params.set("branch", filter.branch);
+			if (filter?.limit) params.set("per_page", String(filter.limit));
+			if (filter?.status) params.set("status", filter.status);
+			const qs = params.toString();
+			const path = qs ? `${repoBase(repo)}/actions/runs?${qs}` : `${repoBase(repo)}/actions/runs`;
+			return rest.request(path).then((r) => r.workflow_runs);
+		},
+		getRun: (repo, id) => rest.request(`${repoBase(repo)}/actions/runs/${id}`)
+	};
+}
+//#endregion
+//#region src/index.ts
+function createGitHubClient(opts) {
+	const rest = createGitHubRestClient(opts);
+	return {
+		branches: branches(rest),
+		environments: environments(rest),
+		git: git(rest),
+		issues: issues(rest),
+		labels: labels(rest),
+		properties: properties(rest),
+		repos: repos(rest),
+		rulesets: rulesets(rest),
+		secrets: secrets(rest),
+		security: security(rest),
+		topics: topics(rest),
+		user: user(rest),
+		workflows: workflows(rest)
+	};
+}
+//#endregion
+export { createGitHubClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "0.1.0",
+  "version": "0.3.2",
   "description": "A TypeScript client for the GitHub REST API",
   "homepage": "https://github.com/theholocron/clients/tree/main/packages/github-client#readme",
   "bugs": "https://github.com/theholocron/clients/issues",