@openally/github.sdk 1.0.0

package/docs/api/users.md

@@ -0,0 +1,76 @@
+# users
+
+The `users` proxy provides access to GitHub user endpoints.
+
+```ts
+import { users } from "@openally/github.sdk";
+
+// Collect all repositories for a user
+const repos = await users.torvalds.repos().all();
+
+// Stream followers one by one
+for await (const follower of users.torvalds.followers().iterate()) {
+  console.log(follower.login);
+}
+
+// Collect all starred repositories
+const starred = await users.torvalds.starred().all();
+```
+
+## Access pattern
+
+```ts
+users[username].<method>()
+```
+
+All methods return an [`ApiEndpoint<T>`](./ApiEndpoint.md) instance.
+
+## Methods
+
+### `.orgs()`
+
+Returns `ApiEndpoint<UserOrg>`.
+
+Lists all organizations the user belongs to.
+
+> GitHub docs: [List organizations for a user](https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-a-user)
+
+### `.repos()`
+
+Returns `ApiEndpoint<UserRepo>`.
+
+Lists all public repositories for the user.
+
+> GitHub docs: [List repositories for a user](https://docs.github.com/en/rest/repos/repos#list-repositories-for-a-user)
+
+### `.gists()`
+
+Returns `ApiEndpoint<UserGist>`.
+
+Lists all public gists for the user.
+
+> GitHub docs: [List gists for a user](https://docs.github.com/en/rest/gists/gists#list-gists-for-a-user)
+
+### `.followers()`
+
+Returns `ApiEndpoint<UserFollower>`.
+
+Lists all followers of the user.
+
+> GitHub docs: [List followers of a user](https://docs.github.com/en/rest/users/followers#list-followers-of-a-user)
+
+### `.following()`
+
+Returns `ApiEndpoint<UserFollowing>`.
+
+Lists all users the user follows.
+
+> GitHub docs: [List the people a user follows](https://docs.github.com/en/rest/users/followers#list-the-people-a-user-follows)
+
+### `.starred()`
+
+Returns `ApiEndpoint<UserStarred>`.
+
+Lists all repositories starred by the user.
+
+> GitHub docs: [List repositories starred by a user](https://docs.github.com/en/rest/activity/starring#list-repositories-starred-by-a-user)

package/eslint.config.mjs

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@openally/github.sdk",
+  "version": "1.0.0",
+  "description": "Opiniated Node.js Github SDK",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node --test ./test/**/*.spec.ts",
+    "coverage": "c8 --reporter=lcov npm run test",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenAlly/github.sdk.git"
+  },
+  "keywords": [
+    "github",
+    "sdk",
+    "api",
+    "client",
+    "nodejs",
+    "typescript"
+  ],
+  "author": "GENTILHOMME Thomas <gentilhomme.thomas@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/OpenAlly/github.sdk/issues"
+  },
+  "homepage": "https://github.com/OpenAlly/github.sdk#readme",
+  "devDependencies": {
+    "@openally/config.eslint": "^2.2.0",
+    "@openally/config.typescript": "^1.2.1",
+    "@types/node": "25.3.1",
+    "c8": "^11.0.0",
+    "typescript": "^5.9.3",
+    "undici": "7.22.0"
+  },
+  "dependencies": {
+    "@octokit/types": "16.0.0"
+  }
+}

package/src/api/repos.ts

@@ -0,0 +1,74 @@
+// Import Internal Dependencies
+import { ApiEndpoint } from "../class/ApiEndpoint.ts";
+import { createApiProxy } from "../class/createApiProxy.ts";
+import type {
+  Tag,
+  PullRequest,
+  Issue,
+  Commit,
+  Workflow,
+  WorkflowRun,
+  Job,
+  Artifact,
+  WorkflowsResponse,
+  WorkflowRunsResponse,
+  JobsResponse,
+  ArtifactsResponse,
+  RequestConfig
+} from "../types.ts";
+
+type RepoEndpointMethods = {
+  tags: () => ApiEndpoint<Tag>;
+  pulls: () => ApiEndpoint<PullRequest>;
+  issues: () => ApiEndpoint<Issue>;
+  commits: () => ApiEndpoint<Commit>;
+  workflows: () => ApiEndpoint<Workflow>;
+  workflowRuns: (workflowId: string | number) => ApiEndpoint<WorkflowRun>;
+  runJobs: (runId: number) => ApiEndpoint<Job>;
+  runArtifacts: (runId: number) => ApiEndpoint<Artifact>;
+};
+
+export type ReposProxy = {
+  [owner: string]: {
+    [repo: string]: RepoEndpointMethods;
+  };
+};
+
+function createRepoProxy(
+  owner: string,
+  repo: string,
+  config: RequestConfig = {}
+): RepoEndpointMethods {
+  return {
+    tags: () => new ApiEndpoint<Tag>(`/repos/${owner}/${repo}/tags`, config),
+    pulls: () => new ApiEndpoint<PullRequest>(`/repos/${owner}/${repo}/pulls`, config),
+    issues: () => new ApiEndpoint<Issue>(`/repos/${owner}/${repo}/issues`, config),
+    commits: () => new ApiEndpoint<Commit>(`/repos/${owner}/${repo}/commits`, config),
+    workflows: () => new ApiEndpoint<Workflow>(
+      `/repos/${owner}/${repo}/actions/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 }
+    ),
+    runJobs: (runId: number) => new ApiEndpoint<Job>(
+      `/repos/${owner}/${repo}/actions/runs/${runId}/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 }
+    )
+  };
+}
+
+export function createReposProxy(config: RequestConfig = {}): ReposProxy {
+  return createApiProxy(
+    (owner) => createApiProxy(
+      (repo) => createRepoProxy(owner, repo, config)
+    )
+  ) as ReposProxy;
+}
+
+export const repos = createReposProxy();

package/src/api/users.ts

@@ -0,0 +1,47 @@
+// Import Internal Dependencies
+import { ApiEndpoint } from "../class/ApiEndpoint.ts";
+import { createApiProxy } from "../class/createApiProxy.ts";
+import type {
+  UserOrg,
+  UserRepo,
+  UserGist,
+  UserFollower,
+  UserFollowing,
+  UserStarred,
+  RequestConfig
+} from "../types.ts";
+
+// CONSTANTS
+const kUserEndpointResponseMap = {
+  orgs: {} as UserOrg,
+  repos: {} as UserRepo,
+  gists: {} as UserGist,
+  followers: {} as UserFollower,
+  following: {} as UserFollowing,
+  starred: {} as UserStarred
+};
+
+type UserEndpoint = keyof typeof kUserEndpointResponseMap;
+type UserEndpointMethods = {
+  [K in UserEndpoint]: () => ApiEndpoint<typeof kUserEndpointResponseMap[K]>;
+};
+export type UsersProxy = {
+  [username: string]: UserEndpointMethods;
+};
+
+function createUserProxy(
+  username: string,
+  config: RequestConfig = {}
+): UserEndpointMethods {
+  return Object.fromEntries(
+    (Object.keys(kUserEndpointResponseMap) as UserEndpoint[]).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 const users = createUsersProxy();

package/src/class/ApiEndpoint.ts

@@ -0,0 +1,105 @@
+// 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

@@ -0,0 +1,31 @@
+// 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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,9 @@
+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/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,37 @@
+// Import Third-party Dependencies
+import type { Endpoints } from "@octokit/types";
+
+export interface RequestConfig {
+  token?: string;
+  userAgent?: string;
+}
+
+// --- Repo entity types ---
+export type Tag = Endpoints["GET /repos/{owner}/{repo}/tags"]["response"]["data"][number];
+export type PullRequest = Endpoints["GET /repos/{owner}/{repo}/pulls"]["response"]["data"][number];
+export type Issue = Endpoints["GET /repos/{owner}/{repo}/issues"]["response"]["data"][number];
+export type Commit = Endpoints["GET /repos/{owner}/{repo}/commits"]["response"]["data"][number];
+export type Workflow = Endpoints["GET /repos/{owner}/{repo}/actions/workflows"]["response"]["data"]["workflows"][number];
+export type WorkflowRun = Endpoints[
+  "GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs"
+]["response"]["data"]["workflow_runs"][number];
+export type Job = Endpoints["GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs"]["response"]["data"]["jobs"][number];
+export type Artifact = Endpoints[
+  "GET /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts"
+]["response"]["data"]["artifacts"][number];
+
+// Extractor response types (envelope objects returned by the GitHub API)
+export type WorkflowsResponse = Endpoints["GET /repos/{owner}/{repo}/actions/workflows"]["response"]["data"];
+export type WorkflowRunsResponse = Endpoints[
+  "GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs"
+]["response"]["data"];
+export type JobsResponse = Endpoints["GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs"]["response"]["data"];
+export type ArtifactsResponse = Endpoints["GET /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts"]["response"]["data"];
+
+// --- User entity types ---
+export type UserOrg = Endpoints["GET /users/{username}/orgs"]["response"]["data"][number];
+export type UserRepo = Endpoints["GET /users/{username}/repos"]["response"]["data"][number];
+export type UserGist = Endpoints["GET /users/{username}/gists"]["response"]["data"][number];
+export type UserFollower = Endpoints["GET /users/{username}/followers"]["response"]["data"][number];
+export type UserFollowing = Endpoints["GET /users/{username}/following"]["response"]["data"][number];
+export type UserStarred = Endpoints["GET /users/{username}/starred"]["response"]["data"][number];