@shivaedev/github 0.0.0-stage → 0.5.1

package/src/artifacts.ts

@@ -0,0 +1,57 @@
+import { Effect } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import { readBoundedBody } from "@shivaedev/http/body.ts";
+import { authenticatedRequest } from "./authenticatedRequest.ts";
+import { GitHubArtifactError, GitHubArtifactTooLarge, GitHubTransportError } from "./errors.ts";
+import type { GitHubToken } from "./GitHubToken.ts";
+import type { RateLimits } from "./rateLimits.ts";
+import type { TokenRefresh } from "./TokenRefresh.ts";
+
+export interface ArtifactArchiveOptions {
+	readonly artifactId: number;
+	readonly byteLimit: number;
+	readonly owner: string;
+	readonly repo: string;
+}
+
+export function artifacts(
+	apiUrl: string,
+	client: HttpClient.HttpClient,
+	token: GitHubToken["Service"],
+	rates: RateLimits,
+	refresh: typeof TokenRefresh.Service = undefined,
+) {
+	const send = authenticatedRequest(HttpClient.withScope(client), token, rates, refresh);
+	const download = HttpClient.withScope(client);
+	return {
+		downloadArtifactArchive: (options: ArtifactArchiveOptions) =>
+			Effect.scoped(
+				Effect.gen(function* () {
+					const path = `/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/actions/artifacts/${options.artifactId}/zip`;
+					const redirect = yield* send(HttpClientRequest.get(new URL(path, apiUrl).href, { accept: "application/vnd.github+json" }), "manual").pipe(
+						Effect.catchTags({
+							RemoteGone: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status })),
+							RemoteNotFound: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status })),
+						}),
+					);
+					const location = redirect.headers.location;
+					if (redirect.status !== 302 || location === undefined) {
+						return yield* new GitHubArtifactError({ stage: "redirect", status: redirect.status });
+					}
+					const response = yield* download.get(location).pipe(
+						Effect.provideService(FetchHttpClient.RequestInit, { credentials: "omit", redirect: "manual" }),
+						Effect.mapError(() => new GitHubTransportError({ path })),
+					);
+					if (response.status < 200 || response.status >= 300) {
+						return yield* new GitHubArtifactError({ stage: "download", status: response.status });
+					}
+					return yield* readBoundedBody(response, options.byteLimit).pipe(
+						Effect.catchTags({
+							HttpClientError: () => Effect.fail(new GitHubTransportError({ path })),
+							ResponseBodyTooLarge: ({ limit }) => Effect.fail(new GitHubArtifactTooLarge({ limit })),
+						}),
+					);
+				}),
+			),
+	};
+}

package/src/authenticatedRequest.ts

