@effected/github 0.17.0 → 0.19.0

package/AuthenticatedApp.js

@@ -0,0 +1,183 @@
+import { GitHubError } from "./GitHubError.js";
+import { GitHubClient } from "./GitHubClient.js";
+import { numericId } from "./internal/ids.js";
+import { Context, Effect, Layer, Schema, Stream } from "effect";
+
+//#region src/AuthenticatedApp.ts
+/**
+* The GitHub App itself, as `GET /app` reports it.
+*
+* @public
+*/
+var AppInfo = class extends Schema.Class("AppInfo")({
+	/** The app's numeric id. */
+	id: Schema.Int,
+	/**
+	* The URL slug, e.g. `"my-app"`; the app's bot user is `<slug>[bot]`.
+	*
+	* @remarks
+	* Optional because GitHub's schema for an app declares it optional; the
+	* authenticated app's own read is where you would expect it.
+	*/
+	slug: Schema.optionalKey(Schema.String),
+	/** The display name. */
+	name: Schema.String,
+	/** The app's GraphQL node id (wire `node_id`). */
+	nodeId: Schema.String,
+	/** The app's OAuth client id (wire `client_id`), when GitHub reports one. */
+	clientId: Schema.optionalKey(Schema.String),
+	/** The app's page on GitHub (wire `html_url`). */
+	htmlUrl: Schema.String
+}) {};
+/**
+* One delivery of the app's webhook, as `GET /app/hook/deliveries` lists it.
+*
+* @remarks
+* **Ids are numbers, and refuse to lose precision.** GitHub types a delivery
+* id (and an installation or repository id) as int64, and octokit as
+* `number | bigint`. A response body arrives through `JSON.parse`, which
+* never produces a bigint: an id beyond 2^53 would already have been rounded.
+* Every id here is decoded as a **safe** integer, so such an id fails the read
+* with a typed `decode` error instead of handing back a rounded id that names
+* a different delivery. Today's ids are many orders of magnitude below that
+* line.
+*
+* Encodable: every field is a JSON primitive, so a delivery can be stored as
+* it is.
+*
+* @public
+*/
+var DeliveryAttempt = class extends Schema.Class("DeliveryAttempt")({
+	/** The delivery's id; pass it to {@link AuthenticatedAppShape.redeliver}. */
+	id: Schema.Int,
+	/**
+	* The event's GUID (the `X-GitHub-Delivery` header). Shared by a delivery
+	* and all its redeliveries, so it identifies the event; `id` identifies
+	* the attempt.
+	*/
+	guid: Schema.String,
+	/** When it was delivered, as GitHub's ISO 8601 string (wire `delivered_at`). */
+	deliveredAt: Schema.String,
+	/** Whether this attempt was a redelivery. */
+	redelivery: Schema.Boolean,
+	/** How long the delivery took, in seconds. */
+	duration: Schema.Number,
+	/** GitHub's description of the outcome, e.g. `"OK"`. */
+	status: Schema.String,
+	/** The HTTP status your endpoint answered (wire `status_code`); `0` when it never answered. */
+	statusCode: Schema.Int,
+	/** The event, e.g. `"workflow_run"`. */
+	event: Schema.String,
+	/** The event's action, e.g. `"completed"`; `null` for an event without one. */
+	action: Schema.NullOr(Schema.String),
+	/** The installation the event concerns (wire `installation_id`); `null` for none. */
+	installationId: Schema.NullOr(Schema.Int),
+	/** The repository the event concerns (wire `repository_id`); `null` for none. */
+	repositoryId: Schema.NullOr(Schema.Int),
+	/** When the delivery was throttled (wire `throttled_at`), when GitHub reports it. */
+	throttledAt: Schema.optionalKey(Schema.NullOr(Schema.String))
+}) {};
+/**
+* The app-level REST surface: the app's own record, its webhook delivery log
+* and redelivery, and uninstalling.
+*
+* @remarks
+* Provide {@link AuthenticatedApp.layer} over an App-JWT client from
+* {@link GitHubApp.appClientLayer}. This module imports no JWT signer: the
+* credential is the client's business, so a test drives it with any client.
+*
+* @example
+* ```ts
+* import { AuthenticatedApp, GitHubApp } from "@effected/github";
+* import { DateTime, Effect, Layer, Redacted, Stream } from "effect";
+*
+* // Redeliver every failed delivery from the last hour.
+* const sweep = Effect.gen(function* () {
+*   const app = yield* AuthenticatedApp;
+*   const since = DateTime.subtract(yield* DateTime.now, { hours: 1 });
+*   yield* app.deliveries({ status: "failure" }).pipe(
+*     Stream.takeWhile((delivery) => DateTime.isGreaterThan(DateTime.makeUnsafe(delivery.deliveredAt), since)),
+*     Stream.runForEach((delivery) => app.redeliver(delivery.id)),
+*   );
+* });
+*
+* const layer = AuthenticatedApp.layer.pipe(
+*   Layer.provide(
+*     GitHubApp.appClientLayer({
+*       appId: "12345",
+*       privateKey: Redacted.make("-----BEGIN RSA PRIVATE KEY-----\n..."),
+*     }),
+*   ),
+* );
+*
+* Effect.runPromise(Effect.provide(sweep, layer));
+* ```
+*
+* @public
+*/
+var AuthenticatedApp = class AuthenticatedApp extends Context.Service()("@effected/github/AuthenticatedApp") {
+	/** The live service, built over an App-JWT `GitHubClient`. */
+	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")),
+		deliveries: overrides.deliveries ?? (() => unstubbed("deliveries")),
+		delivery: overrides.delivery ?? (() => unstubbed("delivery")),
+		redeliver: overrides.redeliver ?? (() => unstubbed("redeliver")),
+		uninstall: overrides.uninstall ?? (() => unstubbed("uninstall"))
+	});
+	/** {@link AuthenticatedApp.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(AuthenticatedApp, AuthenticatedApp.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`AuthenticatedApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const decodeDelivery = Schema.decodeUnknownEffect(DeliveryAttempt);
+const decodeApp = Schema.decodeUnknownEffect(AppInfo);
+/** A nullable int64 id, narrowed like every other id. */
+const nullableId = (id) => id === null ? null : numericId(id);
+const deliveryOf = (operation, raw) => decodeDelivery(typeof raw !== "object" || raw === null ? raw : {
+	id: numericId(raw.id),
+	guid: raw.guid,
+	deliveredAt: raw.delivered_at,
+	redelivery: raw.redelivery,
+	duration: raw.duration,
+	status: raw.status,
+	statusCode: raw.status_code,
+	event: raw.event,
+	action: raw.action,
+	installationId: nullableId(raw.installation_id),
+	repositoryId: nullableId(raw.repository_id),
+	...raw.throttled_at !== void 0 ? { throttledAt: raw.throttled_at } : {}
+}).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(operation, "GitHub returned an unexpected webhook delivery", error))));
+const make = (client) => ({
+	get: Effect.fn("AuthenticatedApp.get")(function* () {
+		const app = yield* client.request("GET /app", {});
+		if (app === null) return yield* GitHubError.decode("AuthenticatedApp.get", "GET /app returned no app");
+		return yield* decodeApp({
+			id: numericId(app.id),
+			...app.slug !== void 0 ? { slug: app.slug } : {},
+			name: app.name,
+			nodeId: app.node_id,
+			...app.client_id !== void 0 ? { clientId: app.client_id } : {},
+			htmlUrl: app.html_url
+		}).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode("AuthenticatedApp.get", "GitHub returned an unexpected app", error))));
+	}),
+	deliveries: (options) => client.paginateStream("GET /app/hook/deliveries", options?.status !== void 0 ? { status: options.status } : {}, options?.page).pipe(Stream.mapEffect((raw) => deliveryOf("AuthenticatedApp.deliveries", raw))),
+	delivery: Effect.fn("AuthenticatedApp.delivery")(function* (deliveryId) {
+		yield* Effect.annotateCurrentSpan({ deliveryId });
+		const raw = yield* client.request("GET /app/hook/deliveries/{delivery_id}", { delivery_id: deliveryId });
+		return yield* deliveryOf("AuthenticatedApp.delivery", raw);
+	}),
+	redeliver: Effect.fn("AuthenticatedApp.redeliver")(function* (deliveryId) {
+		yield* Effect.annotateCurrentSpan({ deliveryId });
+		yield* client.request("POST /app/hook/deliveries/{delivery_id}/attempts", { delivery_id: deliveryId });
+	}),
+	uninstall: Effect.fn("AuthenticatedApp.uninstall")(function* (installationId) {
+		yield* Effect.annotateCurrentSpan({ installationId });
+		yield* client.request("DELETE /app/installations/{installation_id}", { installation_id: installationId });
+	})
+});
+
+//#endregion
+export { AppInfo, AuthenticatedApp, DeliveryAttempt };

