@effected/github 0.1.0

package/index.js

@@ -0,0 +1,24 @@
+import { GitHubError, GitHubErrorKind } from "./GitHubError.js";
+import { GitHubGraphQLError, GraphQLDocument, GraphQLErrorEntry } from "./GraphQL.js";
+import { RateLimitSnapshot, RetryPolicy } from "./Resilience.js";
+import { GitHubClient } from "./GitHubClient.js";
+import { ArtifactMetadata, StorageRecordInput } from "./ArtifactMetadata.js";
+import { InvalidRepoRefError, Repo, RepoRef } from "./Repo.js";
+import { Attestation, AttestationListEntry, AttestationRecord } from "./Attestation.js";
+import { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef } from "./CheckRun.js";
+import { GitBranch } from "./GitBranch.js";
+import { CommitRef, FileChange, FileContent, FileDeletion, FileMode, GitCommit } from "./GitCommit.js";
+import { AppIdentity, BotIdentity, GitHubApp, GitHubAppError, Installation, InstallationToken } from "./GitHubApp.js";
+import { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit } from "./GitHubCommit.js";
+import { GitHubContent } from "./GitHubContent.js";
+import { GitHubIssue, IssueInfo, LinkedIssue } from "./GitHubIssue.js";
+import { GitHubRelease, ReleaseAsset, ReleaseInfo } from "./GitHubRelease.js";
+import { GitHubRepository } from "./GitHubRepository.js";
+import { GitTag, SemverTag, TagRef, versionFromTag } from "./GitTag.js";
+import { PageOptions } from "./Rest.js";
+import { MergeMethod, PullRequest, PullRequestInfo } from "./PullRequest.js";
+import { CommentMarker, CommentRecord, PullRequestComment } from "./PullRequestComment.js";
+import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, TokenPermissionError, TokenPermissions } from "./TokenPermissions.js";
+import { WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
+
+export { Annotation, AnnotationLevel, AppIdentity, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, BotIdentity, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CommentMarker, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, ReleaseAsset, ReleaseInfo, Repo, RepoRef, RetryPolicy, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, versionFromTag };

package/internal/headers.js

@@ -0,0 +1,52 @@
+//#region src/internal/headers.ts
+/**
+* Reading GitHub's response headers.
+*
+* @remarks
+* octokit hands headers back as a plain object whose values may be `string`,
+* `number` or absent depending on the fetch implementation, so every read here
+* is defensive about both. Header names are already lowercased by octokit.
+*
+* @internal
+*/
+/** A header's value as a string, when it is present and non-empty. */
+const headerString = (headers, name) => {
+	const value = headers?.[name];
+	if (typeof value === "string") return value.length > 0 ? value : void 0;
+	if (typeof value === "number") return String(value);
+};
+/** A header's value as a finite integer, when it parses as one. */
+const headerNumber = (headers, name) => {
+	const raw = headerString(headers, name);
+	if (raw === void 0) return void 0;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? Math.trunc(parsed) : void 0;
+};
+/**
+* How long GitHub asked us to wait, in milliseconds, or `undefined` when it
+* did not ask.
+*
+* @remarks
+* Two mechanisms, checked in GitHub's own order of specificity:
+*
+* 1. `retry-after` — whole seconds, sent for secondary rate limits and abuse
+*    detection. Authoritative when present.
+* 2. `x-ratelimit-remaining: 0` plus `x-ratelimit-reset` — the primary rate
+*    limit, where the reset is an absolute epoch **second**. Only meaningful
+*    when the budget is actually exhausted: every successful response carries a
+*    reset header too, and treating that as a delay would make every call look
+*    rate-limited.
+*
+* `nowMillis` is a parameter rather than a `Date.now()` read so this stays pure
+* and so a test can pin it.
+*/
+const retryAfterMillisFrom = (headers, nowMillis) => {
+	const retryAfterSeconds = headerNumber(headers, "retry-after");
+	if (retryAfterSeconds !== void 0 && retryAfterSeconds >= 0) return retryAfterSeconds * 1e3;
+	const remaining = headerNumber(headers, "x-ratelimit-remaining");
+	const reset = headerNumber(headers, "x-ratelimit-reset");
+	if (remaining !== void 0 && remaining <= 0 && reset !== void 0) return Math.max(0, reset * 1e3 - nowMillis);
+};
+
+//#endregion
+export { headerNumber, headerString, retryAfterMillisFrom };

package/internal/octokit.js

@@ -0,0 +1,115 @@
+import { GitHubError, readRateLimitHeaders } from "../GitHubError.js";
+import { GitHubGraphQLError } from "../GraphQL.js";
+import { RateLimitSnapshot } from "../Resilience.js";
+import { Clock, Effect, Option, Redacted, Ref } from "effect";
+import { Octokit } from "@octokit/core";
+import { composePaginateRest } from "@octokit/plugin-paginate-rest";
+
+//#region src/internal/octokit.ts
+const SILENT_LOG = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+/**
+* Build the octokit instance.
+*
+* @remarks
+* `auth` takes the raw token string. `@octokit/auth-token` inspects it and
+* emits `bearer` for a three-segment JWT and `token` otherwise — exactly the
+* distinction an app JWT and an installation token need, so the App path
+* requires no separate auth strategy.
+*
+* `log` is silenced. The package this replaces installed
+* `plugin-request-log` and then rerouted every line of it into an Actions
+* `::debug::` workflow command, which is how GitHub Actions knowledge ended up
+* inside a GitHub API client. Here retries log through `Effect.logDebug`, and an
+* application maps Effect's logs to whatever its runtime wants.
+*/
+const makeOctokit = (options) => new Octokit({
+	...options.token !== void 0 ? { auth: Redacted.value(options.token) } : {},
+	...options.baseUrl !== void 0 ? { baseUrl: options.baseUrl } : {},
+	...options.userAgent !== void 0 ? { userAgent: options.userAgent } : {},
+	...options.fetch !== void 0 ? { request: { fetch: options.fetch } } : {},
+	log: SILENT_LOG
+});
+/**
+* Build a transport over a freshly constructed octokit instance.
+*
+* @remarks
+* The rate-limit cell lives here, in the closure of the layer that writes it.
+* The package this replaces made it an optional shared `Ref` **service** that
+* the writer and the reader both resolved through `Effect.serviceOption`, so an
+* application that forgot to provide it got two private cells, a limiter that
+* never saw the client's headers, and no error, warning or type signal saying
+* so.
+*/
+const makeTransport = (options) => Effect.gen(function* () {
+	const octokit = makeOctokit(options);
+	const snapshot = yield* Ref.make(Option.none());
+	const policy = options.retry;
+	const record = (headers) => {
+		const parsed = readRateLimitHeaders(headers);
+		return parsed === void 0 ? Effect.void : Ref.set(snapshot, Option.some(RateLimitSnapshot.make(parsed)));
+	};
+	/**
+	* Run one promise-producing call, classifying whatever it throws.
+	*
+	* @remarks
+	* The `AbortSignal` `Effect.tryPromise` supplies is threaded into octokit's
+	* `request.signal`, so interrupting the fiber aborts the in-flight HTTP
+	* request rather than leaving it running unobserved.
+	*/
+	const attempt = (call, classify) => Effect.tryPromise({
+		try: call,
+		catch: (error) => error
+	}).pipe(Effect.catch((error) => Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		yield* record(readThrownHeaders(error));
+		return yield* Effect.fail(classify(error, now));
+	})));
+	const withRetry = (operation, effect) => effect.pipe(Effect.tapError((error) => policy.retries(error) ? Effect.logDebug("github.retry").pipe(Effect.annotateLogs({ operation })) : Effect.void), Effect.retry(policy.schedule()));
+	const request = (operation, route, params) => withRetry(operation, attempt((signal) => octokit.request(route, withSignal(params, signal)), (error, now) => GitHubError.fromOctokit(operation, error, now)).pipe(Effect.tap((response) => record(response.headers))));
+	const pageSource = (operation, route, params) => {
+		const iterator = composePaginateRest.iterator(octokit, route, params)[Symbol.asyncIterator]();
+		let finished = false;
+		return { next: Effect.suspend(() => finished ? Effect.succeed(Option.none()) : withRetry(operation, attempt(() => iterator.next(), (error, now) => GitHubError.fromOctokit(operation, error, now)).pipe(Effect.flatMap((result) => {
+			if (result.done === true || result.value === void 0) {
+				finished = true;
+				return Effect.succeed(Option.none());
+			}
+			const response = result.value;
+			return record(response.headers).pipe(Effect.as(Option.some(response.data)));
+		})))) };
+	};
+	const graphql = (operation, document, variables) => withRetry(operation, attempt(() => octokit.graphql(document, variables), (error, now) => GitHubGraphQLError.fromThrowable(operation, error, now)));
+	return {
+		request,
+		pageSource,
+		graphql,
+		rateLimit: Ref.get(snapshot)
+	};
+});
+/** Merge our abort signal into octokit's per-request options without clobbering them. */
+const withSignal = (params, signal) => {
+	const existing = typeof params.request === "object" && params.request !== null ? params.request : {};
+	return {
+		...params,
+		request: {
+			...existing,
+			signal
+		}
+	};
+};
+/** Response headers off a throwable, when it carried any. */
+const readThrownHeaders = (error) => {
+	if (typeof error !== "object" || error === null) return void 0;
+	const response = error.response;
+	if (typeof response !== "object" || response === null) return void 0;
+	const headers = response.headers;
+	return typeof headers === "object" && headers !== null ? headers : void 0;
+};
+
+//#endregion
+export { makeTransport };