@@ -0,0 +1,55 @@
+import { DateTime, Effect, Option, Redacted } from "effect";
+import { FetchHttpClient, type HttpClient, type HttpClientError, HttpClientRequest } from "effect/http";
+import { GitHubTransportError } from "./errors.ts";
+import type { GitHubToken } from "./GitHubToken.ts";
+import { failRateLimited, type RateLimits } from "./rateLimits.ts";
+import { checkStatus, isUnauthorized, isUnchanged } from "./status.ts";
+import type { TokenRefresh } from "./TokenRefresh.ts";
+
+export function authenticatedRequest<R>(
+	client: HttpClient.HttpClient.With<HttpClientError.HttpClientError, R>,
+	token: GitHubToken["Service"],
+	rates: RateLimits,
+	refresh: typeof TokenRefresh.Service = undefined,
+) {
+	const accessToken = Effect.isEffect(token) ? token : Effect.succeed(token);
+	return Effect.fnUntraced(function* (input: HttpClientRequest.HttpClientRequest, mode?: "manual" | "revalidate") {
+		const path = new URL(input.url).pathname;
+		const resource = rates.resource(path);
+		const blocked = rates.blocked.get(resource);
+		if (blocked !== undefined && DateTime.isGreaterThan(blocked.retryAt, yield* DateTime.now)) {
+			return yield* failRateLimited(path, blocked, rates.observations.get(resource)?.remaining);
+		}
+		function send(current: Option.Option<Redacted.Redacted<string>>) {
+			const sent = client.execute(withCredential(input, current));
+			return (
+				mode === "manual" ? sent.pipe(Effect.provideService(FetchHttpClient.RequestInit, { credentials: "omit", redirect: "manual" })) : sent
+			).pipe(Effect.mapError(() => new GitHubTransportError({ path })));
+		}
+		const credential = yield* accessToken;
+		let response = yield* send(credential);
+		if (isUnauthorized(response) && refresh !== undefined) {
+			yield* refresh(credential);
+			response = yield* send(yield* accessToken);
+		}
+		const observedResource = rates.observe(response);
+		if (!((mode === "revalidate" && isUnchanged(response)) || (mode === "manual" && response.status === 302))) {
+			yield* checkStatus(response, observedResource, rates.failures.get(observedResource) ?? 0).pipe(
+				Effect.catchTag("HttpClientError", () => Effect.fail(new GitHubTransportError({ path }))),
+				Effect.catchTag("GitHubRateLimited", (error) => {
+					rates.blocked.set(error.resource, error);
+					rates.failures.set(error.resource, (rates.failures.get(error.resource) ?? 0) + 1);
+					return failRateLimited(path, error, rates.observations.get(error.resource)?.remaining);
+				}),
+			);
+		}
+		rates.failures.delete(observedResource);
+		rates.blocked.delete(observedResource);
+		return response;
+	});
+}
+
+function withCredential(input: HttpClientRequest.HttpClientRequest, credential: Option.Option<Redacted.Redacted<string>>) {
+	const request = HttpClientRequest.setHeader(input, "X-GitHub-Api-Version", "2022-11-28");
+	return Option.isSome(credential) ? HttpClientRequest.setHeader(request, "Authorization", `Bearer ${Redacted.value(credential.value)}`) : request;
+}

package/src/cache.ts

@@ -0,0 +1,25 @@
+import type { Schema } from "effect";
+import type { HttpClientResponse } from "effect/http";
+
+export interface CachedResponse {
+	readonly bytes: Uint8Array;
+	readonly decoded: Map<Schema.Constraint, unknown>;
+	readonly response: HttpClientResponse.HttpClientResponse;
+}
+
+export function responseCache() {
+	const entries = new Map<string, CachedResponse>();
+	return {
+		get: (key: string) => entries.get(key),
+		set(key: string, entry: CachedResponse) {
+			entries.delete(key);
+			entries.set(key, entry);
+			if (entries.size > 1000) {
+				const first = entries.keys().next();
+				if (!first.done) {
+					entries.delete(first.value);
+				}
+			}
+		},
+	};
+}

package/src/checkRuns.ts

