@effected/github 0.16.0 → 0.18.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

@@ -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);
 /**
@@ -417,6 +432,7 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 		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"))
 	});
 	/** {@link GitHubApp.makeTest} behind a `Layer`. */
@@ -541,6 +557,15 @@ function makeApp(options) {
 					...Option.isSome(user) ? { userId: numericId(user.value.id) } : {}
 				});
 			}),
+			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
 		};
 	});
@@ -614,4 +639,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/WorkflowDispatch.js

@@ -26,6 +26,24 @@ var WorkflowRunStatus = class extends Schema.Class("WorkflowRunStatus")({
 		return this.status === "completed";
 	}
 };
+/**
+* The run a `workflow_dispatch` created, as GitHub reports it when asked.
+*
+* @remarks
+* Returned by {@link WorkflowDispatchShape.dispatchWithRun}. `runId` is usable
+* directly with {@link WorkflowDispatchShape.runStatus} and
+* {@link WorkflowDispatchShape.cancelRun}.
+*
+* @public
+*/
+var DispatchedRun = class extends Schema.Class("DispatchedRun")({
+	/** The created run's numeric id. */
+	runId: Schema.Int,
+	/** The run's API URL. */
+	runUrl: Schema.String,
+	/** The run's web URL. */
+	htmlUrl: Schema.String
+}) {};
 const DEFAULT_INTERVAL = Duration.seconds(10);
 const DEFAULT_TIMEOUT = Duration.minutes(5);
 /**
@@ -60,6 +78,7 @@ var WorkflowDispatch = class WorkflowDispatch extends Context.Service()("@effect
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({
 		dispatch: overrides.dispatch ?? (() => unstubbed("dispatch")),
+		dispatchWithRun: overrides.dispatchWithRun ?? (() => unstubbed("dispatchWithRun")),
 		runStatus: overrides.runStatus ?? (() => unstubbed("runStatus")),
 		cancelRun: overrides.cancelRun ?? (() => unstubbed("cancelRun")),
 		list: overrides.list ?? Effect.sync(() => unstubbed("list")),
@@ -77,6 +96,14 @@ const statusOf = (raw) => WorkflowRunStatus.make({
 	...raw.conclusion != null ? { conclusion: raw.conclusion } : {},
 	url: raw.html_url
 });
+/** GitHub's `workflow-dispatch-response`; the id is `number | bigint` in the generated types. */
+const DispatchResponse = Schema.Struct({
+	workflow_run_id: Schema.Union([Schema.Number, Schema.BigInt]),
+	run_url: Schema.String,
+	html_url: Schema.String
+});
+const decodeDispatchResponse = Schema.decodeUnknownEffect(DispatchResponse);
+const decodeDispatchedRun = Schema.decodeUnknownEffect(DispatchedRun);
 const make = (client) => {
 	const dispatch = Effect.fn("WorkflowDispatch.dispatch")(function* (workflow, ref, inputs) {
 		const { owner, repo } = yield* Repo;
@@ -94,6 +121,30 @@ const make = (client) => {
 			...inputs !== void 0 ? { inputs } : {}
 		});
 	});
