@effected/github 0.1.0

package/GitHubClient.js

@@ -0,0 +1,192 @@
+import { GitHubError } from "./GitHubError.js";
+import { GitHubGraphQLError } from "./GraphQL.js";
+import { RetryPolicy } from "./Resilience.js";
+import { makeTransport } from "./internal/octokit.js";
+import { fromArray, paginate } from "./internal/paginate.js";
+import { Config, Context, Effect, Layer, Option, Schema, Stream } from "effect";
+
+//#region src/GitHubClient.ts
+/** GitHub's own maximum page size, and the default this package requests. */
+const DEFAULT_PER_PAGE = 100;
+const resolvePolicy = (retry) => retry === void 0 ? RetryPolicy.default : retry === "off" ? RetryPolicy.none : retry;
+const perPageOf = (options) => options?.perPage ?? DEFAULT_PER_PAGE;
+const unstubbed = (member) => {
+	throw new Error(`GitHubClient.makeTest: ${member}() was called but not stubbed — pass an override, or use GitHubClient.layerFixture for recorded responses.`);
+};
+/**
+* The typed GitHub API client.
+*
+* @remarks
+* The route is the key. `@octokit/types` generates a map from GitHub's OpenAPI
+* description that carries every endpoint's parameter and response shapes, and
+* `@octokit/core`'s `request` already consumes it — so a caller writes a route
+* literal and gets both sides typed, with no callback, no type parameter to
+* invent, and no cast.
+*
+* That is the whole point of this package. The surface it replaces was
+* `rest<T>(operation: string, fn: (octokit: any) => Promise<{ data: T }>)`,
+* where `T` was whatever the caller wrote and nothing connected it to the
+* endpoint. Four consumer repos paid for that with sixteen cast sites and three
+* hand-written octokit interfaces, one of which gave up and typed its methods as
+* `Record<string, (p: unknown) => Promise<{ data: unknown }>>`.
+*
+* @public
+*/
+var GitHubClient = class GitHubClient extends Context.Service()("@effected/github/GitHubClient") {
+	/**
+	* A client authenticated with a token you already hold.
+	*
+	* @remarks
+	* This module imports `@octokit/core` and nothing heavier. A consumer that
+	* only ever authenticates with a token never links the GitHub App JWT signer,
+	* because the App-authenticated layer lives in `GitHubApp` — a different
+	* module — rather than as a third static here.
+	*/
+	static layerFromToken = (options) => Layer.effect(this, makeClientShape(options));
+	/**
+	* A client authenticated from configuration, `GITHUB_TOKEN` by default.
+	*
+	* @remarks
+	* Reads through the ambient `ConfigProvider`, not `process.env`, so a test
+	* provides a provider instead of mutating the environment and a non-Actions
+	* consumer can source the token however it likes.
+	*
+	* Construction fails with core's `ConfigError` — an honest "no token is
+	* configured". The layer this replaces failed with a **wire-failure** error
+	* type instead, which is why one consumer wrapped it in `Layer.orDie` under a
+	* five-line comment explaining that the error did not mean what it said.
+	*/
+	static layerFromConfig = (options = {}) => Layer.effect(this, Effect.gen(function* () {
+		const token = yield* Config.redacted(options.name ?? "GITHUB_TOKEN");
+		return yield* makeClientShape({
+			...options,
+			token
+		});
+	}));
+	/**
+	* An in-memory double: stub the members a test exercises, and every other
+	* member **dies** naming itself.
+	*
+	* @remarks
+	* No member has an honest default. A fabricated response — an empty list, a
+	* made-up sha — would leak into the code under test as fact, so the double
+	* fails loudly instead, which also makes it proof that a test touches nothing
+	* but what it stubbed.
+	*
+	* For recorded responses that page for real, use
+	* {@link GitHubClient.layerFixture}.
+	*/
+	static makeTest = (overrides = {}) => ({
+		request: overrides.request ?? (() => unstubbed("request")),
+		requestDecoded: overrides.requestDecoded ?? (() => unstubbed("requestDecoded")),
+		paginate: overrides.paginate ?? (() => unstubbed("paginate")),
+		paginateStream: overrides.paginateStream ?? (() => unstubbed("paginateStream")),
+		graphql: overrides.graphql ?? (() => unstubbed("graphql")),
+		rateLimit: overrides.rateLimit ?? Effect.succeed(Option.none())
+	});
+	/** {@link GitHubClient.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(GitHubClient, GitHubClient.makeTest(overrides));
+	/**
+	* A double over recorded responses that **pages them for real**.
+	*
+	* @remarks
+	* The one recorded-response double in this package, and the single narrow
+	* exception to the no-behavior-reimplementing-doubles rule — safe precisely
+	* because it reimplements nothing: it builds a `PageSource` over the recorded
+	* array and hands it to the same `paginate` engine the live client uses, so
+	* `perPage` and `maxPages` cannot behave differently here than in production.
+	*
+	* The double it replaces named its pagination parameters `_options` and
+	* ignored them, returning every recorded page regardless of what the caller
+	* asked for — which made every truncation path in every consumer
+	* structurally untestable.
+	*
+	* `fixtures.requested` is appended to as the test runs, so a suite can assert
+	* which routes were walked and at what page size.
+	*/
+	static layerFixture = (fixtures) => Layer.succeed(GitHubClient, makeFixture(fixtures));
+};
+/**
+* Builds the live shape over a constructed transport.
+*
+* @remarks
+* Exported for `GitHubApp`, which builds clients of its own — one speaking as
+* the app (JWT), one as an installation, and one unauthenticated for the bot-user
+* lookup that rejects an app JWT. Not part of the public surface.
+*
+* @internal
+*/
+const makeClientShape = (options) => Effect.gen(function* () {
+	const transport = yield* makeTransport({
+		token: options.token,
+		retry: resolvePolicy(options.retry),
+		baseUrl: options.baseUrl,
+		userAgent: options.userAgent,
+		fetch: options.fetch
+	});
+	const request = Effect.fn("GitHubClient.request")(function* (route, params) {
+		yield* Effect.annotateCurrentSpan({ route });
+		return (yield* transport.request(route, route, params)).data;
+	});
+	const requestDecoded = Effect.fn("GitHubClient.requestDecoded")(function* (route, params, schema) {
+		yield* Effect.annotateCurrentSpan({ route });
+		const response = yield* transport.request(route, route, params);
+		return yield* Schema.decodeUnknownEffect(schema)(response.data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(route, "response did not match its schema", error))));
+	});
+	const paginateStream = (route, params, options) => paginate(() => transport.pageSource(route, route, {
+		per_page: perPageOf(options),
+		...params
+	}), options?.maxPages);
+	return {
+		request,
+		requestDecoded,
+		paginate: Effect.fn("GitHubClient.paginate")(function* (route, params, options) {
+			yield* Effect.annotateCurrentSpan({
+				route,
+				perPage: perPageOf(options),
+				maxPages: options?.maxPages ?? -1
+			});
+			return yield* Stream.runCollect(paginateStream(route, params, options));
+		}),
+		paginateStream,
+		graphql: Effect.fn("GitHubClient.graphql")(function* (document, variables) {
+			yield* Effect.annotateCurrentSpan({ document: document.name });
+			const raw = yield* transport.graphql(document.name, document.document, document.encodeVariables(variables));
+			return yield* document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "response did not match its schema", error))));
+		}),
+		rateLimit: transport.rateLimit
+	};
+});
+const makeFixture = (fixtures) => {
+	const requested = fixtures.requested;
+	const paginateStream = (route, _params, options) => {
+		const items = fixtures.paginate?.[route];
+		if (items === void 0) return Stream.fail(GitHubError.notFound("GitHubClient.paginate", `fixture for ${route}`));
+		const perPage = perPageOf(options);
+		requested?.push({
+			route,
+			perPage
+		});
+		return paginate(() => fromArray(items, perPage), options?.maxPages);
+	};
+	return {
+		request: (route, _params) => {
+			const data = fixtures.request?.[route];
+			return data === void 0 ? Effect.fail(GitHubError.notFound("GitHubClient.request", `fixture for ${route}`)) : Effect.succeed(data);
+		},
+		requestDecoded: (route, _params, schema) => {
+			const data = fixtures.request?.[route];
+			return data === void 0 ? Effect.fail(GitHubError.notFound("GitHubClient.requestDecoded", `fixture for ${route}`)) : Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(route, "fixture did not match its schema", error))));
+		},
+		paginate: (route, params, options) => Stream.runCollect(paginateStream(route, params, options)),
+		paginateStream,
+		graphql: (document, _variables) => {
+			const raw = fixtures.graphql?.[document.name];
+			return raw === void 0 ? Effect.die(/* @__PURE__ */ new Error(`GitHubClient.layerFixture: no graphql fixture for ${document.name}`)) : document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "fixture did not match its schema", error))));
+		},
+		rateLimit: Effect.succeed(Option.fromUndefinedOr(fixtures.rateLimit))
+	};
+};
+
+//#endregion
+export { GitHubClient, makeClientShape };