@@ -0,0 +1,48 @@
+import { Effect, Schema } from "effect";
+import type { Representations } from "./representations.ts";
+
+export const CheckRunOutput = Schema.Struct({
+	summary: Schema.String,
+	text: Schema.optional(Schema.String),
+	title: Schema.String,
+});
+
+export const CheckRunConclusion = Schema.Literals(["action_required", "cancelled", "failure", "neutral", "success", "skipped", "stale", "timed_out"]);
+export const CheckRunStatus = Schema.Literals(["queued", "in_progress", "completed"]);
+
+export const CreateCheckRun = Schema.Struct({
+	conclusion: Schema.optional(CheckRunConclusion),
+	headSha: Schema.String,
+	name: Schema.String,
+	output: Schema.optional(CheckRunOutput),
+	status: CheckRunStatus,
+}).pipe(Schema.encodeKeys({ headSha: "head_sha" }));
+
+export const UpdateCheckRun = Schema.Union([
+	Schema.Struct({ output: Schema.optional(CheckRunOutput), status: Schema.Literals(["queued", "in_progress"]) }),
+	Schema.Struct({ conclusion: CheckRunConclusion, output: Schema.optional(CheckRunOutput), status: Schema.Literal("completed") }),
+]);
+
+export const CheckRun = Schema.Struct({
+	conclusion: Schema.NullOr(CheckRunConclusion),
+	headSha: Schema.String,
+	id: Schema.Number,
+	name: Schema.String,
+	output: Schema.Struct({ summary: Schema.NullOr(Schema.String), text: Schema.NullOr(Schema.String), title: Schema.NullOr(Schema.String) }),
+	status: CheckRunStatus,
+}).pipe(Schema.encodeKeys({ headSha: "head_sha" }));
+
+export function checkRuns(client: Representations) {
+	return {
+		createCheckRun: Effect.fn("GitHub.createCheckRun")(function* (owner: string, repo: string, input: typeof CreateCheckRun.Type) {
+			const body = yield* Schema.encodeEffect(CreateCheckRun)(input);
+			const response = yield* client.write("POST", `/repos/${owner}/${repo}/check-runs`, body);
+			return yield* response.decode(CheckRun);
+		}),
+		updateCheckRun: Effect.fn("GitHub.updateCheckRun")(function* (owner: string, repo: string, id: number, input: typeof UpdateCheckRun.Type) {
+			const body = yield* Schema.encodeEffect(UpdateCheckRun)(input);
+			const response = yield* client.write("PATCH", `/repos/${owner}/${repo}/check-runs/${id}`, body);
+			return yield* response.decode(CheckRun);
+		}),
+	};
+}

package/src/errors.ts

@@ -0,0 +1,34 @@
+import { Schema } from "effect";
+
+export class GitHubPermissionDenied extends Schema.TaggedError<GitHubPermissionDenied>()("GitHubPermissionDenied", {
+	path: Schema.String,
+}) {}
+
+export class GitHubConversationLocked extends Schema.TaggedError<GitHubConversationLocked>()("GitHubConversationLocked", {
+	path: Schema.String,
+}) {}
+
+export class GitHubRateLimited extends Schema.TaggedError<GitHubRateLimited>()("GitHubRateLimited", {
+	resource: Schema.String,
+	retryAt: Schema.DateTimeUtc,
+}) {}
+
+export class GitHubTransportError extends Schema.TaggedError<GitHubTransportError>()("GitHubTransportError", {
+	path: Schema.String,
+}) {}
+
+export class GitHubAppError extends Schema.TaggedError<GitHubAppError>()("GitHubAppError", {
+	stage: Schema.Literals(["sign", "exchange"]),
+	status: Schema.optional(Schema.Number),
+}) {}
+
+export class GitHubWebhookSignatureError extends Schema.TaggedError<GitHubWebhookSignatureError>()("GitHubWebhookSignatureError", {}) {}
+
+export class GitHubArtifactError extends Schema.TaggedError<GitHubArtifactError>()("GitHubArtifactError", {
+	stage: Schema.Literals(["redirect", "download"]),
+	status: Schema.Number,
+}) {}
+
+export class GitHubArtifactTooLarge extends Schema.TaggedError<GitHubArtifactTooLarge>()("GitHubArtifactTooLarge", {
+	limit: Schema.Number,
+}) {}

package/src/githubApp.ts