+	const dispatchWithRun = Effect.fn("WorkflowDispatch.dispatchWithRun")(function* (workflow, ref, inputs) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			workflow,
+			ref
+		});
+		const data = yield* client.request("POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches", {
+			owner,
+			repo,
+			workflow_id: workflow,
+			ref,
+			...inputs !== void 0 ? { inputs } : {},
+			return_run_details: true
+		});
+		if (data === "" || data === null) return Option.none();
+		const run = yield* decodeDispatchResponse(data).pipe(Effect.flatMap((raw) => decodeDispatchedRun({
+			runId: numericId(raw.workflow_run_id),
+			runUrl: raw.run_url,
+			htmlUrl: raw.html_url
+		})), Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode("WorkflowDispatch.dispatchWithRun", "GitHub returned unexpected run details", error))));
+		return Option.some(run);
+	});
 	const runStatus = Effect.fn("WorkflowDispatch.runStatus")(function* (runId) {
 		const { owner, repo } = yield* Repo;
 		yield* Effect.annotateCurrentSpan({
@@ -126,6 +177,7 @@ const make = (client) => {
 	});
 	return {
 		dispatch,
+		dispatchWithRun,
 		runStatus,
 		cancelRun: Effect.fn("WorkflowDispatch.cancelRun")(function* (runId) {
 			const { owner, repo } = yield* Repo;
@@ -154,8 +206,8 @@ const make = (client) => {
 				attempts
 			});
 			const dispatchedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
-			yield* dispatch(workflow, ref, options?.inputs);
-			const findRun = Effect.gen(function* () {
+			const dispatched = yield* dispatchWithRun(workflow, ref, options?.inputs);
+			const findRun = Option.isSome(dispatched) ? Effect.map(runStatus(dispatched.value.runId), Option.some) : Effect.gen(function* () {
 				const match = (yield* client.paginate("GET /repos/{owner}/{repo}/actions/runs", {
 					owner,
 					repo,
@@ -179,4 +231,4 @@ const make = (client) => {
 };
 
 //#endregion
-export { WorkflowDispatch, WorkflowRunStatus };
+export { DispatchedRun, WorkflowDispatch, WorkflowRunStatus };

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.
    *
@@ -2243,6 +2575,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;
@@ -2536,6 +2899,17 @@ 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>;
 }
@@ -4253,6 +4627,25 @@ export declare class WorkflowRunStatus extends WorkflowRunStatus_base {
   /** Has the run finished, whatever the outcome? */
   get isDone(): boolean;
 }
+declare const DispatchedRun_base: Schema.Class<DispatchedRun, Schema.Struct<{
+  /** The created run's numeric id. */
+  readonly runId: Schema.Int;
+  /** The run's API URL. */
+  readonly runUrl: Schema.String;
+  /** The run's web URL. */
+  readonly htmlUrl: Schema.String;
+}>, {}>;
+/**
+ * The run a `workflow_dispatch` created, as GitHub reports it when asked.
+ *
+ * @remarks
+ * Returned by {@link WorkflowDispatchShape.dispatchWithRun}. `runId` is usable
+ * directly with {@link WorkflowDispatchShape.runStatus} and
+ * {@link WorkflowDispatchShape.cancelRun}.
+ *
+ * @public
+ */
+export declare class DispatchedRun extends DispatchedRun_base {}
 /**
  * One workflow defined in the repository.
  *
@@ -4293,8 +4686,34 @@ interface PollOptions {
  * @public
  */
 interface WorkflowDispatchShape {
-  /** Fire a `workflow_dispatch` event. GitHub answers 204 with no run id. */
+  /**
+   * Fire a `workflow_dispatch` event and discard GitHub's answer; use
+   * {@link WorkflowDispatchShape.dispatchWithRun} when the run id is needed.
+   */
   readonly dispatch: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Fire a `workflow_dispatch` event and report the run it created.
+   *
+   * @remarks
+   * Sends the same request as {@link WorkflowDispatchShape.dispatch} with
+   * `return_run_details: true`. GitHub then answers 200 with the run's id and
+   * URLs, which arrive as `Option.some` of a {@link DispatchedRun}; a 200 body
+   * that does not have that shape fails with a `decode` `GitHubError`.
+   *
+   * A 204 with no body is `Option.none()`. That is what a GitHub Enterprise
+   * Server predating the field answers — it ignores `return_run_details` and
+   * still dispatches — so it is **not a failure**: the workflow was dispatched,
+   * the server just did not say which run it created.
+   *
+   * Under `GitHubClient.layerFixture`, stub the 204 the way every other
+   * no-body route is stubbed: answer the dispatch route with `null`. `""`
+   * (what octokit itself hands back for an empty body) works too.
+   *
+   * Every failure of the request itself (a 404 for an unknown workflow, a 422
+   * for a workflow without a `workflow_dispatch` trigger, …) is the
+   * `GitHubError` the client classified, passed through unchanged.
+   */
+  readonly dispatchWithRun: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<Option.Option<DispatchedRun>, GitHubError, Repo>;
   /** Read one workflow run's status. */
   readonly runStatus: (runId: number) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
   /**
@@ -4330,8 +4749,15 @@ interface WorkflowDispatchShape {
    * The wait is `Effect.repeat` with a predicate over the **success** value, so
    * "not finished yet" is never an error. If the run is not found finished
    * within `poll.timeout`, it fails with a `rejected` `GitHubError` (status
-   * 408). The run is matched by branch, creation time and workflow path, so
-   * concurrent dispatches of the same workflow on the same ref can be confused.
+   * 408).
+   *
+   * The run is identified by {@link WorkflowDispatchShape.dispatchWithRun}:
+   * when GitHub reports the run it created, exactly that run is polled, so
+   * concurrent dispatches cannot be confused. When it does not (a 204 from a
+   * GitHub Enterprise Server predating `return_run_details`), the run is found
+   * instead by branch, creation time and workflow path — and on that fallback
+   * alone, concurrent dispatches of the same workflow on the same ref can be
+   * confused.
    */
   readonly dispatchAndWait: (workflow: string, ref: string, options?: {
     readonly inputs?: Record<string, string> | undefined;
@@ -4374,5 +4800,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";
@@ -27,7 +28,7 @@ import { RepositorySecurity } from "./RepositorySecurity.js";
 import { RepositoryVariable } from "./RepositoryVariable.js";
 import { Ruleset } from "./Ruleset.js";
 import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, TokenPermissionError, TokenPermissions } from "./TokenPermissions.js";
-import { WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
+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, 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.16.0",
+	"version": "0.18.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.7.1",
+		"@effected/jwt": "^0.1.1",
+		"@effected/semver": "^0.11.1",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^16.0.0",
 		"@octokit/types": "^18.0.0",
@@ -48,7 +48,7 @@
 		"tweetnacl": "1.0.3"
 	},
 	"peerDependencies": {
-		"effect": "^4.0.0"
+		"effect": "4.0.2"
 	},
 	"engines": {
 		"node": ">=24.11.0"