@effected/github 0.14.0 → 0.15.1

package/ArtifactMetadata.js

@@ -7,10 +7,7 @@ import { Context, Effect, Layer, Schema } from "effect";
 * What to record about a published artifact.
 *
 * @remarks
-* These are the fields the endpoint actually accepts. The version this replaces
-* declared a `version` field the endpoint has no notion of — a fabricated key
-* that a `Record<string, unknown>` body accepted silently and the generated
-* types reject outright.
+* These are the fields the storage-record endpoint accepts.
 *
 * @public
 */
@@ -29,11 +26,16 @@ var StorageRecordInput = class extends Schema.Class("StorageRecordInput")({
 	path: Schema.optionalKey(Schema.String)
 }) {};
 /**
-* Artifact metadata.
+* Records where published artifacts are stored, at the organization level.
+*
+* @remarks
+* Provide it with {@link ArtifactMetadata.layer}, which needs a `GitHubClient`;
+* `createStorageRecord` also needs a `Repo` in `R`.
 *
 * @public
 */
 var ArtifactMetadata = class ArtifactMetadata extends Context.Service()("@effected/github/ArtifactMetadata") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({ createStorageRecord: overrides.createStorageRecord ?? (() => unstubbed("createStorageRecord")) });

package/Attestation.js

@@ -42,11 +42,17 @@ const ListResponse = Schema.Struct({ attestations: Schema.optionalKey(Schema.Arr
 	predicate_type: Schema.optionalKey(Schema.String)
 }))) });
 /**
-* Attestations.
+* Uploads signed attestation bundles to a repository and lists what is attested
+* about a subject digest.
+*
+* @remarks
+* Provide it with {@link Attestation.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
 *
 * @public
 */
 var Attestation = class Attestation extends Context.Service()("@effected/github/Attestation") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/CheckRun.js

