@bridge-ds/core 0.2.0 → 0.3.0

package/dist/github-client.d.ts

@@ -1,9 +1,59 @@
 import { type BridgeConfig } from './config';
+import type { ClassicProtection, Ruleset, RulesetPayload } from './protection';
+/**
+ * What an auth failure means for the token:
+ * - "rejected": GitHub refused the token itself (401). It was revoked, regenerated or has expired; every call
+ *   with it will fail until it is replaced.
+ * - "missing-permission": the token works but lacks a permission this call needs (403 "Resource not accessible
+ *   by personal access token", or a permission GitHub names in X-Accepted-GitHub-Permissions).
+ * Undefined for everything else, including rate limits and a missing token.
+ */
+export type GitHubAuthState = 'rejected' | 'missing-permission';
+/** Fine-grained token permission names, as GitHub spells them (issues, pull_requests, contents...). */
+export type GitHubPermission = string;
+export interface GitHubErrorInfo {
+    auth?: GitHubAuthState | undefined;
+    /** The permission the call needed, when GitHub or the endpoint tells (only with auth "missing-permission"). */
+    permission?: GitHubPermission | undefined;
+}
 export declare class GitHubError extends Error {
     readonly status: number;
     readonly detail?: string | undefined;
-    constructor(status: number, message: string, detail?: string | undefined);
+    /** Set when the failure is about the token: rejected (401) or missing a permission (403). */
+    readonly auth: GitHubAuthState | undefined;
+    /** With auth "missing-permission": the permission the call needed, when known. */
+    readonly permission: GitHubPermission | undefined;
+    constructor(status: number, message: string, detail?: string | undefined, info?: GitHubErrorInfo);
 }
