@theholocron/github-client 1.58.0-alpha.13 → 1.58.0-alpha.14

package/dist/index.d.mts

@@ -799,6 +799,41 @@ export declare function createAppJWT(creds: GitHubAppCredentials, now?: number):
 export declare function getInstallationAccessToken(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<InstallationAccessToken>;
 /** The whole flow in one call — an already-authenticated `GitHubClient` scoped to one installation. */
 export declare function createInstallationClient(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubClient>;
+/** The account an App or one of its installations belongs to. */
+interface GitHubAppAccount {
+  /** The user or organization login. */
+  login: string;
+  /** `User` or `Organization` (GitHub also reports `Enterprise` for an enterprise-owned App). */
+  type: string;
+}
+/** An App as `GET /app` reports it. */
+interface GitHubApp {
+  /** The App's URL name, as in `github.com/apps/<slug>`. */
+  slug: string;
+  /** The App's display name. */
+  name: string;
+  /** Who owns the App: decides which settings page its permissions live on. */
+  owner: GitHubAppAccount | null;
+  /** The permissions the App asks for now: name to `read`, `write` or `admin`. */
+  permissions: Record<string, string>;
+  /** The webhook events the App is subscribed to now. */
+  events: string[];
+}
+/** One installation of an App as `GET /app/installations` reports it. */
+interface GitHubAppInstallation {
+  /** The installation id. */
+  id: number;
+  /** The account the App is installed on. */
+  account: GitHubAppAccount | null;
+  /** What this installation has accepted: it lags the App's own list until an owner accepts a new request. */
+  permissions: Record<string, string>;
+  /** The events delivered to this installation. */
+  events: string[];
+}
+/** The App this JWT identifies: its slug, owner and the permissions and events it asks for now. */
+export declare function getApp(creds: GitHubAppCredentials, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubApp>;
+/** Every installation of the App this JWT identifies, with what each has accepted. Reads all pages. */
+export declare function listAppInstallations(creds: GitHubAppCredentials, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubAppInstallation[]>;
 /**
  * GitHub's own webhook mechanics — signature verification and header/
  * payload shapes. Pure functions, no REST call, no auth token: these
@@ -1035,4 +1070,4 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
 };
 /** The client returned by `createGitHubClient()`: one group of methods per GitHub API area. */
 export type GitHubClient = ReturnType<typeof createGitHubClient>;
-export type { CheckRunAnnotation, CheckRunAnnotationLevel, CheckRunConclusion, CheckRunOutput, CheckRunStatus, CodeScanningSetupResult, CreateCheckRunInput, CreatePagesPayload, CreatePullInput, CreateReviewComment, CreateReviewInput, GitBlob, GitCommit, GitContents, GitDirectoryEntry, GitHubAppCredentials, GitHubCheckRun, GitHubClientOptions, GitHubContents, GitHubEnvironment, GitHubInstallationWebhookPayload, GitHubIssue, GitHubLabel, GitHubMilestone, GitHubPages, GitHubPublicKey, GitHubPullRequest, GitHubPullRequestCommit, GitHubPullRequestFile, GitHubPullRequestReview, GitHubPullRequestWebhookPayload, GitHubPushWebhookPayload, GitHubRepo, GitHubRuleset, GitHubRulesetDetail, GitHubUser, GitHubUserWithExpiry, GitHubVariable, GitHubWebhookHeaders, GitHubWorkflowRun, GitPull, GitRef, GitTree, GitTreeItem, GraphQLClient, InstallationAccessToken, IssueSearchParams, ListDirectoryOptions, OrgProperty, PagesBuildStatus, PagesBuildType, PutContentsInput, PutContentsResult, RepoPropertyValue, RepoTeam, 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, GitDirectoryEntry, GitHubApp, GitHubAppAccount, GitHubAppCredentials, GitHubAppInstallation, GitHubCheckRun, GitHubClientOptions, GitHubContents, GitHubEnvironment, GitHubInstallationWebhookPayload, GitHubIssue, GitHubLabel, GitHubMilestone, GitHubPages, GitHubPublicKey, GitHubPullRequest, GitHubPullRequestCommit, GitHubPullRequestFile, GitHubPullRequestReview, GitHubPullRequestWebhookPayload, GitHubPushWebhookPayload, GitHubRepo, GitHubRuleset, GitHubRulesetDetail, GitHubUser, GitHubUserWithExpiry, GitHubVariable, GitHubWebhookHeaders, GitHubWorkflowRun, GitPull, GitRef, GitTree, GitTreeItem, GraphQLClient, InstallationAccessToken, IssueSearchParams, ListDirectoryOptions, OrgProperty, PagesBuildStatus, PagesBuildType, PutContentsInput, PutContentsResult, RepoPropertyValue, RepoTeam, ReviewThread, SecretScope, TeamMember, TeamPermission, UpdateCheckRunInput, UpdatePagesPayload, VariableScope, VariableVisibility, WorkflowRunFilter };

package/dist/index.mjs

@@ -891,6 +891,62 @@ async function createInstallationClient(creds, installationId, opts = {}) {
 		fetch: opts.fetch
 	});
 }
+// src/app-info/app-info.ts
+/**
+* What a GitHub App is right now, read with the App's own JWT (`GET /app`, `GET /app/installations`). GitHub has no
+* endpoint that changes an existing App's permissions or event subscriptions, so these reads are how a caller
+* checks the settings page was done by hand.
+*
+* https://docs.github.com/en/rest/apps/apps#get-the-authenticated-app
+* https://docs.github.com/en/rest/apps/apps#list-installations-for-the-authenticated-app
+*/
+const PAGE_SIZE = 100;
+const account = (value) => {
+	const { login, type } = value ?? {};
+	return typeof login === "string" ? {
+		login,
+		type: typeof type === "string" ? type : ""
+	} : null;
+};
+async function appGet(creds, path, opts) {
+	const jwt = await createAppJWT(creds);
+	const baseUrl = opts.baseUrl ?? "https://api.github.com";
+	const res = await (opts.fetch ?? globalThis.fetch)(`${baseUrl}${path}`, { headers: {
+		authorization: `Bearer ${jwt}`,
+		accept: "application/vnd.github+json",
+		"x-github-api-version": "2022-11-28"
+	} });
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new ProviderApiError(`GitHub GET ${path} → ${res.status}`, res.status, body);
+	}
+	return res.json();
+}
+/** The App this JWT identifies: its slug, owner and the permissions and events it asks for now. */
+async function getApp(creds, opts = {}) {
+	const raw = await appGet(creds, "/app", opts);
+	return {
+		slug: String(raw.slug),
+		name: String(raw.name),
+		owner: account(raw.owner),
+		permissions: raw.permissions ?? {},
+		events: raw.events ?? []
+	};
+}
+/** Every installation of the App this JWT identifies, with what each has accepted. Reads all pages. */
+async function listAppInstallations(creds, opts = {}) {
+	const installations = [];
+	for (let page = 1;; page++) {
+		const raws = await appGet(creds, `/app/installations?per_page=${PAGE_SIZE}&page=${page}`, opts);
+		for (const raw of raws) installations.push({
+			id: Number(raw.id),
+			account: account(raw.account),
+			permissions: raw.permissions ?? {},
+			events: raw.events ?? []
+		});
+		if (raws.length < PAGE_SIZE) return installations;
+	}
+}
 // src/webhooks/webhooks.ts
 /**
 * GitHub's own webhook mechanics — signature verification and header/
@@ -964,4 +1020,4 @@ function createGitHubClient(opts) {
 		workflows: workflows(rest)
 	};
 }
-export { MAX_CHECK_RUN_ANNOTATIONS, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, parseTokenExpiration, verifyGitHubWebhookSignature };
+export { MAX_CHECK_RUN_ANNOTATIONS, createAppJWT, createGitHubClient, createInstallationClient, getApp, getInstallationAccessToken, listAppInstallations, parseGitHubWebhookHeaders, parseTokenExpiration, verifyGitHubWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.58.0-alpha.13",
+  "version": "1.58.0-alpha.14",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -32,8 +32,8 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/observability": "^0.7.0-alpha.1",
-    "@theholocron/http-client": "^1.58.0-alpha.13"
+    "@theholocron/http-client": "^1.58.0-alpha.14",
+    "@theholocron/observability": "^0.7.0-alpha.1"
   },
   "devDependencies": {
     "@types/node": "^26",
@@ -47,8 +47,8 @@
     "vitest": "^5.0.5",
     "@theholocron/eslint-config": "^8.9.0-alpha.9",
     "@theholocron/tsdown-config": "^8.9.0-alpha.9",
-    "@theholocron/vitest-config": "^8.9.0-alpha.9",
-    "@theholocron/tsconfig": "^8.9.0-alpha.9"
+    "@theholocron/tsconfig": "^8.9.0-alpha.9",
+    "@theholocron/vitest-config": "^8.9.0-alpha.9"
   },
   "engines": {
     "node": ">=22.0.0"