@@ -43,8 +43,8 @@ var Annotation = class extends Schema.Class("Annotation")({
 * GitHub's limits are **byte** limits, and that distinction is the whole reason
 * this class exists rather than a struct: `✅`, `❌`, `🦋` and `│` cost several
 * bytes each, so a character-count check passes while the request comes back
-* 422 saying *"summary exceeds a maximum bytesize of 65535"*. One consumer hit
-* exactly that and wrote the truncation by hand.
+* 422 saying *"summary exceeds a maximum bytesize of 65535"*. Use
+* {@link CheckRunOutput.truncated} to cut an output to fit.
 *
 * @public
 */
@@ -87,8 +87,7 @@ var CheckRunOutput = class CheckRunOutput extends Schema.Class("CheckRunOutput")
 * @remarks
 * Slicing a UTF-8 buffer mid-character decodes to U+FFFD. Splitting a four-byte
 * code point can produce **more than one** replacement character, so the trim
-* loops rather than dropping a single one — which is the hardening this needed
-* over the hand-written version it replaces.
+* loops rather than dropping a single one.
 */
 const capBytes = (value) => {
 	if (Buffer.byteLength(value, "utf8") <= CheckRunOutput.LIMIT_BYTES) return value;
@@ -110,11 +109,17 @@ var CheckRunRef = class extends Schema.Class("CheckRunRef")({
 	status: Schema.String
 }) {};
 /**
-* Check runs.
+* Create, update and conclude GitHub check runs, including the
+* {@link CheckRunShape.withCheckRun} bracket that always reaches a terminal state.
+*
+* @remarks
+* Provide it with {@link CheckRun.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
 *
 * @public
 */
 var CheckRun = class CheckRun extends Context.Service()("@effected/github/CheckRun") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/CodeScanning.js

@@ -4,12 +4,19 @@ import { Context, Effect, Layer } from "effect";
 
 //#region src/CodeScanning.ts
 /**
-* CodeQL default setup.
+* Configure CodeQL default setup and read the languages GitHub detects in a
+* repository.
+*
+* @remarks
+* Provide it with {@link CodeScanning.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
 *
 * @public
 */
 var CodeScanning = class CodeScanning extends Context.Service()("@effected/github/CodeScanning") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* The callback is written `(client) => make(client)` rather than passed as
 	* `make` directly, and that is load-bearing: a static initializer runs while

package/DeploymentEnvironment.js

@@ -4,12 +4,30 @@ import { Context, Effect, Layer } from "effect";
 
 //#region src/DeploymentEnvironment.ts
 /**
-* Deployment environments.
+* Create or update, list and delete a repository's deployment environments.
+*
+* @remarks
+* Provide it with {@link DeploymentEnvironment.layer}, which needs a
+* `GitHubClient`; each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { DeploymentEnvironment } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const environments = yield* DeploymentEnvironment;
+*   yield* environments.upsert("production", { wait_timer: 10 });
+*   return yield* environments.list();
+* });
+* ```
 *
 * @public
 */
 var DeploymentEnvironment = class DeploymentEnvironment extends Context.Service()("@effected/github/DeploymentEnvironment") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* `(client) => make(client)` rather than `make`: a static initializer runs
 	* while the module body is still evaluating, so naming a `const` declared

package/GitBranch.js

@@ -15,12 +15,32 @@ const CreateLinkedBranch = GraphQLDocument.make({
 	response: Schema.Struct({})
 })();
 /**
-* Branches, as refs.
+* Create, move, read and delete branch refs through GitHub's Git Database API,
+* with an `upsert` that needs no existence check.
+*
+* @remarks
+* Provide it with {@link GitBranch.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`. Branch names are accepted as `main`,
+* `heads/main` or `refs/heads/main`.
+*
+* @example
+* ```ts
+* import { GitBranch } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const ensureBranch = (name: string, sha: string) =>
+*   Effect.gen(function* () {
+*     const branches = yield* GitBranch;
+*     return yield* branches.upsert(name, sha); // "created" | "reset"
+*   });
+* ```
 *
 * @public
 */
 var GitBranch = class GitBranch extends Context.Service()("@effected/github/GitBranch") {
 	/**
+	* The live service, built over a `GitHubClient`.
+	*
 	* @remarks
 	* The callback is written `(client) => make(client)` rather than passed as
 	* `make` directly, and that is load-bearing: a static initializer runs while
@@ -71,8 +91,7 @@ const rejectEmpty = (operation, name) => {
 * house pattern for a stable dependency — but it would also make a scoped
 * override silently do nothing, because the resource would already hold the
 * repository it was built with. The repository is precisely the dependency that
-* is *not* stable: silk-sync-action loops one program over many target
-* repositories.
+* is *not* stable: one program may loop over many target repositories.
 *
 * The client stays resolved at construction, so this costs one context read per
 * call and nothing else.

package/GitCommit.js

@@ -44,10 +44,8 @@ const FileChange = Schema.Union([FileContent, FileDeletion]);
 * A commit, projected to the three fields callers actually use.
 *
 * @remarks
-* `treeSha` is here because two surveyed call sites dropped to a raw octokit
-* cast for it alone, both with the comment *"the Git Data API's `base_tree`
-* wants a tree SHA, not a commit SHA"* — the same eight lines written twice, in
-* two files, for one string.
+* `treeSha` is here because the Git Data API's `base_tree` wants a tree SHA,
+* not a commit SHA.
 *
 * @public
 */
@@ -60,11 +58,33 @@ var CommitRef = class extends Schema.Class("CommitRef")({
 	parents: Schema.Array(Schema.String)
 }) {};
 /**
-* Commits, trees and blobs.
+* Read commits and build trees and commits through GitHub's Git Database API,
+* including a one-call "commit these files onto a branch".
+*
+* @remarks
+* Provide it with {@link GitCommit.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`. No local git runs: this is the REST API,
+* not `@effected/git`.
+*
+* @example
+* ```ts
+* import { FileContent, GitCommit } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const writeNotes = Effect.gen(function* () {
+*   const commits = yield* GitCommit;
+*   return yield* commits.commitFiles({
+*     branch: "docs/notes",
+*     message: "docs: add notes",
+*     changes: [FileContent.make({ path: "NOTES.md", content: "# Notes\n" })],
+*   }); // the new commit's sha
+* });
+* ```
 *
 * @public
 */
 var GitCommit = class GitCommit extends Context.Service()("@effected/github/GitCommit") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/GitHubApp.js

@@ -76,9 +76,8 @@ var InstallationToken = class extends Schema.Class("InstallationToken")({
 	* Whether this token is spent, `skew` before its stated expiry.
 	*
 	* @remarks
-	* Modelled **and enforced**. The package this replaces persisted `expiresAt`
-	* and read it nowhere, so a long `main` phase that outlived the hour simply
-	* started answering 401 with no explanation.
+	* `skew` defaults to one minute, so a token is treated as spent slightly early
+	* rather than answering 401 mid-request.
 	*/
 	isExpired(nowMillis, skew = DEFAULT_SKEW) {
 		return DateTime.toEpochMillis(this.expiresAt) - Duration.toMillis(skew) <= nowMillis;
@@ -97,10 +96,10 @@ const DEFAULT_SKEW = Duration.seconds(60);
 * Who a bot commits as.
 *
 * @remarks
-* A **pure class**, not a service member. The package this replaces put
-* `botIdentity(source?)` on the `GitHubApp` service shape as a plain synchronous
-* method, which makes it required in every `Layer.mock` and silently degrades
-* every partial double to a full implementation.
+* A **pure class**, not a `GitHubApp` service member: a synchronous method on
+* the service shape would be required in every `Layer.mock` and would silently
+* degrade every partial double to a full implementation. Get one from
+* `InstallationToken.botIdentity` or `AppIdentity.botIdentity`.
 *
 * @public
 */
@@ -189,9 +188,28 @@ var Installation = class extends Schema.Class("Installation")({
 * `@effected/commands`' service, for the same reason.
 *
 * The JWT signer is `universal-github-app-jwt` — zero dependencies, and
-* `@octokit/auth-app`'s own JWT dependency. Taking it directly rather than
-* taking `auth-app` leaves behind roughly half a megabyte of OAuth app, user and
-* device-flow machinery that this package never calls.
+* `@octokit/auth-app`'s own JWT dependency.
+*
+* @example
+* ```ts
+* import { GitHubApp, GitHubClient } from "@effected/github";
+* import { Effect, Redacted } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const client = yield* GitHubClient;
+*   const accessible = yield* client.request("GET /installation/repositories", { per_page: 1 });
+*   return accessible.total_count;
+* });
+*
+* // Mints an installation token on build, re-mints before expiry, revokes on release.
+* const layer = GitHubApp.clientLayer({
+*   appId: "12345",
+*   privateKey: Redacted.make("-----BEGIN PRIVATE KEY-----\n..."),
+*   owner: "my-org",
+* });
+*
+* Effect.runPromise(Effect.provide(program, layer));
+* ```
 *
 * @public
 */
@@ -214,11 +232,12 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	* The token's lifetime is the layer's scope: it is minted on build and
 	* **revoked on release**, best-effort, so a workflow does not leave live
 	* credentials behind. It is also **re-minted automatically** a minute before
-	* it expires, which the package this replaces did not do — it persisted
-	* `expiresAt` and read it nowhere, so a `main` phase outliving the hour
-	* started answering 401 with nothing explaining why.
+	* it expires, so a long-running program does not start answering 401 when
+	* the hour ends.
 	*
-	* A failure to obtain credentials surfaces to the caller as a
+	* Building the layer mints the first token, so a misconfigured app fails
+	* construction with `GitHubAppError`. After that, a failure to obtain
+	* credentials surfaces to the caller as a
 	* `GitHubError { kind: "unauthorized" }` carrying the `GitHubAppError` as its
 	* cause: from a request's point of view, "could not authenticate" is an
 	* authorization failure, and widening every method's error channel to say so

package/GitHubClient.js

@@ -23,12 +23,27 @@ const unstubbed = (member) => {
 * literal and gets both sides typed, with no callback, no type parameter to
 * invent, and no cast.
 *
-* That is the whole point of this package. The surface it replaces was
-* `rest<T>(operation: string, fn: (octokit: any) => Promise<{ data: T }>)`,
-* where `T` was whatever the caller wrote and nothing connected it to the
-* endpoint. Four consumer repos paid for that with sixteen cast sites and three
-* hand-written octokit interfaces, one of which gave up and typed its methods as
-* `Record<string, (p: unknown) => Promise<{ data: unknown }>>`.
+* Nothing here asks the caller to invent a response type: the route literal is
+* the only thing written, and a mismatch between a route and its parameters is
+* a compile error.
+*
+* @example
+* ```ts
+* import { GitHubClient } from "@effected/github";
+* import { Effect, Redacted } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const client = yield* GitHubClient;
+*   const release = yield* client.request("GET /repos/{owner}/{repo}/releases/latest", {
+*     owner: "effect-ts",
+*     repo: "effect",
+*   });
+*   return release.tag_name;
+* });
+*
+* const layer = GitHubClient.layerFromToken({ token: Redacted.make("ghp_example") });
+* Effect.runPromise(program.pipe(Effect.provide(layer)));
+* ```
 *
 * @public
 */
@@ -51,10 +66,7 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	* provides a provider instead of mutating the environment and a non-Actions
 	* consumer can source the token however it likes.
 	*
-	* Construction fails with core's `ConfigError` — an honest "no token is
-	* configured". The layer this replaces failed with a **wire-failure** error
-	* type instead, which is why one consumer wrapped it in `Layer.orDie` under a
-	* five-line comment explaining that the error did not mean what it said.
+	* Construction fails with core's `ConfigError` when no token is configured.
 	*/
 	static layerFromConfig = (options = {}) => Layer.effect(this, Effect.gen(function* () {
 		const token = yield* Config.Redacted(options.name ?? "GITHUB_TOKEN");
@@ -90,17 +102,11 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	* A double over recorded responses that **pages them for real**.
 	*
 	* @remarks
-	* The one recorded-response double in this package, and the single narrow
-	* exception to the no-behavior-reimplementing-doubles rule — safe precisely
-	* because it reimplements nothing: it builds a `PageSource` over the recorded
+	* The recorded-response double in this package. It reimplements no behavior:
+	* it builds a `PageSource` over the recorded
 	* array and hands it to the same `paginate` engine the live client uses, so
 	* `perPage` and `maxPages` cannot behave differently here than in production.
 	*
-	* The double it replaces named its pagination parameters `_options` and
-	* ignored them, returning every recorded page regardless of what the caller
-	* asked for — which made every truncation path in every consumer
-	* structurally untestable.
-	*
 	* `fixtures.requested` is appended to as the test runs, so a suite can assert
 	* which routes were walked and at what page size.
 	*/

package/GitHubCommit.js

@@ -89,11 +89,30 @@ var CommitComparison = class extends Schema.Class("CommitComparison")({
 	files: Schema.Array(CommitFile)
 }) {};
 /**
-* Commits, as GitHub reports them.
+* Read commits, compare refs and list changed files through GitHub's commits
+* API.
+*
+* @remarks
+* Provide it with {@link GitHubCommit.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`. For commits as Git Database objects (trees,
+* parents), use `GitCommit` instead.
+*
+* @example
+* ```ts
+* import { GitHubCommit } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const changedSinceMain = Effect.gen(function* () {
+*   const commits = yield* GitHubCommit;
+*   const comparison = yield* commits.compare("main", "feature");
+*   return comparison.files.map((file) => file.path);
+* });
+* ```
 *
 * @public
 */
 var GitHubCommit = class GitHubCommit extends Context.Service()("@effected/github/GitHubCommit") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/GitHubContent.js

@@ -5,11 +5,29 @@ import { Context, Effect, Layer, Option } from "effect";
 
 //#region src/GitHubContent.ts
 /**
-* Repository file contents.
+* Read a text file out of a repository at a ref, with absence as an `Option`
+* when you want it.
+*
+* @remarks
+* Provide it with {@link GitHubContent.layer}, which needs a `GitHubClient`;
+* each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { GitHubContent } from "@effected/github";
+* import { Effect, Option } from "effect";
+*
+* const readme = Effect.gen(function* () {
+*   const content = yield* GitHubContent;
+*   const file = yield* content.getFileOption("README.md", { ref: "main" });
+*   return Option.getOrElse(file, () => "");
+* });
+* ```
 *
 * @public
 */
 var GitHubContent = class GitHubContent extends Context.Service()("@effected/github/GitHubContent") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({

package/GitHubError.js

@@ -6,12 +6,9 @@ import { Schema } from "effect";
 * Why a GitHub call failed, as a value you can branch on.
 *
 * @remarks
-* This discriminant is what replaces string-matching an error message. The
-* package this replaces carried a free-form `reason` string and nothing else
-* structural, so consumers grepped it: one repo lowercased a GraphQL message and
-* tested `includes("already") || includes("exists")`, and another re-issued an
-* existence check after every failed branch creation because it could not tell
-* "someone else created it" from "that failed".
+* Branch on this discriminant instead of string-matching an error message:
+* `alreadyExists` tells "someone else created it" apart from "that failed", so
+* an upsert needs no follow-up existence check.
 *
 * @public
 */
@@ -75,16 +72,9 @@ var GitHubValidationEntry = class extends Schema.Class("GitHubValidationEntry")(
 * Every REST failure this package produces, from every resource.
 *
 * @remarks
-* One error class, not one per resource. Across the six repos surveyed for this
-* port, consumers read `reason` about forty times, `status` twice, `operation`
-* twice, and matched a resource-specific `_tag` exactly **once** — at a call
-* site that disappears entirely now that `GitBranch.upsert` exists. Eighteen
-* near-identical error classes and thirteen near-identical mapper closures
-* bought that one match.
-*
-* What replaces them is {@link GitHubErrorKind} for routing and `operation` for
-* identification. This mirrors `@effected/git`, where the rule is that no
-* consumer ever string-matches stderr because classification happens once.
+* One error class, not one per resource: {@link GitHubErrorKind} routes and
+* `operation` identifies what was attempted. This mirrors `@effected/git`,
+* where classification happens once so no consumer string-matches stderr.
 *
 * @public
 */
@@ -103,8 +93,8 @@ var GitHubError = class GitHubError extends Schema.TaggedError()("GitHubError",
 	* @remarks
 	* Written by the client from `retry-after` or the rate-limit reset, and read
 	* by exactly one thing: the retry `Schedule`. It is a policy input, not
-	* information for a caller — which is why it is optional and why the
-	* `retryable` boolean it used to travel with is now a derived getter.
+	* information for a caller. Whether a failure is worth retrying at all is the
+	* derived `retryable` getter.
 	*/
 	retryAfterMillis: Schema.optionalKey(Schema.Int),
 	/**
@@ -176,7 +166,7 @@ var GitHubError = class GitHubError extends Schema.TaggedError()("GitHubError",
 	* @remarks
 	* The single classification step for the whole package — every resource
 	* method's failures come through here, so the taxonomy cannot drift between
-	* resources the way thirteen hand-written mapper closures did.
+	* resources.
 	*
 	* `nowMillis` is passed in rather than read from the wall clock so the
 	* function stays pure and total: the rate-limit reset header is an absolute
@@ -276,9 +266,8 @@ const asRecord = (value) => typeof value === "object" && value !== null ? value
 * multi-kilobyte "message".
 *
 * @remarks
-* The package this replaces detected the "Unicorn" page specifically; this is
-* the general form — an HTML body is never a useful reason string, and letting
-* one through means a log line with a whole web page in it.
+* An HTML body is never a useful reason string, and letting one through means
+* a log line with a whole web page in it.
 */
 const sanitizeReason = (message) => {
 	const trimmed = message.trim();

package/GitHubIssue.js

@@ -37,10 +37,8 @@ var LinkedIssue = class extends Schema.Class("LinkedIssue")({
 	* branch or commit messages.
 	*
 	* @remarks
-	* This is the field the whole document exists for. The version this replaces
-	* could not express `userLinkedOnly`, so one consumer re-declared the query
-	* with the field aliased twice to get it — the single largest duplicated
-	* document in the survey.
+	* Resolved by querying the pull request's closing references twice, once with
+	* `userLinkedOnly`, and marking the issues present in the second result.
 	*/
 	userLinked: Schema.Boolean
 }) {};
@@ -104,11 +102,30 @@ const CrossReferencedDocument = GraphQLDocument.make({
 	response: CrossReferencedResponse
 })();
 /**
-* Issues.
+* Read, list, close and comment on issues, and resolve the issues a pull
+* request closes.
+*
+* @remarks
+* Provide it with {@link GitHubIssue.layer}, which needs a `GitHubClient`; each
+* method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { GitHubIssue } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const closeWontFix = (number: number) =>
+*   Effect.gen(function* () {
+*     const issues = yield* GitHubIssue;
+*     yield* issues.comment(number, "Closing as not planned.");
+*     yield* issues.close(number, "not_planned");
+*   });
+* ```
 *
 * @public
 */
 var GitHubIssue = class GitHubIssue extends Context.Service()("@effected/github/GitHubIssue") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({
@@ -139,15 +156,14 @@ const unstubbed = (member) => {
 * silence it, because the fetch wrapper resolves `request.log ?? console`.
 * `PATCH /repos/{owner}/{repo}/issues/{issue_number}` is on that list (the
 * singular `assignee` parameter was removed), so every `close` warned once per
-* issue in consumer workflow logs (effected#189).
+* issue in consumer workflow logs.
 *
 * Nothing this module sends or reads changed in 2026-03-10: `state` and
 * `state_reason` are untouched, and the projections read only fields both
 * versions carry. Pinning the current version is therefore the whole fix, and
 * it deliberately does **not** hide future deprecations — when GitHub
 * deprecates 2026-03-10 in turn, the header comes back and octokit warns
-* again. Verified live 2026-08-14: the pinned request answers with no
-* `Deprecation`/`Sunset` headers.
+* again.
 */
 const API_VERSION_HEADERS = { "x-github-api-version": "2026-03-10" };
 /** GitHub sends a label as either a string or an object; callers want the name. */

package/GitHubRelease.js

@@ -5,7 +5,7 @@ import { Context, Effect, Layer, Option, Schema } from "effect";
 
 //#region src/GitHubRelease.ts
 /**
-* A release.
+* A release, projected to the fields callers read.
 *
 * @public
 */
@@ -35,11 +35,29 @@ var ReleaseAsset = class extends Schema.Class("ReleaseAsset")({
 	size: Schema.Int
 }) {};
 /**
-* Releases.
+* Create, read, list and update GitHub releases, and upload and list their
+* assets.
+*
+* @remarks
+* Provide it with {@link GitHubRelease.layer}, which needs a `GitHubClient`;
+* each method also needs a `Repo` in `R`.
+*
+* @example
+* ```ts
+* import { GitHubRelease } from "@effected/github";
+* import { Effect } from "effect";
+*
+* const publish = Effect.gen(function* () {
+*   const releases = yield* GitHubRelease;
+*   const release = yield* releases.create({ tag: "v1.2.3", generateReleaseNotes: true });
+*   return release.url;
+* });
+* ```
 *
 * @public
 */
 var GitHubRelease = class GitHubRelease extends Context.Service()("@effected/github/GitHubRelease") {
+	/** The live service, built over a `GitHubClient`. */
 	static layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({