@shivaedev/github 0.8.6 → 0.10.0

package/src/artifacts.ts

@@ -4,13 +4,15 @@ import * as HttpStatus from "effect/http/HttpStatus";
 import { readBoundedBody } from "@shivaedev/http/body.ts";
 import type { RemoteStatusError } from "@shivaedev/http/errors.ts";
 import { filterStatus } from "@shivaedev/http/filterStatus.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";
+import { resolveApiUrl } from "#adapters/resolveApiUrl.ts";
+import { type ArtifactExtractionOptions, extractArtifactArchive } from "#artifactExtraction.ts";
+import { authenticatedRequest } from "#authenticatedRequest.ts";
+import { GitHubArtifactError, GitHubArtifactTooLarge, GitHubTransportError } from "#errors.ts";
+import { GitHubToken } from "#GitHubToken.ts";
+import type { RateLimits } from "#rateLimits.ts";
+import { TokenRefresh } from "#TokenRefresh.ts";
 
-export interface ArtifactArchiveOptions {
+export interface ArtifactArchiveOptions extends ArtifactExtractionOptions {
 	readonly artifactId: number;
 	readonly byteLimit: number;
 	readonly owner: string;
@@ -23,41 +25,36 @@ function downloadFailure(path: string, cause: HttpClientError.HttpClientError |
 		: new GitHubArtifactError({ stage: "download", status: cause.status });
 }
 
-export function artifacts(
-	apiUrl: string,
-	client: HttpClient.HttpClient,
-	token: GitHubToken["Service"],
-	rates: RateLimits,
-	refresh: typeof TokenRefresh.Service = undefined,
-) {
+export const artifacts = Effect.fn("GitHub.artifacts")(function* (apiUrl: string, rates: RateLimits) {
+	const client = yield* HttpClient.HttpClient;
+	const token = yield* GitHubToken;
+	const refresh = yield* TokenRefresh;
 	const send = authenticatedRequest(HttpClient.withScope(client), token, rates, refresh);
 	const download = filterStatus(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 }, { cause: error })),
-							RemoteNotFound: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
-						}),
-					);
-					const location = redirect.headers.location;
-					if (redirect.status !== HttpStatus.fromLiteral("Found") || 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((cause) => downloadFailure(path, cause)),
-					);
-					return yield* readBoundedBody(response, options.byteLimit).pipe(
-						Effect.catchTags({
-							HttpClientError: (cause) => Effect.fail(new GitHubTransportError({ path }, { cause })),
-							ResponseBodyTooLarge: (cause) => Effect.fail(new GitHubArtifactTooLarge({ limit: cause.limit }, { cause })),
-						}),
-					);
+		downloadArtifactArchive: Effect.fn("GitHub.downloadArtifactArchive")(function* (options: ArtifactArchiveOptions) {
+			const path = `/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/actions/artifacts/${options.artifactId}/zip`;
+			const redirect = yield* send(HttpClientRequest.get(resolveApiUrl(apiUrl, path), { accept: "application/vnd.github+json" }), "manual").pipe(
+				Effect.catchTags({
+					RemoteGone: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
+					RemoteNotFound: (error) => Effect.fail(new GitHubArtifactError({ stage: "redirect", status: error.status }, { cause: error })),
 				}),
-			),
+			);
+			const location = redirect.headers.location;
+			if (redirect.status !== HttpStatus.fromLiteral("Found") || 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((cause) => downloadFailure(path, cause)),
+			);
+			return yield* readBoundedBody(response, options.byteLimit).pipe(
+				Effect.catchTags({
+					HttpClientError: (cause) => Effect.fail(new GitHubTransportError({ path }, { cause })),
+					ResponseBodyTooLarge: (cause) => Effect.fail(new GitHubArtifactTooLarge({ limit: cause.limit }, { cause })),
+				}),
+				Effect.flatMap((bytes) => extractArtifactArchive(bytes, options)),
+			);
+		}, Effect.scoped),
 	};
-}
+});

package/src/authenticatedRequest.ts

@@ -1,4 +1,4 @@
-import { DateTime, Effect, Option, Redacted } from "effect";
+import { DateTime, Effect, Option, Redacted, Stream } from "effect";
 import { FetchHttpClient, type HttpClient, type HttpClientError, HttpClientRequest } from "effect/http";
 import * as HttpStatus from "effect/http/HttpStatus";
 import { GitHubTransportError } from "./errors.ts";