package/CheckRun.js

@@ -15,6 +15,48 @@ const CheckConclusion = Schema.Literals([
 	"action_required",
 	"skipped"
 ]);
+/**
+* The phase of its lifecycle a check run is in, as GitHub reports it.
+*
+* @remarks
+* `"waiting"`, `"requested"` and `"pending"` are reserved for GitHub Actions
+* runs; an integrator can only write `"queued"`, `"in_progress"` and, through
+* {@link CheckRunShape.complete}, `"completed"`.
+*
+* @public
+*/
+const CheckRunStatus = Schema.Literals([
+	"queued",
+	"in_progress",
+	"completed",
+	"waiting",
+	"requested",
+	"pending"
+]);
+/**
+* How a check run finished, as GitHub reports it: every
+* {@link CheckConclusion} plus `"stale"`.
+*
+* @remarks
+* GitHub's check-run response schema omits `"stale"`, but its update
+* endpoint documents it: *"You cannot change a check run conclusion to
+* `stale`, only GitHub can set this."* GitHub sets it on a run left
+* incomplete too long, so a read that refused it would fail on any commit
+* carrying one. It is read-only, which is why {@link CheckConclusion}, the
+* write set, does not include it.
+*
+* @public
+*/
+const ReportedCheckConclusion = Schema.Literals([
+	"success",
+	"failure",
+	"neutral",
+	"cancelled",
+	"timed_out",
+	"action_required",
+	"skipped",
+	"stale"
+]);
 /** How serious an annotation is. @public */
 const AnnotationLevel = Schema.Literals([
 	"notice",
@@ -113,22 +155,76 @@ const capBytes = (value) => {
 	return `${cut}${CheckRunOutput.NOTICE}`;
 };
 /**
+* The rendered output a check run reports: its title and summary, and how
+* many annotations it carries.
+*
+* @remarks
+* The read-side counterpart of {@link CheckRunOutput}. It leaves out the
+* long-form `text` deliberately: it can run to 65535 bytes, and a caller
+* listing a commit's runs rarely wants it. Read the run's full output through
+* the typed request surface when you do.
+*
+* @public
+*/
+var ReportedCheckRunOutput = class extends Schema.Class("ReportedCheckRunOutput")({
+	/** The output's title; `null` when the run has none. */
+	title: Schema.NullOr(Schema.String),
+	/** The output's markdown summary; `null` when the run has none. */
+	summary: Schema.NullOr(Schema.String),
+	/** How many annotations the run carries (wire `annotations_count`). */
+	annotationsCount: Schema.Int
+}) {};
+/**
 * A check run as GitHub reports it.
 *
+* @remarks
+* Every field beyond the original five (the four required ones and
+* `externalId`) is optional, so a test double built with
+* `CheckRunRef.make({ id, name, url, status })` stays valid; a run decoded
+* from a GitHub response carries all of them, because GitHub always sends
+* them. A nullable field is `null` when GitHub reported `null`.
+*
+* **Three URLs, named apart.** `url` is the **web** URL (wire `html_url`, or
+* `""` when GitHub reported none), kept under that name so existing callers
+* read what they always read. `htmlUrl` is the same wire field with its
+* `null` preserved, `apiUrl` is the REST URL (wire `url`), and `detailsUrl`
+* is the integrator's own link (wire `details_url`).
+*
 * @public
 */
 var CheckRunRef = class extends Schema.Class("CheckRunRef")({
 	id: Schema.Int,
 	name: Schema.String,
-	/** The web URL. */
+	/** The web URL (wire `html_url`), or `""` when GitHub reported none. See also `htmlUrl`. */
 	url: Schema.String,
-	status: Schema.String,
+	/** The run's lifecycle phase. */
+	status: CheckRunStatus,
 	/**
 	* The integrator's own id for the run (wire `external_id`), when it has
 	* one. GitHub reports a run created without one as `null` or `""`; both
 	* leave this absent.
 	*/
-	externalId: Schema.optionalKey(Schema.String)
+	externalId: Schema.optionalKey(Schema.String),
+	/** The commit the run checks (wire `head_sha`). */
+	headSha: Schema.optionalKey(Schema.String),
+	/** The run's GraphQL node id (wire `node_id`). */
+	nodeId: Schema.optionalKey(Schema.String),
+	/** How the run finished; `null` until it completes. */
+	conclusion: Schema.optionalKey(Schema.NullOr(ReportedCheckConclusion)),
+	/** When the run started, as GitHub's ISO 8601 string; `null` for a run that has not. */
+	startedAt: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	/** When the run completed, as GitHub's ISO 8601 string; `null` for a run that has not. */
+	completedAt: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	/** The integrator's link for the run (wire `details_url`). */
+	detailsUrl: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	/** The web URL (wire `html_url`), `null` preserved. */
+	htmlUrl: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	/** The run's REST API URL (wire `url`). */
+	apiUrl: Schema.optionalKey(Schema.String),
+	/** The check suite the run belongs to (wire `check_suite.id`); `null` when GitHub reported none. */
+	checkSuiteId: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+	/** The run's title, summary and annotation count. */
+	output: Schema.optionalKey(ReportedCheckRunOutput)
 }) {};
 /**
 * Create, update and conclude GitHub check runs, including the
@@ -148,8 +244,11 @@ var CheckRun = class CheckRun extends Context.Service()("@effected/github/CheckR
 		create: overrides.create ?? (() => unstubbed("create")),
 		get: overrides.get ?? (() => unstubbed("get")),
 		update: overrides.update ?? (() => unstubbed("update")),
+		updateRef: overrides.updateRef ?? (() => unstubbed("updateRef")),
+		list: overrides.list ?? (() => unstubbed("list")),
 		findByExternalId: overrides.findByExternalId ?? (() => unstubbed("findByExternalId")),
 		complete: overrides.complete ?? (() => unstubbed("complete")),
+		completeRef: overrides.completeRef ?? (() => unstubbed("completeRef")),
 		withCheckRun: overrides.withCheckRun ?? (() => unstubbed("withCheckRun"))
 	});
 	/** {@link CheckRun.makeTest} behind a `Layer`. */
@@ -226,6 +325,19 @@ const concludeFor = (name, id, exit, recorded, complete) => {
 	return Exit.isSuccess(exit) ? write : Effect.ignore(write);
 };
 const decodeRef = Schema.decodeUnknownEffect(CheckRunRef);
+/** Whether a wire value is an object whose fields can be read. */
+const isRecord = (value) => typeof value === "object" && value !== null;
+/**
+* A nested wire object's fields, renamed for the schema, or the value itself
+* when it is not an object.
+*
+* @remarks
+* Handing the raw value through is what keeps a malformed response typed: a
+* `null` `output` (which GitHub's schema forbids) reaches the decoder and fails
+* as `decode` instead of throwing a `TypeError` while its fields are read,
+* which would be a defect escaping every `GitHubError` handler.
+*/
+const nested = (value, project) => isRecord(value) ? project(value) : value;
 /**
 * Project a check-run response onto {@link CheckRunRef}, **decoding** it.
 *
@@ -233,14 +345,30 @@ const decodeRef = Schema.decodeUnknownEffect(CheckRunRef);
 * Decoded rather than built with `make`, which throws: a response missing a
 * field (a hand-written double, or GitHub changing shape) is input, and input
 * failures are a typed `decode` `GitHubError` naming the operation rather than
-* a defect.
+* a defect. That includes a status or conclusion outside the literal sets:
+* GitHub adding one fails the read loudly instead of passing an unknown
+* string to a caller's exhaustive switch.
 */
-const refOf = (operation, raw) => decodeRef({
+const refOf = (operation, raw) => decodeRef(!isRecord(raw) ? raw : {
 	id: numericId(raw.id),
 	name: raw.name,
 	url: raw.html_url ?? "",
 	status: raw.status,
-	...raw.external_id ? { externalId: raw.external_id } : {}
+	...raw.external_id ? { externalId: raw.external_id } : {},
+	...raw.head_sha !== void 0 ? { headSha: raw.head_sha } : {},
+	...raw.node_id !== void 0 ? { nodeId: raw.node_id } : {},
+	...raw.conclusion !== void 0 ? { conclusion: raw.conclusion } : {},
+	...raw.started_at !== void 0 ? { startedAt: raw.started_at } : {},
+	...raw.completed_at !== void 0 ? { completedAt: raw.completed_at } : {},
+	...raw.details_url !== void 0 ? { detailsUrl: raw.details_url } : {},
+	...raw.html_url !== void 0 ? { htmlUrl: raw.html_url } : {},
+	...raw.url !== void 0 ? { apiUrl: raw.url } : {},
+	...raw.check_suite !== void 0 ? { checkSuiteId: nested(raw.check_suite, (suite) => typeof suite.id === "number" || typeof suite.id === "bigint" ? numericId(suite.id) : suite.id) } : {},
+	...raw.output !== void 0 ? { output: nested(raw.output, (output) => ({
+		title: output.title,
+		summary: output.summary,
+		annotationsCount: output.annotations_count
+	})) } : {}
 }).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(operation, "GitHub returned an unexpected check run", error))));
 /** The current time as GitHub's ISO 8601 timestamp, from `Clock` so `TestClock` drives it. */
 const isoNow = Effect.map(DateTime.now, DateTime.formatIso);
@@ -267,7 +395,17 @@ const make = (client) => {
 		});
 		return yield* refOf("CheckRun.create", created);
 	});
