@openally/github.sdk 1.0.0 → 1.1.0

package/SECURITY.md

@@ -1,5 +1,5 @@
-# Reporting Security Issues
-
-To report a security issue, please [publish a private security advisory](https://github.com/OpenAlly/github.sdk/security/advisories) with a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue.
-
-Our vulnerability management team will respond within one week. If the issue is confirmed as a vulnerability, we will open a Security Advisory and acknowledge your contributions as part of it. This project follows a 90 day disclosure timeline.
+# Reporting Security Issues
+
+To report a security issue, please [publish a private security advisory](https://github.com/OpenAlly/github.sdk/security/advisories) with a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue.
+
+Our vulnerability management team will respond within one week. If the issue is confirmed as a vulnerability, we will open a Security Advisory and acknowledge your contributions as part of it. This project follows a 90 day disclosure timeline.

package/docs/api/ApiEndpoint.md

@@ -10,12 +10,12 @@ const endpoint = repos.nodejs.node.pulls()
   .setAgent("my-app/1.0.0");
 
 // Stream items one by one across all pages
-for await (const pr of endpoint.iterate()) {
+for await (const pr of endpoint) {
   console.log(pr.title);
 }
 
 // Or collect everything at once
-const allPRs = await endpoint.all();
+const allPRs = await endpoint;
 ```
 
 ## Methods
@@ -35,3 +35,32 @@ Asynchronously iterates over all items across all pages. Pagination is handled t
 ### `.all(): Promise<T[]>`
 
 Collects all pages and resolves with a flat array of every item.
+
+### `[Symbol.asyncIterator](): AsyncIterableIterator<T>`
+
+Makes `ApiEndpoint` compatible with `for await...of` loops. Internally delegates to `.iterate()`, so pagination is handled transparently.
+
+```ts
+for await (const pr of endpoint) {
+  console.log(pr.title);
+}
+```
+
+### `.then(onfulfilled?, onrejected?): Promise<TResult1 | TResult2>`
+
+Makes `ApiEndpoint` a **Thenable**, so it can be `await`-ed directly without calling `.all()` explicitly. Internally delegates to `.all()`.
+
+```ts
+// These two are equivalent:
+const prs = await endpoint;
+const prs = await endpoint.all();
+```
+
+This also means `ApiEndpoint` instances can be passed to `Promise.resolve()`, used in `Promise.all()`, and chained with `.then()` / `.catch()` / `.finally()` like a regular promise.
+
+```ts
+endpoint
+  .then((prs) => prs.filter((pr) => pr.draft === false))
+  .then(console.log)
+  .catch(console.error);
+```

package/docs/api/GithubClient.md

@@ -11,15 +11,15 @@ const github = new GithubClient({
 });
 
 // Iterate over all open pull requests
-for await (const pr of github.repos.OpenAlly["github.sdk"].pulls().iterate()) {
+for await (const pr of github.repos.OpenAlly["github.sdk"].pulls()) {
   console.log(pr.title);
 }
 
 // Collect all tags at once
-const tags = await github.repos.OpenAlly["github.sdk"].tags().all();
+const tags = await github.repos.OpenAlly["github.sdk"].tags();
 
 // List all repositories for a user
-const userRepos = await github.users.torvalds.repos().all();
+const userRepos = await github.users.torvalds.repos();
 ```
 
 ## Constructor

package/docs/api/fetchRawFile.md

@@ -0,0 +1,106 @@
+# fetchRawFile
+
+Fetches the raw content of a file from a GitHub repository via `raw.githubusercontent.com`.
+
+```ts
+import { fetchRawFile } from "@openally/github.sdk";
+
+// Fetch file as plain text (default)
+const content = await fetchRawFile("nodejs/node", "README.md");
+
+// Fetch and parse as JSON
+const pkg = await fetchRawFile<{ version: string }>("nodejs/node", "package.json", {
+  parser: "json"
+});
+
+// Fetch and parse with a custom parser
+const lines = await fetchRawFile("nodejs/node", ".gitignore", {
+  parser: (content) => content.split("\n").filter(Boolean)
+});
+
+// Fetch from a specific branch or tag
+const content = await fetchRawFile("nodejs/node", "README.md", {
+  ref: "v20.0.0"
+});
+
+// Fetch a private file with a token
+const content = await fetchRawFile("myorg/private-repo", "config.json", {
+  token: process.env.GITHUB_TOKEN,
+  parser: "json"
+});
+```
+
+## Signature
+
+```ts
+function fetchRawFile(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options?: FetchRawFileOptions
+): Promise<string>;
+
+function fetchRawFile<T>(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options: FetchRawFileOptions & { parser: "json" }
+): Promise<T>;
+
+function fetchRawFile<T>(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options: FetchRawFileOptions & { parser: (content: string) => T }
+): Promise<T>;
+```
+
+## Parameters
+
+### `repository`
+
+Type: `` `${string}/${string}` ``
+
+The repository in `owner/repo` format (e.g. `"nodejs/node"`).
+
+### `filePath`
+
+Type: `string`
+
+Path to the file within the repository (e.g. `"src/index.ts"` or `"README.md"`).
+
+### `options`
+
+```ts
+interface FetchRawFileOptions extends RequestConfig {
+  /**
+   * Branch, tag, or commit SHA.
+   * @default "HEAD"
+   */
+  ref?: string;
+}
+
+interface RequestConfig {
+  /**
+   * A personal access token is required to access private resources,
+   * and to increase the rate limit for unauthenticated requests.
+   */
+  token?: string;
+  /**
+   * @default "@openally/github.sdk/1.0.0"
+   * @see https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28#user-agent
+   */
+  userAgent?: string;
+}
+
+```
+
+## Return value
+
+- `Promise<string>` when no `parser` is provided.
+- `Promise<T>` when `parser: "json"` or a custom parser function is provided.
+
+## Errors
+
+Throws an `Error` if the HTTP response is not `ok` (e.g. 404 for a missing file, 401 for an unauthorized request):
+
+```
+Failed to fetch raw file 'README.md' from nodejs/node@HEAD: HTTP 404
+```

package/docs/api/repos.md

@@ -6,20 +6,20 @@ The `repos` proxy provides access to GitHub repository endpoints.
 import { repos } from "@openally/github.sdk";
 
 // Collect all tags
-const tags = await repos.OpenAlly["github.sdk"].tags().all();
+const tags = await repos.OpenAlly["github.sdk"].tags();
 
 // Stream pull requests page by page
-for await (const pr of repos.nodejs.node.pulls().iterate()) {
+for await (const pr of repos.nodejs.node.pulls()) {
   console.log(pr.number, pr.title);
 }
 
 // Stream workflow runs for a specific workflow file
-for await (const run of repos.nodejs.node.workflowRuns("ci.yml").iterate()) {
+for await (const run of repos.nodejs.node.workflowRuns("ci.yml")) {
   console.log(run.id, run.status);
 }
 
 // Collect all jobs for a specific run
-const jobs = await repos.nodejs.node.runJobs(12345678).all();
+const jobs = await repos.nodejs.node.runJobs(12345678);
 ```
 
 ## Access pattern

package/docs/api/users.md

@@ -6,15 +6,15 @@ The `users` proxy provides access to GitHub user endpoints.
 import { users } from "@openally/github.sdk";
 
 // Collect all repositories for a user
-const repos = await users.torvalds.repos().all();
+const repos = await users.torvalds.repos();
 
 // Stream followers one by one
-for await (const follower of users.torvalds.followers().iterate()) {
+for await (const follower of users.torvalds.followers()) {
   console.log(follower.login);
 }
 
 // Collect all starred repositories
-const starred = await users.torvalds.starred().all();
+const starred = await users.torvalds.starred();
 ```
 
 ## Access pattern

package/eslint.config.mjs

@@ -1,3 +1,3 @@
-import { typescriptConfig } from "@openally/config.eslint";
-
-export default typescriptConfig();
+import { typescriptConfig } from "@openally/config.eslint";
+
+export default typescriptConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openally/github.sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Opiniated Node.js Github SDK",
   "type": "module",
   "exports": "./dist/index.js",
@@ -16,7 +16,7 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",
-    "provenance": false
+    "provenance": true
   },
   "repository": {
     "type": "git",

package/src/api/rawFile.ts

@@ -0,0 +1,73 @@
+// Import Internal Dependencies
+import {
+  DEFAULT_USER_AGENT,
+  GITHUB_RAW_API
+} from "../constants.ts";
+import type { RequestConfig } from "../types.ts";
+
+// CONSTANTS
+const kDefaultRef = "HEAD";
+
+export interface FetchRawFileOptions extends RequestConfig {
+  /**
+   * Branch, tag, or commit SHA.
+   * @default "HEAD"
+   */
+  ref?: string;
+}
+
+export type FetchRawFileClientOptions = Omit<FetchRawFileOptions, "token" | "userAgent">;
+export type RawFileParser<T> = "json" | ((content: string) => T);
+
+export function fetchRawFile(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options?: FetchRawFileOptions & { parser?: undefined; }
+): Promise<string>;
+export function fetchRawFile<T = unknown>(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options: FetchRawFileOptions & { parser: "json"; }
+): Promise<T>;
+export function fetchRawFile<T>(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options: FetchRawFileOptions & { parser: (content: string) => T; }
+): Promise<T>;
+export async function fetchRawFile<T>(
+  repository: `${string}/${string}`,
+  filePath: string,
+  options: FetchRawFileOptions & { parser?: RawFileParser<T>; } = {}
+): Promise<string | T> {
+  const {
+    ref = kDefaultRef,
+    token,
+    userAgent = DEFAULT_USER_AGENT,
+    parser
+  } = options;
+
+  const url = new URL(`${repository}/${ref}/${filePath}`, GITHUB_RAW_API);
+  const headers: Record<string, string> = {
+    "User-Agent": userAgent,
+    ...(typeof token === "string" ? { Authorization: `token ${token}` } : {})
+  };
+
+  const response = await fetch(url, { headers });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch raw file '${filePath}' from ${repository}@${ref}: HTTP ${response.status}`
+    );
+  }
+
+  const content = await response.text();
+
+  if (parser === "json") {
+    return JSON.parse(content) as T;
+  }
+  if (typeof parser === "function") {
+    return parser(content);
+  }
+
+  return content;
+}

package/src/api/repos.ts

@@ -46,24 +46,38 @@ function createRepoProxy(
     commits: () => new ApiEndpoint<Commit>(`/repos/${owner}/${repo}/commits`, config),
     workflows: () => new ApiEndpoint<Workflow>(
       `/repos/${owner}/${repo}/actions/workflows`,
-      { ...config, extractor: (raw: WorkflowsResponse) => raw.workflows }
+      {
+        ...config,
+        extractor: (raw: WorkflowsResponse) => raw.workflows
+      }
     ),
     workflowRuns: (workflowId: string | number) => new ApiEndpoint<WorkflowRun>(
       `/repos/${owner}/${repo}/actions/workflows/${workflowId}/runs`,
-      { ...config, extractor: (raw: WorkflowRunsResponse) => raw.workflow_runs }
+      {
+        ...config,
+        extractor: (raw: WorkflowRunsResponse) => raw.workflow_runs
+      }
     ),
     runJobs: (runId: number) => new ApiEndpoint<Job>(
       `/repos/${owner}/${repo}/actions/runs/${runId}/jobs`,
-      { ...config, extractor: (raw: JobsResponse) => raw.jobs }
+      {
+        ...config,
+        extractor: (raw: JobsResponse) => raw.jobs
+      }
     ),
     runArtifacts: (runId: number) => new ApiEndpoint<Artifact>(
       `/repos/${owner}/${repo}/actions/runs/${runId}/artifacts`,
-      { ...config, extractor: (raw: ArtifactsResponse) => raw.artifacts }
+      {
+        ...config,
+        extractor: (raw: ArtifactsResponse) => raw.artifacts
+      }
     )
   };
 }
 
-export function createReposProxy(config: RequestConfig = {}): ReposProxy {
+export function createReposProxy(
+  config: RequestConfig = {}
+): ReposProxy {
   return createApiProxy(
     (owner) => createApiProxy(
       (repo) => createRepoProxy(owner, repo, config)

package/src/api/users.ts

@@ -32,16 +32,20 @@ export type UsersProxy = {
 function createUserProxy(
   username: string,
   config: RequestConfig = {}
-): UserEndpointMethods {
+) {
   return Object.fromEntries(
-    (Object.keys(kUserEndpointResponseMap) as UserEndpoint[]).map(
+    Object.keys(kUserEndpointResponseMap).map(
       (endpoint) => [endpoint, () => new ApiEndpoint(`/users/${username}/${endpoint}`, config)]
     )
-  ) as UserEndpointMethods;
+  );
 }
 
-export function createUsersProxy(config: RequestConfig = {}): UsersProxy {
-  return createApiProxy((username) => createUserProxy(username, config)) as UsersProxy;
+export function createUsersProxy(
+  config: RequestConfig = {}
+): UsersProxy {
+  return createApiProxy(
+    (username) => createUserProxy(username, config)
+  ) as UsersProxy;
 }
 
 export const users = createUsersProxy();

package/src/class/ApiEndpoint.ts

@@ -1,26 +1,18 @@
 // Import Internal Dependencies
 import { HttpLinkParser } from "./HttpLinkParser.ts";
+import {
+  DEFAULT_USER_AGENT,
+  GITHUB_API
+} from "../constants.ts";
+import type { RequestConfig } from "../types.ts";
 
-// CONSTANTS
-const kGithubURL = new URL("https://api.github.com/");
-
-export class ApiEndpointOptions<T> {
+export interface ApiEndpointOptions<T> extends RequestConfig {
   /**
    * By default, the raw response from the GitHub API is returned as-is.
    * You can provide a custom extractor function to transform the raw response
    * into an array of type T.
    */
   extractor?: (raw: any) => T[];
-  /**
-   * A personal access token is required to access private resources,
-   * and to increase the rate limit for unauthenticated requests.
-   */
-  token?: string;
-  /**
-   * @default "@openally/github.sdk/1.0.0"
-   * @see https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28#user-agent
-   */
-  userAgent?: string;
 }
 
 export class ApiEndpoint<T> {
@@ -36,7 +28,7 @@ export class ApiEndpoint<T> {
     options: ApiEndpointOptions<T> = {}
   ) {
     const {
-      userAgent = "@openally/github.sdk/1.0.0",
+      userAgent = DEFAULT_USER_AGENT,
       token,
       extractor = ((raw) => raw as T[])
     } = options;
@@ -75,8 +67,8 @@ export class ApiEndpoint<T> {
     };
 
     const url = this.#nextURL === null ?
-      new URL(this.#apiEndpoint, kGithubURL) :
-      new URL(this.#nextURL, kGithubURL);
+      new URL(this.#apiEndpoint, GITHUB_API) :
+      new URL(this.#nextURL, GITHUB_API);
     const response = await fetch(
       url,
       { headers }
@@ -99,7 +91,18 @@ export class ApiEndpoint<T> {
     } while (this.#nextURL !== null);
   }
 
+  [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+    return this.iterate();
+  }
+
   all(): Promise<T[]> {
     return Array.fromAsync(this.iterate());
   }
+
+  then<TResult1 = T[], TResult2 = never>(
+    onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.all().then(onfulfilled, onrejected);
+  }
 }

package/src/class/GithubClient.ts

@@ -7,25 +7,56 @@ import {
   createReposProxy,
   type ReposProxy
 } from "../api/repos.ts";
+import {
+  fetchRawFile,
+  type FetchRawFileClientOptions,
+  type RawFileParser
+} from "../api/rawFile.ts";
+import type { RequestConfig } from "../types.ts";
 
-export interface GithubClientOptions {
-  token?: string;
-  userAgent?: string;
-}
+export interface GithubClientOptions extends RequestConfig {}
 
 export class GithubClient {
   readonly users: UsersProxy;
   readonly repos: ReposProxy;
+  #config: RequestConfig;
 
   constructor(
     options: GithubClientOptions = {}
   ) {
-    const config = {
+    this.#config = {
       token: options.token,
       userAgent: options.userAgent
     };
 
-    this.users = createUsersProxy(config);
-    this.repos = createReposProxy(config);
+    this.users = createUsersProxy(this.#config);
+    this.repos = createReposProxy(this.#config);
+  }
+
+  fetchRawFile(
+    repository: `${string}/${string}`,
+    filePath: string,
+    options?: FetchRawFileClientOptions & { parser?: undefined; }
+  ): Promise<string>;
+  fetchRawFile<T = unknown>(
+    repository: `${string}/${string}`,
+    filePath: string,
+    options: FetchRawFileClientOptions & { parser: "json"; }
+  ): Promise<T>;
+  fetchRawFile<T>(
+    repository: `${string}/${string}`,
+    filePath: string,
+    options: FetchRawFileClientOptions & { parser: (content: string) => T; }
+  ): Promise<T>;
+  fetchRawFile<T>(
+    repository: `${string}/${string}`,
+    filePath: string,
+    options: FetchRawFileClientOptions & { parser?: RawFileParser<T>; } = {}
+  ): Promise<string | T> {
+    return fetchRawFile<T>(
+      repository,
+      filePath,
+      { ...this.#config, ...options } as any
+    );
   }
 }

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_USER_AGENT = "@openally/github.sdk/1.0.0";
+export const GITHUB_API = new URL("https://api.github.com/");
+export const GITHUB_RAW_API = new URL("https://raw.githubusercontent.com/");

package/src/index.ts

@@ -1,5 +1,9 @@
 export * from "./api/users.ts";
 export * from "./api/repos.ts";
+export {
+  fetchRawFile,
+  type FetchRawFileOptions
+} from "./api/rawFile.ts";
 export * from "./class/GithubClient.ts";
 export type { RequestConfig } from "./types.ts";
 

package/src/types.ts

@@ -2,7 +2,15 @@
 import type { Endpoints } from "@octokit/types";
 
 export interface RequestConfig {
+  /**
+   * A personal access token is required to access private resources,
+   * and to increase the rate limit for unauthenticated requests.
+   */
   token?: string;
+  /**
+   * @default "@openally/github.sdk/1.0.0"
+   * @see https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28#user-agent
+   */
   userAgent?: string;
 }
 

package/test/ApiEndpoint.spec.ts

@@ -140,6 +140,21 @@ describe("ApiEndpoint", () => {
     });
   });
 
+  describe("all() with thenable", () => {
+    it("should fetch a single page and return all items", async() => {
+      mockAgent
+        .get(kGithubOrigin)
+        .intercept({ path: "/users/foo/repos", method: "GET" })
+        .reply(200, JSON.stringify([{ id: 1 }, { id: 2 }]), {
+          headers: { "content-type": "application/json" }
+        });
+
+      const result = await new ApiEndpoint("/users/foo/repos");
+
+      assert.deepEqual(result, [{ id: 1 }, { id: 2 }]);
+    });
+  });
+
   describe("iterate()", () => {
     it("should yield items one at a time", async() => {
       mockAgent
@@ -184,6 +199,50 @@ describe("ApiEndpoint", () => {
     });
   });
 
+  describe("Symbol.asyncIterator", () => {
+    it("should yield items one at a time", async() => {
+      mockAgent
+        .get(kGithubOrigin)
+        .intercept({ path: "/users/foo/repos", method: "GET" })
+        .reply(200, JSON.stringify([{ id: 1 }, { id: 2 }]), {
+          headers: { "content-type": "application/json" }
+        });
+
+      const items: unknown[] = [];
+      for await (const item of new ApiEndpoint("/users/foo/repos")) {
+        items.push(item);
+      }
+
+      assert.deepEqual(items, [{ id: 1 }, { id: 2 }]);
+    });
+
+    it("should yield items across paginated pages", async() => {
+      const pool = mockAgent.get(kGithubOrigin);
+
+      pool
+        .intercept({ path: "/users/foo/repos", method: "GET" })
+        .reply(200, JSON.stringify([{ id: 1 }]), {
+          headers: {
+            "content-type": "application/json",
+            link: '<https://api.github.com/users/foo/repos?page=2>; rel="next"'
+          }
+        });
+
+      pool
+        .intercept({ path: "/users/foo/repos?page=2", method: "GET" })
+        .reply(200, JSON.stringify([{ id: 2 }, { id: 3 }]), {
+          headers: { "content-type": "application/json" }
+        });
+
+      const items: unknown[] = [];
+      for await (const item of new ApiEndpoint("/users/foo/repos")) {
+        items.push(item);
+      }
+
+      assert.deepEqual(items, [{ id: 1 }, { id: 2 }, { id: 3 }]);
+    });
+  });
+
   describe("headers", () => {
     it("should send the default User-Agent header", async() => {
       mockAgent
@@ -257,10 +316,12 @@ describe("ApiEndpoint", () => {
 
   describe("extractor", () => {
     it("should apply the extractor to transform the raw response", async() => {
+      const workflows = [{ id: 10 }, { id: 20 }];
+
       mockAgent
         .get(kGithubOrigin)
         .intercept({ path: "/repos/foo/bar/actions/workflows", method: "GET" })
-        .reply(200, JSON.stringify({ total_count: 2, workflows: [{ id: 10 }, { id: 20 }] }), {
+        .reply(200, JSON.stringify({ total_count: 2, workflows }), {
           headers: { "content-type": "application/json" }
         });
 
@@ -269,7 +330,7 @@ describe("ApiEndpoint", () => {
         { extractor: (raw) => raw.workflows }
       ).all();
 
-      assert.deepEqual(result, [{ id: 10 }, { id: 20 }]);
+      assert.deepEqual(result, workflows);
     });
 
     it("should apply the extractor on every page when paginating", async() => {