@theholocron/github-client 1.58.0-alpha.10 → 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

@@ -209,6 +209,26 @@ interface GitContents {
   /** 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. */
@@ -848,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<{
@@ -964,4 +985,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, 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, 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, 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.
 		*/

package/package.json

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