chore: implement new APIs

Author: fraxken

.gitignore

@@ -139,3 +139,5 @@ vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 
 temp.ts
+
+.claude

README.md

@@ -38,15 +38,62 @@ $ npm i @openally/github.sdk
 $ yarn add @openally/github.sdk
 ```
 
-## 📚 Usage
+## 👀 Usage
 
 ```ts
-// TBC
+import {
+  repos,
+  users
+} from "@openally/github.sdk";
+
+// Iterate over all pull requests (pagination handled automatically)
+for await (const pr of repos.OpenAlly["github.sdk"].pulls().iterate()) {
+  console.log(pr.title);
+}
+
+// Fetch all tags at once
+const tags = await repos.OpenAlly["github.sdk"].tags().all();
+
+// List all repos for a user
+const userRepos = await users.torvalds.repos().all();
+
+// Iterate over workflow runs for a specific workflow
+for await (const run of repos.nodejs.node.workflowRuns("ci.yml").iterate()) {
+  console.log(run.id, run.status);
+}
 ```
 
-## API
-
-TBC
+Each method returns an `ApiEndpoint<T>` instance with:
+- `.setBearerToken(token)` — attach a GitHub personal access token
+- `.setAgent(userAgent)` — override the default `User-Agent` header
+- `.iterate()` — `AsyncIterableIterator<T>` that handles pagination transparently
+- `.all()` — `Promise<T[]>` collecting all pages
+
+## 📚 API
+
+### `repos[owner][repo]`
+
+| Method | GitHub Documentation |
+|---|---|
+| `.tags()` | [List repository tags](https://docs.github.com/en/rest/repos/repos#list-repository-tags) |
+| `.pulls()` | [List pull requests](https://docs.github.com/en/rest/pulls/pulls#list-pull-requests) |
+| `.issues()` | [List repository issues](https://docs.github.com/en/rest/issues/issues#list-repository-issues) |
+| `.commits()` | [List commits](https://docs.github.com/en/rest/commits/commits#list-commits) |
+| `.workflows()` | [List repository workflows](https://docs.github.com/en/rest/actions/workflows#list-repository-workflows) |
+| `.workflowRuns(workflowId)` | [List workflow runs for a workflow](https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-workflow) |
+| `.runJobs(runId)` | [List jobs for a workflow run](https://docs.github.com/en/rest/actions/workflow-jobs#list-jobs-for-a-workflow-run) |
+| `.runArtifacts(runId)` | [List workflow run artifacts](https://docs.github.com/en/rest/actions/artifacts#list-workflow-run-artifacts) |
+
+### `users[username]`
+
+| Method | GitHub Documentation |
+|---|---|
+| `.orgs()` | [List organizations for a user](https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-a-user) |
+| `.repos()` | [List repositories for a user](https://docs.github.com/en/rest/repos/repos#list-repositories-for-a-user) |
+| `.gists()` | [List gists for a user](https://docs.github.com/en/rest/gists/gists#list-gists-for-a-user) |
+| `.followers()` | [List followers of a user](https://docs.github.com/en/rest/users/followers#list-followers-of-a-user) |
+| `.following()` | [List the people a user follows](https://docs.github.com/en/rest/users/followers#list-the-people-a-user-follows) |
+| `.starred()` | [List repositories starred by a user](https://docs.github.com/en/rest/activity/starring#list-repositories-starred-by-a-user) |
 
 ## Contributors ✨
 

package.json

@@ -39,13 +39,11 @@
   "devDependencies": {
     "@openally/config.eslint": "^2.2.0",
     "@openally/config.typescript": "^1.2.1",
-    "@types/http-link-header": "1.0.7",
     "@types/node": "25.3.1",
     "c8": "^11.0.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@octokit/types": "16.0.0",
-    "http-link-header": "1.1.3"
+    "@octokit/types": "16.0.0"
   }
 }

src/api/.gitkeep

@@ -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();

src/api/repos.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();

src/api/users.ts

@@ -1,26 +1,50 @@
 // Import Internal Dependencies
-import * as utils from "../utils/index.ts";
+import { HttpLinkParser } from "./HttpLinkParser.ts";
 
 // CONSTANTS
 const kGithubURL = new URL("https://api.github.com/");
 
-/**
- * @see https://github.com/dashlog/fetch-github-repositories/blob/master/src/api.ts#L66
- * @see https://github.com/fraxken/dep-updater/blob/master/src/githubActions.ts#L97C53-L97C66
- */
+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
+    apiEndpoint: string | URL,
+    options: ApiEndpointOptions<T> = {}
   ) {
-    this.#userAgent = "@openally/github.sdk/1.0.0";
+    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(
@@ -57,12 +81,14 @@ export class ApiEndpoint<T> {
       url,
       { headers }
     );
-    const data = await response.json() as T[];
+    const rawData = await response.json();
 
     const linkHeader = response.headers.get("link");
-    this.#nextURL = utils.getNextPageURL(linkHeader);
+    this.#nextURL = linkHeader
+      ? HttpLinkParser.parse(linkHeader).get("next") ?? null
+      : null;
 
-    return data;
+    return this.#extractor(rawData);
   }
 
   async* iterate(): AsyncIterableIterator<T> {
@@ -74,6 +100,6 @@ export class ApiEndpoint<T> {
   }
 
   all(): Promise<T[]> {
-    return utils.fromAsync(this.iterate());
+    return Array.fromAsync(this.iterate());
   }
 }

src/class/ApiEndpoint.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);
+  }
+}

src/class/GithubClient.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;
+  }
+}

src/class/HttpLinkParser.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>;
+}