package/internal/paginate.js

@@ -0,0 +1,54 @@
+import { Effect, Option, Stream } from "effect";
+
+//#region src/internal/paginate.ts
+/**
+* Walk a {@link PageSource} into a stream of its items.
+*
+* @remarks
+* **This is the only pagination implementation in the package**, and it is why
+* the fixture double cannot drift from the live client: both build a
+* `PageSource` and hand it here, so `maxPages` and item flattening have exactly
+* one behavior. The package this replaces had a live loop that honored
+* `maxPages` and a test double whose equivalent parameters were named
+* `_options` and ignored — which made every truncation path structurally
+* untestable.
+*
+* `maxPages` bounds **requests, not items**: the walk stops issuing them rather
+* than fetching everything and slicing.
+*
+* @internal
+*/
+const paginate = (openSource, maxPages) => Stream.suspend(() => {
+	const source = openSource();
+	return Stream.paginate(0, (pagesTaken) => Effect.map(source.next, (page) => {
+		if (Option.isNone(page)) return [[], Option.none()];
+		const taken = pagesTaken + 1;
+		const exhausted = maxPages !== void 0 && taken >= maxPages;
+		return [page.value, exhausted ? Option.none() : Option.some(taken)];
+	}));
+});
+/**
+* A {@link PageSource} over an already-collected array, sliced into pages.
+*
+* @remarks
+* What the fixture double records. Slicing here rather than inside the double
+* keeps "what is a page" in one place: a recorded fixture of 250 items with
+* `perPage: 100` pages exactly as GitHub would, so a test can assert a caller's
+* `maxPages` truncation against real page boundaries.
+*
+* @internal
+*/
+const fromArray = (items, perPage) => {
+	let offset = 0;
+	let finished = false;
+	return { next: Effect.sync(() => {
+		if (finished) return Option.none();
+		const page = items.slice(offset, offset + perPage);
+		offset += perPage;
+		if (page.length < perPage) finished = true;
+		return page.length === 0 ? Option.none() : Option.some(page);
+	}) };
+};
+
+//#endregion
+export { fromArray, paginate };

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@effected/github",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
+	"keywords": [
+		"github",
+		"octokit",
+		"rest",
+		"graphql",
+		"app-auth",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/github#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/github"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effected/semver": "~0.2.1",
+		"@octokit/core": "^7.0.6",
+		"@octokit/plugin-paginate-rest": "^14.0.0",
+		"@octokit/types": "^16.0.0",
+		"universal-github-app-jwt": "^2.2.2"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.101"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.12"
+    }
+  ]
+}