# @effected/github ## 0.33.0 ### Bug Fixes - `RepositorySecret` fails with a decode `GitHubError` when GitHub's public key is not 32 bytes or is a low-order X25519 point. Before, a wrong-length key died as a defect and a low-order key was used unchecked. ### Refactoring - The libsodium sealed box behind `RepositorySecret` is now built from in-house copies of audited `@noble` code: X25519, XSalsa20-Poly1305 and BLAKE2b, each with a provenance header. The output is byte-compatible with libsodium's `crypto_box_seal`, and the tests check it against libsodium itself. ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | blakejs | dependency | removed | 1.2.1 | — | | tweetnacl | dependency | removed | 1.0.3 | — | ## 0.32.1 ### Bug Fixes - `CheckRun.complete`, `completeRef`, `update` and `updateRef` retry a 404 three times over 1.75s before failing. GitHub's checks API can answer 404 for a run created moments earlier, which left the run `in_progress` forever. The waits run on `Clock`, a retried completion resends the first attempt's `completed_at`, and every other failure still follows the client's retry policy. Closes #1330 ## 0.32.0 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/crypto | dependency | updated | 0.6.0 | 0.7.0 | | @effected/github-references | dependency | updated | 0.14.0 | 0.15.0 | | @effected/jwt | dependency | updated | 0.9.1 | 0.10.0 | | @effected/oidc | dependency | updated | 0.4.0 | 0.5.0 | | @effected/semver | dependency | updated | 0.23.0 | 0.24.0 | ### Maintenance - Force release all packages to pin new effect versions. ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! ## 0.31.0 ### Features - `ChangelogInfo` looks up what a changelog line credits, replacing `@changesets/get-github-info`. `commit(sha)` returns the author login, the pull request number and markdown links for the commit, pull request and user; `pullRequest(number)` returns the same for a changeset that names its pull request. Each answer is an `Option`, as is every value inside it that can be missing. - The token and the server come from the `GitHubClient` the layer is built over, and the repository from `Repo`. Nothing is read from `process.env` or `.env`, and GitHub Enterprise Server works through the client's `baseUrl`. - The query and the link strings match upstream's. Lookups that run concurrently are sent as one aliased GraphQL query of up to 50. - A pull request number the repository lacks returns `Option.none()`, and so does a sha that names a tree or blob. Upstream fails the whole batch on the first and builds a link to `undefined` on the second. A sha that is not 4 to 64 hex characters, or a pull number that is not a positive integer, fails `InvalidChangelogRefError` before anything is sent. - `GraphQLErrorEntry` now carries the `path` GitHub reports for an error, which names the aliased field that failed. [#1318][#1318] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.22.0 | 0.23.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1318]: https://github.com/spencerbeggs/effected/pull/1318 ## 0.30.0 ### Features #### `GitHubUserAuth` - Runs the OAuth web flow a GitHub App or OAuth App uses to act as a user: `exchange` (with PKCE), `refresh` and `revokeGrant`. It calls `fetch` directly, so a Worker that only signs users in links neither octokit nor the JWT signer. Tokens are `Redacted`, expiries are absolute instants, and no credential reaches an error message or a kept cause. `GitHubUserAuth.layerTest` is the test double. - Every failure is one of two errors: - `GitHubUserAuthFinal`: GitHub refused. It keeps the `code` and carries a `remedy` - `GitHubUserAuthTemporary`: `network`, `timeout`, `status` (5xx, 429, 408, or a 403 whose message names a rate limit) or `malformed`. Retry later and keep the tokens you hold - Branch on `remedy`, not on the error being final. `reconnect` means the user's grant is dead, while `reconfigure` means the app is wrong. `incorrect_client_credentials` lands on `reconfigure`, so a handler that drops tokens on any final failure signs every user out when a client secret is rotated. ```ts import { GitHubUserAuth } from "@effected/github"; import { Effect, Redacted } from "effect"; // bind once — layers memoize by reference const UserAuth = GitHubUserAuth.layer({ clientId: "Iv23liExample", clientSecret: Redacted.make(process.env.GITHUB_CLIENT_SECRET as string), }); const renew = (refreshToken: Redacted.Redacted) => Effect.gen(function* () { const auth = yield* GitHubUserAuth; return yield* auth.refresh({ refreshToken }); }).pipe( Effect.catchTag("GitHubUserAuthFinal", (error) => error.remedy === "reconnect" ? Effect.succeed("sign-in-again" as const) : Effect.fail(error), ), ); ``` - GitHub rotates the refresh token on every refresh it processes, so a refresh that failed after reaching GitHub answers `bad_refresh_token` when retried, and the user signs in again. [#1250][#1250] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/crypto | dependency | updated | 0.5.0 | 0.6.0 | | @effected/jwt | dependency | updated | 0.9.0 | 0.9.1 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1250]: https://github.com/spencerbeggs/effected/pull/1250 ## 0.29.0 ### Breaking Changes - `GitCommitShape` gains two required members, `createCommitWithUrl` and `commitFilesWithUrl`, so a hand-rolled `Layer.succeed` double stops typechecking. `GitCommit.makeTest` already covers them. `createCommit` and `commitFiles` are unchanged and still return the sha. ### Features - `CreatedCommit` (#1207) carries the new commit's `sha` and its `htmlUrl`, taken from GitHub's reply so it has the right host on GitHub Enterprise Server. - `createCommitWithUrl` and `commitFilesWithUrl` return a `CreatedCommit`. A reply with no `html_url` fails with a `GitHubError` that names the commit already created. ### Documentation - Interrupting a request aborts its underlying fetch (#1217). That was already the behaviour; it is now tested and documented. [#1239][#1239] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.21.0 | 0.22.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1239]: https://github.com/spencerbeggs/effected/pull/1239 ## 0.28.0 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/crypto | dependency | updated | 0.4.0 | 0.5.0 | | @effected/github-references | dependency | updated | 0.13.0 | 0.14.0 | | @effected/jwt | dependency | updated | 0.8.0 | 0.9.0 | | @effected/oidc | dependency | updated | 0.3.0 | 0.4.0 | | @effected/semver | dependency | updated | 0.20.0 | 0.21.0 | ### Maintenance - Upgrades core Effect library dependencies to v4.1.2 [#1229][#1229] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1229]: https://github.com/spencerbeggs/effected/pull/1229 ## 0.27.0 ### Breaking Changes - Rebuilt on Effect 4.1.1. The `effect` peer dependency (and any `@effect/*` peer) is now `~4.1.0`, so an Effect 4.0.x install no longer satisfies it. Upgrade `effect` to 4.1 alongside this release; mixing this package with a copy built on 4.0.x is unsupported. - The App JWT is now signed through `@effected/jwt` on core `effect/jose`, so `GitHubApp.layer`, `GitHubApp.layerWith`, `GitHubApp.clientLayer` and `GitHubApp.appClientLayer` require core's `Signature` service, and `ActionsOidc.verify` requires it alongside `JwksResolver`. Provide it once at the edge: ```ts import { Layer } from "effect"; import { SecureRandom, Signature } from "effect/crypto"; const CryptoLive = Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto)); ``` - The `GitHubApp` methods and the client layers' re-signing still need nothing: the layer captures `Signature` when it is built. The App JWT on the wire is unchanged: header `{"alg":"RS256","typ":"JWT"}`, claims `iat`, `exp` and `iss`, and the same signature bytes for the same key and clock. [#1168][#1168] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/crypto | dependency | updated | 0.3.0 | 0.4.0 | | @effected/github-references | dependency | updated | 0.12.0 | 0.13.0 | | @effected/jwt | dependency | updated | 0.7.0 | 0.8.0 | | @effected/oidc | dependency | updated | 0.2.0 | 0.3.0 | | @effected/semver | dependency | updated | 0.19.0 | 0.20.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1168]: https://github.com/spencerbeggs/effected/pull/1168 ## 0.26.0 ### Breaking Changes - `AppliedSettings.unverified` is required. Test doubles that build `AppliedSettings` literals must add it. - `RestExtras.baseUrl` is removed, and `Rest.Params` and `requestDecoded` params forbid `baseUrl`. Point the client at another host through its configuration instead. - The raw `request`, `requestDecoded`, `paginate` and `paginateStream` refuse `baseUrl`, `url`, `request` and `method` params and any route that resolves off the configured origin. A top-level `url` body field must go in `data`. Cross-origin pagination `Link` headers and continuations fail as rejected instead of truncating. - `RepositoryPatch` drops the `RequestExtras` transport keys (`headers`, `mediaType`, `baseUrl`). - `layerFixture` records a repository PATCH as `{ owner, repo, data: {...} }`, not a flat object. - `DeploymentEnvironment.upsert` takes its configuration in the PUT body only; an `owner` or `repo` in the config now dies instead of silently overriding the target. - `uploadAsset` uses a private channel: a spread client that overrides `requestDecoded` no longer sees uploads. A hand-built `ReleaseInfo` with an empty, relative or foreign `uploadUrl` now fails as rejected. - GraphQL variables named `query`, `method` or `url` are now sent as variables, in the POST body; the abort signal now reaches GraphQL calls. - The test doubles (`makeTest`, `layerTest`, `layerFixture`) refuse the same request options and any route off `api.github.com`, even in GHES-simulating suites. Refused calls are not recorded in `fixtures.requested`. ### Features - `repositoryPatch(draft, { extra })` sends extras verbatim while the draft stays type-checked, and `applySettings(settings, { unknownKeys: "send" })` forwards undescribed settings keys, reported in `AppliedSettings.unverified` (#1115). - Interrupting `paginate` aborts the in-flight page. ### Bug Fixes #### Security: request-option injection - `updateSettings` and `applySettings` spread an open settings map beside octokit's request options, so a key such as `baseUrl`, `headers` or `request` could send the authenticated PATCH to another host with the token attached. Settings now travel as octokit's `data` body. `repositoryPatch` throws a `RangeError` for a reserved name or `__proto__`, and `applySettings` reports one in `ignored`. #### Security: token confined to the configured base - The configured token is only sent to the configured base. Routes that resolve elsewhere, absolute-URL routes and pagination `Link` headers pointing to another origin are refused. #### Security: GHES upload host - On GitHub Enterprise Server the release-asset upload host is derived from the configured base, so the token is no longer sent to `uploads.github.com`. #### Security: credential-free error causes - `GitHubError` and `GitHubGraphQLError` keep a scrubbed copy of the cause: no request body, options, `set-cookie`, response data or GraphQL data and errors. `instanceof` still holds but object identity does not. `@effected/github` now depends on `@effected/crypto`. [#1151][#1151] * Release-asset uploads through `GitHubApp.clientLayer` and `appClientLayer` clients go to the upload host (`uploads.github.com`, or `/api/uploads` on GHES) with the current installation token, also after a token rotation. They were sent to the API host, and refused on GHES. [#1151][#1151] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/crypto | dependency | updated | 0.2.1 | 0.3.0 | | @effected/github-references | dependency | updated | 0.11.0 | 0.12.0 | | @effected/jwt | dependency | updated | 0.6.0 | 0.7.0 | | @effected/oidc | dependency | updated | 0.1.2 | 0.2.0 | | @effected/semver | dependency | updated | 0.18.0 | 0.19.0 | ### Maintenance - Upgrades core Effect library dependencies to v4.0.7 [#1145][#1145] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1145]: https://github.com/spencerbeggs/effected/pull/1145 [#1151]: https://github.com/spencerbeggs/effected/pull/1151 ## 0.25.1 ### Maintenance - Bump ocx-parser ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! ## 0.25.0 ### Breaking Changes #### REST API version pinned on every request - `GitHubClientOptions` and `GitHubAppOptions` take a new `apiVersion` option. Every request now sends `X-GitHub-Api-Version`, defaulting to `2026-03-10`, and the value in effect is readable as `client.apiVersion`. A per-call override still wins. The option must be a `YYYY-MM-DD` calendar version. Closes #364. - **Migration:** GitHub Enterprise Server releases that predate `2026-03-10` reject that version. Set `apiVersion` to one your server supports. Behaviour that depends on the version follows the pin: - `dispatchWithRun` sends `return_run_details` only when `apiVersion` predates `2026-03-10`. Later versions return run details without it. - Uninstalling an app answers `202` under the new version. #### `mergeCommitSha` comes from GraphQL - The REST pull request object no longer carries a merge commit, so `PullRequestInfo.mergeCommitSha` is now read from GraphQL `mergeCommit.oid`. It is present only once the pull request is merged. `get`, `update` and `upsert` always fill it. `list` and `listAssociatedWithCommit` fill it only when you pass `mergeCommits: true`, at one GraphQL call per 100 merged pull requests. All five methods can now fail with `GitHubGraphQLError`. Closes #364. - **Migration:** pass `mergeCommits: true` to `list` or `listAssociatedWithCommit` where you read `mergeCommitSha`, and handle `GitHubGraphQLError` on those calls. #### `applySettings` drops keys REST does not accept - `AppliedSettings` gains a required `ignored` array next to `rest` and `graphql`. It names the keys neither API accepts, a typo for example. Those keys are no longer sent: the REST `PATCH` would ignore them and still answer `200`. The accepted REST keys come from GitHub's OpenAPI description, and a key a later API version removed is ignored only for a client pinned at or past that version. Closes #376. - **Migration:** code that builds or matches `AppliedSettings` values must account for `ignored`. ### Features #### Repository topics - `GitHubRepository.topics` reads a repository's topics. `setTopics(names)` replaces the whole set and returns the names GitHub stored, which GitHub lowercases. Closes #359. [#1098][#1098] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.17.0 | 0.18.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1098]: https://github.com/spencerbeggs/effected/pull/1098 ## 0.24.0 ### Breaking Changes #### Unstubbed test-double members die when run - In every `makeTest` double, an unstubbed member now returns `Effect.die(...)` evaluated when the effect runs, rather than throwing synchronously when the member is called. `GitHubClient.makeTest().paginateStream` returns `Stream.fromEffect` of the die. Code that relied on a synchronous throw (for example `assert.throws`) must run the effect and assert on the defect. - The defect message now names the member and the override to pass, for example "`GitHubRepository.makeTest`: `get()` was called but not stubbed — pass a `get` override." Value members read "was read but not stubbed" in the same form. #### `ActionsOidc` and `GitHubFixtures` are static classes - Both were typed const objects and are now classes with static members (`ActionsOidc` has a private constructor). Members are unchanged: `ActionsOidc.issuer`, `verify`, `testClaims`, and `GitHubFixtures.failure`. `typeof ActionsOidc` and `typeof GitHubFixtures` change, and the API model kind moves from Variable to Class. [#1091][#1091] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.16.0 | 0.17.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1091]: https://github.com/spencerbeggs/effected/pull/1091 ## 0.23.1 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/jwt | dependency | updated | 0.5.0 | 0.6.0 | | @effected/oidc | dependency | updated | 0.1.1 | 0.1.2 | | @effected/semver | dependency | updated | 0.15.0 | 0.16.0 | ## 0.23.0 ### Features #### `ActionsOidcClaimsFromWire` - New export: a schema that decodes the wire form of a GitHub Actions OIDC token payload (GitHub's own snake_case claim names) into `ActionsOidcClaims`, and encodes it back. `@effected/github-actions` uses it to read and mint tokens. ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/oidc | dependency | updated | 0.0.0 | 0.1.0 | ### Maintenance - `ActionsOidc.verify` is now built on `Oidc.verify` from `@effected/oidc`. Its API and behaviour are unchanged. [#1051][#1051] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1051]: https://github.com/spencerbeggs/effected/pull/1051 ## 0.22.0 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.10.0 | 0.11.0 | | @effected/jwt | dependency | updated | 0.4.0 | 0.5.0 | | @effected/semver | dependency | updated | 0.14.0 | 0.15.0 | ### Maintenance - Upgrades core Effect library dependencies to v4.0.6 [#1039][#1039] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1039]: https://github.com/spencerbeggs/effected/pull/1039 ## 0.21.0 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.9.0 | 0.10.0 | | @effected/jwt | dependency | updated | 0.3.0 | 0.4.0 | | @effected/semver | dependency | updated | 0.13.0 | 0.14.0 | ### Maintenance - Upgrades core Effect library dependencies to v4.0.5 [#1019][#1019] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1019]: https://github.com/spencerbeggs/effected/pull/1019 ## 0.20.0 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.8.0 | 0.9.0 | | @effected/jwt | dependency | updated | 0.2.0 | 0.3.0 | | @effected/semver | dependency | updated | 0.12.0 | 0.13.0 | ### Maintenance - Upgrades core Effect library dependencies to v4.0.4 [#1008][#1008] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1008]: https://github.com/spencerbeggs/effected/pull/1008 ## 0.19.0 ### Features #### Single-flight installation tokens - `GitHubApp.cachedToken` now single-flights concurrent misses per installation within one process, through a new `GitHubAppShape.cachedToken` member built with the layer (`makeTest` honours an override). Closes #999. - Joiners receive the new `CachedToken.source` value `"joined"`; the union is now `"cached" | "minted" | "joined"`. - A failed mint fails every waiter with the same `GitHubAppError` and releases the key. - Interrupting the leader leaves the mint running for waiters. - The key is the installation id only. Cross-isolate double-minting remains accepted. [#1000][#1000] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.7.1 | 0.8.0 | | @effected/jwt | dependency | updated | 0.1.1 | 0.2.0 | | @effected/semver | dependency | updated | 0.11.1 | 0.12.0 | | effect | peerDependency | updated | 4.0.2 | ^4.0.3 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#1000]: https://github.com/spencerbeggs/effected/pull/1000 ## 0.18.0 ### Breaking Changes - `CheckRunRef.status` is now the `CheckRunStatus` literal set, not `string`. A double that builds a ref from an arbitrary string no longer type-checks. - A response whose status or conclusion falls outside the documented sets now fails `create`, `get` and `findByExternalId` with a `decode` `GitHubError` instead of passing an unknown string through. [#997][#997] ### Features #### A full check-run read model - `CheckRunRef` now carries what GitHub reports about a run. Every new field is optional, so a double built with `CheckRunRef.make({ id, name, url, status })` stays valid. - `headSha`, `nodeId`, `startedAt`, `completedAt`, `detailsUrl` and `checkSuiteId`. - `conclusion`, typed by the new `ReportedCheckConclusion`: the write set plus `stale`, which only GitHub sets. - `output`, a new `ReportedCheckRunOutput` with `title`, `summary` and `annotationsCount`. It never carries the long-form text. - `apiUrl` (the REST URL) and `htmlUrl` (the web URL with GitHub's `null` kept). `url` still means the web URL, `""` when GitHub sent none. #### Returning variants and a commit listing on `CheckRun` - `updateRef` and `completeRef` send the same PATCH as `update` and `complete` and answer the decoded `CheckRunRef`. `update` and `complete` still discard the response, so doubles that stub them with `Effect.void` keep compiling. - `list(ref, { checkName?, appId?, status?, filter?, page? })` reads the check runs on a commit, filtered on GitHub's side and paginated. #### `AuthenticatedApp` - A new resource service for the app-level routes, provided over `GitHubApp.appClientLayer`: - `get()` reads `GET /app` into `AppInfo` (`id`, `slug`, `name`, `nodeId`, `clientId`, `htmlUrl`). - `deliveries({ status?, page? })` is a lazy `Stream` over the webhook delivery log, so `Stream.takeWhile` stops it without fetching further pages. - `delivery(id)`, `redeliver(id)` and `uninstall(installationId)`. - Delivery, installation and repository ids decode as safe integers. An id past 2^53 fails the read with a `decode` error instead of being rounded to a different id. #### `GitHubApp.botUser` - `botUser({ slug, installationToken? })` reads the app's bot user into `BotUser` (`id`, `login`). Where `identity` leaves out the id when the lookup fails, `botUser` fails with `kind: "identity"`. ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.7.0 | 0.7.1 | | @effected/jwt | dependency | updated | 0.1.0 | 0.1.1 | | @effected/semver | dependency | updated | 0.11.0 | 0.11.1 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#997]: https://github.com/spencerbeggs/effected/pull/997 ## 0.17.0 ### Features #### `WorkflowDispatch.dispatchWithRun` - Dispatches a workflow and reports the run it created, using GitHub's `return_run_details` request field. It answers `Option`, where `DispatchedRun` (newly exported) carries `runId`, `runUrl` and `htmlUrl`. - A 204 is `Option.none()`, not a failure. That is what a GitHub Enterprise Server that predates the field answers. - A 200 body that is not run details fails with a `decode` `GitHubError`. - Request errors such as 404 and 422 pass through unchanged. - `dispatch` is unchanged and never sends `return_run_details`. #### `dispatchAndWait` follows the exact run - When GitHub reports the run id, `dispatchAndWait` polls that run directly, so concurrent dispatches of the same workflow on the same ref can no longer be confused. On a 204 it falls back to the previous search by time, branch and path. [#986][#986] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#986]: https://github.com/spencerbeggs/effected/pull/986 ## 0.16.0 ### Breaking Changes - `CheckRunShape` changed: the `update` output is optional, `complete` takes options, and `findByExternalId` is new. `WorkflowDispatchShape` gained `cancelRun`. Hand-written implementations of these shapes must be updated; calls through `CheckRun` and `WorkflowDispatch` are source-compatible. - RSA App private keys under 2048 bits are refused with a `GitHubAppError` of `kind` `"jwt"`. - `getFile` fails with a typed `decode` error when the content is not standard padded base64, and a check-run response missing required fields fails as a typed `decode` error. ### Features #### App authentication - `GitHubApp.appClientLayer` builds a client authenticated as the App itself, for endpoints that take the App JWT rather than an installation token. - `GitHubApp.cachedToken` and `GitHubApp.cachedClientLayer` cache installation tokens, backed by the new `InstallationTokenStore` seam. - `Installation` gains `suspendedAt`, `accountType`, `accountId` and `updatedAt`. They are read leniently, so a response without them still decodes. #### Actions OIDC verification - `ActionsOidc.verify` checks a GitHub Actions OIDC token against GitHub's published keys and returns the decoded `ActionsOidcClaims`. #### Errors and fixtures - `GitHubError.fromResponse` classifies an HTTP response into a `GitHubError`. It requires `nowMillis`. - `GitHubFixtures.failure` scripts a failing call in tests. #### Check runs and workflow runs - `CheckRun.create`, `update` and `complete` take richer options, and `CheckRun.findByExternalId` finds a check run by its external id. - `WorkflowDispatch.cancelRun` cancels a workflow run. ### Bug Fixes - PKCS#1 App keys now work on every runtime, and keys with escaped `\n` line breaks are accepted. - Concurrent credential rotation now rotates once instead of once per caller. ### Build System - The App JWT is now signed by `@effected/jwt`, and no `Buffer` is used on the request path, so `nodejs_compat` is no longer needed on Cloudflare Workers. [#984][#984] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | universal-github-app-jwt | dependency | removed | ^2.2.2 | — | | @effected/jwt | dependency | added | — | 0.1.0 | [#984][#984] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#984]: https://github.com/spencerbeggs/effected/pull/984 ## 0.15.1 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @octokit/plugin-paginate-rest | dependency | updated | ^15.0.0 | ^16.0.0 | [#933][#933] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#933]: https://github.com/spencerbeggs/effected/pull/933 ## 0.15.0 ### Breaking Changes - The kit now builds on and peers stable `effect` `^4.0.0`, in place of an exact release-candidate pin. Move `effect` and every `@effect/*` package to the same `4.x` version in one install: Effect releases them together at one version. A package from this release cannot share an install with an `effect` release candidate. The peer is a caret range, so later `4.x` releases of Effect satisfy the kit without a kit release. - Kit exports are unchanged. A consumer moving to stable `effect` meets these changes in its own code: - `Array`, `Chunk`, `Effect` and `Record` `partition`, their `separate` helpers and `Option.partitionMap` return `[successes, failures]`. Where both sides share a type, the reversed destructuring still compiles, so search for every call. - `Schema.brand` takes one identifier and is type-only: the identifier is not stored on the AST and does not survive `SchemaRepresentation`. Compose distinct brands by applying `brand` more than once. - `TestSchema`'s round-trip assertion is `verifyRoundTrip`, with Effect forms `succeedEffect`, `failEffect` and `verifyRoundTripEffect`. - Effect marks some APIs `@stability unstable`: those may change in a minor Effect release. Untagged APIs follow semver. ### Documentation - Every exported construct's TSDoc was reviewed against the current API. Summaries open with what the construct does, error channels and requirements are stated, examples use real imports and compile, and links resolve. Comments that described options, errors or defaults the code does not have were corrected. [#910][#910] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.6.0 | 0.7.0 | | @effected/semver | dependency | updated | 0.10.1 | 0.11.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#910]: https://github.com/spencerbeggs/effected/pull/910 ## 0.14.0 ### Breaking Changes - The kit now builds on and peers `effect` `4.0.0-rc.118`, pinned exactly. Consumers must move `effect` and every `@effect/*` package to `4.0.0-rc.118` in the same install. Effect removed the `effect/unstable/*` export paths in this release, so an `@effected` package built on rc.118 cannot share an install with `effect` rc.117. - Moving the pin also closes a fresh-install failure on rc.117. `@effect/platform-node@4.0.0-rc.117` depends on `@effect/platform-node-shared` with a caret, so an install without a lockfile paired the rc.118 shared package with `effect` rc.117 and failed at startup with `ERR_MODULE_NOT_FOUND`. - Consumers moving to this release: effect removed the `effect/unstable/*` export paths (imports become `effect/`), moved `Arbitrary` to `effect`, split `effect/Encoding` into `effect/encoding/Base64`, `Base64Url` and `Hex`, and renamed the `Schema` range and string checks (`isLengthBetween` → `isBetweenLength`, `isStartsWith` → `isStartingWith`, and so on). Kit exports are otherwise unchanged; the kit's own imports moved onto the new paths. [#864][#864] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.5.0 | 0.6.0 | | @effected/semver | dependency | updated | 0.9.0 | 0.10.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#864]: https://github.com/spencerbeggs/effected/pull/864 ## 0.13.0 ### Features #### Structured 422 validation entries - `GitHubError` now carries GitHub's validation entries, so a caller can branch on a 422's cause without matching `reason` text. - `validation` holds each `data.errors[]` entry as a `GitHubValidationEntry` (`resource`, `field`, `code`, `message`, all optional). It is absent when GitHub sent no `errors` array. - `GitHubValidationCode` lists the six codes GitHub documents: `missing`, `missing_field`, `invalid`, `already_exists`, `unprocessable` and `custom`. A code outside that set is still carried. - `GitHubError.hasValidationCode(...codes)` is a predicate for `Effect.catchIf`, alongside `hasKind`. ```ts import { GitHubError } from "@effected/github"; import { Effect } from "effect"; declare const create: Effect.Effect; const tolerant = create.pipe( Effect.catchIf(GitHubError.hasValidationCode("missing_field"), () => Effect.void), ); ``` - `already_exists` is the only code with its own `kind`; the other five classify as `rejected`. `missing` refers to a resource the request pointed at, such as a commit SHA, not the resource being acted on, so it stays out of `notFound`. ### Bug Fixes - A 422 or 409 whose validation entries carry `code: "already_exists"` now classifies as `alreadyExists` even when no message says so. Creating a release for a tag that already has one returns exactly that shape. It was classified as `rejected`, so `catchIf(GitHubError.hasKind("alreadyExists"), ...)` fallbacks never ran. [#825][#825] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#825]: https://github.com/spencerbeggs/effected/pull/825 ## 0.12.0 ### Features - Upgrades core Effect to `rc-117` [#812][#812] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.4.0 | 0.5.0 | | @effected/semver | dependency | updated | 0.8.0 | 0.9.0 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#812]: https://github.com/spencerbeggs/effected/pull/812 ## 0.11.0 ### Breaking Changes #### The whole kit tracks Effect `4.0.0-rc.116` - Every package's `effect` peer moves from `4.0.0-rc.115` to `4.0.0-rc.116`. The kit uses exact prerelease pins rather than a caret, so a consumer must move with it. No `@effected` API changes shape on this advance; the kit itself needed one edit (`Stream.scan` now takes a lazy initial state, met once in `@effected/jsonl`'s `Journal.projection`). A consumer that upgrades meets the rc.116 renames on its own code: - `SchemaTransformation.make` is `makeTransformation`, and `Transformation#compose` is the dual standalone `SchemaTransformation.composeTransformation`. - `SchemaGetter.Getter` is a tagged union exposing only `pipe`: `new SchemaGetter.Getter`, `onSome` and `onNone` are gone in favour of `SchemaGetter.map` / `compose` / `run` and `transformEffect` / `transformOptionalEffect`. - `Stream.scan` and `Stream.scanEffect` take `() => initial`; `Stream.partition` returns `[passes, fails]`; `Stream.mapBoth` takes `onElement` / `onError`. - `Effect.orElseSucceed` passes the error to its fallback and `Effect.isEffect` narrows to `Effect`. - `ByteSize.Input` string literals are checked at compile time; parse external strings with `ByteSize.fromString`. - Arbitrary shrinking changed, so property-test replay tokens recorded at rc.115 no longer reproduce. ### Documentation #### The Claude Code and Copilot plugins teach the rc.116 surface - The `effect-v4-schema` transformation reference composes transformations with `SchemaTransformation.composeTransformation` and describes the `Getter` surface rc.116 left behind; the source-lookup and testing skills report rc.116 as the kit's pin and the two-copy lockfile shape the bridge now produces (`rc.115` for the toolchain, `rc.116` for the kit); the session-start briefing reports rc.116. ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.3.1 | 0.4.0 | | @effected/semver | dependency | updated | 0.7.1 | 0.8.0 | | @effect/platform-node | devDependency | updated | 4.0.0-rc.115 | 4.0.0-rc.116 | | @effect/vitest | devDependency | updated | 4.0.0-rc.115 | 4.0.0-rc.116 | | effect | devDependency | updated | 4.0.0-rc.115 | 4.0.0-rc.116 | | effect | peerDependency | updated | 4.0.0-rc.115 | 4.0.0-rc.116 | ### Maintenance #### The rc.115 `packageExtensions` bridge is retired - The toolchain (`@savvy-web/tsdown-plugins`, `rolldown-pnpm-config`, `@vitest-agent/*`) has republished declaring `effect` and its `@effected/*` inputs as regular dependencies, so the workspace no longer needs the `packageExtensions` block that pinned them by hand. Its ten keys named versions no longer installed and the lockfile diff on removal was the checksum line alone. Nothing published changes; this is the workspace's own install shape. [#792][#792] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#792]: https://github.com/spencerbeggs/effected/pull/792 ## 0.10.2 ### Bug Fixes - Fixes closure issues in all packages. ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.3.0 | 0.3.1 | | @effected/semver | dependency | updated | 0.7.0 | 0.7.1 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! ## 0.10.1 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @octokit/types | dependency | updated | ^17.0.0 | ^18.0.0 | [#699][#699] ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#699]: https://github.com/spencerbeggs/effected/pull/699 ## 0.10.0 ### Breaking Changes #### The whole kit tracks Effect `4.0.0-rc.115` - Every package's `effect` peer moves from `4.0.0-rc.112` to `4.0.0-rc.115`. The kit uses exact prerelease pins rather than a caret, so a consumer must move with it. This advance is the first whose Effect changes are not source-compatible with the previous pin, so a consumer that upgrades meets the same renames the kit did: - `SchemaTransformation.transformOrFail` and `SchemaGetter.transformOrFail` are `transformEffect`. - The `Config` constructors are PascalCase (`Config.String`, `Config.Redacted`, `Config.Int`, `Config.Boolean`, …) and `Config.mapOrFail` is `Config.mapEffect`. - `FileSystem.Size` and `FileSystem.SizeInput` are gone in favour of the `ByteSize` module: `File.Info.size` is a `ByteSize`, `File.seek` takes a `bigint`, `read`/`write` return a `number`. - The fast-check bridge (`effect/testing/FastCheck`, `Schema.toArbitrary`, the `fastCheck` property-test option) is removed in favour of `effect/unstable/arbitrary/Arbitrary`; `it.effect.prop` takes `arbitrary: { runs, size, seed, … }`. #### `@effected/schemastore` documents are open unless told otherwise - `Schema.ToJsonSchemaOptions.additionalProperties` became `onExcessProperty: "ignore" | "error"` upstream, and its default now mirrors the decoder's: generated object schemas carry `additionalProperties: true` unless `jsonSchema: { onExcessProperty: "error" }` is passed. `StoreDocument.fromSchema` passes the option through unchanged, so a document that was closed by default at rc.112 is open by default now. Pass `onExcessProperty: "error"` to keep a closed document; a generator that silently disagreed with the decoder it is paired with would be the worse default. #### `@effected/memfs` seeks before the start of a file fail - `File.seek` gained a `PlatformError` channel upstream, and memfs now matches Node: a seek whose resulting position would be negative fails with `BadArgument` ("Cannot seek before the start of the file") and leaves the cursor unchanged, where it previously stored the negative position and failed on the next read. No memfs-declared type changes; the `File`/`File.Info` shape changes are Effect's own, reaching consumers through the peer. ### Documentation #### A `Schema.Class` root is annotated on the `Struct` it wraps - [Effect-TS/effect#8084](https://github.com/Effect-TS/effect/issues/8084), which the rc.112 notes carried as an open limitation, was closed upstream as by design: annotations passed as `Schema.Class`'s second argument sit on the class node, while the `$defs` entry is generated from the encoded fields `Struct`. Annotate that `Struct` — `Schema.Class("X")(Schema.Struct({ … }).annotate({ title, description, "x-taplo": … }))` — and every key reaches the document. `@effected/schemastore`'s design doc and context files now state the rule instead of the limitation. #### The Claude Code and Copilot plugins teach the rc.115 surface - The `effect-v4-schema`, `effect-v4-testing` and `effect-v4-module-index` skills describe the native `Arbitrary` module in place of the fast-check bridge, including the migration traps met on this advance: the `size` clamp (default 10) that silently shrinks a property's string and array domains, the `-0` the generator's near-zero bias emits for an unbounded `Schema.Int` or any `Schema.Number`, which JSON and YAML cannot round-trip, and the absence of `oneof`/`constantFrom`/`array` combinators. `ByteSize` has a module-index row, the `Config` and CLI constructors are shown in their PascalCase spellings, and the session-start briefing reports rc.115 as the kit's pin. [#686][#686] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.2.0 | 0.3.0 | | @effected/semver | dependency | updated | 0.6.0 | 0.7.0 | | @effect/platform-node | devDependency | updated | 4.0.0-rc.112 | 4.0.0-rc.115 | | @effect/tsgo | devDependency | updated | 0.41.0 | 0.45.0 | | @effect/vitest | devDependency | updated | 4.0.0-rc.112 | 4.0.0-rc.115 | | effect | devDependency | updated | 4.0.0-rc.112 | 4.0.0-rc.115 | | effect | peerDependency | updated | 4.0.0-rc.112 | 4.0.0-rc.115 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#686]: https://github.com/spencerbeggs/effected/pull/686 ## 0.9.0 ### Breaking Changes #### `@effected/schemastore` no longer ships `AnnotationCarriers` - `AnnotationCarriers` and `CarrierDepthExceededError` are removed, and the module is deleted. - Effect `4.0.0-rc.112` ("Make JSON Schema dialect conversions preserve custom keywords") changed the Draft-07 lowering to carry unknown and custom keywords through as opaque values, in place — including across the tuple coordinate moves (`prefixItems[i]` to `items[i]`, and a trailing `items` to `additionalItems`). The post-lowering re-graft those symbols performed is therefore redundant, and **emitted documents are unchanged**. - If you imported either symbol, delete the call: annotate a schema node and the key now reaches the document on its own. #### `StoreDocument` and `SchemaPipeline` error channels are wider - `StoreDocument.fromSchema`, `StoreDocument.fromSchemaResult`, and `SchemaPipeline.run` / `check` / `runOne` / `checkOne` can now fail with `UndeclaredAnnotationKeyError`. Callers matching exhaustively on the error channel need one new branch. ### Features #### `@effected/schemastore` refuses undeclared annotation keys instead of dropping them - `StoreDocument.fromSchema` now fails with the new `@public` `UndeclaredAnnotationKeyError` — carrying the document's `$id` and every offending key — when a caller-supplied `includeAnnotationKey` admits a key outside the declared keyword families (the vscode set, `x-taplo`, `x-tombi-*`, `x-intellij-*`, `x-ai-*`). - Previously such keys were admitted into the Draft 2020-12 document and silently discarded by the Draft-07 lowering, so the package's compatibility guarantee was really a side effect of a dependency's behavior. Since rc.112 no longer discards them, that guarantee is now enforced by the package itself — and enforced loudly, because a caller who asks for a key and silently does not get it has no way to notice. - Declared families are still admitted unconditionally, regardless of the caller's predicate. ```ts // Fails: UndeclaredAnnotationKeyError, keys: ["x-custom"] yield* StoreDocument.fromSchema(schema, { $id: "https://example.com/schemas/tool.json", jsonSchema: { includeAnnotationKey: (key) => key === "x-custom" }, }); ``` #### The whole kit tracks Effect `4.0.0-rc.112` - Every package's `effect` peer moves to the new pin. The kit uses exact prerelease pins rather than a caret, so a consumer must move with it. ### Bug Fixes - `@effected/schemastore`: the `#/definitions` to `#/$defs` `$ref` rewrite no longer descends into declared-family annotation values. A `$ref`-shaped string inside an `x-taplo` or `x-ai-*` payload is opaque advice addressed to a language server, and was being rewritten in transit. - A known limitation, still open upstream as [Effect-TS/effect#8084](https://github.com/Effect-TS/effect/issues/8084): a `Schema.Class`'s class-level annotations — `title` and `description` as well as the declared families — never reach the emitted document, because core generates the definition from the class's encoded AST. A hoisted `Schema.Struct` keeps its annotations. Annotate a `Schema.Struct` root instead. ### Documentation #### The Claude Code and Copilot plugins are Effect v4 only - The v3-to-v4 migration material is retired: the `effect-migrator` agent and the `effect-v4-construct-map` skill are removed, along with the migration framing that ran through the remaining skills. The facts underneath it are kept, restated as statements of what v4 is rather than what changed. - The SessionStart briefing now states plainly that an agent's recall of Effect is out of date by construction, and routes it to the specialist agents or the skills rather than to a guess. It also reports whether the repo vendors Effect source at `.repos/effect` and whether that pin matches the kit's — a stale vendored tree is worse than none, because it answers confidently and wrongly. - Several skill claims were re-measured against rc.112 and corrected, including one whose stated mitigation pointed at the wrong signal: for a zero-collection vitest run it is the `Tests: 0/0 passed` line that lies, while the exit code is honest. [#623][#623] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | updated | 0.1.0 | 0.2.0 | | @effected/semver | dependency | updated | 0.5.1 | 0.6.0 | | @effect/tsgo | devDependency | updated | 0.36.5 | 0.41.0 | | @effect/vitest | devDependency | updated | 4.0.0-rc.109 | 4.0.0-rc.112 | | effect | devDependency | updated | 4.0.0-rc.109 | 4.0.0-rc.112 | | effect | peerDependency | updated | 4.0.0-rc.109 | 4.0.0-rc.112 | ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#623]: https://github.com/spencerbeggs/effected/pull/623 ## 0.8.0 ### Features - `repositoryPatch` — builds a `RepositoryPatch` from a `RepositoryPatchDraft`, dropping every explicitly-`undefined` field. Solves the `exactOptionalPropertyTypes` mismatch between a settings object built from your own schema (`has_issues: boolean | undefined`) and octokit's generated params (`has_issues?: boolean`, no `undefined`), so a sync action that applies only what was configured no longer needs an `as` cast. [#497][#497] ```ts import { repositoryPatch } from "@effected/github"; // `config.has_issues` is `boolean | undefined`; absent fields drop out. const patch = repositoryPatch({ has_issues: config.has_issues, has_wiki: config.has_wiki, description: config.description, }); ``` ### Thanks Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#497]: https://github.com/spencerbeggs/effected/pull/497 ## 0.7.0 ### Refactoring - The issue-reference grammar (`harvestIssueReferences`, `parseBareLineReference`, `CLOSING_KEYWORDS` and friends) moved to the new `@effected/github-references` package, which `@effected/github` now takes as a regular dependency. The six moved names remain re-exported from this package's entrypoint, so existing consumers keep working with no changes required: ```ts // Still works, unchanged: import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github"; ``` The new closing-list dialect (`parseClosingList`, `parseReferenceList`) added to `@effected/github-references` is deliberately **not** re-exported here — new consumers should import `@effected/github-references` directly, especially those that don't need octokit at all. This compat re-export is droppable at a later bump; the underlying grammar now lives in `@effected/github-references`. ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/github-references | dependency | added | — | 0.0.0 | ## 0.6.1 ### Dependencies - | Dependency | Type | Action | From | To | | | --- | --- | --- | --- | --- | --- | | @octokit/plugin-paginate-rest | dependency | updated | ^14.0.0 | ^15.0.0 | | | @octokit/types | dependency | updated | ^16.0.0 | ^17.0.0 | [#400][#400] Thanks [@spencerbeggs](https://github.com/spencerbeggs)! | [#400]: https://github.com/spencerbeggs/effected/pull/400 ## 0.6.0 ### Features - ### `GitHubIssue.commentOnce` Post a marked comment on an issue exactly once — create it, or skip if it's already there: ```ts import { CommentMarker } from "@effected/github"; const marker = CommentMarker.make({ namespace: "my-action", key: "status" }); const result = yield* issues.commentOnce(42, marker, "Build succeeded."); // result.wrote: true if this call created the comment, false if it already existed // result.comment: the marked comment either way ``` This is create-or-skip, never edit — the counterpart to `PullRequestComment.upsert`, which edits in place. The marker is appended to the body exactly as `upsert` formats it, so either surface can find the other's comment; the existence check paginates the issue's comments looking for it. Closes effected#306. ### `IssueReferences` A new pure module for GitHub's closing-keyword reference grammar — no service, no layer, just strings in and values out: ```ts import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github"; harvestIssueReferences("fixes #12 and closes #13"); // every inline closing reference in the text, in document order, each with its keyword and offsets parseBareLineReference("Closes: #12"); // Option.some({ issueNumber: 12, keyword: "closes" }) — the bare-line dialect, colon optional ``` `harvestIssueReferences` covers the inline-in-prose dialect GitHub itself scans PR bodies for (mandatory whitespace, no colon); `parseBareLineReference` covers a generated references region's one-reference-per-line dialect (colon optional). `CLOSING_KEYWORDS` lists the nine documented keywords both dialects derive from. Closes effected#194. [#397][#397] ### Minor Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#397]: https://github.com/spencerbeggs/effected/pull/397 ## 0.5.0 ### Refactoring - Adopted effect rc.108's relocation of `SchemaError` into the `Schema` module: the GraphQL `decode` signature now types its failure as `Schema.SchemaError`. The error surface is unchanged; no consumer action is required. [#389][#389] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.4.0 | 0.5.0 | | effect | peerDependency | updated | 4.0.0-beta.107 | 4.0.0-rc.109 | ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#389]: https://github.com/spencerbeggs/effected/pull/389 ## 0.4.3 ### Bug Fixes - ### `has_discussions` now routes through GraphQL instead of being silently dropped `GitHubRepository.applySettings` sent `has_discussions` to the REST patch, which ignores unknown fields and answers 200 — so the setting was reported as applied on every run while the repository never changed. It now routes through the GraphQL arm as `hasDiscussionsEnabled` (verified against `UpdateRepositoryInput` by live introspection), alongside `has_sponsorships` and `has_pull_requests`. Also documented: `GitHubIssue.isCrossReferencedBy`'s two guard hazards (issues obtained from `linkedIssues` answer `true` from the outset; sidebar-connected issues without a cross-reference read `false`), and `PullRequestInfo.body`'s wire behavior — present via `get` and `list`, absent (never `""`) when GitHub sends `null` — is now pinned by tests. [#375][#375] ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#375]: https://github.com/spencerbeggs/effected/pull/375 ## 0.4.2 ### Bug Fixes - `GitHubIssue`'s REST calls now pin `x-github-api-version: 2026-03-10`, eliminating the `Deprecation` header warning `@octokit/request` was printing straight to consumer workflow logs under the previous default calendar version. [#366][#366] ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#366]: https://github.com/spencerbeggs/effected/pull/366 ## 0.4.1 ### Documentation - `CodeScanning.configure` now records that turning default setup back to `not-configured` **does not remove the synthetic CodeQL workflow** GitHub created when it was enabled — it stays listed among the repository's workflows. A caller treating "default setup is off" as "no CodeQL workflow exists", or counting workflows to decide whether a repository has CI, will be wrong. Observed against a real organization rather than inferred from the API description. - `RepositoryVariable.set` now states that its 404-for-absent existence check is **documented, not probed** — no suite has issued that read against real GitHub. If the assumption is wrong, every write takes the create branch, so a surprising `alreadyExists` from the `POST` is evidence about the assumption rather than about the caller. [#354][#354] ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#354]: https://github.com/spencerbeggs/effected/pull/354 ## 0.4.0 ### Breaking Changes - An unstubbed route now dies rather than failing typed. A test that asserted `GitHubError.notFound` from an absent fixture sets `unstubbed: "fail"` to keep the old behaviour. `GitHubFixtures.requested` is typed `Array` rather than `Array<{ route, perPage }>`. A test that declares the array with the old inline type needs the new one — the elements now carry `kind` and `params` as well. Assertions that compared whole recorded entries need those two fields added. [#352][#352] ### Features - ### `layerFixture` records every call, with params `GitHubFixtures.requested` previously logged paginated reads only, as `{ route, perPage }`. `request`, `requestDecoded` and `graphql` named their arguments `_params` / `_variables` and appended nothing, so a suite whose methods all go through `request` could assert the route it hit but nothing about what it sent. It now records every surface, as the new `RecordedCall`: ```ts const requested: Array = []; const layer = GitHubClient.layerFixture({ request: { "GET /repos/{owner}/{repo}": data }, requested }); // after the call: // [{ kind: "request", route: "GET /repos/{owner}/{repo}", params: { owner: "acme", repo: "widgets" } }] ``` `kind` distinguishes `request` / `requestDecoded` / `paginate` / `graphql`; `params` carries what the call was made with (GraphQL variables for `graphql`, whose `route` is the document name); `perPage` still appears on paginated reads. This closes the gap that made a consumer hand-roll an \~80-line harness to test resource modules whose every method goes through `request`. ### An unstubbed route now dies instead of failing A route with no fixture entry used to fail with `GitHubError.notFound`. It now **dies**, naming the route — the same treatment an absent `graphql` fixture has always had, and consistent with the rest of the kit's rule that wiring mistakes are defects rather than domain errors. The reason for the change is worth knowing, because a typed failure looks strictly safer: **it is only loud in code that does not catch.** A consumer whose methods each catch `GitHubError` and report it — a per-resource sync, for instance — turns a missing stub into a *different execution path* rather than a failure. The assertions then fail for a new reason, and nothing in any message names a fixture. That cost one consumer 28 tests reading as ordinary logic bugs. Two opt-outs, via the new `unstubbed` field: ```ts GitHubClient.layerFixture({ unstubbed: "fail" }) // the old typed notFound GitHubClient.layerFixture({ unstubbed: "empty" }) // {} for a request, no items for a page ``` Use `"fail"` when the suite's subject *is* 404 handling — though stubbing the 404 explicitly is better. Use `"empty"` for a suite whose subject is decisions rather than endpoints. `graphql` ignores the field and always dies: its payload is decoded against the document's schema, so no empty value would satisfy it. * ### Six repository resource services, and an extension to a seventh Secrets, variables, rulesets, deployment environments, security features and CodeQL default setup — route families this package did not cover at all — plus four settings behaviours folded onto the existing `GitHubRepository`. Ported from `@spencerbeggs/reposets`, restructured onto this package's `Repo`-from-context convention. | Service | Covers | | :-- | :-- | | `GitHubRepository` (extended) | the GraphQL `updateRepository` mutation, `security_and_analysis` folding, dependent-merge-key dropping and `ownerType` — folded into the existing service rather than shipped as a second one | | `RepositorySecret` | Actions / Dependabot / Codespaces / environment secrets, with sealed-box encryption | | `RepositoryVariable` | Actions and environment variables | | `Ruleset` | ruleset CRUD, team-slug and org-role resolution | | `DeploymentEnvironment` | deployment environments | | `RepositorySecurity` | vulnerability alerts, automated fixes, private vulnerability reporting | | `CodeScanning` | CodeQL default setup and repository language detection | No method takes `owner`/`repo`: every one resolves `Repo` per call and carries it in `R`, so `Repo.provide` redirects a program at another repository — the same contract `GitBranch` and its neighbours already keep. ```ts const program = Effect.gen(function* () { const settings = yield* RepositorySettings yield* settings.update({ has_issues: true, has_sponsorships: true }) }) // One program, many repositories. yield* program.pipe(Repo.provide(RepoRef.make({ owner: "acme", repo: "widget" }))) ``` ### Secrets are encrypted client-side, and the value is `Redacted` `RepositorySecret.set` takes a `Redacted.Redacted`, fetches the store's public key and sends a libsodium sealed box; the plaintext never crosses the wire. The single `Redacted.value` unwrap happens at the moment of encryption. `tweetnacl` and `blakejs` are new runtime dependencies, and neither ties this package to Node: `blakejs` is pure JavaScript, and `tweetnacl` feature-detects `getRandomValues` before falling back to Node's `crypto`. The sealing itself uses core's `Encoding` and `TextEncoder`, so **`src` imports no runtime builtin at all**. A public key that is not valid base64 fails as a typed `GitHubError` naming the route it came from, rather than throwing — garbage from the API is input, and input failures are typed. ### `WorkflowDispatch.list` — ask whether a repository has workflows ```ts const workflows = yield* (yield* WorkflowDispatch).list; // ReadonlyArray: { id, name, path, state } ``` Nothing in this package could answer that question before. It matters for CodeQL setup: `actions` is a real CodeQL language, and GitHub validates it against **workflow files** — which repository *languages* can never report, because those come from linguist. A consumer offering CodeQL setup otherwise had to request `actions` blindly and absorb a 422, or drop it for every repository including the ones where it is valid. `state` is GitHub's own string (`active`, `disabled_manually`, …), reported rather than interpreted: whether a *disabled* workflow counts for a given GitHub feature is that feature's server-side rule, which this package cannot test, so it does not encode a guess. Filter on it yourself if you care. A repository with no workflows is an empty array, not a failure. ### `updateSettings` now prepares the patch it sends `GitHubRepository.updateSettings` gained two transformations, so an existing method's behaviour changed: - **`security_and_analysis` is normalised.** A bare `"enabled"` / `"disabled"` is wrapped into the `{ status }` form GitHub requires; an already-wrapped value passes through untouched. Both shapes now work, and a block that is neither is dropped rather than sent. - **Dependent merge keys are dropped when their strategy is disabled.** Sending `merge_commit_title` in the same request that sets `allow_merge_commit: false` is a 422 from GitHub, so those keys now travel only with the strategy that owns them. If you were assembling either shape by hand before calling `updateSettings`, that work is now done for you and doing it yourself is still correct — the wrapped form is passed through, not re-wrapped. ### `applySettings` reports what it sent It now returns `AppliedSettings` — `{ rest, graphql }`, the field names that actually went out — instead of `void`. The reason is a dry run. `applySettings` drops what GitHub would reject, so a caller reporting `Object.keys(desired)` describes its own *intent* while this package decides the *content*. The two agree right up until a field is dropped, which is exactly the case someone reading a plan is checking. Both lists use the caller's key names, not the wire names, because the audience is a person reading the plan against the config they wrote. Deriving the drop rule a second time downstream would be worse than the original mistake, since nothing fails when the copy drifts. ### Bug Fixes - ### List reads were truncated to one page Every list read in the new services — secrets, variables, rulesets, deployment environments, workflows — used a single request, which returns **one page**. A repository with more items than a page holds reported a subset that looked complete. The most consequential was `Ruleset.upsert`: its existence check is what decides create-versus-update, so past the first page an existing ruleset was invisible and an update became a create. `RepositoryVariable.set` had the same shape. All of them paginate now. The symptom to recognise, if you have been reading these listings: the array length disagrees with GitHub's own `total_count`. ### A repository-scoped write can no longer overwrite an organization's ruleset **This is a live defect in `@spencerbeggs/reposets` v3 and anyone running that shape should treat it as a security fix.** `GET /repos/{owner}/{repo}/rulesets` returns rulesets **inherited from the organization** alongside the repository's own. Matching a ruleset by name alone therefore lets a repository-scoped call issue a `PUT` against the **organization's** ruleset id — rewriting policy for *every repository the organization owns*, from a caller that never mentioned the organization and had no intention of changing anything beyond one repository. `Ruleset.upsert` filters on `source_type` before matching, so an inherited ruleset can never be the target of a write. Removing that predicate fails two tests, one of which places the organization's ruleset first in the listing precisely so a `find` without the filter takes it. ### A type-correct `security_and_analysis` is no longer silently dropped Caught in review before this shipped: the first version of the patch preparation above wrapped bare strings only, so a caller passing the shape `RepositoryPatch` actually declares — `{ advanced_security: { status: "enabled" } }`, GitHub's own parameter type — had the entire block discarded on the way out. The request still succeeded, and the setting was never applied. [#352][#352] ### Dependencies - | Dependency | Type | Action | From | To | | | --- | --- | --- | --- | --- | --- | | blakejs | dependency | added | — | 1.2.1 | | | tweetnacl | dependency | added | — | 1.0.3 | [#352][#352] Thanks [@spencerbeggs](https://github.com/spencerbeggs)! | ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#352]: https://github.com/spencerbeggs/effected/pull/352 ## 0.3.0 ### Refactoring - Migrated error classes to Effect's renamed `Schema.TaggedError` (was `Schema.TaggedErrorClass`); the call shape is unchanged and no consumer action is required. [#322][#322] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.3.2 | 0.4.0 | | effect | peerDependency | updated | 4.0.0-beta.101 | 4.0.0-beta.107 | ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#322]: https://github.com/spencerbeggs/effected/pull/322 ## 0.2.3 ### Documentation - `PullRequest.list` now documents that its `head` option accepts either a qualified `owner:ref` or a bare `ref`, which is qualified with the current repo's owner automatically. For a pull request opened from the current repository, feeding `PullRequestInfo.head` — the bare ref — straight back into the filter round-trips correctly, so consumers filtering client-side to work around the raw REST route no longer need to. The docs also state the limit: `PullRequestInfo` drops the source owner, so the round trip does not hold for a fork-originated pull request, where qualifying with the current owner names a branch in the wrong account and matches nothing. - `GitTag.latestSemver` now states that "newest" means highest version, not most recent, and that it is the wrong instrument for a monorepo publishing independently versioned packages. Version ordering and recency are unrelated there, so the result can sit several releases behind the head and never move, with nothing visible to signal it. Filter by the package's tag prefix instead. - `PullRequestInfo` and the private `RawPull` wire interface now cross-reference each other, naming which is the domain shape and which is what GitHub answers with. The two differ in exactly the places that matter (`head`/`headSha` versus a nested `head: { ref, sha }`, `url` versus `html_url`). [#268][#268] ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.3.1 | 0.3.2 | - | Dependency | Type | Action | From | To | | | --- | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.3.1 | 0.3.2 | Thanks [@spencerbeggs](https://github.com/spencerbeggs)! | ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#268]: https://github.com/spencerbeggs/effected/pull/268 ## 0.2.2 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.3.0 | 0.3.1 | ### Maintenance - Switching internal dependency versioning from `~` to `^` ranges. ### Patch Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! ## 0.2.1 ### Dependencies | Dependency | Type | Action | From | To | | --- | --- | --- | --- | --- | | @effected/semver | dependency | updated | 0.2.1 | 0.3.0 | ## 0.2.0 ### Breaking Changes - ### `PullRequest.listFiles` returns full file records `listFiles` used to project each changed file down to its path. It now returns the same `CommitFile` shape `GitHubCommit.changedFiles` does — path, status, line counts and any pre-rename path — because GitHub answers both endpoints with the same `diff-entry` payload. ```ts // Before const paths: ReadonlyArray = yield* pullRequest.listFiles(42); // After const files: ReadonlyArray = yield* pullRequest.listFiles(42); const paths = files.map((file) => file.path); ``` ### `PullRequestInfo` carries the branch shas `PullRequestInfo` gains two required fields: `headSha` and `baseSha` — the commits `head` and `base` pointed at when GitHub answered. `baseSha` answers "which commit did this pull request branch from" without a second call. Any code constructing a `PullRequestInfo` by hand must supply both. ### `CommitSummary` carries `parents` `CommitSummary` gains a required `parents: ReadonlyArray` field — the parent commit shas in GitHub's order, empty for a root commit and two or more for a merge commit. Any code constructing a `CommitSummary` by hand must supply it. ### `ArtifactMetadata.createStorageRecord` no longer takes a positional `org` The organization is now resolved from `Repo`'s `owner`, the same way every other resource on this surface reads it — `createStorageRecord` was the one method that took `org` positionally instead. `Repo` is required in `R`; `Repo.provide` covers the cross-org case. ```ts // Before yield* artifactMetadata.createStorageRecord(org, input); // After yield* artifactMetadata.createStorageRecord(input); // Repo required in R ``` ### Features - `BotIdentity` gains a `signoff` getter rendering the DCO 1.1 sign-off trailer — `Signed-off-by: ` — from the type that owns the data. Commits created through the Git Data API bypass `git commit -s`, so the trailer has no porcelain to come from, and a hand-built one that is subtly wrong surfaces late as a red DCO check on someone else's pull request. Whether a missing identity falls back to `BotIdentity.githubActions` stays the caller's policy. ### Bug Fixes - `GitHubRelease.uploadAsset` now carries the asset `name` in the route template. The release-asset route is the one route outside GitHub's generated endpoint map, so no schema told octokit that `name` is a query parameter — passed only as a parameter it was silently dropped, GitHub answered `400 Invalid name for request`, and every release asset upload failed quietly. The member also gains the endpoint's optional `label` (the display label shown in place of the file name on the release page). ### Documentation - `GitBranch.upsert`'s remarks now warn about a live incident: resetting a branch to its pull request's base makes that PR's head equal its base for a window, and GitHub **auto-closes a PR whose diff is empty**. A consumer that means to end at "target head plus a commit" should build the commit first — `GitCommit.get` the target for its tree sha, `createTree`, `createCommit` with the target as parent — and `upsert` once, straight to the finished sha. `GitCommit.commitFiles`'s remarks now state plainly that it commits onto a branch you own, not a rebase, and spell out the atomic composition — `get`, `createTree`, `createCommit`, `upsert` — that moves the ref once with no observable intermediate state. Sequencing `upsert(branch, targetHead)` followed by `commitFiles` is the hazardous two-step above written a different way: an open pull request from that branch sees an empty diff in the window between the two calls and GitHub can close it out from under a run that otherwise reports success. [#191][#191] ### Minor Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#191]: https://github.com/spencerbeggs/effected/pull/191 ## 0.1.0 ### Features - First release. Typed GitHub REST and GraphQL over octokit's core request surface, with GitHub App authentication and a set of resource services. ### The route is the key — no casts ```ts import { GitHubClient } from "@effected/github"; import { Effect } from "effect"; const defaultBranch = Effect.gen(function* () { const client = yield* GitHubClient; const repo = yield* client.request("GET /repos/{owner}/{repo}", { owner: "o", repo: "r" }); return repo.default_branch; // string — no cast, no hand-written interface }); ``` `client.request(route, params)` types both the parameters and the returned data from the route literal alone; a route outside the generated map goes through `requestDecoded(route, params, schema)`, where the schema is mandatory. One paginating engine backs every paginated read. ### Resource services `GitBranch.upsert`, `GitTag.latestSemver` / `.upsert`, `CheckRun.withCheckRun` (with `conclude`), `PullRequest` / `PullRequestComment` upserts, `GitHubRelease`, `ArtifactMetadata`, `Attestation`, `GitHubCommit`, `GitHubContent`, `GitHubIssue`, `GitHubRepository` and `WorkflowDispatch` round out the typed surface over the raw request primitive. ### Errors and auth One `GitHubError` covers every REST resource, with a `kind` for routing and `hasKind` for narrowing; `kind: "alreadyExists"` is what makes an upsert implementable without a second existence check. `GitHubGraphQLError` covers GraphQL, and `GitHubApp` mints installation tokens (`GitHubAppError` on failure) without pulling in `@octokit/auth-app`'s OAuth machinery. [#180][#180] ### Minor Changes Thanks to [@spencerbeggs](https://github.com/spencerbeggs) for their contributions! [#180]: https://github.com/spencerbeggs/effected/pull/180