@horizon36596/zenith-github 0.1.1

package/dist/client.js

@@ -0,0 +1,265 @@
+import { assertPathAllowed } from "./allowlist.js";
+import { decodeBase64Utf8, encodeBase64Utf8 } from "./base64.js";
+import { BaseBranchWriteError, MergeConflictError, NotFoundError } from "./errors.js";
+import { HttpClient } from "./http.js";
+function toRepo(raw) {
+    return {
+        owner: raw.owner.login,
+        repo: raw.name,
+        fullName: raw.full_name,
+        defaultBranch: raw.default_branch,
+        private: raw.private,
+        htmlUrl: raw.html_url,
+    };
+}
+function toBranch(raw) {
+    return { name: raw.name, sha: raw.commit.sha, protected: raw.protected };
+}
+function toPull(raw) {
+    return {
+        number: raw.number,
+        url: raw.url,
+        htmlUrl: raw.html_url,
+        state: raw.state,
+        title: raw.title,
+        body: raw.body,
+        head: { ref: raw.head.ref, sha: raw.head.sha },
+        base: { ref: raw.base.ref, sha: raw.base.sha },
+    };
+}
+function toPullFile(raw) {
+    return { filename: raw.filename, status: raw.status, sha: raw.sha, patch: raw.patch };
+}
+/**
+ * An isomorphic (browser + Node), `fetch`-based GitHub client: no Octokit, no Node-only APIs. One
+ * instance is bound to an `AuthProvider`, not to a repository — `GitHubProject` is the layer bound
+ * to `{owner, repo, base}` (site/docs/github.md).
+ */
+export class GitHubClient {
+    http;
+    constructor(auth, options = {}) {
+        this.http = new HttpClient(auth, options);
+    }
+    /** The most recent `x-ratelimit-*` snapshot seen, or `null` before the first request. */
+    get rateLimit() {
+        return this.http.rateLimit;
+    }
+    repos = {
+        /** Repositories the authenticated account can push to, across personal and org affiliation. */
+        listWritable: async () => {
+            const repos = await this.paginate("/user/repos", {
+                affiliation: "owner,collaborator,organization_member",
+                per_page: 100,
+            });
+            return repos.filter((repo) => repo.permissions?.push).map(toRepo);
+        },
+        get: async (owner, repo) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}`);
+            return toRepo(raw);
+        },
+        /**
+         * Merges `head` into `base` (`POST /repos/{owner}/{repo}/merges`) — the "update the work
+         * branch from the base branch" step of propose (06 §3 step 2). On conflict, recovers the
+         * files in play by comparing both branches against their merge base; see `MergeConflictError`.
+         * `guard`, when given, refuses the call outright when `base` (the ref the merge commit lands
+         * on) is the project's protected base branch (finding 12).
+         */
+        merge: async (owner, repo, base, head, guard) => {
+            if (guard !== undefined && base === guard.base) {
+                throw new BaseBranchWriteError(base);
+            }
+            try {
+                const raw = await this.http.request(`/repos/${owner}/${repo}/merges`, {
+                    method: "POST",
+                    body: { base, head, commit_message: `Merge ${head} into ${base}` },
+                });
+                if (raw === null)
+                    return { commitSha: null, merged: false };
+                return { commitSha: raw.sha, merged: true };
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === "ConflictError") {
+                    const files = await this.conflictingFiles(owner, repo, base, head);
+                    throw new MergeConflictError(`"${head}" cannot be merged into "${base}" without a conflict in ${files.join(", ") || "an unknown file"}.`, files);
+                }
+                throw error;
+            }
+        },
+    };
+    branches = {
+        list: async (owner, repo) => {
+            const raw = await this.paginate(`/repos/${owner}/${repo}/branches`, { per_page: 100 });
+            return raw.map(toBranch);
+        },
+        get: async (owner, repo, branch) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}`);
+            return toBranch(raw);
+        },
+        /** Creates `name` pointing at `from`'s current sha. Never touches an existing ref (no force-push). */
+        create: async (owner, repo, name, from) => {
+            const source = await this.branches.get(owner, repo, from.branch);
+            await this.http.request(`/repos/${owner}/${repo}/git/refs`, {
+                method: "POST",
+                body: { ref: `refs/heads/${name}`, sha: source.sha },
+            });
+            return { name, sha: source.sha, protected: false };
+        },
+    };
+    contents = {
+        get: async (owner, repo, path, ref) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}/contents/${encodePath(path)}`, {
+                query: { ref },
+            });
+            if (raw.type !== "file") {
+                throw new NotFoundError(`"${path}" at ${ref} is a ${raw.type}, not a file.`);
+            }
+            return { path: raw.path, sha: raw.sha, text: decodeBase64Utf8(raw.content) };
+        },
+        /** `guard`, when given, refuses a write to the base branch or to a path outside `link`'s
+         * allowlist before any network call (finding 12). `GitHubProject.save` always passes one; a
+         * raw `GitHubClient` caller that cares about the same protection can pass one too. */
+        put: async (owner, repo, path, text, message, branch, sha, guard) => {
+            if (guard !== undefined) {
+                if (branch === guard.base)
+                    throw new BaseBranchWriteError(branch);
+                assertPathAllowed(guard.link, path);
+            }
+            const raw = await this.http.request(`/repos/${owner}/${repo}/contents/${encodePath(path)}`, {
+                method: "PUT",
+                body: {
+                    message,
+                    content: encodeBase64Utf8(text),
+                    branch,
+                    ...(sha === undefined ? {} : { sha }),
+                },
+            });
+            return { sha: raw.content.sha, commitSha: raw.commit.sha };
+        },
+        list: async (owner, repo, dir, ref) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}/contents/${encodePath(dir)}`, {
+                query: { ref },
+            });
+            return raw.map((entry) => ({ name: entry.name, path: entry.path, sha: entry.sha, type: entry.type }));
+        },
+        /** Same guard as `put` (site/docs/github.md): the "never write base, only inside
+         * the allowlist" rule covers a delete exactly as much as it covers a write. */
+        deleteFile: async (owner, repo, path, message, branch, sha, guard) => {
+            if (guard !== undefined) {
+                if (branch === guard.base)
+                    throw new BaseBranchWriteError(branch);
+                assertPathAllowed(guard.link, path);
+            }
+            await this.http.request(`/repos/${owner}/${repo}/contents/${encodePath(path)}`, {
+                method: "DELETE",
+                body: { message, sha, branch },
+            });
+        },
+    };
+    git = {
+        /** The commit both `base` and `head` descend from, via the compare API's `merge_base_commit`. */
+        mergeBase: async (owner, repo, base, head) => {
+            try {
+                const raw = await this.http.request(`/repos/${owner}/${repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`);
+                return raw.merge_base_commit.sha;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError)
+                    return null;
+                throw error;
+            }
+        },
+    };
+    pulls = {
+        create: async (owner, repo, input) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}/pulls`, {
+                method: "POST",
+                body: { title: input.title, head: input.head, base: input.base, body: input.body },
+            });
+            return toPull(raw);
+        },
+        update: async (owner, repo, number, input) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}/pulls/${number}`, {
+                method: "PATCH",
+                body: input,
+            });
+            return toPull(raw);
+        },
+        get: async (owner, repo, number) => {
+            const raw = await this.http.request(`/repos/${owner}/${repo}/pulls/${number}`);
+            return toPull(raw);
+        },
+        listForBranch: async (owner, repo, branch, state = "open") => {
+            const raw = await this.paginate(`/repos/${owner}/${repo}/pulls`, {
+                head: `${owner}:${branch}`,
+                state,
+                per_page: 100,
+            });
+            return raw.map(toPull);
+        },
+        files: async (owner, repo, number) => {
+            const raw = await this.paginate(`/repos/${owner}/${repo}/pulls/${number}/files`, {
+                per_page: 100,
+            });
+            return raw.map(toPullFile);
+        },
+        requestReviewers: async (owner, repo, number, reviewers) => {
+            if (reviewers.length === 0)
+                return;
+            await this.http.request(`/repos/${owner}/${repo}/pulls/${number}/requested_reviewers`, {
+                method: "POST",
+                body: { reviewers },
+            });
+        },
+    };
+    users = {
+        me: async () => {
+            const raw = await this.http.request("/user");
+            return { login: raw.login, id: raw.id, name: raw.name };
+        },
+    };
+    /** Follows `Link: rel="next"` headers to collect every page. */
+    async paginate(path, query) {
+        const results = [];
+        let next = path;
+        let nextQuery = query;
+        while (next) {
+            const { body, headers } = await this.http.requestRaw(next, { query: nextQuery });
+            results.push(...body);
+            next = nextLinkFrom(headers.get("link"));
+            nextQuery = undefined;
+        }
+        return results;
+    }
+    /** Files touched on both sides since the merge base: a conservative guess at the conflict set. */
+    async conflictingFiles(owner, repo, base, head) {
+        const mergeBase = await this.git.mergeBase(owner, repo, base, head);
+        if (mergeBase === null)
+            return [];
+        const [baseSide, headSide] = await Promise.all([
+            this.comparedFiles(owner, repo, mergeBase, base),
+            this.comparedFiles(owner, repo, mergeBase, head),
+        ]);
+        return [...baseSide].filter((path) => headSide.has(path));
+    }
+    async comparedFiles(owner, repo, from, to) {
+        const raw = await this.http.request(`/repos/${owner}/${repo}/compare/${encodeURIComponent(from)}...${encodeURIComponent(to)}`);
+        return new Set((raw.files ?? []).map((file) => file.filename));
+    }
+}
+function encodePath(path) {
+    return path
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+function nextLinkFrom(header) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(",")) {
+        const match = /<([^>]+)>;\s*rel="next"/.exec(part.trim());
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed errors for the GitHub client (site/docs/github.md).
+ *
+ * Every network or protocol failure the client can distinguish gets its own class so callers (the
+ * CLI, the MCP server, the editor) can branch on `instanceof` instead of parsing messages.
+ */
+/** Base class for anything the GitHub API itself reported. Carries the HTTP status when known. */
+export declare class GitHubError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, body?: unknown | undefined);
+}
+/** 401, or 403 for a reason that is not a rate limit: the token is missing, bad or lacks scope. */
+export declare class AuthError extends GitHubError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 404: the repository, branch, path or pull request does not exist, or the token cannot see it. */
+export declare class NotFoundError extends GitHubError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 409, or 422 for a stale `sha`: someone else moved the ref or the file since we last read it. */
+export declare class ConflictError extends GitHubError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 429, or 403 with `x-ratelimit-remaining: 0` / a secondary-rate-limit message, after retries. */
+export declare class RateLimitError extends GitHubError {
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, retryAfterMs: number | undefined, status?: number, body?: unknown);
+}
+/**
+ * The work branch could not be brought up to date with the base branch because the two sides
+ * touched the same lines. `files` names the paths in conflict so the caller can tell the user
+ * exactly what to resolve (06 §3 step 2).
+ *
+ * GitHub's merge API (`POST /repos/{owner}/{repo}/merges`) reports a 409 on conflict but does not
+ * itself enumerate the files involved. `GitHubClient.repos.merge` recovers the list by comparing
+ * both branches against their merge base and intersecting the changed paths — a conservative
+ * superset of the true conflicts, not an exact diff3 result.
+ */
+export declare class MergeConflictError extends GitHubError {
+    readonly files: string[];
+    constructor(message: string, files: string[], status?: number, body?: unknown);
+}
+/**
+ * A write targeted a path outside `zenith.json`'s `autosDir`, `deploy.dir` or `codegen.dir`
+ * (site/docs/github.md). Never sent to GitHub.
+ */
+export declare class PathNotAllowedError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * A write targeted the base branch. The app never writes to base (06 §7); this guard makes that a
+ * thrown error instead of a silent commit. Never sent to GitHub.
+ */
+export declare class BaseBranchWriteError extends Error {
+    readonly branch: string;
+    constructor(branch: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kGAAkG;AAClG,qBAAa,WAAY,SAAQ,KAAK;IAGlC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO;gBAFvB,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,IAAI,CAAC,EAAE,OAAO,YAAA;CAK1B;AAED,mGAAmG;AACnG,qBAAa,SAAU,SAAQ,WAAW;gBAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAI7D;AAED,oGAAoG;AACpG,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAI7D;AAED,mGAAmG;AACnG,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAI7D;AAED,mGAAmG;AACnG,qBAAa,cAAe,SAAQ,WAAW;IAG3C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS;gBADzC,OAAO,EAAE,MAAM,EACN,YAAY,EAAE,MAAM,GAAG,SAAS,EACzC,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO;CAKjB;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IAG/C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE;gBADxB,OAAO,EAAE,MAAM,EACN,KAAK,EAAE,MAAM,EAAE,EACxB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO;CAKjB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIlC;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC"}

package/dist/errors.js

@@ -0,0 +1,90 @@
+/**
+ * Typed errors for the GitHub client (site/docs/github.md).
+ *
+ * Every network or protocol failure the client can distinguish gets its own class so callers (the
+ * CLI, the MCP server, the editor) can branch on `instanceof` instead of parsing messages.
+ */
+/** Base class for anything the GitHub API itself reported. Carries the HTTP status when known. */
+export class GitHubError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "GitHubError";
+    }
+}
+/** 401, or 403 for a reason that is not a rate limit: the token is missing, bad or lacks scope. */
+export class AuthError extends GitHubError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "AuthError";
+    }
+}
+/** 404: the repository, branch, path or pull request does not exist, or the token cannot see it. */
+export class NotFoundError extends GitHubError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "NotFoundError";
+    }
+}
+/** 409, or 422 for a stale `sha`: someone else moved the ref or the file since we last read it. */
+export class ConflictError extends GitHubError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "ConflictError";
+    }
+}
+/** 429, or 403 with `x-ratelimit-remaining: 0` / a secondary-rate-limit message, after retries. */
+export class RateLimitError extends GitHubError {
+    retryAfterMs;
+    constructor(message, retryAfterMs, status, body) {
+        super(message, status, body);
+        this.retryAfterMs = retryAfterMs;
+        this.name = "RateLimitError";
+    }
+}
+/**
+ * The work branch could not be brought up to date with the base branch because the two sides
+ * touched the same lines. `files` names the paths in conflict so the caller can tell the user
+ * exactly what to resolve (06 §3 step 2).
+ *
+ * GitHub's merge API (`POST /repos/{owner}/{repo}/merges`) reports a 409 on conflict but does not
+ * itself enumerate the files involved. `GitHubClient.repos.merge` recovers the list by comparing
+ * both branches against their merge base and intersecting the changed paths — a conservative
+ * superset of the true conflicts, not an exact diff3 result.
+ */
+export class MergeConflictError extends GitHubError {
+    files;
+    constructor(message, files, status, body) {
+        super(message, status, body);
+        this.files = files;
+        this.name = "MergeConflictError";
+    }
+}
+/**
+ * A write targeted a path outside `zenith.json`'s `autosDir`, `deploy.dir` or `codegen.dir`
+ * (site/docs/github.md). Never sent to GitHub.
+ */
+export class PathNotAllowedError extends Error {
+    path;
+    constructor(path) {
+        super(`"${path}" is outside the allowed autos/deploy/codegen directories; refusing to write it.`);
+        this.path = path;
+        this.name = "PathNotAllowedError";
+    }
+}
+/**
+ * A write targeted the base branch. The app never writes to base (06 §7); this guard makes that a
+ * thrown error instead of a silent commit. Never sent to GitHub.
+ */
+export class BaseBranchWriteError extends Error {
+    branch;
+    constructor(branch) {
+        super(`Refusing to write to "${branch}": it is the base branch, and Zenith never writes there.`);
+        this.branch = branch;
+        this.name = "BaseBranchWriteError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kGAAkG;AAClG,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGzB;IACA;IAHX,YACE,OAAe,EACN,MAAe,EACf,IAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAS;QACf,SAAI,GAAJ,IAAI,CAAU;QAGvB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,mGAAmG;AACnG,MAAM,OAAO,SAAU,SAAQ,WAAW;IACxC,YAAY,OAAe,EAAE,MAAe,EAAE,IAAc;QAC1D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,oGAAoG;AACpG,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C,YAAY,OAAe,EAAE,MAAe,EAAE,IAAc;QAC1D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,mGAAmG;AACnG,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C,YAAY,OAAe,EAAE,MAAe,EAAE,IAAc;QAC1D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,mGAAmG;AACnG,MAAM,OAAO,cAAe,SAAQ,WAAW;IAGlC;IAFX,YACE,OAAe,EACN,YAAgC,EACzC,MAAe,EACf,IAAc;QAEd,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAJpB,iBAAY,GAAZ,YAAY,CAAoB;QAKzC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IAGtC;IAFX,YACE,OAAe,EACN,KAAe,EACxB,MAAe,EACf,IAAc;QAEd,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAJpB,UAAK,GAAL,KAAK,CAAU;QAKxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACvB;IAArB,YAAqB,IAAY;QAC/B,KAAK,CAAC,IAAI,IAAI,kFAAkF,CAAC,CAAC;QAD/E,SAAI,GAAJ,IAAI,CAAQ;QAE/B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACxB;IAArB,YAAqB,MAAc;QACjC,KAAK,CAAC,yBAAyB,MAAM,0DAA0D,CAAC,CAAC;QAD9E,WAAM,GAAN,MAAM,CAAQ;QAEjC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}

package/dist/http.d.ts

@@ -0,0 +1,50 @@
+import type { AuthProvider } from "./auth.js";
+/** The last rate-limit snapshot the client saw, read off `x-ratelimit-*` response headers. */
+export interface RateLimitSnapshot {
+    limit: number;
+    remaining: number;
+    /** Epoch milliseconds. */
+    resetAt: number;
+}
+export interface HttpOptions {
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+    /** Retries for 429s and secondary-rate-limit 403s before giving up with `RateLimitError`. */
+    maxRetries?: number;
+    /** Base delay for the backoff used when GitHub gives no `Retry-After` header. */
+    retryDelayMs?: number;
+    /** Injectable so tests do not actually wait. Defaults to a real `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+    /** Extra headers, e.g. an `Accept` override for a raw-content fetch. */
+    headers?: Record<string, string>;
+}
+/**
+ * The one place every `GitHubClient` method funnels through: attaches the bearer token, retries
+ * 429s and secondary rate limits with backoff, and turns a non-2xx response into a typed error
+ * (site/docs/github.md). Isomorphic: `fetch`, no Octokit, no Node APIs.
+ */
+export declare class HttpClient {
+    readonly apiBase: string;
+    private readonly auth;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly sleep;
+    private lastRateLimit;
+    constructor(auth: AuthProvider, options?: HttpOptions);
+    get rateLimit(): RateLimitSnapshot | null;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Like `request`, but also returns the response headers (pagination, ETags, raw byte counts). */
+    requestRaw(path: string, options?: RequestOptions): Promise<{
+        status: number;
+        body: unknown;
+        headers: Headers;
+    }>;
+    private buildUrl;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,8FAA8F;AAC9F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAwCD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,aAAa,CAAkC;gBAE3C,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,WAAgB;IASzD,IAAI,SAAS,IAAI,iBAAiB,GAAG,IAAI,CAExC;IAEK,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKxE,kGAAkG;IAC5F,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAkD/D,OAAO,CAAC,QAAQ;CAkBjB"}

package/dist/http.js

@@ -0,0 +1,150 @@
+import { AuthError, ConflictError, GitHubError, NotFoundError, RateLimitError } from "./errors.js";
+const DEFAULT_API_BASE = "https://api.github.com";
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isSecondaryRateLimitBody(body) {
+    if (typeof body !== "object" || body === null)
+        return false;
+    const message = body.message;
+    return typeof message === "string" && /secondary rate limit/i.test(message);
+}
+function parseRateLimit(headers) {
+    const limit = headers.get("x-ratelimit-limit");
+    const remaining = headers.get("x-ratelimit-remaining");
+    const reset = headers.get("x-ratelimit-reset");
+    if (limit === null || remaining === null || reset === null)
+        return null;
+    return {
+        limit: Number(limit),
+        remaining: Number(remaining),
+        resetAt: Number(reset) * 1000,
+    };
+}
+function retryDelayFromHeaders(headers, fallbackMs) {
+    const retryAfter = headers.get("retry-after");
+    if (retryAfter !== null) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds))
+            return Math.max(0, seconds * 1000);
+    }
+    const reset = headers.get("x-ratelimit-reset");
+    if (reset !== null) {
+        const resetAt = Number(reset) * 1000;
+        if (Number.isFinite(resetAt))
+            return Math.max(0, resetAt - Date.now());
+    }
+    return fallbackMs;
+}
+/**
+ * The one place every `GitHubClient` method funnels through: attaches the bearer token, retries
+ * 429s and secondary rate limits with backoff, and turns a non-2xx response into a typed error
+ * (site/docs/github.md). Isomorphic: `fetch`, no Octokit, no Node APIs.
+ */
+export class HttpClient {
+    apiBase;
+    auth;
+    fetchImpl;
+    maxRetries;
+    retryDelayMs;
+    sleep;
+    lastRateLimit = null;
+    constructor(auth, options = {}) {
+        this.auth = auth;
+        this.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.retryDelayMs = options.retryDelayMs ?? 500;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    get rateLimit() {
+        return this.lastRateLimit;
+    }
+    async request(path, options = {}) {
+        const { body } = await this.requestRaw(path, options);
+        return body;
+    }
+    /** Like `request`, but also returns the response headers (pagination, ETags, raw byte counts). */
+    async requestRaw(path, options = {}) {
+        const token = await this.auth.token();
+        const url = this.buildUrl(path, options.query);
+        let attempt = 0;
+        for (;;) {
+            const response = await this.fetchImpl(url, {
+                method: options.method ?? "GET",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: "application/vnd.github+json",
+                    "X-GitHub-Api-Version": "2022-11-28",
+                    ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                    ...options.headers,
+                },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            });
+            const rateLimit = parseRateLimit(response.headers);
+            if (rateLimit)
+                this.lastRateLimit = rateLimit;
+            const parsedBody = await parseBody(response);
+            const isRateLimited = response.status === 429 ||
+                (response.status === 403 && (rateLimit?.remaining === 0 || isSecondaryRateLimitBody(parsedBody)));
+            if (isRateLimited) {
+                if (attempt >= this.maxRetries) {
+                    throw new RateLimitError("GitHub's rate limit was hit and the retry budget ran out.", retryDelayFromHeaders(response.headers, this.retryDelayMs), response.status, parsedBody);
+                }
+                const delay = retryDelayFromHeaders(response.headers, this.retryDelayMs * 2 ** attempt);
+                await this.sleep(delay);
+                attempt += 1;
+                continue;
+            }
+            if (response.ok) {
+                return { status: response.status, body: parsedBody, headers: response.headers };
+            }
+            throw errorFor(response.status, path, parsedBody);
+        }
+    }
+    buildUrl(path, query) {
+        const url = new URL(path.startsWith("http") ? path : `${this.apiBase}${path}`);
+        // `path` can be an absolute URL taken straight from a response's `Link: rel="next"` header
+        // (`GitHubClient`'s `paginate`); the bearer token is attached to every request this method
+        // builds a URL for, so an attacker-controlled `Link` header pointing off-host must never reach
+        // `fetch` (site/docs/github.md).
+        if (url.origin !== new URL(this.apiBase).origin) {
+            throw new GitHubError(`Refusing to follow a URL whose origin (${url.origin}) is not this client's API base (${new URL(this.apiBase).origin}).`);
+        }
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+}
+async function parseBody(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function messageOf(body, fallback) {
+    if (typeof body === "object" && body !== null && typeof body.message === "string") {
+        return body.message;
+    }
+    return fallback;
+}
+function errorFor(status, path, body) {
+    const message = messageOf(body, `GitHub returned ${status} for ${path}.`);
+    if (status === 401 || status === 403)
+        return new AuthError(message, status, body);
+    if (status === 404)
+        return new NotFoundError(message, status, body);
+    if (status === 409 || status === 422)
+        return new ConflictError(message, status, body);
+    return new GitHubError(message, status, body);
+}
+//# sourceMappingURL=http.js.map