@theholocron/github-client 1.58.0-alpha.1 → 1.58.0-alpha.11

package/README.md

@@ -32,6 +32,11 @@ 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");
+
+// List a directory; a 404 is an empty list. `recursive` descends into nested directories
+// (one request each) and returns a flat list of full paths.
+const entries = await client.git.listDirectory("owner/name", ".holocron", { recursive: true });
+// [{ name, path, type: "file" | "dir" | "symlink" | "submodule", size, sha }]
 ```
 
 ## Namespaces
@@ -50,7 +55,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`, `putContents`, `createBlob`, `createTree`, `createCommit`, `createRef`, `updateRef`, `createPull`                                                      |
+| `git`          | `getRef`, `getCommit`, `getTree`, `getContents`, `listDirectory`, `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

@@ -1,8 +1,29 @@
 import "@theholocron/http-client";
 import { ErrorSink, Logger } from "@theholocron/observability/core";
+/**
+ * GitHub's GraphQL API has exactly one endpoint (`POST /graphql`, always) —
+ * unlike REST's per-resource paths, there's nothing here for `createRestClient()`
+ * to route on. Reused anyway for the transport it already gets right (auth
+ * header, JSON body/parsing, network-failure wrapping into `ProviderApiError`
+ * with `status: 0`) — only the response-shape difference needs handling on
+ * top: GraphQL always answers `200 OK`, even for a query error, with the
+ * error(s) in the response body's own `errors` array rather than the HTTP
+ * status. `createRestClient()`'s own `!res.ok` branch never fires for a
+ * GraphQL error — this wrapper's the one place that translates a 200 with a
+ * populated `errors` array into a thrown `ProviderApiError`, matching the
+ * REST client's own error-throwing contract so callers don't need to know
+ * which transport they're talking to.
+ */
+interface GraphQLClient {
+  query<T>(document: string, variables?: Record<string, unknown>): Promise<T>;
+}
+/** Options for creating a GitHub client. */
 interface GitHubClientOptions {
+  /** The token sent as the bearer credential. */
   token: string;
+  /** The GitHub API base URL; defaults to `https://api.github.com`. */
   baseUrl?: string;
+  /** The `fetch` implementation to use; defaults to the global `fetch`. */
   fetch?: typeof fetch;
   /** Structured logger for request/response diagnostics. Defaults to a no-op. */
   logger?: Logger;
@@ -16,8 +37,11 @@ interface GitHubBranch {
     sha: string;
   };
 }
+/** The lifecycle state of a check run. */
 type CheckRunStatus = "queued" | "in_progress" | "completed";
+/** The final result of a completed check run. */
 type CheckRunConclusion = "success" | "failure" | "neutral" | "cancelled" | "timed_out" | "action_required" | "skipped";
+/** The severity of a check run annotation. */
 type CheckRunAnnotationLevel = "notice" | "warning" | "failure";
 /**
  * GitHub's cap on `output.annotations` per `createCheckRun()` /
@@ -26,15 +50,19 @@ type CheckRunAnnotationLevel = "notice" | "warning" | "failure";
  * do for you; slice with it rather than hardcoding the number.
  */
 export declare const MAX_CHECK_RUN_ANNOTATIONS = 50;
