@openally/github.sdk 1.0.0 → 1.1.1

package/src/class/ApiEndpoint.ts

@@ -1,105 +0,0 @@
-// Import Internal Dependencies
-import { HttpLinkParser } from "./HttpLinkParser.ts";
-
-// CONSTANTS
-const kGithubURL = new URL("https://api.github.com/");
-
-export class ApiEndpointOptions<T> {
-  /**
-   * 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> {
-  #userAgent: string;
-  #bearerToken?: string;
-
-  #nextURL: string | null = null;
-  #apiEndpoint: string | URL;
-  #extractor: (raw: any) => T[];
-
-  constructor(
-    apiEndpoint: string | URL,
-    options: ApiEndpointOptions<T> = {}
-  ) {
-    const {
-      userAgent = "@openally/github.sdk/1.0.0",
-      token,
-      extractor = ((raw) => raw as T[])
-    } = options;
-
-    this.#userAgent = userAgent;
-    this.#bearerToken = token;
-    this.#apiEndpoint = apiEndpoint;
-    this.#extractor = extractor;
-  }
-
-  setBearerToken(
-    token: string
-  ): this {
-    this.#bearerToken = token;
-
-    return this;
-  }
-
-  setAgent(
-    userAgent: string
-  ): this {
-    this.#userAgent = userAgent;
-
-    return this;
-  }
-
-  async #next(): Promise<T[]> {
-    const headers = {
-      "User-Agent": this.#userAgent,
-      Accept: "application/vnd.github.v3.raw",
-      ...(
-        typeof this.#bearerToken === "string" ?
-          { Authorization: `token ${this.#bearerToken}` } :
-          {}
-      )
-    };
-
-    const url = this.#nextURL === null ?
-      new URL(this.#apiEndpoint, kGithubURL) :
-      new URL(this.#nextURL, kGithubURL);
-    const response = await fetch(
-      url,
-      { headers }
-    );
-    const rawData = await response.json();
-
-    const linkHeader = response.headers.get("link");
-    this.#nextURL = linkHeader
-      ? HttpLinkParser.parse(linkHeader).get("next") ?? null
-      : null;
-
-    return this.#extractor(rawData);
-  }
-
-  async* iterate(): AsyncIterableIterator<T> {
-    do {
-      const pageResults = await this.#next();
-
-      yield* pageResults;
-    } while (this.#nextURL !== null);
-  }
-
-  all(): Promise<T[]> {
-    return Array.fromAsync(this.iterate());
-  }
-}

package/src/class/GithubClient.ts

@@ -1,31 +0,0 @@
-// Import Internal Dependencies
-import {
-  createUsersProxy,
-  type UsersProxy
-} from "../api/users.ts";
-import {
-  createReposProxy,
-  type ReposProxy
-} from "../api/repos.ts";
-
-export interface GithubClientOptions {
-  token?: string;
-  userAgent?: string;
-}
-
-export class GithubClient {
-  readonly users: UsersProxy;
-  readonly repos: ReposProxy;
-
-  constructor(
-    options: GithubClientOptions = {}
-  ) {
-    const config = {
-      token: options.token,
-      userAgent: options.userAgent
-    };
-
-    this.users = createUsersProxy(config);
-    this.repos = createReposProxy(config);
-  }
-}

package/src/class/HttpLinkParser.ts

@@ -1,17 +0,0 @@
-export class HttpLinkParser {
-  static parse(
-    headerValue: string
-  ): Map<string, string> {
-    const result = new Map<string, string>();
-
-    for (const part of headerValue.split(", ")) {
-      const urlMatch = part.match(/^<([^>]+)>/);
-      const relMatch = part.match(/rel="([^"]+)"/);
-      if (urlMatch && relMatch) {
-        result.set(relMatch[1], urlMatch[1]);
-      }
-    }
-
-    return result;
-  }
-}

package/src/class/createApiProxy.ts

@@ -1,9 +0,0 @@
-export function createApiProxy<T>(
-  factory: (key: string) => T
-): Record<string, T> {
-  return new Proxy(Object.create(null), {
-    get(_, key: string) {
-      return factory(key);
-    }
-  }) as Record<string, T>;
-}

package/test/ApiEndpoint.spec.ts

@@ -1,301 +0,0 @@
-// Import Node.js Dependencies
-import { describe, it, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-
-// Import Third-party Dependencies
-import { MockAgent, setGlobalDispatcher, getGlobalDispatcher, type Dispatcher } from "undici";
-
-// Import Internal Dependencies
-import { ApiEndpoint } from "../src/class/ApiEndpoint.ts";
-
-// CONSTANTS
-const kGithubOrigin = "https://api.github.com";
-
-describe("ApiEndpoint", () => {
-  let mockAgent: MockAgent;
-  let originalDispatcher: Dispatcher;
-
-  beforeEach(() => {
-    originalDispatcher = getGlobalDispatcher();
-    mockAgent = new MockAgent();
-    mockAgent.disableNetConnect();
-    setGlobalDispatcher(mockAgent);
-  });
-
-  afterEach(async() => {
-    await mockAgent.close();
-    setGlobalDispatcher(originalDispatcher);
-  });
-
-  describe("constructor", () => {
-    it("should accept a string endpoint", () => {
-      const endpoint = new ApiEndpoint("/users/foo/repos");
-
-      assert.ok(endpoint instanceof ApiEndpoint);
-    });
-
-    it("should accept a URL endpoint", () => {
-      const endpoint = new ApiEndpoint(new URL("https://api.github.com/users/foo/repos"));
-
-      assert.ok(endpoint instanceof ApiEndpoint);
-    });
-  });
-
-  describe("setBearerToken()", () => {
-    it("should return this for chaining", () => {
-      const endpoint = new ApiEndpoint("/users/foo/repos");
-
-      assert.strictEqual(endpoint.setBearerToken("mytoken"), endpoint);
-    });
-  });
-
-  describe("setAgent()", () => {
-    it("should return this for chaining", () => {
-      const endpoint = new ApiEndpoint("/users/foo/repos");
-
-      assert.strictEqual(endpoint.setAgent("my-agent/1.0"), endpoint);
-    });
-  });
-
-  describe("all()", () => {
-    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").all();
-
-      assert.deepEqual(result, [{ id: 1 }, { id: 2 }]);
-    });
-
-    it("should return an empty array when the response is empty", async() => {
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({ path: "/users/foo/repos", method: "GET" })
-        .reply(200, JSON.stringify([]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await new ApiEndpoint("/users/foo/repos").all();
-
-      assert.deepEqual(result, []);
-    });
-
-    it("should follow pagination using the link header", 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 }]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await new ApiEndpoint("/users/foo/repos").all();
-
-      assert.deepEqual(result, [{ id: 1 }, { id: 2 }]);
-    });
-
-    it("should follow multiple pages until no next link", 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 }]), {
-          headers: {
-            "content-type": "application/json",
-            link: '<https://api.github.com/users/foo/repos?page=3>; rel="next"'
-          }
-        });
-
-      pool
-        .intercept({ path: "/users/foo/repos?page=3", method: "GET" })
-        .reply(200, JSON.stringify([{ id: 3 }]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await new ApiEndpoint("/users/foo/repos").all();
-
-      assert.deepEqual(result, [{ id: 1 }, { id: 2 }, { id: 3 }]);
-    });
-  });
-
-  describe("iterate()", () => {
-    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").iterate()) {
-        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").iterate()) {
-        items.push(item);
-      }
-
-      assert.deepEqual(items, [{ id: 1 }, { id: 2 }, { id: 3 }]);
-    });
-  });
-
-  describe("headers", () => {
-    it("should send the default User-Agent header", async() => {
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/users/foo/repos",
-          method: "GET",
-          headers: { "user-agent": "@openally/github.sdk/1.0.0" }
-        })
-        .reply(200, JSON.stringify([]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      // If header doesn't match, undici will throw — this is the assertion
-      await assert.doesNotReject(
-        new ApiEndpoint("/users/foo/repos").all()
-      );
-    });
-
-    it("should send a custom User-Agent when set via setAgent()", async() => {
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/users/foo/repos",
-          method: "GET",
-          headers: { "user-agent": "custom-agent/2.0" }
-        })
-        .reply(200, JSON.stringify([]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      await assert.doesNotReject(
-        new ApiEndpoint("/users/foo/repos").setAgent("custom-agent/2.0").all()
-      );
-    });
-
-    it("should send the Authorization header when a token is provided", async() => {
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/users/foo/repos",
-          method: "GET",
-          headers: { authorization: "token secret123" }
-        })
-        .reply(200, JSON.stringify([]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      await assert.doesNotReject(
-        new ApiEndpoint("/users/foo/repos", { token: "secret123" }).all()
-      );
-    });
-
-    it("should send the Authorization header when set via setBearerToken()", async() => {
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/users/foo/repos",
-          method: "GET",
-          headers: { authorization: "token runtime-token" }
-        })
-        .reply(200, JSON.stringify([]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      await assert.doesNotReject(
-        new ApiEndpoint("/users/foo/repos").setBearerToken("runtime-token").all()
-      );
-    });
-  });
-
-  describe("extractor", () => {
-    it("should apply the extractor to transform the raw response", async() => {
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({ path: "/repos/foo/bar/actions/workflows", method: "GET" })
-        .reply(200, JSON.stringify({ total_count: 2, workflows: [{ id: 10 }, { id: 20 }] }), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await new ApiEndpoint(
-        "/repos/foo/bar/actions/workflows",
-        { extractor: (raw) => raw.workflows }
-      ).all();
-
-      assert.deepEqual(result, [{ id: 10 }, { id: 20 }]);
-    });
-
-    it("should apply the extractor on every page when paginating", async() => {
-      const pool = mockAgent.get(kGithubOrigin);
-
-      pool
-        .intercept({ path: "/repos/foo/bar/actions/workflows", method: "GET" })
-        .reply(200, JSON.stringify({ total_count: 3, workflows: [{ id: 10 }] }), {
-          headers: {
-            "content-type": "application/json",
-            link: '<https://api.github.com/repos/foo/bar/actions/workflows?page=2>; rel="next"'
-          }
-        });
-
-      pool
-        .intercept({ path: "/repos/foo/bar/actions/workflows?page=2", method: "GET" })
-        .reply(200, JSON.stringify({ total_count: 3, workflows: [{ id: 20 }, { id: 30 }] }), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await new ApiEndpoint(
-        "/repos/foo/bar/actions/workflows",
-        { extractor: (raw) => raw.workflows }
-      ).all();
-
-      assert.deepEqual(result, [{ id: 10 }, { id: 20 }, { id: 30 }]);
-    });
-  });
-});

package/test/GithubClient.spec.ts

@@ -1,166 +0,0 @@
-// Import Node.js Dependencies
-import { describe, it, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-
-// Import Third-party Dependencies
-import { MockAgent, setGlobalDispatcher, getGlobalDispatcher, type Dispatcher } from "undici";
-
-// Import Internal Dependencies
-import { GithubClient } from "../src/class/GithubClient.ts";
-import { ApiEndpoint } from "../src/class/ApiEndpoint.ts";
-
-// CONSTANTS
-const kGithubOrigin = "https://api.github.com";
-
-describe("GithubClient", () => {
-  let mockAgent: MockAgent;
-  let originalDispatcher: Dispatcher;
-
-  beforeEach(() => {
-    originalDispatcher = getGlobalDispatcher();
-    mockAgent = new MockAgent();
-    mockAgent.disableNetConnect();
-    setGlobalDispatcher(mockAgent);
-  });
-
-  afterEach(async() => {
-    await mockAgent.close();
-    setGlobalDispatcher(originalDispatcher);
-  });
-
-  describe("constructor", () => {
-    it("should instantiate with no options", () => {
-      const client = new GithubClient();
-
-      assert.ok(client instanceof GithubClient);
-    });
-
-    it("should instantiate with a token", () => {
-      const client = new GithubClient({ token: "mytoken" });
-
-      assert.ok(client instanceof GithubClient);
-    });
-
-    it("should instantiate with a custom userAgent", () => {
-      const client = new GithubClient({ userAgent: "my-app/1.0" });
-
-      assert.ok(client instanceof GithubClient);
-    });
-
-    it("should expose a users proxy", () => {
-      const client = new GithubClient();
-
-      assert.ok(client.users !== undefined);
-    });
-
-    it("should expose a repos proxy", () => {
-      const client = new GithubClient();
-
-      assert.ok(client.repos !== undefined);
-    });
-  });
-
-  describe("client.users", () => {
-    it("should return ApiEndpoints for user sub-resources", () => {
-      const client = new GithubClient();
-
-      assert.ok(client.users.foo.repos() instanceof ApiEndpoint);
-      assert.ok(client.users.foo.orgs() instanceof ApiEndpoint);
-    });
-
-    it("should use the configured token when fetching user data", async() => {
-      const client = new GithubClient({ token: "clienttoken" });
-
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/users/octocat/repos",
-          method: "GET",
-          headers: { authorization: "token clienttoken" }
-        })
-        .reply(200, JSON.stringify([{ id: 1 }]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await client.users.octocat.repos().all();
-
-      assert.deepEqual(result, [{ id: 1 }]);
-    });
-
-    it("should fetch user data without a token", async() => {
-      const client = new GithubClient();
-
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({ path: "/users/octocat/followers", method: "GET" })
-        .reply(200, JSON.stringify([{ login: "user1" }]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await client.users.octocat.followers().all();
-
-      assert.deepEqual(result, [{ login: "user1" }]);
-    });
-  });
-
-  describe("client.repos", () => {
-    it("should return ApiEndpoints for repo sub-resources", () => {
-      const client = new GithubClient();
-
-      assert.ok(client.repos.owner.myrepo.tags() instanceof ApiEndpoint);
-      assert.ok(client.repos.owner.myrepo.pulls() instanceof ApiEndpoint);
-      assert.ok(client.repos.owner.myrepo.workflows() instanceof ApiEndpoint);
-    });
-
-    it("should use the configured token when fetching repo data", async() => {
-      const client = new GithubClient({ token: "repotoken" });
-
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/repos/octocat/hello-world/tags",
-          method: "GET",
-          headers: { authorization: "token repotoken" }
-        })
-        .reply(200, JSON.stringify([{ name: "v1.0.0" }]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await client.repos.octocat["hello-world"].tags().all();
-
-      assert.deepEqual(result, [{ name: "v1.0.0" }]);
-    });
-
-    it("should use the configured userAgent when fetching", async() => {
-      const client = new GithubClient({ userAgent: "my-app/1.0" });
-
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({
-          path: "/repos/octocat/hello-world/tags",
-          method: "GET",
-          headers: { "user-agent": "my-app/1.0" }
-        })
-        .reply(200, JSON.stringify([]), {
-          headers: { "content-type": "application/json" }
-        });
-
-      await assert.doesNotReject(client.repos.octocat["hello-world"].tags().all());
-    });
-
-    it("should fetch workflows with the envelope extractor", async() => {
-      const client = new GithubClient();
-
-      mockAgent
-        .get(kGithubOrigin)
-        .intercept({ path: "/repos/octocat/hello-world/actions/workflows", method: "GET" })
-        .reply(200, JSON.stringify({ total_count: 1, workflows: [{ id: 7, name: "CI" }] }), {
-          headers: { "content-type": "application/json" }
-        });
-
-      const result = await client.repos.octocat["hello-world"].workflows().all();
-
-      assert.deepEqual(result, [{ id: 7, name: "CI" }]);
-    });
-  });
-});