@@ -0,0 +1,87 @@
+import { Cache, Clock, Context, Effect, Exit, Layer, Option, Redacted, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { readBoundedJson } from "@shivaedev/http/body.ts";
+import { type AppCredentials, appJwt } from "#appJwt.ts";
+import { GitHubAppError } from "#errors.ts";
+import { GitHubConfig } from "#GitHubConfig.ts";
+import { GitHubToken } from "#GitHubToken.ts";
+import { TokenRefresh } from "#TokenRefresh.ts";
+
+export interface InstallationScope {
+	readonly permissions?: Readonly<Record<string, "read" | "write" | "admin">>;
+	readonly repositories?: readonly string[];
+	readonly repositoryIds?: readonly number[];
+}
+
+export type GitHubAppOptions = AppCredentials &
+	(
+		| { readonly installationId: number; readonly scope?: InstallationScope }
+		| { readonly owner: string; readonly repository: string; readonly scope?: InstallationScope }
+		| { readonly installationId?: never; readonly owner?: never; readonly repository?: never; readonly scope?: never }
+	);
+
+const Installation = Schema.Struct({ id: Schema.Number });
+const AccessToken = Schema.Struct({ expiresAt: Schema.DateFromString, token: Schema.RedactedFromValue(Schema.String) }).pipe(
+	Schema.encodeKeys({ expiresAt: "expires_at" }),
+);
+
+export function githubApp(options: GitHubAppOptions) {
+	return Layer.effectContext(
+		Effect.gen(function* () {
+			if (!("installationId" in options || "owner" in options)) {
+				return Context.make(GitHubToken, Effect.map(appJwt(options), Option.some)).pipe(Context.add(TokenRefresh, undefined));
+			}
+			const client = yield* HttpClient.HttpClient;
+			const { apiUrl } = yield* GitHubConfig;
+			const clock = yield* Clock.Clock;
+			let installationId = "installationId" in options ? options.installationId : undefined;
+			const request = appRequests(client, apiUrl);
+			const exchange = Effect.gen(function* () {
+				const jwt = yield* appJwt(options);
+				if (installationId === undefined && "owner" in options && options.owner !== undefined) {
+					const path = `/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repository)}/installation`;
+					installationId = (yield* request("GET", path, jwt, Installation)).id;
+				}
+				return yield* request("POST", `/app/installations/${installationId}/access_tokens`, jwt, AccessToken, {
+					permissions: options.scope?.permissions,
+					repositories: options.scope?.repositories,
+					"repository_ids": options.scope?.repositoryIds,
+				});
+			});
+			const cache = yield* Cache.makeWith((_: undefined) => exchange, {
+				capacity: 1,
+				timeToLive: (exit) => (Exit.isSuccess(exit) ? Math.max(0, exit.value.expiresAt.getTime() - clock.currentTimeMillisUnsafe() - 300_000) : 0),
+			});
+			return Context.make(
+				GitHubToken,
+				Effect.map(Cache.get(cache, undefined), ({ token }) => Option.some(token)),
+			).pipe(
+				Context.add(TokenRefresh, (rejected) =>
+					Cache.invalidateWhen(cache, undefined, ({ token }) => Option.isSome(rejected) && token === rejected.value),
+				),
+			);
+		}),
+	);
+}
+
+function appRequests(client: HttpClient.HttpClient, apiUrl: string) {
+	return Effect.fnUntraced(function* <TSchema extends Schema.Constraint>(
+		method: "GET" | "POST",
+		path: string,
+		jwt: Redacted.Redacted<string>,
+		schema: TSchema,
+		body?: unknown,
+	) {
+		let input = HttpClientRequest.make(method)(new URL(path, apiUrl).href, {
+			headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${Redacted.value(jwt)}`, "X-GitHub-Api-Version": "2022-11-28" },
+		});
+		if (body !== undefined) {
+			input = yield* HttpClientRequest.bodyJson(input, body).pipe(Effect.mapError(() => new GitHubAppError({ stage: "exchange" })));
+		}
+		const response = yield* client.execute(input).pipe(Effect.mapError(() => new GitHubAppError({ stage: "exchange" })));
+		if (response.status < 200 || response.status >= 300) {
+			return yield* new GitHubAppError({ stage: "exchange", status: response.status });
+		}
+		return yield* readBoundedJson(response, 64 * 1024, schema).pipe(Effect.mapError(() => new GitHubAppError({ stage: "exchange" })));
+	});
+}

package/src/json.ts

@@ -0,0 +1,16 @@
+import { Effect, Schema } from "effect";
+import type { CachedResponse } from "./cache.ts";
+
+export const decodeJson = Effect.fnUntraced(function* <TSchema extends Schema.Constraint>(entry: CachedResponse, schema: TSchema) {
+	const cached = entry.decoded.get(schema);
+	if (entry.decoded.has(schema) && Schema.is(schema)(cached)) {
+		return cached;
+	}
+	const value = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(new TextDecoder().decode(entry.bytes));
+	entry.decoded.set(schema, value);
+	return value;
+});
+
+export function jsonResponse(entry: CachedResponse) {
+	return { decode: <TSchema extends Schema.Constraint>(schema: TSchema) => decodeJson(entry, schema) };
+}

package/src/markdown.ts

@@ -0,0 +1,25 @@
+export function plainText(text: string): string {
+	return text.replace(/[!-/:-@[-`{-~]/gu, (character) => {
+		const separator = character === "@" || character === "#" ? "​" : "";
+		return `&#${character.charCodeAt(0)};${separator}`;
+	});
+}
+
+export function codeSpan(text: string): string {
+	const content = text.replace(/\r\n|\r|\n/gu, " ");
+	if (content === "") {
+		return "";
+	}
+	let longest = 0;
+	for (const [run] of content.matchAll(/`+/gu)) {
+		longest = Math.max(longest, run.length);
+	}
+	const fence = "`".repeat(longest + 1);
+	const pad = content.startsWith("`") || content.endsWith("`") || (/^ .* $/u.test(content) && /[^ ]/u.test(content)) ? " " : "";
+	return `${fence}${pad}${content}${pad}${fence}`;
+}
+
+export function tableCell(text: string, format: "text" | "code" = "text"): string {
+	const content = text.replace(/\r\n|[\r\n\u2028\u2029]/gu, " ");
+	return format === "code" ? codeSpan(content.replaceAll("|", "\\|")) : plainText(content);
+}

package/src/markdownRows.ts

@@ -0,0 +1,30 @@
+export interface MarkdownRowsOptions {
+	readonly byteLimit?: number;
+	readonly header?: string;
+}
+
+export function renderRows(rows: readonly string[], { byteLimit = 60_000, header = "" }: MarkdownRowsOptions = {}): string {
+	const encoder = new TextEncoder();
+	const sizes = [0];
+	for (const row of rows) {
+		sizes.push((sizes.at(-1) ?? 0) + encoder.encode(row).byteLength + 1);
+	}
+	const headerBytes = encoder.encode(header).byteLength;
+	function bodySize(kept: number) {
+		return headerBytes + (kept > 0 ? (header === "" ? 0 : 1) + (sizes[kept] ?? 0) - 1 : 0);
+	}
+	function body(kept: number) {
+		return [...(header === "" ? [] : [header]), ...rows.slice(0, kept)].join("\n");
+	}
+	if (bodySize(rows.length) <= byteLimit) {
+		return body(rows.length);
+	}
+	for (let kept = rows.length - 1; kept >= 0; kept -= 1) {
+		const notice = `and ${rows.length - kept} more`;
+		const separator = kept > 0 || header !== "" ? "\n\n" : "";
+		if (bodySize(kept) + separator.length + encoder.encode(notice).byteLength <= byteLimit) {
+			return body(kept) + separator + notice;
+		}
+	}
+	throw new RangeError("The byte limit must fit the header and omitted-row notice");
+}

package/src/rateLimits.ts

@@ -0,0 +1,56 @@
+import { Clock, DateTime, Effect } from "effect";
+import type { HttpClientResponse } from "effect/http";
+import type { GitHubRateLimited } from "./errors.ts";
+
+export interface RateLimitObservation {
+	readonly limit: number;
+	readonly remaining: number;
+	readonly reset: DateTime.Utc;
+	readonly resource: string;
+	readonly used: number;
+}
+
+export function rateLimits() {
+	const observations = new Map<string, RateLimitObservation>();
+	const blocked = new Map<string, GitHubRateLimited>();
+	const failures = new Map<string, number>();
+	const resources = new Map<string, string>();
+	function resource(path: string) {
+		return resources.get(path) ?? (path.startsWith("/search/") ? "search" : "core");
+	}
+	return {
+		blocked,
+		failures,
+		observations,
+		observe(response: HttpClientResponse.HttpClientResponse) {
+			const headers = response.headers;
+			const path = new URL(response.request.url).pathname;
+			const name = headers["x-ratelimit-resource"] ?? resource(path);
+			resources.set(path, name);
+			const values = ["limit", "remaining", "used", "reset"].map((key) => headers[`x-ratelimit-${key}`]);
+			if (values.every((value) => value !== undefined && Number.isFinite(Number(value)))) {
+				observations.set(name, {
+					limit: Number(headers["x-ratelimit-limit"]),
+					remaining: Number(headers["x-ratelimit-remaining"]),
+					reset: DateTime.makeUnsafe(Number(headers["x-ratelimit-reset"]) * 1000),
+					resource: name,
+					used: Number(headers["x-ratelimit-used"]),
+				});
+			}
+			return name;
+		},
+		resource,
+	};
+}
+
+export type RateLimits = ReturnType<typeof rateLimits>;
+
+export const failRateLimited = Effect.fnUntraced(function* (path: string, error: GitHubRateLimited, remaining: number | undefined) {
+	const fields = { path, remaining, resource: error.resource, retryAt: DateTime.formatIso(error.retryAt) };
+	yield* Effect.logWarning("GitHub rate limited", fields);
+	const span = yield* Effect.currentSpan.pipe(Effect.option);
+	if (span._tag === "Some") {
+		span.value.event("GitHub.rateLimited", yield* Clock.currentTimeNanos, fields);
+	}
+	return yield* error;
+});

package/src/representations.ts

@@ -0,0 +1,57 @@
+import { Effect, Stream } from "effect";
+import { HttpClient, HttpClientRequest, type HttpClientResponse } from "effect/http";
+import type { ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
+import { paginate } from "@shivaedev/http/paginate.ts";
+import type { CachedResponse } from "#cache.ts";
+import { jsonResponse } from "#json.ts";
+import type { requests } from "#requests.ts";
+
+export function representations(
+	apiUrl: string,
+	request: ReturnType<typeof requests>,
+	resource: (path: string) => string,
+	responseByteLimit = 1024 * 1024,
+) {
+	function get(path: string, accept = "application/vnd.github+json") {
+		return HttpClientRequest.get(new URL(path, apiUrl).href, { headers: { Accept: accept } });
+	}
+	function readRepresentation(path: string, byteLimit = responseByteLimit) {
+		return Effect.map(request(get(path), byteLimit), jsonResponse);
+	}
+	function listRepresentations(
+		path: string,
+		beforeRequest?: (resource: string) => Effect.Effect<void, ServiceUnavailable>,
+		byteLimit = responseByteLimit,
+	) {
+		const entries = new WeakMap<HttpClientResponse.HttpClientResponse, CachedResponse>();
+		function fetchPage(input: HttpClientRequest.HttpClientRequest) {
+			return (beforeRequest?.(resource(new URL(input.url).pathname)) ?? Effect.void).pipe(
+				Effect.andThen(request(input, byteLimit)),
+				Effect.map((entry) => {
+					entries.set(entry.response, entry);
+					return entry.response;
+				}),
+			);
+		}
+		const client = HttpClient.makeWith(
+			(effect: Effect.Effect<HttpClientRequest.HttpClientRequest>) => Effect.flatMap(effect, fetchPage),
+			Effect.succeed,
+		);
+		return Effect.succeed(
+			paginate(client, get(path)).pipe(
+				Stream.mapEffect((response) => Effect.fromNullishOr(entries.get(response))),
+				Stream.map(jsonResponse),
+			),
+		);
+	}
+	function writeRepresentation(method: "POST" | "PATCH", path: string, body: unknown, byteLimit = responseByteLimit) {
+		return HttpClientRequest.make(method)(new URL(path, apiUrl).href, { headers: { Accept: "application/vnd.github+json" } }).pipe(
+			HttpClientRequest.bodyJson(body),
+			Effect.flatMap((input) => request(input, byteLimit)),
+			Effect.map(jsonResponse),
+		);
+	}
+	return { get, list: listRepresentations, read: readRepresentation, write: writeRepresentation };
+}
+
+export type Representations = Omit<ReturnType<typeof representations>, "get">;

package/src/requests.ts

@@ -0,0 +1,44 @@
+import { Effect } from "effect";
+import { type HttpClient, HttpClientRequest } from "effect/http";
+import { readBoundedBody } from "@shivaedev/http/body.ts";
+import { ResponseBodyTooLarge } from "@shivaedev/http/errors.ts";
+import { authenticatedRequest } from "./authenticatedRequest.ts";
+import { type CachedResponse, responseCache } from "./cache.ts";
+import { GitHubTransportError } from "./errors.ts";
+import type { GitHubToken } from "./GitHubToken.ts";
+import type { RateLimits } from "./rateLimits.ts";
+import { isUnchanged } from "./status.ts";
+import type { TokenRefresh } from "./TokenRefresh.ts";
+
+export function requests(
+	client: HttpClient.HttpClient,
+	token: GitHubToken["Service"],
+	rates: RateLimits,
+	refresh: typeof TokenRefresh.Service = undefined,
+) {
+	const cache = responseCache();
+	const send = authenticatedRequest(client, token, rates, refresh);
+	return Effect.fn("GitHub.request")(function* (input: HttpClientRequest.HttpClientRequest, limit: number) {
+		const key = `${input.url} ${input.headers.accept}`;
+		const cached = input.method === "GET" ? cache.get(key) : undefined;
+		let request = HttpClientRequest.removeHeader(input, "if-none-match");
+		if (cached?.response.headers.etag !== undefined) {
+			request = HttpClientRequest.setHeader(request, "If-None-Match", cached.response.headers.etag);
+		}
+		const response = yield* send(request, cached === undefined ? undefined : "revalidate");
+		if (isUnchanged(response) && cached !== undefined) {
+			if (cached.bytes.byteLength > limit) {
+				return yield* new ResponseBodyTooLarge({ limit });
+			}
+			return cached;
+		}
+		const bytes = yield* readBoundedBody(response, limit).pipe(
+			Effect.catchTag("HttpClientError", () => Effect.fail(new GitHubTransportError({ path: new URL(input.url).pathname }))),
+		);
+		const entry: CachedResponse = { bytes, decoded: new Map(), response };
+		if (input.method === "GET" && response.headers.etag !== undefined) {
+			cache.set(key, entry);
+		}
+		return entry;
+	});
+}

package/src/status.ts

@@ -0,0 +1,64 @@
+import { DateTime, Effect, Option, Schema } from "effect";
+import { HttpClient, type HttpClientResponse } from "effect/http";
+import { readBoundedText } from "@shivaedev/http/body.ts";
+import { filterStatus } from "@shivaedev/http/filterStatus.ts";
+import { parseRetryAfter } from "@shivaedev/http/parseRetryAfter.ts";
+import { GitHubConversationLocked, GitHubPermissionDenied, GitHubRateLimited } from "#errors.ts";
+
+export function isUnauthorized(response: HttpClientResponse.HttpClientResponse) {
+	return response.status === 401;
+}
+
+export function isUnchanged(response: HttpClientResponse.HttpClientResponse) {
+	return response.status === 304;
+}
+
+export const checkStatus = Effect.fnUntraced(function* (response: HttpClientResponse.HttpClientResponse, resource: string, failures = 0) {
+	const { status, headers } = response;
+	if (status === 403 || status === 429) {
+		const limitedByHeaders = status === 429 || headers["x-ratelimit-remaining"] === "0" || headers["retry-after"] !== undefined;
+		const message = !limitedByHeaders && status === 403 ? yield* responseMessage(response) : undefined;
+		const limitedByMessage = message !== undefined && /rate limit/iu.test(message);
+		if (limitedByHeaders || limitedByMessage) {
+			return yield* refuseRateLimit(response, resource, failures);
+		}
+		const refusal = githubRefusal(message, new URL(response.request.url).pathname);
+		if (refusal !== undefined) {
+			return yield* refusal;
+		}
+	}
+	return yield* filterStatus(HttpClient.makeWith(() => Effect.succeed(response), Effect.succeed)).execute(response.request);
+});
+
+const Message = Schema.fromJsonString(Schema.Struct({ message: Schema.String }));
+
+const responseMessage = Effect.fnUntraced(function* (response: HttpClientResponse.HttpClientResponse) {
+	const text = yield* readBoundedText(response, 64 * 1024);
+	const body = Schema.decodeUnknownOption(Message)(text);
+	return Option.isSome(body) ? body.value.message : undefined;
+});
+
+function githubRefusal(message: string | undefined, path: string) {
+	if (message === undefined) {
+		return undefined;
+	}
+	if (/^Resource not accessible by integration$/iu.test(message)) {
+		return new GitHubPermissionDenied({ path });
+	}
+	if (/\bconversation (?:is|has been) locked\b/iu.test(message)) {
+		return new GitHubConversationLocked({ path });
+	}
+	return undefined;
+}
+
+const refuseRateLimit = Effect.fnUntraced(function* (response: HttpClientResponse.HttpClientResponse, resource: string, failures: number) {
+	const { headers } = response;
+	const now = yield* DateTime.now;
+	const reset = Number(headers["x-ratelimit-reset"] ?? 0) * 1000;
+	const fallback =
+		headers["x-ratelimit-remaining"] === "0" && reset > DateTime.toEpochMillis(now)
+			? reset
+			: DateTime.toEpochMillis(now) + Math.min(15 * 60_000, 60_000 * 2 ** failures);
+	const retryAt = parseRetryAfter(headers["retry-after"], now) ?? DateTime.makeUnsafe(fallback);
+	return yield* new GitHubRateLimited({ resource, retryAt });
+});

package/src/stickyComments.ts

@@ -0,0 +1,49 @@
+import { Effect, Option, Schema, Stream } from "effect";
+import type { Representations } from "#representations.ts";
+
+export const PullRequestComment = Schema.Struct({
+	body: Schema.String,
+	id: Schema.Number,
+	performedViaGithubApp: Schema.optional(Schema.NullOr(Schema.Struct({ id: Schema.Number }))),
+	user: Schema.NullOr(Schema.Struct({ login: Schema.String, type: Schema.optional(Schema.String) })),
+}).pipe(Schema.encodeKeys({ performedViaGithubApp: "performed_via_github_app" }));
+
+export const StickyComment = Schema.Struct({
+	appId: Schema.optional(Schema.Number),
+	author: Schema.optional(Schema.String),
+	body: Schema.String,
+	marker: Schema.String,
+	number: Schema.Number,
+	owner: Schema.String,
+	repo: Schema.String,
+});
+
+const CommentBody = Schema.Struct({ body: Schema.String });
+
+export function stickyComments(client: Representations) {
+	return {
+		upsertStickyComment: Effect.fn("GitHub.upsertStickyComment")(function* (input: typeof StickyComment.Type) {
+			const { owner, repo, number, marker, body, author, appId } = yield* Schema.decodeUnknownEffect(StickyComment)(input);
+			const hiddenMarker = `<!-- ${marker} -->`;
+			const root = `/repos/${owner}/${repo}/issues`;
+			const pages = yield* client.list(`${root}/${number}/comments`);
+			const existing = yield* pages.pipe(
+				Stream.mapEffect((page) => page.decode(Schema.Array(PullRequestComment))),
+				Stream.flatMap(Stream.fromIterable),
+				Stream.filter(
+					(comment) =>
+						(author === undefined || comment.user?.login === author)
+						&& (appId === undefined
+							? comment.body.includes(hiddenMarker)
+							: comment.body.startsWith(hiddenMarker) && comment.performedViaGithubApp?.id === appId && comment.user?.type === "Bot"),
+				),
+				Stream.runHead,
+			);
+			const payload = yield* Schema.encodeEffect(CommentBody)({ body: `${hiddenMarker}\n${body}` });
+			const response = yield* Option.isSome(existing)
+				? client.write("PATCH", `${root}/comments/${existing.value.id}`, payload)
+				: client.write("POST", `${root}/${number}/comments`, payload);
+			return yield* response.decode(PullRequestComment);
+		}),
+	};
+}