@@ -30,12 +30,14 @@ export function authenticatedRequest<R>(
 		const credential = yield* accessToken;
 		let response = yield* send(credential);
 		if (isUnauthorized(response) && refresh !== undefined) {
+			yield* Effect.scoped(Stream.toPull(response.stream));
 			yield* refresh(credential);
 			response = yield* send(yield* accessToken);
 		}
 		const observedResource = rates.observe(response);
 		if (!((mode === "revalidate" && isUnchanged(response)) || (mode === "manual" && response.status === HttpStatus.fromLiteral("Found")))) {
 			yield* checkStatus(response, observedResource, rates.failures.get(observedResource) ?? 0).pipe(
+				Effect.onError(() => Effect.scoped(Stream.toPull(response.stream))),
 				Effect.catchTag("HttpClientError", (cause) => Effect.fail(new GitHubTransportError({ path }, { cause }))),
 				Effect.catchTag("GitHubRateLimited", (error) => {
 					rates.blocked.set(error.resource, error);

package/src/cache.ts

@@ -4,9 +4,14 @@ import type { HttpClientResponse } from "effect/http";
 export interface CachedResponse {
 	readonly bytes: Uint8Array;
 	readonly decoded: Map<Schema.Constraint, unknown>;
+	readonly etag?: string | undefined;
 	readonly response: HttpClientResponse.HttpClientResponse;
 }
 
+export function revalidatedResponse(cached: CachedResponse, response: HttpClientResponse.HttpClientResponse): CachedResponse {
+	return { ...cached, etag: response.headers.etag ?? cached.etag, response };
+}
+
 export function responseCache() {
 	const entries = new Map<string, CachedResponse>();
 	return {

package/src/checkRuns.ts

@@ -1,4 +1,5 @@
-import { Effect, Schema } from "effect";
+import { Effect, Option, Schema, Stream } from "effect";
+import { decodedPages } from "#pagedLists.ts";
 import type { Representations } from "#representations.ts";
 
 export const CheckRunOutput = Schema.Struct({
@@ -8,16 +9,22 @@ export const CheckRunOutput = Schema.Struct({
 });
 
 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 CheckRunStatus = Schema.Literals(["queued", "in_progress", "completed", "waiting", "requested", "pending"]);
 
-export const CreateCheckRun = Schema.Struct({
-	conclusion: Schema.optional(CheckRunConclusion),
+const createFields = {
 	detailsUrl: Schema.optional(Schema.String),
 	headSha: Schema.String,
 	name: Schema.String,
 	output: Schema.optional(CheckRunOutput),
-	status: CheckRunStatus,
-}).pipe(Schema.encodeKeys({ detailsUrl: "details_url", headSha: "head_sha" }));
+};
+export const CreateCheckRun = Schema.Union([
+	Schema.Struct({ ...createFields, conclusion: Schema.optional(CheckRunConclusion), status: Schema.Literals(["queued", "in_progress"]) }).pipe(
+		Schema.encodeKeys({ detailsUrl: "details_url", headSha: "head_sha" }),
+	),
+	Schema.Struct({ ...createFields, conclusion: CheckRunConclusion, status: Schema.Literal("completed") }).pipe(
+		Schema.encodeKeys({ detailsUrl: "details_url", headSha: "head_sha" }),
+	),
+]);
 
 export const UpdateCheckRun = Schema.Union([
 	Schema.Struct({
@@ -34,6 +41,7 @@ export const UpdateCheckRun = Schema.Union([
 ]);
 
 export const CheckRun = Schema.Struct({
+	app: Schema.optional(Schema.NullOr(Schema.Struct({ id: Schema.Number }))),
 	conclusion: Schema.NullOr(CheckRunConclusion),
 	detailsUrl: Schema.NullOr(Schema.String),
 	headSha: Schema.String,
@@ -43,17 +51,49 @@ export const CheckRun = Schema.Struct({
 	status: CheckRunStatus,
 }).pipe(Schema.encodeKeys({ detailsUrl: "details_url", headSha: "head_sha" }));
 
+export const FindCheckRun = Schema.Union([
+	Schema.Struct({ appId: Schema.optional(Schema.Number), headSha: Schema.String, name: Schema.String }),
+	Schema.Struct({ appId: Schema.Number, headSha: Schema.String, name: Schema.optional(Schema.String) }),
+]);
+
 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);
-		}),
-	};
+	const 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);
+	});
+	const 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);
+	});
+	const findLatestCheckRun = Effect.fn("GitHub.findLatestCheckRun")(function* (owner: string, repo: string, input: typeof FindCheckRun.Type) {
+		const { headSha, name, appId } = yield* Schema.decodeUnknownEffect(FindCheckRun)(input);
+		const query = new URLSearchParams({ filter: "all", "per_page": "100" });
+		if (name !== undefined) {
+			query.set("check_name", name);
+		}
+		const pages = decodedPages(client, `/repos/${owner}/${repo}/commits/${encodeURIComponent(headSha)}/check-runs?${query}`, CheckRun, {
+			arrayKey: "check_runs",
+		});
+		return yield* pages.pipe(
+			Stream.flatMap((page) => Stream.fromIterable(page.items)),
+			Stream.filter((run) => (name === undefined || run.name === name) && (appId === undefined || run.app?.id === appId)),
+			Stream.runFold(
+				() => Option.none<typeof CheckRun.Type>(),
+				(latest, run) => (Option.isNone(latest) || run.id > latest.value.id ? Option.some(run) : latest),
+			),
+		);
+	});
+	const upsertCheckRun = Effect.fn("GitHub.upsertCheckRun")(function* (
+		owner: string,
+		repo: string,
+		input: typeof CreateCheckRun.Type,
+		appId?: number,
+	) {
+		yield* Schema.encodeEffect(CreateCheckRun)(input);
+		const existing = yield* findLatestCheckRun(owner, repo, { appId, headSha: input.headSha, name: input.name });
+		return yield* Option.isSome(existing) ? updateCheckRun(owner, repo, existing.value.id, input) : createCheckRun(owner, repo, input);
+	});
+	return { createCheckRun, findLatestCheckRun, updateCheckRun, upsertCheckRun };
 }

package/src/gitSchemas.ts

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+import { PullRequestFile, User } from "#repositorySchemas.ts";
+
+const CommitIdentity = Schema.Struct({ date: Schema.String, email: Schema.String, name: Schema.String });
+const CommitData = Schema.Struct({
+	author: Schema.NullOr(CommitIdentity),
+	committer: Schema.NullOr(CommitIdentity),
+	message: Schema.String,
+	tree: Schema.Struct({ sha: Schema.String, url: Schema.String }),
+});
+
+const commitFields = {
+	author: Schema.NullOr(User),
+	commit: CommitData,
+	committer: Schema.NullOr(User),
+	htmlUrl: Schema.String,
+	parents: Schema.Array(Schema.Struct({ sha: Schema.String, url: Schema.String })),
+	sha: Schema.String,
+};
+
+export const Commit = Schema.Struct(commitFields).pipe(Schema.encodeKeys({ htmlUrl: "html_url" }));
+
+export const CommitDetail = Schema.Struct({
+	...commitFields,
+	files: Schema.optional(Schema.Array(PullRequestFile)),
+	stats: Schema.Struct({ additions: Schema.Number, deletions: Schema.Number, total: Schema.Number }),
+}).pipe(Schema.encodeKeys({ htmlUrl: "html_url" }));
+
+export const Comparison = Schema.Struct({
+	aheadBy: Schema.Number,
+	behindBy: Schema.Number,
+	commits: Schema.Array(Commit),
+	files: Schema.optional(Schema.Array(PullRequestFile)),
+	status: Schema.Literals(["diverged", "ahead", "behind", "identical"]),
+	totalCommits: Schema.Number,
+}).pipe(Schema.encodeKeys({ aheadBy: "ahead_by", behindBy: "behind_by", totalCommits: "total_commits" }));
+
+export const GitTree = Schema.Struct({
+	sha: Schema.String,
+	tree: Schema.Array(
+		Schema.Struct({
+			mode: Schema.String,
+			path: Schema.String,
+			sha: Schema.String,
+			size: Schema.optional(Schema.Number),
+			type: Schema.Literals(["blob", "tree", "commit"]),
+			url: Schema.optional(Schema.String),
+		}),
+	),
+	truncated: Schema.Boolean,
+	url: Schema.String,
+});

package/src/githubApp.ts

@@ -1,12 +1,7 @@
-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 { filterStatus } from "@shivaedev/http/filterStatus.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";
+import { Layer } from "effect";
+import type { AppCredentials } from "#appJwt.ts";
+import { appTokens } from "#appTokens.ts";
+import { GitHubApp, GitHubAppCredentials } from "#installationClients.ts";
 
 export interface InstallationScope {
 	readonly permissions?: Readonly<Record<string, "read" | "write" | "admin">>;
@@ -21,76 +16,7 @@ export type GitHubAppOptions = AppCredentials &
 		| { 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) {
-	const checked = filterStatus(client);
-	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((cause) => new GitHubAppError({ reason: "encode" }, { cause })));
-		}
-		const response = yield* checked
-			.execute(input)
-			.pipe(
-				Effect.mapError((cause) =>
-					cause._tag === "HttpClientError"
-						? new GitHubAppError({ reason: "transport" }, { cause })
-						: new GitHubAppError({ reason: "status", status: cause.status }),
-				),
-			);
-		return yield* readBoundedJson(response, 64 * 1024, schema).pipe(
-			Effect.mapError((cause) => new GitHubAppError({ reason: cause._tag === "HttpClientError" ? "transport" : "response" }, { cause })),
-		);
-	});
+	const authentication = appTokens(options);
+	return Layer.merge(authentication, GitHubApp.layer.pipe(Layer.provide(Layer.succeed(GitHubAppCredentials)({ credentials: options }))));
 }

package/src/installationClients.ts

@@ -0,0 +1,50 @@
+import { Cache, Context, Effect, Layer } from "effect";
+import { HttpClient } from "effect/http";
+import { defineService } from "@shivaedev/service/defineService.ts";
+import type { AppCredentials } from "#appJwt.ts";
+import { appTokens } from "#appTokens.ts";
+import { GitHub } from "#GitHub.ts";
+import { GitHubConfig } from "#GitHubConfig.ts";
+import { viewerRepositoryAccess } from "#viewerRepositoryAccess.ts";
+
+export const GitHubAppCredentials = Context.Service<{ readonly credentials: AppCredentials }>("@shivaedev/github/AppCredentials");
+
+export const GitHubApp = defineService({
+	id: "@shivaedev/github/GitHubApp",
+	initialize: Effect.gen(function* () {
+		const { credentials: supplied } = yield* GitHubAppCredentials;
+		const credentials = { appId: supplied.appId, privateKey: supplied.privateKey };
+		const http = yield* HttpClient.HttpClient;
+		const config = yield* GitHubConfig;
+		const environment = Layer.mergeAll(Layer.succeed(HttpClient.HttpClient)(http), Layer.succeed(GitHubConfig)(config));
+		const app = yield* Layer.build(GitHub.layer.pipe(Layer.provide(appTokens(credentials)), Layer.provide(environment))).pipe(
+			Effect.scoped,
+			Effect.map((context) => Context.get(context, GitHub)),
+		);
+		const clients = yield* Cache.make({
+			capacity: 100,
+			lookup: (installationId: number) =>
+				Layer.build(GitHub.layer.pipe(Layer.provide(appTokens({ ...credentials, installationId })), Layer.provide(environment))).pipe(
+					Effect.scoped,
+					Effect.map((context) => Context.get(context, GitHub)),
+				),
+			timeToLive: "30 minutes",
+		});
+		function installation(id: number) {
+			return Cache.get(clients, id).pipe(Effect.tap((client) => Cache.set(clients, id, client)));
+		}
+		return { installation, viewers: yield* viewerRepositoryAccess(app, installation) };
+	}),
+	methods: ({ installation, viewers }) => ({
+		installation,
+		viewerRepositories: (account: number | string) =>
+			Cache.get(viewers, typeof account === "number" ? `id:${account}` : `login:${account.toLowerCase()}`),
+	}),
+	requires: [GitHubAppCredentials, HttpClient.HttpClient, GitHubConfig],
+});
+
+export function withInstallation<A, E, R>(installationId: number, effect: Effect.Effect<A, E, R>) {
+	return Effect.flatMap(GitHubApp, (app) =>
+		Effect.flatMap(app.installation(installationId), (client) => Effect.provideService(effect, GitHub, client)),
+	);
+}

package/src/json.ts

@@ -1,7 +1,11 @@
 import { Effect, Schema } from "effect";
+import * as HttpStatus from "effect/http/HttpStatus";
 import type { CachedResponse } from "./cache.ts";
 
 export const decodeJson = Effect.fnUntraced(function* <TSchema extends Schema.Constraint>(entry: CachedResponse, schema: TSchema) {
+	if (entry.response.status === HttpStatus.fromLiteral("NoContent")) {
+		return yield* Schema.decodeUnknownEffect(schema)(undefined);
+	}
 	const cached = entry.decoded.get(schema);
 	if (entry.decoded.has(schema) && Schema.is(schema)(cached)) {
 		return cached;

package/src/pagedLists.ts

@@ -0,0 +1,40 @@
+import { Effect, Option, Schema, Stream } from "effect";
+import type { ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
+import type { Representations } from "#representations.ts";
+
+export interface ListOptions {
+	readonly arrayKey?: string | undefined;
+	readonly beforeRequest?: (resource: string) => Effect.Effect<void, ServiceUnavailable>;
+	readonly onDecodeError?: "fail" | "skip" | undefined;
+	readonly responseByteLimit?: number | undefined;
+}
+
+export function decodedPages<TSchema extends Schema.Constraint>(
+	client: Representations,
+	path: string,
+	schema: TSchema,
+	options: ListOptions | number = {},
+) {
+	const settings = typeof options === "number" ? { responseByteLimit: options } : options;
+	const decode = Schema.decodeUnknownEffect(schema);
+	return Stream.unwrap(client.list(path, settings.beforeRequest, settings.responseByteLimit)).pipe(
+		Stream.mapEffect((page) =>
+			Effect.gen(function* () {
+				const body = yield* page.decode(Schema.Unknown);
+				const source =
+					settings.arrayKey === undefined
+						? body
+						: (yield* Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown))(body))[settings.arrayKey];
+				const values = yield* Schema.decodeUnknownEffect(Schema.Array(Schema.Unknown))(source);
+				const decoded = yield* Effect.forEach(values, (value) =>
+					decode(value).pipe(
+						Effect.map(Option.some),
+						Effect.catchTag("SchemaError", (error) => (settings.onDecodeError === "skip" ? Effect.succeed(Option.none()) : Effect.fail(error))),
+					),
+				);
+				const items = decoded.flatMap(Option.toArray);
+				return { hasNext: page.hasNext, items, skipped: values.length - items.length };
+			}),
+		),
+	);
+}

package/src/repositoryReads.ts

@@ -0,0 +1,61 @@
+import { Effect } from "effect";
+import { Commit, CommitDetail, Comparison, GitTree } from "#gitSchemas.ts";
+import { decodedPages, type ListOptions } from "#pagedLists.ts";
+import { CollaboratorPermission, Issue, PullRequestFile, User } from "#repositorySchemas.ts";
+import type { Representations } from "#representations.ts";
+
+export interface RepositoryListOptions extends ListOptions {
+	readonly query?: Readonly<Record<string, string | number | boolean | undefined>>;
+}
+
+export function repositoryReads(client: Representations) {
+	function repository(owner: string, repo: string) {
+		return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+	}
+	function pathWithQuery(path: string, options?: RepositoryListOptions) {
+		const query = new URLSearchParams({ "per_page": "100" });
+		for (const [key, value] of Object.entries(options?.query ?? {})) {
+			if (value !== undefined) {
+				query.set(key, String(value));
+			}
+		}
+		return `${path}?${query}`;
+	}
+	return {
+		compareCommits: (owner: string, repo: string, base: string, head: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`, byteLimit), (page) =>
+				page.decode(Comparison),
+			),
+		getCollaboratorPermission: (owner: string, repo: string, username: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/collaborators/${encodeURIComponent(username)}/permission`, byteLimit), (page) =>
+				page.decode(CollaboratorPermission),
+			),
+		getCommit: (owner: string, repo: string, ref: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/commits/${encodeURIComponent(ref)}`, byteLimit), (page) => page.decode(CommitDetail)),
+		getIssue: (owner: string, repo: string, number: number, byteLimit?: number) =>
+			Effect.flatMap(client.read(`${repository(owner, repo)}/issues/${number}`, byteLimit), (page) => page.decode(Issue)),
+		getTree: (
+			owner: string,
+			repo: string,
+			sha: string,
+			options?: { readonly recursive?: boolean; readonly responseByteLimit?: number | undefined },
+		) =>
+			Effect.flatMap(
+				client.read(
+					`${repository(owner, repo)}/git/trees/${encodeURIComponent(sha)}${options?.recursive ? "?recursive=1" : ""}`,
+					options?.responseByteLimit,
+				),
+				(page) => page.decode(GitTree),
+			),
+		getUser: (username?: string, byteLimit?: number) =>
+			Effect.flatMap(client.read(username === undefined ? "/user" : `/users/${encodeURIComponent(username)}`, byteLimit), (page) =>
+				page.decode(User),
+			),
+		listCommits: (owner: string, repo: string, options?: RepositoryListOptions) =>
+			Effect.succeed(decodedPages(client, pathWithQuery(`${repository(owner, repo)}/commits`, options), Commit, options)),
+		listIssues: (owner: string, repo: string, options?: RepositoryListOptions) =>
+			Effect.succeed(decodedPages(client, pathWithQuery(`${repository(owner, repo)}/issues`, options), Issue, options)),
+		listPullRequestFiles: (owner: string, repo: string, number: number, options?: RepositoryListOptions) =>
+			Effect.succeed(decodedPages(client, pathWithQuery(`${repository(owner, repo)}/pulls/${number}/files`, options), PullRequestFile, options)),
+	};
+}

package/src/repositorySchemas.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+
+export const User = Schema.Struct({
+	avatarUrl: Schema.String,
+	htmlUrl: Schema.String,
+	id: Schema.Number,
+	login: Schema.String,
+	type: Schema.String,
+}).pipe(Schema.encodeKeys({ avatarUrl: "avatar_url", htmlUrl: "html_url" }));
+
+export const Issue = Schema.Struct({
+	body: Schema.NullOr(Schema.String),
+	closedAt: Schema.NullOr(Schema.String),
+	createdAt: Schema.String,
+	htmlUrl: Schema.String,
+	id: Schema.Number,
+	labels: Schema.Array(Schema.Union([Schema.String, Schema.Struct({ name: Schema.optional(Schema.String) })])),
+	number: Schema.Number,
+	pullRequest: Schema.optional(Schema.Struct({ url: Schema.String })),
+	state: Schema.Literals(["open", "closed"]),
+	title: Schema.String,
+	updatedAt: Schema.String,
+	user: Schema.NullOr(User),
+}).pipe(
+	Schema.encodeKeys({ closedAt: "closed_at", createdAt: "created_at", htmlUrl: "html_url", pullRequest: "pull_request", updatedAt: "updated_at" }),
+);
+
+export const PullRequestFile = Schema.Struct({
+	additions: Schema.Number,
+	changes: Schema.Number,
+	deletions: Schema.Number,
+	filename: Schema.String,
+	patch: Schema.optional(Schema.String),
+	previousFilename: Schema.optional(Schema.String),
+	sha: Schema.String,
+	status: Schema.String,
+}).pipe(Schema.encodeKeys({ previousFilename: "previous_filename" }));
+
+export const CollaboratorPermission = Schema.Struct({
+	permission: Schema.String,
+	roleName: Schema.String,
+	user: User,
+}).pipe(Schema.encodeKeys({ roleName: "role_name" }));

package/src/representations.ts

@@ -3,6 +3,7 @@ import { HttpClient, HttpClientRequest, type HttpClientResponse } from "effect/h
 import type { ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
 import { nextLink } from "@shivaedev/http/nextLink.ts";
 import { paginate } from "@shivaedev/http/paginate.ts";
+import { resolveApiUrl } from "#adapters/resolveApiUrl.ts";
 import type { CachedResponse } from "#cache.ts";
 import { jsonResponse } from "#json.ts";
 import type { requests } from "#requests.ts";
@@ -14,7 +15,7 @@ export function representations(
 	responseByteLimit = 1024 * 1024,
 ) {
 	function get(path: string, accept = "application/vnd.github+json") {
-		return HttpClientRequest.get(new URL(path, apiUrl).href, { headers: { Accept: accept } });
+		return HttpClientRequest.get(resolveApiUrl(apiUrl, path), { headers: { Accept: accept } });
 	}
 	function readRepresentation(path: string, byteLimit = responseByteLimit) {
 		return Effect.map(request(get(path), byteLimit), jsonResponse);
@@ -45,9 +46,9 @@ export function representations(
 			),
 		);
 	}
-	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),
+	function writeRepresentation(method: "POST" | "PATCH" | "PUT" | "DELETE", path: string, body?: unknown, byteLimit = responseByteLimit) {
+		return HttpClientRequest.make(method)(resolveApiUrl(apiUrl, path), { headers: { Accept: "application/vnd.github+json" } }).pipe(
+			(input) => (body === undefined ? Effect.succeed(input) : HttpClientRequest.bodyJson(input, body)),
 			Effect.flatMap((input) => request(input, byteLimit)),
 			Effect.map(jsonResponse),
 		);