-	const complete = Effect.fn("CheckRun.complete")(function* (id, conclusion, output, options) {
+	/**
+	* The completing PATCH, answering GitHub's raw response.
+	*
+	* @remarks
+	* Shared by `complete`, which discards the response, and `completeRef`,
+	* which decodes it. Only the second can fail on an unexpected response:
+	* `complete` runs inside the bracket's finalizer, and a run GitHub has
+	* already concluded must not fail the program over a field it did not ask
+	* to read.
+	*/
+	const completePatch = (id, conclusion, output, options) => Effect.gen(function* () {
 		const { owner, repo } = yield* Repo;
 		yield* Effect.annotateCurrentSpan({
 			owner,
@@ -275,7 +413,7 @@ const make = (client) => {
 			id,
 			conclusion
 		});
-		yield* client.request("PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}", {
+		return yield* client.request("PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}", {
 			owner,
 			repo,
 			check_run_id: id,
@@ -286,6 +424,30 @@ const make = (client) => {
 			...options?.detailsUrl !== void 0 ? { details_url: options.detailsUrl } : {}
 		});
 	});
+	const complete = Effect.fn("CheckRun.complete")(function* (id, conclusion, output, options) {
+		yield* completePatch(id, conclusion, output, options);
+	});
+	const completeRef = Effect.fn("CheckRun.completeRef")(function* (id, conclusion, output, options) {
+		return yield* refOf("CheckRun.completeRef", yield* completePatch(id, conclusion, output, options));
+	});
+	/** The updating PATCH, answering GitHub's raw response; see `completePatch` for why it is shared. */
+	const updatePatch = (id, output, options) => Effect.gen(function* () {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			id
+		});
+		return yield* client.request("PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}", {
+			owner,
+			repo,
+			check_run_id: id,
+			...output !== void 0 ? { output: wireOutput(output) } : {},
+			...options?.status !== void 0 ? { status: options.status } : {},
+			...options?.status === "in_progress" ? { started_at: yield* isoNow } : {},
+			...options?.detailsUrl !== void 0 ? { details_url: options.detailsUrl } : {}
+		});
+	});
 	return {
 		create,
 		complete,
@@ -304,21 +466,29 @@ const make = (client) => {
 			return yield* refOf("CheckRun.get", raw);
 		}),
 		update: Effect.fn("CheckRun.update")(function* (id, output, options) {
+			yield* updatePatch(id, output, options);
+		}),
+		updateRef: Effect.fn("CheckRun.updateRef")(function* (id, output, options) {
+			return yield* refOf("CheckRun.updateRef", yield* updatePatch(id, output, options));
+		}),
+		completeRef,
+		list: Effect.fn("CheckRun.list")(function* (ref, options) {
 			const { owner, repo } = yield* Repo;
 			yield* Effect.annotateCurrentSpan({
 				owner,
 				repo,
-				id
+				ref
 			});
-			yield* client.request("PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}", {
+			const runs = yield* client.paginate("GET /repos/{owner}/{repo}/commits/{ref}/check-runs", {
 				owner,
 				repo,
-				check_run_id: id,
-				...output !== void 0 ? { output: wireOutput(output) } : {},
+				ref,
+				...options?.checkName !== void 0 ? { check_name: options.checkName } : {},
+				...options?.appId !== void 0 ? { app_id: options.appId } : {},
 				...options?.status !== void 0 ? { status: options.status } : {},
-				...options?.status === "in_progress" ? { started_at: yield* isoNow } : {},
-				...options?.detailsUrl !== void 0 ? { details_url: options.detailsUrl } : {}
-			});
+				...options?.filter !== void 0 ? { filter: options.filter } : {}
+			}, options?.page);
+			return yield* Effect.forEach(runs, (run) => refOf("CheckRun.list", run));
 		}),
 		findByExternalId: Effect.fn("CheckRun.findByExternalId")(function* (headSha, name, externalId) {
 			if (externalId === "") return Option.none();
@@ -357,4 +527,4 @@ const make = (client) => {
 };
 
 //#endregion
-export { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef };
+export { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CheckRunStatus, ReportedCheckConclusion, ReportedCheckRunOutput };

package/GitHubApp.js

@@ -4,7 +4,7 @@ import { GitHubClient, makeClientShape } from "./GitHubClient.js";
 import { numericId } from "./internal/ids.js";
 import { InstallationTokenStore } from "./InstallationTokenStore.js";
 import { Jwt, JwtKey } from "@effected/jwt";
-import { Cause, Clock, Context, DateTime, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
+import { Cause, Clock, Context, DateTime, Deferred, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
 
 //#region src/GitHubApp.ts
 /**
@@ -163,6 +163,21 @@ var AppIdentity = class extends Schema.Class("AppIdentity")({
 		});
 	}
 };
+/**
+* An app's bot user: the account its installation tokens act as.
+*
+* @remarks
+* `id` is what to compare against an actor id on an event, such as
+* `workflow_run.triggering_actor.id`: a login can be renamed, an id cannot.
+*
+* @public
+*/
+var BotUser = class extends Schema.Class("BotUser")({
+	/** The bot user's numeric id. */
+	id: Schema.Int,
+	/** The bot user's login, `<slug>[bot]`. */
+	login: Schema.String
+}) {};
 /** `suspended_at` as GitHub sends it: an ISO string, or `null` while active. */
 const SuspendedAt = Schema.OptionFromNullOr(Schema.DateTimeUtcFromString);
 /**
@@ -358,14 +373,23 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	* **A cached token is never revoked**: another scope or isolate may be using
 	* it. It expires on its own, within the hour.
 	*
-	* Two concurrent calls that both miss will both mint, and the later write
-	* wins. That is expected: the store may span isolates, so the kit cannot
-	* lock it, and an extra token costs one call and expires on its own.
+	* Within one process, concurrent misses for one installation are
+	* **single-flight**: the first caller mints and the others wait for that
+	* mint and return the same token with `source: "joined"`, so a batch that
+	* fans out over one installation on a cold store costs one mint, not one
+	* per fiber. The in-flight record lives with the `GitHubApp` service and is
+	* released when the mint settles, however it settles: a failed mint fails
+	* every waiter with the same `GitHubAppError`, and the next call mints
+	* again. Interrupting the leader does not strand the waiters: the mint runs
+	* in its own fiber and completes for them. Across isolates, two misses
+	* still both mint and the later write wins. That is expected: the store may
+	* span isolates, so the kit cannot lock it, and an extra token costs one
+	* call and expires on its own.
 	*
 	* The encoded value written to the store contains the raw token, so
 	* encrypting it at rest is the store's job.
 	*/
-	static cachedToken = (request) => cachedTokenFor(request);
+	static cachedToken = (request) => Effect.flatMap(GitHubApp, (app) => app.cachedToken(request));
 	/**
 	* A {@link GitHubClient} authenticated with {@link GitHubApp.cachedToken}.
 	*
@@ -407,18 +431,23 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	* Effect.runPromise(Effect.provide(handle(42), Live));
 	* ```
 	*/
-	static cachedClientLayer = (request, options = {}) => Layer.unwrap(Effect.map(cachedTokenFor(request), (cached) => GitHubClient.layerFromToken({
+	static cachedClientLayer = (request, options = {}) => Layer.unwrap(Effect.map(GitHubApp.cachedToken(request), (cached) => GitHubClient.layerFromToken({
 		...options,
 		token: cached.token.token
 	})));
 	/** An in-memory double; unstubbed members die naming themselves. */
-	static makeTest = (overrides = {}) => ({
-		token: overrides.token ?? (() => unstubbed("token")),
-		scopedToken: overrides.scopedToken ?? (() => unstubbed("scopedToken")),
-		revoke: overrides.revoke ?? (() => unstubbed("revoke")),
-		identity: overrides.identity ?? (() => unstubbed("identity")),
-		installations: overrides.installations ?? (() => unstubbed("installations"))
-	});
+	static makeTest = (overrides = {}) => {
+		const token = overrides.token ?? (() => unstubbed("token"));
+		return {
+			token,
+			scopedToken: overrides.scopedToken ?? (() => unstubbed("scopedToken")),
+			revoke: overrides.revoke ?? (() => unstubbed("revoke")),
+			identity: overrides.identity ?? (() => unstubbed("identity")),
+			botUser: overrides.botUser ?? (() => unstubbed("botUser")),
+			installations: overrides.installations ?? (() => unstubbed("installations")),
+			cachedToken: overrides.cachedToken ?? makeCachedToken(token)
+		};
+	};
 	/** {@link GitHubApp.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubApp, GitHubApp.makeTest(overrides));
 };
@@ -428,33 +457,64 @@ const DEFAULT_CACHE_MARGIN = Duration.minutes(5);
 const StoredToken = Schema.fromJsonString(InstallationToken);
 /** A store call that can never fail its caller: failures and defects become `fallback`; interruption propagates. */
 const swallowStore = (effect, fallback) => Effect.catchCause(effect, (cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.succeed(fallback));
-const cachedTokenFor = Effect.fn("GitHubApp.cachedToken")(function* (request) {
-	const input = request.margin ?? DEFAULT_CACHE_MARGIN;
-	const margin = typeof input === "number" && !Number.isFinite(input) ? Option.none() : Option.filter(Duration.fromInput(input), (duration) => Duration.isFinite(duration) && !Duration.isNegative(duration));
-	if (Option.isNone(margin)) return yield* GitHubAppError.of("token", "the cache margin must be a finite, non-negative duration");
-	const app = yield* GitHubApp;
-	const store = yield* InstallationTokenStore;
-	const stored = yield* swallowStore(store.get(request.installationId), Option.none());
-	if (Option.isSome(stored)) {
-		const decoded = yield* Effect.option(Schema.decodeUnknownEffect(StoredToken)(stored.value));
-		const now = yield* Clock.currentTimeMillis;
-		if (Option.isSome(decoded) && decoded.value.installationId === request.installationId && !decoded.value.isExpired(now, margin.value)) return {
-			token: decoded.value,
-			source: "cached"
+/**
+* The caching read over `token`, with one in-flight mint per installation.
+*
+* @remarks
+* The map is the single-flight record. A key is present exactly while a mint
+* for that installation is running in this process; the first miss creates it
+* and forks the mint, later misses await the same `Deferred`, and the mint's
+* exit finalizer deletes the key before completing the `Deferred` with
+* whatever exit the mint produced, so a failed mint fails every waiter with the
+* same error and never pins the key. The mint is forked detached from the
+* leader, so the leader being interrupted does not interrupt the mint the
+* waiters depend on; the leader itself just stops waiting. The key is the
+* installation id alone because that is also the store's key: a `TokenRequest`
+* cannot narrow a token, so two requests for one installation ask for the same
+* token.
+*/
+const makeCachedToken = (token) => {
+	const inFlight = /* @__PURE__ */ new Map();
+	return Effect.fn("GitHubApp.cachedToken")(function* (request) {
+		const input = request.margin ?? DEFAULT_CACHE_MARGIN;
+		const margin = typeof input === "number" && !Number.isFinite(input) ? Option.none() : Option.filter(Duration.fromInput(input), (duration) => Duration.isFinite(duration) && !Duration.isNegative(duration));
+		if (Option.isNone(margin)) return yield* GitHubAppError.of("token", "the cache margin must be a finite, non-negative duration");
+		const store = yield* InstallationTokenStore;
+		const stored = yield* swallowStore(store.get(request.installationId), Option.none());
+		if (Option.isSome(stored)) {
+			const decoded = yield* Effect.option(Schema.decodeUnknownEffect(StoredToken)(stored.value));
+			const now = yield* Clock.currentTimeMillis;
+			if (Option.isSome(decoded) && decoded.value.installationId === request.installationId && !decoded.value.isExpired(now, margin.value)) return {
+				token: decoded.value,
+				source: "cached"
+			};
+		}
+		const joined = inFlight.get(request.installationId);
+		if (joined !== void 0) return {
+			token: yield* Deferred.await(joined),
+			source: "joined"
 		};
-	}
-	const minted = yield* app.token(request);
-	const now = yield* Clock.currentTimeMillis;
-	const ttlMillis = DateTime.toEpochMillis(minted.expiresAt) - Duration.toMillis(margin.value) - now;
-	if (ttlMillis > 0) {
-		const encoded = yield* Effect.option(Schema.encodeUnknownEffect(StoredToken)(minted));
-		if (Option.isSome(encoded)) yield* swallowStore(store.set(request.installationId, encoded.value, Duration.millis(ttlMillis)), void 0);
-	}
-	return {
-		token: minted,
-		source: "minted"
-	};
-});
+		const deferred = Deferred.makeUnsafe();
+		const mint = Effect.gen(function* () {
+			const minted = yield* token(request);
+			const now = yield* Clock.currentTimeMillis;
+			const ttlMillis = DateTime.toEpochMillis(minted.expiresAt) - Duration.toMillis(margin.value) - now;
+			if (ttlMillis > 0) {
+				const encoded = yield* Effect.option(Schema.encodeUnknownEffect(StoredToken)(minted));
+				if (Option.isSome(encoded)) yield* swallowStore(store.set(request.installationId, encoded.value, Duration.millis(ttlMillis)), void 0);
+			}
+			return minted;
+		}).pipe(Effect.onExit((exit) => Effect.andThen(Effect.sync(() => inFlight.delete(request.installationId)), Deferred.done(deferred, exit))));
+		yield* Effect.uninterruptible(Effect.suspend(() => {
+			inFlight.set(request.installationId, deferred);
+			return Effect.forkDetach(mint);
+		}));
+		return {
+			token: yield* Deferred.await(deferred),
+			source: "minted"
+		};
+	});
+};
 const unstubbed = (member) => {
 	throw new Error(`GitHubApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
 };
@@ -541,7 +601,17 @@ function makeApp(options) {
 					...Option.isSome(user) ? { userId: numericId(user.value.id) } : {}
 				});
 			}),
-			installations
+			botUser: Effect.fn("GitHubApp.botUser")(function* (request) {
+				yield* Effect.annotateCurrentSpan({ slug: request.slug });
+				const user = yield* (yield* asBearer(request.installationToken, options)).request("GET /users/{username}", { username: `${request.slug}[bot]` }).pipe(Effect.catch(appFailure("identity")));
+				const raw = user;
+				return yield* Schema.decodeUnknownEffect(BotUser)(typeof raw === "object" && raw !== null ? {
+					id: numericId(user.id),
+					login: user.login
+				} : raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubAppError.of("identity", "GitHub returned an unexpected bot user", error))));
+			}),
+			installations,
+			cachedToken: makeCachedToken(token)
 		};
 	});
 }
@@ -614,4 +684,4 @@ const makeRotatingClient = (mint, release, options, operation) => Effect.gen(fun
 });
 
 //#endregion
-export { AppIdentity, BotIdentity, GitHubApp, GitHubAppError, Installation, InstallationToken };
+export { AppIdentity, BotIdentity, BotUser, GitHubApp, GitHubAppError, Installation, InstallationToken };

package/index.d.ts

@@ -1303,9 +1303,230 @@ export declare class Attestation extends Attestation_base {
   static readonly layerTest: (overrides?: Partial<AttestationShape>) => Layer.Layer<Attestation>;
 }
 //#endregion
+//#region src/AuthenticatedApp.d.ts
+declare const AppInfo_base: Schema.Class<AppInfo, Schema.Struct<{
+  /** The app's numeric id. */
+  readonly id: Schema.Int;
+  /**
+   * The URL slug, e.g. `"my-app"`; the app's bot user is `<slug>[bot]`.
+   *
+   * @remarks
+   * Optional because GitHub's schema for an app declares it optional; the
+   * authenticated app's own read is where you would expect it.
+   */
+  readonly slug: Schema.optionalKey<Schema.String>;
+  /** The display name. */
+  readonly name: Schema.String;
+  /** The app's GraphQL node id (wire `node_id`). */
+  readonly nodeId: Schema.String;
+  /** The app's OAuth client id (wire `client_id`), when GitHub reports one. */
+  readonly clientId: Schema.optionalKey<Schema.String>;
+  /** The app's page on GitHub (wire `html_url`). */
+  readonly htmlUrl: Schema.String;
+}>, {}>;
+/**
+ * The GitHub App itself, as `GET /app` reports it.
+ *
+ * @public
+ */
+export declare class AppInfo extends AppInfo_base {}
+declare const DeliveryAttempt_base: Schema.Class<DeliveryAttempt, Schema.Struct<{
+  /** The delivery's id; pass it to {@link AuthenticatedAppShape.redeliver}. */
+  readonly id: Schema.Int;
+  /**
+   * The event's GUID (the `X-GitHub-Delivery` header). Shared by a delivery
+   * and all its redeliveries, so it identifies the event; `id` identifies
+   * the attempt.
+   */
+  readonly guid: Schema.String;
+  /** When it was delivered, as GitHub's ISO 8601 string (wire `delivered_at`). */
+  readonly deliveredAt: Schema.String;
+  /** Whether this attempt was a redelivery. */
+  readonly redelivery: Schema.Boolean;
+  /** How long the delivery took, in seconds. */
+  readonly duration: Schema.Number;
+  /** GitHub's description of the outcome, e.g. `"OK"`. */
+  readonly status: Schema.String;
+  /** The HTTP status your endpoint answered (wire `status_code`); `0` when it never answered. */
+  readonly statusCode: Schema.Int;
+  /** The event, e.g. `"workflow_run"`. */
+  readonly event: Schema.String;
+  /** The event's action, e.g. `"completed"`; `null` for an event without one. */
+  readonly action: Schema.NullOr<Schema.String>;
+  /** The installation the event concerns (wire `installation_id`); `null` for none. */
+  readonly installationId: Schema.NullOr<Schema.Int>;
+  /** The repository the event concerns (wire `repository_id`); `null` for none. */
+  readonly repositoryId: Schema.NullOr<Schema.Int>;
+  /** When the delivery was throttled (wire `throttled_at`), when GitHub reports it. */
+  readonly throttledAt: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>, {}>;
+/**
+ * One delivery of the app's webhook, as `GET /app/hook/deliveries` lists it.
+ *
+ * @remarks
+ * **Ids are numbers, and refuse to lose precision.** GitHub types a delivery
+ * id (and an installation or repository id) as int64, and octokit as
+ * `number | bigint`. A response body arrives through `JSON.parse`, which
+ * never produces a bigint: an id beyond 2^53 would already have been rounded.
+ * Every id here is decoded as a **safe** integer, so such an id fails the read
+ * with a typed `decode` error instead of handing back a rounded id that names
+ * a different delivery. Today's ids are many orders of magnitude below that
+ * line.
+ *
+ * Encodable: every field is a JSON primitive, so a delivery can be stored as
+ * it is.
+ *
+ * @public
+ */
+export declare class DeliveryAttempt extends DeliveryAttempt_base {}
+/**
+ * Options for {@link AuthenticatedAppShape.deliveries}.
+ *
+ * @public
+ */
+interface DeliveriesOptions {
+  /**
+   * Only deliveries that succeeded or failed, filtered by GitHub. A delivery
+   * is a failure when your endpoint did not answer with a 2xx.
+   */
+  readonly status?: "success" | "failure" | undefined;
+  /** How far to page. Unset, pages of 100 until GitHub stops. */
+  readonly page?: PageOptions | undefined;
+}
+/**
+ * The app-level REST surface: the app's own record, its webhook deliveries and
+ * removing an installation.
+ *
+ * @remarks
+ * Every member needs a `GitHubClient` authenticated **as the app** (an App
+ * JWT), which is what {@link GitHubApp.appClientLayer} provides; an
+ * installation token answers these routes with 401. No member needs a `Repo`.
+ *
+ * @public
+ */
+interface AuthenticatedAppShape {
+  /** The app itself (`GET /app`). */
+  readonly get: () => Effect.Effect<AppInfo, GitHubError>;
+  /**
+   * The app's webhook deliveries, newest first (`GET /app/hook/deliveries`).
+   *
+   * @remarks
+   * **Lazy in requests**: a page is fetched only when the stream is pulled
+   * past the previous one, so `Stream.takeWhile` on `deliveredAt` stops a
+   * sweep at the window's edge without reading the rest of the log. GitHub
+   * pages this route by cursor; the walk follows its `Link` header.
+   *
+   * Each delivery is decoded as it arrives; a malformed one fails the stream
+   * with a `decode` `GitHubError`.
+   */
+  readonly deliveries: (options?: DeliveriesOptions) => Stream.Stream<DeliveryAttempt, GitHubError>;
+  /**
+   * One delivery attempt (`GET /app/hook/deliveries/{delivery_id}`).
+   *
+   * @remarks
+   * Projected onto the same {@link DeliveryAttempt} the listing answers; the
+   * request and response payloads GitHub also returns are not kept. Read them
+   * through the typed request surface when you need them.
+   */
+  readonly delivery: (deliveryId: number) => Effect.Effect<DeliveryAttempt, GitHubError>;
+  /**
+   * Ask GitHub to deliver an attempt's event again
+   * (`POST /app/hook/deliveries/{delivery_id}/attempts`).
+   *
+   * @remarks
+   * GitHub answers 202: the redelivery is queued, not done, and appears in
+   * {@link AuthenticatedAppShape.deliveries} as a new attempt with the same
+   * `guid` and `redelivery: true`.
+   */
+  readonly redeliver: (deliveryId: number) => Effect.Effect<void, GitHubError>;
+  /**
+   * Uninstall the app from an account
+   * (`DELETE /app/installations/{installation_id}`).
+   *
+   * @remarks
+   * Irreversible from the app's side: only the account can install it again.
+   * An installation that does not exist (or is already gone) fails with
+   * `GitHubError { kind: "notFound" }`.
+   */
+  readonly uninstall: (installationId: number) => Effect.Effect<void, GitHubError>;
+}
+declare const AuthenticatedApp_base: Context.ServiceClass<AuthenticatedApp, "@effected/github/AuthenticatedApp", AuthenticatedAppShape>;
+/**
+ * The app-level REST surface: the app's own record, its webhook delivery log
+ * and redelivery, and uninstalling.
+ *
+ * @remarks
+ * Provide {@link AuthenticatedApp.layer} over an App-JWT client from
+ * {@link GitHubApp.appClientLayer}. This module imports no JWT signer: the
+ * credential is the client's business, so a test drives it with any client.
+ *
+ * @example
+ * ```ts
+ * import { AuthenticatedApp, GitHubApp } from "@effected/github";
+ * import { DateTime, Effect, Layer, Redacted, Stream } from "effect";
+ *
+ * // Redeliver every failed delivery from the last hour.
+ * const sweep = Effect.gen(function* () {
+ *   const app = yield* AuthenticatedApp;
+ *   const since = DateTime.subtract(yield* DateTime.now, { hours: 1 });
+ *   yield* app.deliveries({ status: "failure" }).pipe(
+ *     Stream.takeWhile((delivery) => DateTime.isGreaterThan(DateTime.makeUnsafe(delivery.deliveredAt), since)),
+ *     Stream.runForEach((delivery) => app.redeliver(delivery.id)),
+ *   );
+ * });
+ *
+ * const layer = AuthenticatedApp.layer.pipe(
+ *   Layer.provide(
+ *     GitHubApp.appClientLayer({
+ *       appId: "12345",
+ *       privateKey: Redacted.make("-----BEGIN RSA PRIVATE KEY-----\n..."),
+ *     }),
+ *   ),
+ * );
+ *
+ * Effect.runPromise(Effect.provide(sweep, layer));
+ * ```
+ *
+ * @public
+ */
+export declare class AuthenticatedApp extends AuthenticatedApp_base {
+  /** The live service, built over an App-JWT `GitHubClient`. */
+  static readonly layer: Layer.Layer<AuthenticatedApp, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<AuthenticatedAppShape>) => AuthenticatedAppShape;
+  /** {@link AuthenticatedApp.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<AuthenticatedAppShape>) => Layer.Layer<AuthenticatedApp>;
+}
+//#endregion
 //#region src/CheckRun.d.ts
 /** How a check run finished. @public */
 export declare const CheckConclusion: Schema.Literals<readonly ["success", "failure", "neutral", "cancelled", "timed_out", "action_required", "skipped"]>;
+/**
+ * The phase of its lifecycle a check run is in, as GitHub reports it.
+ *
+ * @remarks
+ * `"waiting"`, `"requested"` and `"pending"` are reserved for GitHub Actions
+ * runs; an integrator can only write `"queued"`, `"in_progress"` and, through
+ * {@link CheckRunShape.complete}, `"completed"`.
+ *
+ * @public
+ */
+export declare const CheckRunStatus: Schema.Literals<readonly ["queued", "in_progress", "completed", "waiting", "requested", "pending"]>;
+/**
+ * How a check run finished, as GitHub reports it: every
+ * {@link CheckConclusion} plus `"stale"`.
+ *
+ * @remarks
+ * GitHub's check-run response schema omits `"stale"`, but its update
+ * endpoint documents it: *"You cannot change a check run conclusion to
+ * `stale`, only GitHub can set this."* GitHub sets it on a run left
+ * incomplete too long, so a read that refused it would fail on any commit
+ * carrying one. It is read-only, which is why {@link CheckConclusion}, the
+ * write set, does not include it.
+ *
+ * @public
+ */
+export declare const ReportedCheckConclusion: Schema.Literals<readonly ["success", "failure", "neutral", "cancelled", "timed_out", "action_required", "skipped", "stale"]>;
 /** How serious an annotation is. @public */
 export declare const AnnotationLevel: Schema.Literals<readonly ["notice", "warning", "failure"]>;
 declare const Annotation_base: Schema.Class<Annotation, Schema.Struct<{
@@ -1363,22 +1584,77 @@ export declare class CheckRunOutput extends CheckRunOutput_base {
    */
   truncated(): CheckRunOutput;
 }
+declare const ReportedCheckRunOutput_base: Schema.Class<ReportedCheckRunOutput, Schema.Struct<{
+  /** The output's title; `null` when the run has none. */
+  readonly title: Schema.NullOr<Schema.String>;
+  /** The output's markdown summary; `null` when the run has none. */
+  readonly summary: Schema.NullOr<Schema.String>;
+  /** How many annotations the run carries (wire `annotations_count`). */
+  readonly annotationsCount: Schema.Int;
+}>, {}>;
+/**
+ * The rendered output a check run reports: its title and summary, and how
+ * many annotations it carries.
+ *
+ * @remarks
+ * The read-side counterpart of {@link CheckRunOutput}. It leaves out the
+ * long-form `text` deliberately: it can run to 65535 bytes, and a caller
+ * listing a commit's runs rarely wants it. Read the run's full output through
+ * the typed request surface when you do.
+ *
+ * @public
+ */
+export declare class ReportedCheckRunOutput extends ReportedCheckRunOutput_base {}
 declare const CheckRunRef_base: Schema.Class<CheckRunRef, Schema.Struct<{
   readonly id: Schema.Int;
   readonly name: Schema.String;
-  /** The web URL. */
+  /** The web URL (wire `html_url`), or `""` when GitHub reported none. See also `htmlUrl`. */
   readonly url: Schema.String;
-  readonly status: Schema.String;
+  /** The run's lifecycle phase. */
+  readonly status: Schema.Literals<readonly ["queued", "in_progress", "completed", "waiting", "requested", "pending"]>;
   /**
    * The integrator's own id for the run (wire `external_id`), when it has
    * one. GitHub reports a run created without one as `null` or `""`; both
    * leave this absent.
    */
   readonly externalId: Schema.optionalKey<Schema.String>;
+  /** The commit the run checks (wire `head_sha`). */
+  readonly headSha: Schema.optionalKey<Schema.String>;
+  /** The run's GraphQL node id (wire `node_id`). */
+  readonly nodeId: Schema.optionalKey<Schema.String>;
+  /** How the run finished; `null` until it completes. */
+  readonly conclusion: Schema.optionalKey<Schema.NullOr<Schema.Literals<readonly ["success", "failure", "neutral", "cancelled", "timed_out", "action_required", "skipped", "stale"]>>>;
+  /** When the run started, as GitHub's ISO 8601 string; `null` for a run that has not. */
+  readonly startedAt: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+  /** When the run completed, as GitHub's ISO 8601 string; `null` for a run that has not. */
+  readonly completedAt: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+  /** The integrator's link for the run (wire `details_url`). */
+  readonly detailsUrl: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+  /** The web URL (wire `html_url`), `null` preserved. */
+  readonly htmlUrl: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+  /** The run's REST API URL (wire `url`). */
+  readonly apiUrl: Schema.optionalKey<Schema.String>;
+  /** The check suite the run belongs to (wire `check_suite.id`); `null` when GitHub reported none. */
+  readonly checkSuiteId: Schema.optionalKey<Schema.NullOr<Schema.Int>>;
+  /** The run's title, summary and annotation count. */
+  readonly output: Schema.optionalKey<typeof ReportedCheckRunOutput>;
 }>, {}>;
 /**
  * A check run as GitHub reports it.
  *
+ * @remarks
+ * Every field beyond the original five (the four required ones and
+ * `externalId`) is optional, so a test double built with
+ * `CheckRunRef.make({ id, name, url, status })` stays valid; a run decoded
+ * from a GitHub response carries all of them, because GitHub always sends
+ * them. A nullable field is `null` when GitHub reported `null`.
+ *
+ * **Three URLs, named apart.** `url` is the **web** URL (wire `html_url`, or
+ * `""` when GitHub reported none), kept under that name so existing callers
+ * read what they always read. `htmlUrl` is the same wire field with its
+ * `null` preserved, `apiUrl` is the REST URL (wire `url`), and `detailsUrl`
+ * is the integrator's own link (wire `details_url`).
+ *
  * @public
  */
 export declare class CheckRunRef extends CheckRunRef_base {}
@@ -1419,6 +1695,29 @@ interface UpdateCheckRunOptions {
   /** Where the integrator's full details live (wire `details_url`). */
   readonly detailsUrl?: string | undefined;
 }
+/**
+ * Options for {@link CheckRunShape.list}.
+ *
+ * @public
+ */
+interface ListCheckRunsOptions {
+  /** Only runs with this name (wire `check_name`). */
+  readonly checkName?: string | undefined;
+  /** Only runs created by this GitHub App (wire `app_id`). */
+  readonly appId?: number | undefined;
+  /**
+   * Only runs in this phase. GitHub filters on these three only; the
+   * Actions-reserved phases are not a filter it accepts.
+   */
+  readonly status?: "queued" | "in_progress" | "completed" | undefined;
+  /**
+   * `"latest"` (GitHub's default) answers only the newest run per name;
+   * `"all"` answers every run, re-runs included.
+   */
+  readonly filter?: "latest" | "all" | undefined;
+  /** How far to page. Unset, every page is read, 100 runs at a time. */
+  readonly page?: PageOptions | undefined;
+}
 /**
  * Options for {@link CheckRunShape.complete}.
  *
@@ -1480,6 +1779,28 @@ interface CheckRunShape {
    * handling sees a missing run or a revoked token the same way either way.
    */
   readonly update: (id: number, output?: CheckRunOutput, options?: UpdateCheckRunOptions) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * {@link CheckRunShape.update}, answering the run as GitHub reports it
+   * after the PATCH.
+   *
+   * @remarks
+   * The same single request, with the same omission rules; the difference is
+   * only that GitHub's response is decoded into a {@link CheckRunRef} rather
+   * than discarded. A separate member rather than a new return type on
+   * `update`, so a test double that stubs `update` with `Effect.void` keeps
+   * compiling.
+   */
+  readonly updateRef: (id: number, output?: CheckRunOutput, options?: UpdateCheckRunOptions) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
+  /**
+   * The check runs on a commit, newest per name unless `options.filter` is
+   * `"all"`.
+   *
+   * @remarks
+   * `ref` is a commit SHA, a branch name or a tag name. Every page is read
+   * unless `options.page` bounds the walk, so a filter that matches past
+   * page one is still answered in full.
+   */
+  readonly list: (ref: string, options?: ListCheckRunsOptions) => Effect.Effect<ReadonlyArray<CheckRunRef>, GitHubError, Repo>;
   /**
    * The newest run on `headSha` named `name` whose external id is
    * `externalId`; none when there is no such run.
@@ -1504,6 +1825,17 @@ interface CheckRunShape {
    * workflow run that produced it.
    */
   readonly complete: (id: number, conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput, options?: CompleteCheckRunOptions) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * {@link CheckRunShape.complete}, answering the finished run as GitHub
+   * reports it after the PATCH.
+   *
+   * @remarks
+   * The same single request, with the same `completed_at` stamp and output
+   * byte cap; GitHub's response is decoded into a {@link CheckRunRef} rather
+   * than discarded. A separate member for the same reason as
+   * {@link CheckRunShape.updateRef}.
+   */
+  readonly completeRef: (id: number, conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput, options?: CompleteCheckRunOptions) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
   /**
    * Run `use` inside a check run, concluding it however `use` exits.
    *
@@ -2142,8 +2474,17 @@ interface CachedTokenRequest extends TokenRequest {
 interface CachedToken {
   /** The token. */
   readonly token: InstallationToken;
-  /** `"cached"` when it was read from the store, `"minted"` when GitHub issued it just now. */
-  readonly source: "cached" | "minted";
+  /**
+   * `"cached"` when it was read from the store, `"minted"` when GitHub
+   * issued it to this call just now, `"joined"` when this call missed the
+   * store but another call in the same process was already minting for the
+   * installation and this one took that token instead of minting its own.
+   *
+   * @remarks
+   * A `"joined"` token is as fresh as a `"minted"` one; the label exists so
+   * a caller counting mints against GitHub can tell the two apart.
+   */
+  readonly source: "cached" | "minted" | "joined";
 }
 declare const InstallationToken_base: Schema.Class<InstallationToken, Schema.Struct<{
   /** The token. Decodes to `Redacted`, encodes back to the raw string. */
@@ -2243,6 +2584,37 @@ export declare class AppIdentity extends AppIdentity_base {
   /** The committer identity for this app. */
   botIdentity(): BotIdentity;
 }
+declare const BotUser_base: Schema.Class<BotUser, Schema.Struct<{
+  /** The bot user's numeric id. */
+  readonly id: Schema.Int;
+  /** The bot user's login, `<slug>[bot]`. */
+  readonly login: Schema.String;
+}>, {}>;
+/**
+ * An app's bot user: the account its installation tokens act as.
+ *
+ * @remarks
+ * `id` is what to compare against an actor id on an event, such as
+ * `workflow_run.triggering_actor.id`: a login can be renamed, an id cannot.
+ *
+ * @public
+ */
+export declare class BotUser extends BotUser_base {}
+/**
+ * What {@link GitHubAppShape.botUser} looks up.
+ *
+ * @public
+ */
+interface BotUserRequest {
+  /** The app's slug; the bot user is `<slug>[bot]`. */
+  readonly slug: string;
+  /**
+   * An installation token to authenticate the lookup with. Without one the
+   * lookup runs unauthenticated, at GitHub's 60-requests-per-hour-per-IP
+   * limit: `GET /users/{username}` rejects an App JWT.
+   */
+  readonly installationToken?: Redacted.Redacted<string> | undefined;
+}
 declare const Installation_base: Schema.Class<Installation, Schema.Struct<{
   /** The installation id, which is what a token is minted against. */
   readonly id: Schema.Int;
@@ -2440,9 +2812,18 @@ export declare class GitHubApp extends GitHubApp_base {
    * **A cached token is never revoked**: another scope or isolate may be using
    * it. It expires on its own, within the hour.
    *
-   * Two concurrent calls that both miss will both mint, and the later write
-   * wins. That is expected: the store may span isolates, so the kit cannot
-   * lock it, and an extra token costs one call and expires on its own.
+   * Within one process, concurrent misses for one installation are
+   * **single-flight**: the first caller mints and the others wait for that
+   * mint and return the same token with `source: "joined"`, so a batch that
+   * fans out over one installation on a cold store costs one mint, not one
+   * per fiber. The in-flight record lives with the `GitHubApp` service and is
+   * released when the mint settles, however it settles: a failed mint fails
+   * every waiter with the same `GitHubAppError`, and the next call mints
+   * again. Interrupting the leader does not strand the waiters: the mint runs
+   * in its own fiber and completes for them. Across isolates, two misses
+   * still both mint and the later write wins. That is expected: the store may
+   * span isolates, so the kit cannot lock it, and an extra token costs one
+   * call and expires on its own.
    *
    * The encoded value written to the store contains the raw token, so
    * encrypting it at rest is the store's job.
@@ -2536,8 +2917,32 @@ interface GitHubAppShape {
   readonly identity: (request: AppCredentials & {
     readonly installationToken?: Redacted.Redacted<string> | undefined;
   }) => Effect.Effect<AppIdentity, GitHubAppError>;
+  /**
+   * The app's bot user, `GET /users/{slug}[bot]`.
+   *
+   * @remarks
+   * Unlike {@link GitHubAppShape.identity}, which treats the bot user as
+   * optional enrichment and omits it when the lookup fails, this fails with
+   * `kind: "identity"` — for a caller that authorizes on the bot's id, a
+   * missing id is an error, not a degraded answer. Get the slug from
+   * `identity` or from `AuthenticatedApp.get`.
+   */
+  readonly botUser: (request: BotUserRequest) => Effect.Effect<BotUser, GitHubAppError>;
   /** Every installation of the app. */
   readonly installations: (credentials: AppCredentials) => Effect.Effect<ReadonlyArray<Installation>, GitHubAppError>;
+  /**
+   * An installation token, reused from the {@link InstallationTokenStore}
+   * while it has `margin` left to live; {@link GitHubApp.cachedToken} is this
+   * member on the provided service.
+   *
+   * @remarks
+   * A member rather than a free function because the in-process
+   * single-flight record for concurrent misses lives with the service: it is
+   * created with the layer and shared by every call through it.
+   * {@link GitHubApp.makeTest} builds it over the double's `token`, so a test
+   * that stubs `token` gets the real caching and single-flight behaviour.
+   */
+  readonly cachedToken: (request: CachedTokenRequest) => Effect.Effect<CachedToken, GitHubAppError, InstallationTokenStore>;
 }
 //#endregion
 //#region src/GitHubCommit.d.ts
@@ -4426,5 +4831,5 @@ export declare class WorkflowDispatch extends WorkflowDispatch_base {
   static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
 }
 //#endregion
-export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ArtifactMetadataShape, type AttestationShape, type BareLineReference, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, type GitBranchShape, type GitCommitShape, type GitHubAppOptions, type GitHubAppShape, type GitHubClientOptions, type GitHubClientShape, type GitHubCommitShape, type GitHubContentShape, type GitHubIssueShape, type GitHubReleaseShape, type GitHubRepositoryShape, type GitTagShape, type InstallationTokenStoreShape, type IssueReference, type LatestSemverOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositorySecretShape, type RepositorySecurityShape, type RepositorySettings, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, type RetryableFailure, type RulesetInfo, type RulesetPayload, type RulesetShape, type SecretInfo, type SecretScope, type TokenRequest, type UpdateCheckRunOptions, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, type WorkflowDispatchShape, type WorkflowInfo, harvestIssueReferences, parseBareLineReference };
+export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ArtifactMetadataShape, type AttestationShape, type AuthenticatedAppShape, type BareLineReference, type BotUserRequest, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeliveriesOptions, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, type GitBranchShape, type GitCommitShape, type GitHubAppOptions, type GitHubAppShape, type GitHubClientOptions, type GitHubClientShape, type GitHubCommitShape, type GitHubContentShape, type GitHubIssueShape, type GitHubReleaseShape, type GitHubRepositoryShape, type GitTagShape, type InstallationTokenStoreShape, type IssueReference, type LatestSemverOptions, type ListCheckRunsOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositorySecretShape, type RepositorySecurityShape, type RepositorySettings, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, type RetryableFailure, type RulesetInfo, type RulesetPayload, type RulesetShape, type SecretInfo, type SecretScope, type TokenRequest, type UpdateCheckRunOptions, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, type WorkflowDispatchShape, type WorkflowInfo, harvestIssueReferences, parseBareLineReference };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -6,13 +6,14 @@ import { GitHubClient, GitHubFixtures, RawFailure } from "./GitHubClient.js";
 import { InvalidRepoRefError, Repo, RepoRef } from "./Repo.js";
 import { ArtifactMetadata, StorageRecordInput } from "./ArtifactMetadata.js";
 import { Attestation, AttestationListEntry, AttestationRecord } from "./Attestation.js";
-import { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef } from "./CheckRun.js";
+import { AppInfo, AuthenticatedApp, DeliveryAttempt } from "./AuthenticatedApp.js";
+import { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CheckRunStatus, ReportedCheckConclusion, ReportedCheckRunOutput } from "./CheckRun.js";
 import { CodeScanning } from "./CodeScanning.js";
 import { DeploymentEnvironment } from "./DeploymentEnvironment.js";
 import { GitBranch } from "./GitBranch.js";
 import { CommitRef, FileChange, FileContent, FileDeletion, FileMode, GitCommit } from "./GitCommit.js";
 import { InstallationTokenStore } from "./InstallationTokenStore.js";
-import { AppIdentity, BotIdentity, GitHubApp, GitHubAppError, Installation, InstallationToken } from "./GitHubApp.js";
+import { AppIdentity, BotIdentity, BotUser, GitHubApp, GitHubAppError, Installation, InstallationToken } from "./GitHubApp.js";
 import { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit } from "./GitHubCommit.js";
 import { GitHubContent } from "./GitHubContent.js";
 import { CommentMarker, CommentRecord, PullRequestComment } from "./PullRequestComment.js";
@@ -30,4 +31,4 @@ import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, Toke
 import { DispatchedRun, WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
 import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
 
-export { ActionsOidc, ActionsOidcClaims, Annotation, AnnotationLevel, AppIdentity, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, BotIdentity, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, DeploymentEnvironment, DispatchedRun, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubFixtures, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InstallationTokenStore, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, RawFailure, ReleaseAsset, ReleaseInfo, Repo, RepoRef, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, repositoryPatch, transformSecurityAndAnalysis, versionFromTag };
+export { ActionsOidc, ActionsOidcClaims, Annotation, AnnotationLevel, AppIdentity, AppInfo, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, AuthenticatedApp, BotIdentity, BotUser, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CheckRunStatus, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, DeliveryAttempt, DeploymentEnvironment, DispatchedRun, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubFixtures, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InstallationTokenStore, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, RawFailure, ReleaseAsset, ReleaseInfo, Repo, RepoRef, ReportedCheckConclusion, ReportedCheckRunOutput, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, repositoryPatch, transformSecurityAndAnalysis, versionFromTag };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.17.0",
+	"version": "0.19.0",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -38,9 +38,9 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/github-references": "^0.7.0",
-		"@effected/jwt": "^0.1.0",
-		"@effected/semver": "^0.11.0",
+		"@effected/github-references": "^0.8.0",
+		"@effected/jwt": "^0.2.0",
+		"@effected/semver": "^0.12.0",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^16.0.0",
 		"@octokit/types": "^18.0.0",