+/** True when `err` says GitHub refused the token itself (revoked, regenerated or expired). */
+export declare const isTokenRejected: (err: unknown) => boolean;
+/** True when `err` says the token works but lacks a permission for that call. */
+export declare const isMissingPermission: (err: unknown) => boolean;
+/** "pull_requests" -> "Pull requests", as GitHub labels it on the token page. */
+export declare function permissionLabel(permission: GitHubPermission): string;
+/** Where a fine-grained token's permissions are edited. */
+export declare const TOKEN_SETTINGS_URL = "https://github.com/settings/personal-access-tokens";
+/** The one sentence for a token GitHub no longer accepts. */
+export declare const TOKEN_REJECTED_MESSAGE = "Your GitHub token stopped working. It was revoked, regenerated or has expired: replace it with a new one.";
+/**
+ * "This token cannot create issues. Add Issues: Read and write on GitHub." `action` is a verb phrase
+ * ("create issues"); without it the sentence names only the permission.
+ */
+export declare function missingPermissionMessage(permission: GitHubPermission | undefined, action?: string): string;
+/**
+ * The permission a refused call needed. GitHub names it in X-Accepted-GitHub-Permissions ("issues=write",
+ * alternatives split by ";"); otherwise the endpoint says it (/issues, /pulls, /contents, /git...).
+ */
+export declare function requiredPermission(path: string, acceptedHeader?: string | null): GitHubPermission | undefined;
+/**
+ * Classifies a GitHub error response for the token. 401 with a token sent = rejected. 403 (not a rate limit,
+ * not archived) where GitHub names a permission or says the resource is not accessible = missing permission.
+ */
+export declare function classifyAuth(status: number, detail: string, opts?: {
+    path?: string;
+    acceptedPermissions?: string | null;
+    withToken?: boolean;
+}): GitHubErrorInfo;
 export interface RepoInfo {
     fullName: string;
     defaultBranch: string;
@@ -80,6 +130,8 @@ export interface CheckRun {
     status: string;
     conclusion: string | null;
     url: string | undefined;
+    /** Slug of the GitHub App that reported it ("github-actions", "vercel"), when GitHub says. */
+    app?: string | undefined;
 }
 export interface CommitSummary {
     sha: string;
@@ -231,6 +283,13 @@ export declare class GitHubClient {
     /** Best effort: labels need the repo to allow it; failure is not fatal. */
     addLabels(issueNumber: number, labels: string[]): Promise<boolean>;
     addComment(issueNumber: number, body: string): Promise<void>;
+    /** Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early). */
+    listIssueComments(issueNumber: number): Promise<{
+        id: number;
+        body: string;
+        author: string;
+        updatedAt: string;
+    }[]>;
     createIssue(input: {
         title: string;
         body: string;
@@ -244,6 +303,34 @@ export declare class GitHubClient {
         perPage?: number;
     }): Promise<IssueSummary[]>;
     getIssue(n: number): Promise<IssueSummary>;
+    /** Edits an issue: its body, or closes it with a reason ("not_planned" for a declined request). */
+    updateIssue(n: number, patch: {
+        body?: string;
+        state?: 'open' | 'closed';
+        state_reason?: 'completed' | 'not_planned' | 'reopened';
+    }): Promise<IssueSummary>;
+    /** Adds people to an issue's assignees (GitHub ignores logins that cannot be assigned: the result says who is). */
+    addAssignees(n: number, logins: string[]): Promise<string[]>;
+    /** People with at least `permission` on the repository (reading the list needs push access). First 100. */
+    listCollaborators(permission?: 'pull' | 'triage' | 'push' | 'maintain' | 'admin'): Promise<{
+        login: string;
+        avatarUrl: string;
+    }[]>;
+    /** Whether a token is sent with each request (TeamReader). */
+    get hasToken(): boolean;
+    /** Every page of a list endpoint (per_page 100), up to `maxPages`. */
+    private paginate;
+    /** Every member login of an organization team (needs read:org, or Members: Read on a fine-grained token). */
+    listTeamMembers(org: string, slug: string): Promise<string[]>;
+    /** A user's membership of a team: "active", "pending", or null when GitHub says they are not a member (404). */
+    getTeamMembership(org: string, slug: string, login: string): Promise<'active' | 'pending' | null>;
+    /** "User" or "Organization" for a login, null when GitHub does not know it. */
+    getAccountType(login: string): Promise<'User' | 'Organization' | null>;
+    /** The organization's teams this token can see. */
+    listOrgTeams(org: string): Promise<{
+        slug: string;
+        name: string;
+    }[]>;
     /** Create or update a binary file (base64 content) on a branch, e.g. a Figma export attached to a request. */
     putBase64File(input: {
         path: string;
@@ -311,6 +398,23 @@ export declare class GitHubClient {
             conclusion: string | null;
         }[];
     }>;
+    /** Commit statuses of a commit, newest first (Vercel reports each project as "Vercel – <project>"). */
+    listCommitStatuses(sha: string): Promise<{
+        context: string;
+        state: string;
+        target_url: string | null;
+        description: string | null;
+    }[]>;
+    /**
+     * GitHub deployments of a commit with their latest status (environment "Preview – <project>", environment_url the
+     * preview). Latest per environment only, so it costs one read plus one per environment.
+     */
+    listDeployments(sha: string): Promise<{
+        id: number;
+        environment: string;
+        state: string | null;
+        environmentUrl: string | null;
+    }[]>;
     getPullRequest(n: number): Promise<PullRequest & PullRequestSummary & {
         body: string;
         mergeable: boolean | null;
@@ -328,6 +432,20 @@ export declare class GitHubClient {
         body: string;
     }): Promise<Review>;
     listCheckRuns(ref: string): Promise<CheckRun[]>;
+    /** Rulesets that apply to the repository, without their rules (GET /rulesets; read access is enough). */
+    listRulesets(): Promise<Ruleset[]>;
+    /** One ruleset with its rules. */
+    getRuleset(id: number): Promise<Ruleset>;
+    /** Creates a repository ruleset. Needs admin on the repo (fine-grained token: Administration read and write). */
+    createRuleset(payload: RulesetPayload): Promise<Ruleset>;
+    /** Replaces a repository ruleset (same permissions as createRuleset). */
+    updateRuleset(id: number, payload: RulesetPayload): Promise<Ruleset>;
+    /**
+     * Classic branch protection of `branch`: the settings, null when the branch has none (404), undefined when this
+     * token cannot read them (403: the endpoint needs admin). On a 403 the public branch summary still tells
+     * whether the branch is protected at all: `protected: false` means there is nothing to read, so null.
+     */
+    getBranchProtection(branch: string): Promise<ClassicProtection | null | undefined>;
     /** Create a check run (needs a GitHub App token; personal tokens are refused by GitHub). */
     createCheckRun(input: {
         name: string;
@@ -342,7 +460,7 @@ export declare class GitHubClient {
     }): Promise<CheckRun>;
     removeLabel(issueNumber: number, label: string): Promise<void>;
 }
-export declare function friendlyMessage(status: number, detail: string): string;
+export declare function friendlyMessage(status: number, detail: string, info?: GitHubErrorInfo): string;
 export interface RepoFiles {
     commitSha: string;
     treeSha: string;

package/dist/index.d.ts

@@ -18,18 +18,25 @@ export * from './layered';
 export * from './token-edits';
 export * from './layered-review';
 export * from './governance';
+export * from './rights';
+export * from './teams';
+export * from './protection';
+export * from './protection-github';
 export * from './usage';
 export * from './github-client';
 export * from './history';
 export * from './history-github';
 export * from './history-demo';
 export * from './previews';
+export * from './previews-github';
 export * from './ramps';
 export * from './brand';
 export * from './docs-draft';
+export * from './docs-ai';
 export * from './requests';
 export * from './change-drafts';
 export * from './draft-exchange';
 export * from './explorations';
 export * from './explorations-github';
+export * from './requests-github';
 export * from './component-spec';