+/** One inline annotation attached to a check run's output, anchored to a file and line range. */
 interface CheckRunAnnotation {
   /** File path relative to the repo root. */
   path: string;
   /** 1-indexed. */
   start_line: number;
+  /** 1-indexed last line of the annotated range. */
   end_line: number;
   /** Only valid when `start_line === end_line`. */
   start_column?: number;
+  /** Column of the end of the range; only valid when `start_line === end_line`. */
   end_column?: number;
+  /** Severity of the annotation. */
   annotation_level: CheckRunAnnotationLevel;
   /** Max 64KB. */
   message: string;
@@ -43,9 +71,13 @@ interface CheckRunAnnotation {
   /** Max 64KB. */
   raw_details?: string;
 }
+/** The title, summary and optional annotations shown on a check run. */
 interface CheckRunOutput {
+  /** The output's title. */
   title: string;
+  /** The output's summary, rendered as Markdown. */
   summary: string;
+  /** Longer details text, rendered as Markdown. */
   text?: string;
   /**
    * Inline PR annotations — up to {@link MAX_CHECK_RUN_ANNOTATIONS} per
@@ -54,7 +86,9 @@ interface CheckRunOutput {
    */
   annotations?: CheckRunAnnotation[];
 }
+/** The body of a `createCheckRun()` request. */
 interface CreateCheckRunInput {
+  /** The check run's name, as shown in the checks list. */
   name: string;
   /** The commit SHA the check run attaches to. */
   head_sha: string;
@@ -62,30 +96,46 @@ interface CreateCheckRunInput {
   status?: CheckRunStatus;
   /** Required when `status` is `"completed"`. */
   conclusion?: CheckRunConclusion;
+  /** The title, summary and annotations to show on the check run. */
   output?: CheckRunOutput;
   /** URL for the "Details" link on the check run. GitHub defaults to the check suite's own summary page when omitted. */
   details_url?: string;
 }
+/** A check run as GitHub returns it, with only the fields this client reads. */
 interface GitHubCheckRun {
+  /** The check run's numeric id. */
   id: number;
+  /** The check run's name. */
   name: string;
+  /** The commit SHA the check run is attached to. */
   head_sha: string;
+  /** The check run's current lifecycle state. */
   status: CheckRunStatus;
+  /** The check run's result, or `null` until it is completed. */
   conclusion: CheckRunConclusion | null;
+  /** The URL of the check run's page on GitHub. */
   html_url: string;
 }
+/** The body of an `updateCheckRun()` request; every field is optional. */
 interface UpdateCheckRunInput {
+  /** The lifecycle state to move the check run to. */
   status?: CheckRunStatus;
   /** Required when `status` is `"completed"`. */
   conclusion?: CheckRunConclusion;
+  /** The title, summary and annotations to set on the check run. */
   output?: CheckRunOutput;
   /** URL for the "Details" link on the check run. */
   details_url?: string;
 }
+/** A deployment environment of a repository and its protection settings. */
 interface GitHubEnvironment {
+  /** The environment's name. */
   name: string;
+  /** Minutes to wait before a job that targets the environment may proceed. */
   wait_timer?: number;
+  /** Whether the user who triggered a deployment may also approve it. */
   prevent_self_review?: boolean;
+  /** The protection rules on the environment; each has a `type` and, for required reviewers, the reviewers. */
   protection_rules?: Array<{
     type: string;
     reviewers?: Array<{
@@ -96,52 +146,107 @@ interface GitHubEnvironment {
     }>;
   }>;
 }
+/** A git reference (such as a branch) and the object it points at. */
 interface GitRef {
+  /** The object the reference points at. */
   object: {
+    /** The object's SHA. */
     sha: string;
+    /** The object's type, e.g. `commit`. */
     type: string;
+    /** The API URL of the object. */
     url: string;
   };
+  /** The full reference name, e.g. `refs/heads/main`. */
   ref: string;
+  /** The API URL of the reference. */
   url: string;
 }
+/** A git commit, with only the fields this client reads. */
 interface GitCommit {
+  /** The commit's SHA. */
   sha: string;
+  /** The tree the commit points at. */
   tree: {
+    /** The tree's SHA. */
     sha: string;
+    /** The API URL of the tree. */
     url: string;
   };
 }
+/** One entry of a git tree. */
 interface GitTreeItem {
+  /** The entry's path within the tree. */
   path: string;
+  /** The entry's object SHA. */
   sha: string;
+  /** The kind of object the entry points at, e.g. `blob` or `tree`. */
   type: string;
+  /** The entry's file mode, e.g. `100644`. */
   mode?: string;
+  /** The blob's size in bytes; absent for trees. */
   size?: number;
 }
+/** A git tree as GitHub returns it. */
 interface GitTree {
+  /** The tree's SHA. */
   sha: string;
+  /** The entries of the tree. */
   tree: GitTreeItem[];
+  /** Whether GitHub cut the entry list short because the tree was too large. */
   truncated: boolean;
 }
+/** A file's contents as the contents API returns them. */
 interface GitContents {
+  /** The file content, encoded as named by `encoding`. */
   content: string;
+  /** The encoding of `content`, normally `base64`. */
   encoding: string;
+  /** The file's blob SHA. */
   sha: string;
+  /** The file's name. */
   name: string;
+  /** The file's path in the repository. */
   path: string;
 }
+/** One entry of a directory listing from the contents API. */
+interface GitDirectoryEntry {
+  /** The entry's name, without its directory. */
+  name: string;
+  /** The entry's path from the repository root, e.g. `.holocron/notifications.ts`. */
+  path: string;
+  /** What the entry is; `dir` entries are listed, and descended into only when `recursive` is set. */
+  type: "file" | "dir" | "symlink" | "submodule";
+  /** The size in bytes; GitHub reports `0` for directories and submodules. */
+  size: number;
+  /** The entry's object SHA. */
+  sha: string;
+}
+/** Options for `listDirectory()`. */
+interface ListDirectoryOptions {
+  /** A branch, tag or commit SHA; defaults to the repo's default branch. */
+  ref?: string;
+  /** Also list the contents of every nested directory, as one flat list of full paths. Defaults to `false`. */
+  recursive?: boolean;
+}
 /** What `git.putContents` returns: the file's new blob sha (the `sha` to pass next time) and the commit it made. */
 interface PutContentsResult {
+  /** The file written: its path and its new blob SHA. */
   content: {
+    /** The file's new blob SHA. */
     sha: string;
+    /** The file's path. */
     path: string;
   };
+  /** The commit that was made. */
   commit: {
+    /** The new commit's SHA. */
     sha: string;
   };
 }
+/** The body of a `putContents()` request. */
 interface PutContentsInput {
+  /** The commit message. */
   message: string;
   /** The new file text (UTF-8); the client encodes it. */
   content: string;
@@ -154,99 +259,172 @@ interface PutContentsInput {
   /** Defaults to the repo's default branch. */
   branch?: string;
 }
+/** A git blob created in the repository. */
 interface GitBlob {
+  /** The blob's SHA. */
   sha: string;
+  /** The API URL of the blob. */
   url: string;
 }
+/** A pull request as returned when one is created, with only the fields this client reads. */
 interface GitPull {
+  /** The pull request's number. */
   number: number;
+  /** The URL of the pull request's page on GitHub. */
   html_url: string;
+  /** The pull request's title. */
   title: string;
 }
+/** The body of a `createPull()` request. */
 interface CreatePullInput {
+  /** The pull request's title. */
   title: string;
+  /** The branch the changes come from. */
   head: string;
+  /** The branch the changes are to be merged into. */
   base: string;
+  /** The pull request's description. */
   body?: string;
 }
+/** An issue as GitHub returns it, with only the fields this client reads. */
 interface GitHubIssue {
+  /** The issue's numeric id. */
   id: number;
+  /** The issue's number within its repository. */
   number: number;
+  /** The issue's title. */
   title: string;
+  /** The issue's description; `null` or absent when empty. */
   body?: string | null;
+  /** Whether the issue is open or closed. */
   state: "open" | "closed";
+  /** The labels on the issue. */
   labels: Array<{
     name: string;
   }>;
+  /** The user the issue is assigned to, or `null` when unassigned. */
   assignee: {
     login: string;
     name?: string | null;
     email?: string | null;
   } | null;
+  /** When the issue was last updated, as an ISO 8601 timestamp. */
   updated_at: string;
+  /** The URL of the issue's page on GitHub. */
   html_url: string;
+  /** Set when the item is a pull request; GitHub's issues API returns pull requests too. */
   pull_request?: unknown;
 }
+/** A milestone, with only the fields this client reads. */
 interface GitHubMilestone {
+  /** The milestone's number. */
   number: number;
+  /** The milestone's title. */
   title: string;
 }
+/** Filters for listing issues. */
 interface IssueSearchParams {
+  /** Which issues to list by state; GitHub defaults to `open`. */
   state?: "open" | "closed" | "all";
+  /** The field to sort by, passed through to GitHub. */
   sort?: string;
+  /** The sort direction, passed through to GitHub. */
   direction?: string;
+  /** The number of issues per page. */
   per_page?: number;
+  /** Which issues to list by relation to the user, passed through to GitHub. */
   filter?: string;
+  /** Limit to issues assigned to this login. */
   assignee?: string;
 }
+/** A repository label. */
 interface GitHubLabel {
+  /** The label's name. */
   name: string;
+  /** The label's color as a hex code without the leading `#`. */
   color: string;
+  /** The label's description, or `null` when it has none. */
   description: string | null;
 }
+/** How a Pages site is built: by a workflow or from a branch. */
 type PagesBuildType = "workflow" | "legacy";
+/** The status of a Pages build. */
 type PagesBuildStatus = "built" | "building" | "errored" | "unknown";
+/** A repository's GitHub Pages site configuration. */
 interface GitHubPages {
+  /** The latest build's status, or `null` when there is none. */
   status: PagesBuildStatus | null;
+  /** How the site is built, or `null` when unknown. */
   build_type: PagesBuildType | null;
+  /** The branch and folder the site is published from, for a legacy build. */
   source?: {
+    /** The branch the site is published from. */
     branch: string;
+    /** The folder on the branch, `/` or `/docs`. */
     path: string;
   };
+  /** Whether HTTPS is enforced for the site. */
   https_enforced: boolean;
+  /** The site's custom domain, or `null` when it has none. */
   custom_domain: string | null;
 }
+/** The body of a Pages creation request. */
 interface CreatePagesPayload {
+  /** How the site is built. */
   build_type: PagesBuildType;
   /** Required when build_type is "legacy". */
   source?: {
+    /** The branch the site is published from. */
     branch: string;
+    /** The folder on the branch, `/` or `/docs`. */
     path: string;
   };
 }
+/** The body of a Pages update request; every field is optional. */
 interface UpdatePagesPayload {
+  /** How the site is built. */
   build_type?: PagesBuildType;
+  /** The branch and folder to publish from. */
   source?: {
+    /** The branch the site is published from. */
     branch: string;
+    /** The folder on the branch, `/` or `/docs`. */
     path: string;
   };
+  /** The custom domain, or `null` to remove it. */
   cname?: string | null;
+  /** Whether to enforce HTTPS. */
   https_enforced?: boolean;
 }
 /** One custom property of an organization, as its schema defines it. */
 interface OrgProperty {
+  /** The property's name. */
   property_name: string;
   /** `string`, `single_select`, `multi_select`, `true_false` or `url`. */
   value_type: string;
+  /** Whether a repository must set the property. */
   required?: boolean;
   /** The values a `single_select` or `multi_select` property accepts; `null` for any other type. */
   allowed_values?: string[] | null;
 }
+/** One custom property value set on a repository. */
+interface RepoPropertyValue {
+  /** The property's name. */
+  property_name: string;
+  /** A string, a string array for `multi_select`, or `null` when unset. */
+  value: string | string[] | null;
+}
+/** A pull request as GitHub returns it, with only the fields this client reads. */
 interface GitHubPullRequest {
+  /** The pull request's number. */
   number: number;
+  /** The pull request's title. */
   title: string;
+  /** Whether the pull request is open or closed. */
   state: "open" | "closed";
+  /** When the pull request was merged as an ISO 8601 timestamp, or `null` if it was not merged. */
   merged_at: string | null;
+  /** The URL of the pull request's page on GitHub. */
   html_url: string;
   /** The head branch: its name and the commit it pointed at when the PR was read. */
   head: {
@@ -263,10 +441,15 @@ interface GitHubCommitIdentity {
 }
 /** One commit as returned by `GET /pulls/{pull_number}/commits` — only the fields any known consumer needs. */
 interface GitHubPullRequestCommit {
+  /** The commit's SHA. */
   sha: string;
+  /** The commit's message and git identities. */
   commit: {
+    /** The commit message. */
     message: string;
+    /** The commit's author, as git recorded it. */
     author: GitHubCommitIdentity;
+    /** The commit's committer, as git recorded it. */
     committer: GitHubCommitIdentity;
   };
   /** The commit's linked GitHub account, when GitHub can associate one — `null` for a commit email with no linked account. `type: "Bot"` identifies an app-authored commit (e.g. Dependabot, a prior Sentinel auto-fix-commit). */
@@ -281,7 +464,9 @@ interface GitHubPullRequestCommit {
 }
 /** One file as returned by `GET /pulls/{pull_number}/files` — only the fields any known consumer needs. */
 interface GitHubPullRequestFile {
+  /** The file's path in the repository. */
   filename: string;
+  /** How the pull request changes the file. */
   status: "added" | "removed" | "modified" | "renamed" | "copied" | "changed" | "unchanged";
   /** Set only when `status === "renamed"`. */
   previous_filename?: string;
@@ -301,8 +486,10 @@ interface CreateReviewComment {
   line: number;
   /** Almost always `"RIGHT"` (the PR's own new content) — `"LEFT"` targets the base/pre-PR version instead. */
   side: "LEFT" | "RIGHT";
+  /** The comment text. */
   body: string;
 }
+/** The body of a review creation request. */
 interface CreateReviewInput {
   /** The PR's head SHA the review attaches to. */
   commit_id: string;
@@ -315,11 +502,14 @@ interface CreateReviewInput {
    * required-approval counts and dismissal.
    */
   event: "COMMENT" | "REQUEST_CHANGES" | "APPROVE";
+  /** Inline comments to post with the review. */
   comments?: CreateReviewComment[];
 }
 /** `POST /pulls/{pull_number}/reviews`'s response — only the fields any known consumer needs. */
 interface GitHubPullRequestReview {
+  /** The review's numeric id. */
   id: number;
+  /** The URL of the review on GitHub. */
   html_url: string;
 }
 /**
@@ -330,7 +520,9 @@ interface GitHubPullRequestReview {
  * never compare it against a REST-sourced ID.
  */
 interface ReviewThread {
+  /** The thread's GraphQL node id. */
   id: string;
+  /** Whether the thread is resolved. */
   isResolved: boolean;
   /** The thread's first comment's author login (e.g. `"the-holocron-sentinel[bot]"`) — `undefined` if GitHub ever returns a thread with no comments, which shouldn't happen in practice. Callers filter on this before resolving anything, so a bot never touches a human reviewer's own thread. */
   authorLogin: string | undefined;
@@ -348,19 +540,70 @@ interface ReviewThread {
    */
   body: string | undefined;
 }
+/** A repository as GitHub returns it, with only the fields this client reads. */
 interface GitHubRepo {
+  /** The name of the repository's default branch. */
   default_branch: string;
+  /** The repository's `owner/name`. */
   full_name: string;
-}
+  /** The repository description. */
+  description?: string | null;
+  /** The repository homepage URL. */
+  homepage?: string | null;
+  /** The topics set on the repository. */
+  topics?: string[];
+  /** Whether squash merging is allowed. */
+  allow_squash_merge?: boolean;
+  /** Whether merge commits are allowed. */
+  allow_merge_commit?: boolean;
+  /** Whether rebase merging is allowed. */
+  allow_rebase_merge?: boolean;
+  /** Whether auto-merge is allowed. */
+  allow_auto_merge?: boolean;
+  /** Whether a pull request branch can be updated from its base. */
+  allow_update_branch?: boolean;
+  /** Whether a merged pull request's branch is deleted. */
+  delete_branch_on_merge?: boolean;
+  /** Whether issues are enabled. */
+  has_issues?: boolean;
+  /** Whether discussions are enabled. */
+  has_discussions?: boolean;
+  /** Whether projects are enabled. */
+  has_projects?: boolean;
+  /** Whether the wiki is enabled. */
+  has_wiki?: boolean;
+  /** Each feature's `status` (`enabled` / `disabled`). Only an admin token sees it; absent for the rest. */
+  security_and_analysis?: Record<string, {
+    status: string;
+  } | undefined> | null;
+}
+/** A file's contents as the contents API returns them. */
 interface GitHubContents {
+  /** The file content, encoded as named by `encoding`. */
   content: string;
+  /** The encoding of `content`, normally `base64`. */
   encoding: string;
 }
+/** A repository ruleset in summary form. */
 interface GitHubRuleset {
+  /** The ruleset's numeric id. */
   id: number;
+  /** The ruleset's name. */
   name: string;
+  /** How the ruleset is enforced, e.g. `active`, `evaluate` or `disabled`. */
   enforcement: string;
 }
+/** One ruleset in full, as `GET /repos/{repo}/rulesets/{id}` returns it. */
+interface GitHubRulesetDetail extends GitHubRuleset {
+  /** What the ruleset applies to, e.g. `branch`. */
+  target?: string;
+  /** Each rule has a `type`; some carry `parameters`. */
+  rules?: Array<{
+    type: string;
+    parameters?: Record<string, unknown>;
+  }>;
+}
+/** Where a secret lives: the repository, one of its environments, or an organization. */
 type SecretScope = {
   kind: "repo";
 } | {
@@ -370,21 +613,39 @@ type SecretScope = {
   kind: "organization";
   org: string;
 };
+/** A public key used to encrypt a secret before it is sent. */
 interface GitHubPublicKey {
+  /** The key's id, sent back with the encrypted secret. */
   key_id: string;
+  /** The Base64-encoded public key. */
   key: string;
 }
+/** The workflow run that a code scanning setup started. */
 interface CodeScanningSetupResult {
+  /** The id of the workflow run. */
   run_id: number;
+  /** The URL of the workflow run. */
   run_url: string;
 }
+/** A permission level a team can hold on a repository. */
 type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
+/** A team with access to a repository, and the permission it has there. */
+interface RepoTeam {
+  /** The team's slug. */
+  slug: string;
+  /** The team's permission on the repository. */
+  permission: TeamPermission;
+}
 /** A member of a team, as GitHub lists it. `id` is the numeric user id, which survives a rename; `login` does not. */
 interface TeamMember {
+  /** The member's numeric user id. */
   id: number;
+  /** The member's login. */
   login: string;
+  /** The kind of account, e.g. `User`. */
   type?: string;
 }
+/** Where a variable lives: the repository, one of its environments, or an organization. */
 type VariableScope = {
   kind: "repo";
 } | {
@@ -401,40 +662,76 @@ type VariableScope = {
 type VariableVisibility = "all" | "private" | "selected";
 /** A GitHub Actions variable. Unlike a secret its value is readable, so a reconcile can tell whether it differs. */
 interface GitHubVariable {
+  /** The variable's name. */
   name: string;
+  /** The variable's value. */
   value: string;
   /** Present on organization variables only. */
   visibility?: VariableVisibility;
 }
+/** The authenticated user, with only the fields this client reads. */
 interface GitHubUser {
+  /** The user's login. */
   login: string;
+  /** The user's display name, or `null` when not set. */
   name: string | null;
+  /** The user's public email, or `null` when not set. */
   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;
+/** A workflow run as GitHub returns it, with only the fields this client reads. */
 interface GitHubWorkflowRun {
+  /** The run's numeric id. */
   id: number;
+  /** The workflow's name, or `null` when unnamed. */
   name: string | null;
+  /** The run's display title. */
   display_title: string;
+  /** The branch the run was triggered on. */
   head_branch: string;
+  /** The commit SHA the run was triggered on. */
   head_sha: string;
+  /** The run's status, e.g. `queued`, `in_progress` or `completed`. */
   status: string;
+  /** The run's result once completed, or `null` before. */
   conclusion: string | null;
+  /** The URL of the run's page on GitHub. */
   html_url: string;
+  /** When the run was created, as an ISO 8601 timestamp. */
   created_at: string;
+  /** When the run was last updated, as an ISO 8601 timestamp. */
   updated_at: string;
 }
+/** Filters for listing workflow runs. */
 interface WorkflowRunFilter {
+  /** Only runs on this branch. */
   branch?: string;
+  /** The maximum number of runs to return. */
   limit?: number;
+  /** Only runs with this status. */
   status?: string;
 }
+/** The credentials identifying a GitHub App: its id and private key. */
 interface GitHubAppCredentials {
   /** The App's numeric id (not the client id). */
   appId: string;
   /** PEM-encoded RSA private key — PKCS#1 (GitHub's default download format) or PKCS#8, either works. */
   privateKey: string;
 }
+/** A short-lived installation access token and when it expires. */
 interface InstallationAccessToken {
+  /** The installation access token, used as a bearer token for the REST API. */
   token: string;
   /** ISO 8601 — installation tokens are short-lived, about an hour. */
   expiresAt: string;
@@ -484,6 +781,7 @@ export declare function verifyGitHubWebhookSignature(input: {
   signature: string | undefined;
   secret: string;
 }): boolean;
+/** The three GitHub webhook headers a consumer needs. */
 interface GitHubWebhookHeaders {
   /** `X-GitHub-Event` — the event category, e.g. `"push"`, `"pull_request"`. */
   event: string | undefined;
@@ -494,31 +792,62 @@ interface GitHubWebhookHeaders {
 }
 /** Extracts GitHub's three webhook headers, case-insensitively (Node's raw headers may arrive lower-cased, or as an array when a header repeats). */
 export declare function parseGitHubWebhookHeaders(headers: Record<string, string | string[] | undefined>): GitHubWebhookHeaders;
+/** The payload of an `installation` webhook delivery. */
 interface GitHubInstallationWebhookPayload {
+  /** What happened to the installation, e.g. `created` or `deleted`. */
   action: string;
+  /** The installation the delivery is about. */
   installation: {
+    /** The installation id. */
     id: number;
   };
 }
+/** The payload of a `push` webhook delivery. */
 interface GitHubPushWebhookPayload {
+  /** The full name of the pushed ref, e.g. `refs/heads/main`. */
   ref: string;
+  /** The installation the delivery is about, when sent. */
   installation?: {
+    /** The installation id. */
     id: number;
   };
+  /** The repository that was pushed to. */
   repository: {
+    /** The repository's owner/name. */
     full_name: string;
+    /** The name of the default branch. */
     default_branch: string;
   };
 }
+/** The payload of a `pull_request` webhook delivery. */
 interface GitHubPullRequestWebhookPayload {
+  /** What happened to the pull request, e.g. `opened` or `closed`. */
   action: string;
+  /** For an `edited` action, the fields that changed (each holds the previous value); absent for other actions. */
+  changes?: {
+    /** Present when the title was edited. */
+    title?: {
+      /** The title before the edit. */
+      from: string;
+    };
+    /** Present when the description was edited. */
+    body?: {
+      /** The description before the edit; `null` when it was empty. */
+      from: string | null;
+    };
+  };
+  /** The installation the delivery is about, when sent. */
   installation?: {
+    /** The installation id. */
     id: number;
   };
+  /** The repository the pull request belongs to. */
   repository: {
+    /** The repository's owner/name. */
     full_name: string;
   };
 }
+/** Creates a GitHub client with a group of methods per API area (branches, pulls, issues, secrets and so on), backed by one REST client and one GraphQL client built from the same options. */
 export declare function createGitHubClient(opts: GitHubClientOptions): {
   branches: {
     protectBranch: (repo: string, branch: string, payload: Record<string, unknown>) => Promise<void>;
@@ -539,6 +868,7 @@ export 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>;
+    listDirectory: (repo: string, path: string, options?: ListDirectoryOptions) => Promise<GitDirectoryEntry[]>;
     putContents: (repo: string, path: string, input: PutContentsInput) => Promise<PutContentsResult>;
     createBlob: (repo: string, content: string, encoding?: string) => Promise<GitBlob>;
     createTree: (repo: string, tree: Array<{
@@ -552,6 +882,8 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     updateRef: (repo: string, ref: string, sha: string, force?: boolean) => Promise<GitRef>;
     createPull: (repo: string, input: CreatePullInput) => Promise<GitPull>;
   };
+  /** The GraphQL client, for the callers whose API (Projects v2) has no REST form. */
+  graphql: GraphQLClient;
   issues: {
     listIssues: (repo: string, params?: IssueSearchParams) => Promise<GitHubIssue[]>;
     getIssue: (repo: string, number: number) => Promise<GitHubIssue>;
@@ -583,6 +915,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     updatePages: (repo: string, payload: UpdatePagesPayload) => Promise<void>;
   };
   properties: {
+    getValues: (repo: string) => Promise<RepoPropertyValue[]>;
     orgSchema: (org: string) => Promise<OrgProperty[]>;
     setProperties: (repo: string, values: Record<string, string | string[]>) => Promise<void>;
   };
@@ -601,6 +934,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     getContents: (repo: string, path: string) => Promise<GitHubContents>;
   };
   rulesets: {
+    getRuleset: (repo: string, id: number) => Promise<GitHubRulesetDetail>;
     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>;
@@ -612,6 +946,10 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     deleteSecret: (repo: string, scope: SecretScope, name: string) => Promise<void>;
   };
   security: {
+    vulnerabilityAlertsEnabled: (repo: string) => Promise<boolean>;
+    automatedSecurityFixesEnabled: (repo: string) => Promise<boolean>;
+    privateVulnerabilityReportingEnabled: (repo: string) => Promise<boolean>;
+    codeScanningDefaultSetupState: (repo: string) => Promise<string>;
     enableVulnerabilityAlerts: (repo: string) => Promise<void>;
     enableAutomatedSecurityFixes: (repo: string) => Promise<void>;
     enableSecretScanning: (repo: string) => Promise<void>;
@@ -622,6 +960,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
   };
   teams: {
     members: (org: string, teamSlug: string) => Promise<TeamMember[]>;
+    listForRepo: (repo: string) => Promise<RepoTeam[]>;
     addRepo: (org: string, teamSlug: string, owner: string, repo: string, permission: TeamPermission) => Promise<void>;
   };
   topics: {
@@ -636,6 +975,7 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
   };
   user: {
     getCurrentUser: () => Promise<GitHubUser>;
+    getCurrentUserWithExpiry(): Promise<GitHubUserWithExpiry>;
   };
   workflows: {
     listRuns: (repo: string, filter?: WorkflowRunFilter) => Promise<GitHubWorkflowRun[]>;
@@ -643,5 +983,6 @@ export declare function createGitHubClient(opts: GitHubClientOptions): {
     createWorkflowDispatch: (repo: string, workflowFile: string, ref: string, inputs?: Record<string, string>) => Promise<void>;
   };
 };
+/** 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, 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, 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 };

package/dist/index.mjs

@@ -150,6 +150,36 @@ function git(rest) {
 		*/
 		getContents: (repo, path, ref) => rest.request(`${repoBase(repo)}/contents/${path}`, ref ? { query: { ref } } : void 0),
 		/**
+		* Lists the directory at `path` through the contents API (`GET /repos/:repo/contents/:path`, which
+		* answers an array for a directory). A 404 (no such directory) is an empty list, not an error; any
+		* other failure is the usual `ProviderApiError`. One request lists one level: with
+		* `recursive: true` it makes one more request per nested directory and returns a flat list of
+		* full paths (directories included). A `path` that is a file, not a directory, throws.
+		*/
+		listDirectory: async (repo, path, options = {}) => {
+			const list = async (at) => {
+				let body;
+				try {
+					body = await rest.request(`${repoBase(repo)}/contents/${filePath(at)}`, options.ref ? { query: { ref: options.ref } } : void 0);
+				} catch (err) {
+					if (err instanceof ProviderApiError && err.status === 404) return [];
+					throw err;
+				}
+				if (!Array.isArray(body)) throw new Error(`${repo}:${at} is a file, not a directory`);
+				const entries = body.map(({ name, path: p, type, size, sha }) => ({
+					name,
+					path: p,
+					type,
+					size,
+					sha
+				}));
+				if (!options.recursive) return entries;
+				const nested = await Promise.all(entries.filter((e) => e.type === "dir").map((e) => list(e.path)));
+				return [...entries, ...nested.flat()];
+			};
+			return list(path.replace(/^\/+|\/+$/g, ""));
+		},
+		/**
 		* `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.
 		*/
@@ -293,6 +323,8 @@ function pages(rest) {
 // src/properties/properties.ts
 function properties(rest) {
 	return {
+		/** The custom property values set on a repository (read-only). */
+		getValues: (repo) => rest.request(`${repoBase(repo)}/properties/values`),
 		/**
 		* The custom properties an organization defines, with their types and allowed values (read-only).
 		* The token needs read access to the organization's custom properties.
@@ -431,6 +463,7 @@ function repos(rest) {
 // src/rulesets/rulesets.ts
 function rulesets(rest) {
 	return {
+		getRuleset: (repo, id) => rest.request(`${repoBase(repo)}/rulesets/${id}`),
 		listRulesets: (repo) => rest.request(`${repoBase(repo)}/rulesets`),
 		createRuleset: (repo, payload) => rest.request(`${repoBase(repo)}/rulesets`, {
 			method: "POST",
@@ -468,6 +501,22 @@ function secrets(rest) {
 // src/security/security.ts
 function security(rest) {
 	return {
+		/** Whether vulnerability alerts are on: GitHub answers 204 when they are and 404 when they are not. */
+		vulnerabilityAlertsEnabled: async (repo) => {
+			try {
+				await rest.request(`${repoBase(repo)}/vulnerability-alerts`, { expectNoContent: true });
+				return true;
+			} catch (err) {
+				if (err instanceof ProviderApiError && err.status === 404) return false;
+				throw err;
+			}
+		},
+		/** Whether Dependabot security updates are on. */
+		automatedSecurityFixesEnabled: async (repo) => (await rest.request(`${repoBase(repo)}/automated-security-fixes`)).enabled,
+		/** Whether private vulnerability reporting is on. */
+		privateVulnerabilityReportingEnabled: async (repo) => (await rest.request(`${repoBase(repo)}/private-vulnerability-reporting`)).enabled,
+		/** The state of CodeQL default setup: `configured` or `not-configured`. */
+		codeScanningDefaultSetupState: async (repo) => (await rest.request(`${repoBase(repo)}/code-scanning/default-setup`)).state,
 		enableVulnerabilityAlerts: (repo) => rest.request(`${repoBase(repo)}/vulnerability-alerts`, {
 			method: "PUT",
 			expectNoContent: true
@@ -535,6 +584,8 @@ function teams(rest) {
 			if ((await read(51)).length > 0) throw new Error(`team ${org}/${teamSlug} has more than 5000 members; refusing to read them all`);
 			return all;
 		},
+		/** The teams that have access to a repository, with each team's permission there (read-only). */
+		listForRepo: (repo) => rest.request(`${repoBase(repo)}/teams`, { query: { per_page: String(PAGE$1) } }),
 		addRepo: (org, teamSlug, owner, repo, permission) => rest.request(`/orgs/${org}/teams/${teamSlug}/repos/${owner}/${repo}`, {
 			method: "PUT",
 			body: { permission }
@@ -549,8 +600,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. */
@@ -847,6 +921,7 @@ function parseGitHubWebhookHeaders(headers) {
 	};
 }
 // src/index.ts
+/** Creates a GitHub client with a group of methods per API area (branches, pulls, issues, secrets and so on), backed by one REST client and one GraphQL client built from the same options. */
 function createGitHubClient(opts) {
 	const rest = createGitHubRestClient(opts);
 	const graphql = createGitHubGraphQLApiClient(opts);
@@ -855,6 +930,8 @@ function createGitHubClient(opts) {
 		checks: checks(rest),
 		environments: environments(rest),
 		git: git(rest),
+		/** The GraphQL client, for the callers whose API (Projects v2) has no REST form. */
+		graphql,
 		issues: issues(rest),
 		labels: labels(rest),
 		pages: pages(rest),
@@ -871,4 +948,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.58.0-alpha.1",
+  "version": "1.58.0-alpha.11",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -32,23 +32,23 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.58.0-alpha.1",
-    "@theholocron/observability": "^0.6.1-alpha.1"
+    "@theholocron/observability": "^0.7.0-alpha.1",
+    "@theholocron/http-client": "^1.58.0-alpha.11"
   },
   "devDependencies": {
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
-    "@vitest/eslint-plugin": "^1.6.27",
-    "eslint": "^10.8.1",
-    "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.11.0",
-    "tsdown": "^0.23.3",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.4",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3"
+    "@theholocron/tsconfig": "^8.9.0-alpha.8",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -57,10 +57,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown && node ../scripts/check-bundle-size.mjs",
-    "sourceQuality.staticAnalysis": "eslint .",
+    "build": "tsdown && node ../scripts/check-bundle-size.mjs",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "tsc --noEmit",
-    "verification.unitTests": "vitest run"
+    "typecheck": "tsc --noEmit"
   }
 }