package/GitHubCommit.js

@@ -0,0 +1,198 @@
+import { paginate } from "./internal/paginate.js";
+import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
+import { Context, Effect, Layer, Option, Schema, Stream } from "effect";
+
+//#region src/GitHubCommit.ts
+/**
+* A commit, projected to what callers read.
+*
+* @public
+*/
+var CommitSummary = class extends Schema.Class("CommitSummary")({
+	/** The commit sha. */
+	sha: Schema.String,
+	/** The full commit message, untrimmed — this package does not decide what "the message" means. */
+	message: Schema.String,
+	/** The author's name as git recorded it, or `"Unknown"` when GitHub reports none. */
+	author: Schema.String,
+	/** The GitHub login of the authoring account, when GitHub could attribute one. */
+	authorLogin: Schema.optionalKey(Schema.String),
+	/** The web URL for the commit. */
+	url: Schema.String
+}) {
+	/** The message's first line. */
+	get subject() {
+		return this.message.split("\n", 1)[0] ?? "";
+	}
+};
+/**
+* How a file changed in a commit or a comparison.
+*
+* @public
+*/
+const FileStatus = Schema.Literals([
+	"added",
+	"removed",
+	"modified",
+	"renamed",
+	"copied",
+	"changed",
+	"unchanged"
+]);
+/**
+* One changed file.
+*
+* @public
+*/
+var CommitFile = class extends Schema.Class("CommitFile")({
+	/** Repository-relative path, after any rename. */
+	path: Schema.String,
+	/** What happened to it. */
+	status: FileStatus,
+	/** Lines added. */
+	additions: Schema.Int,
+	/** Lines removed. */
+	deletions: Schema.Int,
+	/** The path before a rename or copy. */
+	previousPath: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* The result of comparing two refs.
+*
+* @public
+*/
+var CommitComparison = class extends Schema.Class("CommitComparison")({
+	/** How head relates to base. */
+	status: Schema.Literals([
+		"diverged",
+		"ahead",
+		"behind",
+		"identical"
+	]),
+	/** Commits head has that base does not. */
+	aheadBy: Schema.Int,
+	/** Commits base has that head does not. */
+	behindBy: Schema.Int,
+	/** The commits in the range. */
+	commits: Schema.Array(CommitSummary),
+	/** The files that differ, subject to GitHub's own 300-file cap on this endpoint. */
+	files: Schema.Array(CommitFile)
+}) {};
+/**
+* Commits, as GitHub reports them.
+*
+* @public
+*/
+var GitHubCommit = class GitHubCommit extends Context.Service()("@effected/github/GitHubCommit") {
+	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		get: overrides.get ?? (() => unstubbed("get")),
+		list: overrides.list ?? (() => unstubbed("list")),
+		compare: overrides.compare ?? (() => unstubbed("compare")),
+		changedFiles: overrides.changedFiles ?? (() => unstubbed("changedFiles"))
+	});
+	/** {@link GitHubCommit.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(GitHubCommit, GitHubCommit.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`GitHubCommit.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const summarize = (raw) => CommitSummary.make({
+	sha: raw.sha,
+	message: raw.commit.message,
+	author: raw.commit.author?.name ?? "Unknown",
+	...raw.author?.login !== void 0 ? { authorLogin: raw.author.login } : {},
+	url: raw.html_url
+});
+const fileOf = (raw) => CommitFile.make({
+	path: raw.filename,
+	status: raw.status,
+	additions: raw.additions,
+	deletions: raw.deletions,
+	...raw.previous_filename !== void 0 ? { previousPath: raw.previous_filename } : {}
+});
+const make = (client) => ({
+	get: Effect.fn("GitHubCommit.get")(function* (ref) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			ref
+		});
+		const commit = yield* client.request("GET /repos/{owner}/{repo}/commits/{ref}", {
+			owner,
+			repo,
+			ref
+		});
+		return summarize(commit);
+	}),
+	list: Effect.fn("GitHubCommit.list")(function* (options) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			ref: options?.ref ?? ""
+		});
+		return (yield* client.paginate("GET /repos/{owner}/{repo}/commits", {
+			owner,
+			repo,
+			...options?.ref !== void 0 ? { sha: options.ref } : {},
+			...options?.path !== void 0 ? { path: options.path } : {}
+		}, options?.page)).map(summarize);
+	}),
+	compare: Effect.fn("GitHubCommit.compare")(function* (base, head) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			base,
+			head
+		});
+		const comparison = yield* client.request("GET /repos/{owner}/{repo}/compare/{basehead}", {
+			owner,
+			repo,
+			basehead: `${base}...${head}`
+		});
+		return CommitComparison.make({
+			status: comparison.status,
+			aheadBy: comparison.ahead_by,
+			behindBy: comparison.behind_by,
+			commits: comparison.commits.map(summarize),
+			files: (comparison.files ?? []).map(fileOf)
+		});
+	}),
+	changedFiles: Effect.fn("GitHubCommit.changedFiles")(function* (ref, options) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			ref
+		});
+		const perPage = options?.page?.perPage ?? 100;
+		const source = () => {
+			let page = 0;
+			let finished = false;
+			return { next: Effect.suspend(() => {
+				if (finished) return Effect.succeed(Option.none());
+				page += 1;
+				return client.request("GET /repos/{owner}/{repo}/commits/{ref}", {
+					owner,
+					repo,
+					ref,
+					page,
+					per_page: perPage
+				}).pipe(Effect.map((commit) => {
+					const files = commit.files ?? [];
+					if (files.length < perPage) finished = true;
+					return files.length === 0 ? Option.none() : Option.some(files.map(fileOf));
+				}));
+			}) };
+		};
+		return yield* Stream.runCollect(paginate(source, options?.page?.maxPages));
+	})
+});
+
+//#endregion
+export { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit };

package/GitHubContent.js

@@ -0,0 +1,54 @@
+import { GitHubError } from "./GitHubError.js";
+import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
+import { Context, Effect, Layer, Option } from "effect";
+
+//#region src/GitHubContent.ts
+/**
+* Repository file contents.
+*
+* @public
+*/
+var GitHubContent = class GitHubContent extends Context.Service()("@effected/github/GitHubContent") {
+	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		getFile: overrides.getFile ?? (() => unstubbed("getFile")),
+		getFileOption: overrides.getFileOption ?? (() => unstubbed("getFileOption"))
+	});
+	/** {@link GitHubContent.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(GitHubContent, GitHubContent.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`GitHubContent.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const make = (client) => {
+	const getFile = Effect.fn("GitHubContent.getFile")(function* (path, options) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			path,
+			ref: options?.ref ?? ""
+		});
+		const content = yield* client.request("GET /repos/{owner}/{repo}/contents/{path}", {
+			owner,
+			repo,
+			path,
+			...options?.ref !== void 0 ? { ref: options.ref } : {}
+		});
+		if (Array.isArray(content)) return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} is a directory`));
+		if (content.type !== "file") return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} is a ${content.type}, not a file`));
+		if (content.encoding !== "base64") return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} came back with encoding ${JSON.stringify(content.encoding)} — it is probably too large for the contents API`));
+		return Buffer.from(content.content.replace(/\s/g, ""), "base64").toString("utf8");
+	});
+	return {
+		getFile,
+		getFileOption: Effect.fn("GitHubContent.getFileOption")(function* (path, options) {
+			return yield* getFile(path, options).pipe(Effect.map(Option.some), Effect.catchIf(GitHubError.hasKind("notFound"), () => Effect.succeed(Option.none())));
+		})
+	};
+};
+
+//#endregion
+export { GitHubContent };

package/GitHubError.js

@@ -0,0 +1,254 @@
+import { headerNumber, retryAfterMillisFrom } from "./internal/headers.js";
+import { Schema } from "effect";
+
+//#region src/GitHubError.ts
+/**
+* Why a GitHub call failed, as a value you can branch on.
+*
+* @remarks
+* This discriminant is what replaces string-matching an error message. The
+* package this replaces carried a free-form `reason` string and nothing else
+* structural, so consumers grepped it: one repo lowercased a GraphQL message and
+* tested `includes("already") || includes("exists")`, and another re-issued an
+* existence check after every failed branch creation because it could not tell
+* "someone else created it" from "that failed".
+*
+* @public
+*/
+const GitHubErrorKind = Schema.Literals([
+	"notFound",
+	"alreadyExists",
+	"rejected",
+	"unauthorized",
+	"rateLimited",
+	"transport",
+	"decode"
+]);
+/**
+* Every REST failure this package produces, from every resource.
+*
+* @remarks
+* One error class, not one per resource. Across the six repos surveyed for this
+* port, consumers read `reason` about forty times, `status` twice, `operation`
+* twice, and matched a resource-specific `_tag` exactly **once** — at a call
+* site that disappears entirely now that `GitBranch.upsert` exists. Eighteen
+* near-identical error classes and thirteen near-identical mapper closures
+* bought that one match.
+*
+* What replaces them is {@link GitHubErrorKind} for routing and `operation` for
+* identification. This mirrors `@effected/git`, where the rule is that no
+* consumer ever string-matches stderr because classification happens once.
+*
+* @public
+*/
+var GitHubError = class GitHubError extends Schema.TaggedErrorClass()("GitHubError", {
+	/** Structural routing. Branch on this, never on the rendered message. */
+	kind: GitHubErrorKind,
+	/** What was attempted: a resource method (`"GitBranch.upsert"`) or a raw route. */
+	operation: Schema.String,
+	/** Human-readable cause, for logs and messages. Never a routing surface. */
+	reason: Schema.String,
+	/** GitHub's HTTP status, when the request reached GitHub at all. */
+	status: Schema.optionalKey(Schema.Int),
+	/**
+	* A server-advised delay before retrying, in milliseconds.
+	*
+	* @remarks
+	* Written by the client from `retry-after` or the rate-limit reset, and read
+	* by exactly one thing: the retry `Schedule`. It is a policy input, not
+	* information for a caller — which is why it is optional and why the
+	* `retryable` boolean it used to travel with is now a derived getter.
+	*/
+	retryAfterMillis: Schema.optionalKey(Schema.Int),
+	/** The underlying throwable, when one exists. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	/** `"GitBranch.upsert failed (422): Reference already exists"`. */
+	get message() {
+		return this.status === void 0 ? `${this.operation} failed: ${this.reason}` : `${this.operation} failed (${this.status}): ${this.reason}`;
+	}
+	/**
+	* Whether retrying could plausibly succeed.
+	*
+	* @remarks
+	* Derived from `kind` rather than stored. A 404 or a
+	* validation rejection will fail identically on every attempt; only a
+	* transport failure or a rate limit can change its mind.
+	*/
+	get retryable() {
+		return this.kind === "transport" || this.kind === "rateLimited";
+	}
+	/** The requested thing is not there. */
+	static notFound(operation, subject) {
+		return new GitHubError({
+			kind: "notFound",
+			operation,
+			reason: `${subject} not found`,
+			status: 404
+		});
+	}
+	/** The thing you asked to create is already there. */
+	static alreadyExists(operation, subject) {
+		return new GitHubError({
+			kind: "alreadyExists",
+			operation,
+			reason: `${subject} already exists`,
+			status: 422
+		});
+	}
+	/** GitHub understood the request and refused it. */
+	static rejected(operation, status, reason) {
+		return new GitHubError({
+			kind: "rejected",
+			operation,
+			reason,
+			status
+		});
+	}
+	/** A response did not match the schema it was decoded against. */
+	static decode(operation, reason, cause) {
+		return new GitHubError({
+			kind: "decode",
+			operation,
+			reason,
+			...cause !== void 0 ? { cause } : {}
+		});
+	}
+	/**
+	* Classify anything octokit threw.
+	*
+	* @remarks
+	* The single classification step for the whole package — every resource
+	* method's failures come through here, so the taxonomy cannot drift between
+	* resources the way thirteen hand-written mapper closures did.
+	*
+	* `nowMillis` is passed in rather than read from the wall clock so the
+	* function stays pure and total: the rate-limit reset header is an absolute
+	* epoch second, and turning it into a delay needs a "now" the caller controls.
+	* The client supplies `Clock.currentTimeMillis`, which is the `TestClock`
+	* under test.
+	*/
+	static fromOctokit(operation, error, nowMillis) {
+		const facts = readThrowable(error);
+		const retryAfterMillis = retryAfterMillisFrom(facts.headers, nowMillis);
+		const kind = classify(facts, retryAfterMillis);
+		return new GitHubError({
+			kind,
+			operation,
+			reason: facts.reason,
+			...facts.status !== void 0 ? { status: facts.status } : {},
+			...retryAfterMillis !== void 0 ? { retryAfterMillis } : {},
+			cause: error
+		});
+	}
+	/**
+	* A predicate over one or more kinds, for `Effect.catchIf`.
+	*
+	* @example
+	* ```ts
+	* import { GitHubError } from "@effected/github";
+	* import { Effect } from "effect";
+	*
+	* declare const read: Effect.Effect<string, GitHubError>;
+	*
+	* const orDefault = read.pipe(
+	*   Effect.catchIf(GitHubError.hasKind("notFound"), () => Effect.succeed("")),
+	* );
+	* ```
+	*/
+	static hasKind(...kinds) {
+		const set = new Set(kinds);
+		return (error) => set.has(error.kind);
+	}
+};
+/**
+* Read an unknown throwable structurally.
+*
+* @remarks
+* Deliberately structural rather than `instanceof RequestError`:
+* `@octokit/request-error` is a transitive dependency this package does not
+* declare, and importing a package you did not declare is how a peer closure
+* rots. The shape it throws — `{ status, response: { headers, data } }` — is
+* stable and public.
+*/
+const readThrowable = (error) => {
+	if (typeof error !== "object" || error === null) return {
+		status: void 0,
+		headers: void 0,
+		reason: String(error),
+		detailMessages: []
+	};
+	const record = error;
+	const response = asRecord(record.response);
+	const headers = asRecord(response?.headers);
+	const data = asRecord(response?.data);
+	return {
+		status: typeof record.status === "number" ? record.status : void 0,
+		headers,
+		reason: sanitizeReason(typeof record.message === "string" ? record.message : String(error)),
+		detailMessages: readDetailMessages(data)
+	};
+};
+const asRecord = (value) => typeof value === "object" && value !== null ? value : void 0;
+/**
+* GitHub answers some requests with an HTML error page whose body becomes a
+* multi-kilobyte "message".
+*
+* @remarks
+* The package this replaces detected the "Unicorn" page specifically; this is
+* the general form — an HTML body is never a useful reason string, and letting
+* one through means a log line with a whole web page in it.
+*/
+const sanitizeReason = (message) => {
+	const trimmed = message.trim();
+	if (trimmed.startsWith("<") || trimmed.length > MAX_REASON_LENGTH) return trimmed.startsWith("<") ? "GitHub returned an HTML error page instead of a JSON response" : `${trimmed.slice(0, MAX_REASON_LENGTH)}…`;
+	return trimmed;
+};
+const MAX_REASON_LENGTH = 500;
+/** GitHub's validation failures arrive as `data.errors[].message`. */
+const readDetailMessages = (data) => {
+	const errors = data?.errors;
+	if (!Array.isArray(errors)) return [];
+	const messages = [];
+	for (const entry of errors) {
+		const message = asRecord(entry)?.message;
+		if (typeof message === "string") messages.push(message);
+	}
+	return messages;
+};
+const ALREADY_EXISTS = "already exists";
+const classify = (facts, retryAfterMillis) => {
+	const { status } = facts;
+	if (status === void 0) return "transport";
+	if (status === 404) return "notFound";
+	if (status >= 500) return "transport";
+	if (status === 429) return "rateLimited";
+	if (status === 403) return retryAfterMillis !== void 0 ? "rateLimited" : "unauthorized";
+	if (status === 401) return "unauthorized";
+	if (status === 422 || status === 409) return saysAlreadyExists(facts) ? "alreadyExists" : "rejected";
+	return "rejected";
+};
+const saysAlreadyExists = (facts) => {
+	if (facts.reason.toLowerCase().includes(ALREADY_EXISTS)) return true;
+	return facts.detailMessages.some((message) => message.toLowerCase().includes(ALREADY_EXISTS));
+};
+/**
+* Re-exported for the client, which reads the same headers on the **success**
+* path to keep its rate-limit snapshot current.
+*
+* @internal
+*/
+const readRateLimitHeaders = (headers) => {
+	const remaining = headerNumber(headers, "x-ratelimit-remaining");
+	const limit = headerNumber(headers, "x-ratelimit-limit");
+	const reset = headerNumber(headers, "x-ratelimit-reset");
+	if (remaining === void 0 || limit === void 0 || reset === void 0) return void 0;
+	return {
+		remaining,
+		limit,
+		resetEpochSeconds: reset
+	};
+};
+
+//#endregion
+export { GitHubError, GitHubErrorKind, readRateLimitHeaders };