Repositories

Get and list

const repo = await forge.repos.get("nitrojs", "nitro");
const page = await forge.repos.list("nitrojs", { page: 1, perPage: 30 });

get reads fresh every time. list reads one page of an owner's repositories.

The shape

interface Repository {
  id: string; // always a string, even when the API sends a number
  name: string;
  fullName: string; // "owner/name"
  description: string; // "" when the platform has none
  private: boolean;
  defaultBranch: string;
  url: string;
  cloneUrl: string;
  isFork: boolean;
  parent: { fullName: string; url: string } | null; // null when not a fork, or hidden
  viewerPermission: "none" | "read" | "triage" | "write" | "maintain" | "admin" | null;
  owner: { login: string; avatarUrl: string };
}

Two fields deserve a sentence. parent is the immediate upstream of a fork, null when there is none or the platform hides it. viewerPermission is your highest role on the repo. null means the platform said nothing about access, not that you have none. Anonymous calls always get null, do not read anything into it.

Owners that are groups

On GitLab, /users/:owner/projects is a 404 for a group. repos.list falls back to /groups/:owner/projects on that one status and re throws everything else, so a real 404 stays a NotFoundError instead of turning into a second guess.

Pagination

Every list returns:

interface PageResult<T> {
  items: T[];
  hasNextPage: boolean;
  nextPage?: number;
  totalCount?: number; // when the platform counts
}

GitHub and Gitea say what is next in a Link header, GitLab in x-next-page. Both are read for you. nextPage is the number you pass back as page.

To walk everything:

import { fetchAllPages, paginate } from "@agntn/forges";

const all = await fetchAllPages(fetcher, url); // one array
for await (const page of paginate(fetcher, url)) {
  // one page at a time
}

Both take a raw fetcher and a URL. They are the pieces the providers are built from, exported for custom ones.

Caching

Stable reads go through an LRU, five minutes and five hundred entries by default, scoped to the base URL and a hash of the token. Repository, issue, pull request, comment and user item reads skip it, because you call those to check current state and a stale answer there is worse than no cache. Lists use it.

const forge = createProvider("github", {
  cache: { ttl: 60_000, enabled: true },
});

cache.enabled: false turns it off for one provider. Mutations never touch it.