@effected/github 0.29.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts CHANGED
@@ -398,6 +398,16 @@ declare const GraphQLErrorEntry_base: Schema.Class<GraphQLErrorEntry, Schema.Str
398
398
  readonly message: Schema.String;
399
399
  /** GitHub's own classification, e.g. `"NOT_FOUND"` or `"FORBIDDEN"`. */
400
400
  readonly type: Schema.optionalKey<Schema.String>;
401
+ /**
402
+ * Where in the response the entry applies: field names (aliases, when the
403
+ * document aliases) and list indexes, outermost first.
404
+ *
405
+ * @remarks
406
+ * This is what tells a batched document which aliased lookup GitHub could
407
+ * not resolve: a missing pull request in a batch reports
408
+ * `["repo__0", "pull__42"]`, a missing repository `["repo__0"]`.
409
+ */
410
+ readonly path: Schema.optionalKey<Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>>;
401
411
  }>, {}>;
402
412
  /**
403
413
  * One entry from a GraphQL response's `errors` array.
@@ -1645,6 +1655,160 @@ export declare class AuthenticatedApp extends AuthenticatedApp_base {
1645
1655
  /** {@link AuthenticatedApp.makeTest} behind a `Layer`. */
1646
1656
  static readonly layerTest: (overrides?: Partial<AuthenticatedAppShape>) => Layer.Layer<AuthenticatedApp>;
1647
1657
  }
1658
+ declare const InvalidChangelogRefError_base: Schema.Class<InvalidChangelogRefError, Schema.TaggedStruct<"InvalidChangelogRefError", {
1659
+ /** Which lookup refused it. */
1660
+ readonly ref: Schema.Literals<readonly ["commit", "pull"]>;
1661
+ /** What was handed in, as text. */
1662
+ readonly input: Schema.String;
1663
+ }>, import("effect/Cause").YieldableError>;
1664
+ /**
1665
+ * A changelog lookup was handed a commit sha or pull request number it cannot
1666
+ * send.
1667
+ *
1668
+ * @remarks
1669
+ * The batch names each lookup by an alias built from its input
1670
+ * (`commit__<sha>`, `pull__<number>`), so the input must be something a
1671
+ * GraphQL alias can carry: a hexadecimal sha of 4 to 64 characters, or a
1672
+ * positive integer. Nothing is sent when this fails.
1673
+ *
1674
+ * @public
1675
+ */
1676
+ export declare class InvalidChangelogRefError extends InvalidChangelogRefError_base {
1677
+ get message(): string;
1678
+ }
1679
+ declare const CommitChangelogInfo_base: Schema.Class<CommitChangelogInfo, Schema.Struct<{
1680
+ /**
1681
+ * The login to credit: the pull request's author when the commit has one,
1682
+ * otherwise the GitHub user the commit's author maps to.
1683
+ */
1684
+ readonly user: Schema.Option<Schema.String>;
1685
+ /** The pull request the commit landed through: the earliest-merged one, else the first GitHub lists. */
1686
+ readonly pull: Schema.Option<Schema.Int>;
1687
+ /** Markdown links for the line. */
1688
+ readonly links: Schema.Struct<{
1689
+ /** The first 7 characters of the sha asked for, in a code span, linked to the commit URL. */
1690
+ readonly commit: Schema.String;
1691
+ /** `#` and the number, linked to the pull request URL, when there is a pull request. */
1692
+ readonly pull: Schema.Option<Schema.String>;
1693
+ /** `@` and the login, linked to the user's URL, when there is a user. */
1694
+ readonly user: Schema.Option<Schema.String>;
1695
+ }>;
1696
+ }>, {}>;
1697
+ /**
1698
+ * What a changelog line says about one commit.
1699
+ *
1700
+ * @remarks
1701
+ * The shape `@changesets/get-github-info`'s `getInfo` returns, with every
1702
+ * value that can be missing as an `Option`. The links are markdown, in
1703
+ * upstream's exact format: the short sha in a code span linked to the commit
1704
+ * URL, `[#42](https://github.com/acme/widget/pull/42)` and
1705
+ * `[@octocat](https://github.com/octocat)`. Every URL is the one GitHub answered with, so on
1706
+ * GitHub Enterprise Server the links name that server; nothing here builds a
1707
+ * URL from a configured host.
1708
+ *
1709
+ * @public
1710
+ */
1711
+ export declare class CommitChangelogInfo extends CommitChangelogInfo_base {}
1712
+ declare const PullRequestChangelogInfo_base: Schema.Class<PullRequestChangelogInfo, Schema.Struct<{
1713
+ /** The pull request author's login. */
1714
+ readonly user: Schema.Option<Schema.String>;
1715
+ /** The merge commit's abbreviated sha, once the pull request has merged. */
1716
+ readonly commit: Schema.Option<Schema.String>;
1717
+ /** Markdown links for the line. */
1718
+ readonly links: Schema.Struct<{
1719
+ /** The first 7 characters of the abbreviated merge sha, in a code span, linked to the commit URL, once merged. */
1720
+ readonly commit: Schema.Option<Schema.String>;
1721
+ /** `#` and the number, linked to the pull request URL. */
1722
+ readonly pull: Schema.String;
1723
+ /** `@` and the login, linked to the user's URL, when the author still exists. */
1724
+ readonly user: Schema.Option<Schema.String>;
1725
+ }>;
1726
+ }>, {}>;
1727
+ /**
1728
+ * What a changelog line says about one pull request.
1729
+ *
1730
+ * @remarks
1731
+ * The shape `@changesets/get-github-info`'s `getInfoFromPullRequest` returns,
1732
+ * for a changeset that names its pull request (`pr: #42`) instead of leaving
1733
+ * it to the commit. Links are in the same format as
1734
+ * {@link CommitChangelogInfo}'s, from the URLs GitHub answered with.
1735
+ *
1736
+ * @public
1737
+ */
1738
+ export declare class PullRequestChangelogInfo extends PullRequestChangelogInfo_base {}
1739
+ /**
1740
+ * The commit and pull request facts a changelog line credits.
1741
+ *
1742
+ * @public
1743
+ */
1744
+ interface ChangelogInfoShape {
1745
+ /**
1746
+ * What to credit for a commit of the surrounding `Repo`.
1747
+ *
1748
+ * @remarks
1749
+ * `Option.none()` when the repository has no such commit (or the sha names
1750
+ * something that is not a commit). Lookups that run concurrently are sent as
1751
+ * one aliased GraphQL query, up to 50 per query: run them with
1752
+ * `Effect.forEach(..., { concurrency: "unbounded" })` to get the batch.
1753
+ */
1754
+ readonly commit: (sha: string) => Effect.Effect<Option.Option<CommitChangelogInfo>, GitHubGraphQLError | InvalidChangelogRefError, Repo>;
1755
+ /**
1756
+ * What to credit for a pull request of the surrounding `Repo`.
1757
+ *
1758
+ * @remarks
1759
+ * `Option.none()` when the repository has no such pull request. Batched with
1760
+ * concurrent {@link ChangelogInfoShape.commit} lookups into the same query.
1761
+ */
1762
+ readonly pullRequest: (number: number) => Effect.Effect<Option.Option<PullRequestChangelogInfo>, GitHubGraphQLError | InvalidChangelogRefError, Repo>;
1763
+ }
1764
+ declare const ChangelogInfo_base: Context.ServiceClass<ChangelogInfo, "@effected/github/ChangelogInfo", ChangelogInfoShape>;
1765
+ /**
1766
+ * The commit and pull request facts a changelog line credits, batched into
1767
+ * one GraphQL query.
1768
+ *
1769
+ * @remarks
1770
+ * The kit's `@changesets/get-github-info`. The token and the server come from
1771
+ * the `GitHubClient` the layer is built over, and the repository from `Repo`;
1772
+ * nothing is read from the environment. The query is upstream's, alias for
1773
+ * alias, so concurrent lookups cost one round trip per 50.
1774
+ *
1775
+ * Two answers differ from upstream's, both toward the lookup convention: a
1776
+ * pull request number the repository does not have is `Option.none()` (GitHub
1777
+ * reports it as an error, which upstream throws for the whole batch), and a
1778
+ * sha naming a tree or blob is `Option.none()` (upstream builds links to
1779
+ * `undefined`). A missing repository still fails, with `kind: "notFound"`.
1780
+ *
1781
+ * Batching happens within one built service: each `ChangelogInfo.layer`
1782
+ * build owns its own resolver, and nothing is cached across batches.
1783
+ *
1784
+ * @example
1785
+ * ```ts
1786
+ * import { ChangelogInfo } from "@effected/github";
1787
+ * import { Effect, Option } from "effect";
1788
+ *
1789
+ * const lines = (shas: ReadonlyArray<string>) =>
1790
+ * Effect.gen(function* () {
1791
+ * const info = yield* ChangelogInfo;
1792
+ * const found = yield* Effect.forEach(shas, info.commit, { concurrency: "unbounded" });
1793
+ * return found.flatMap((entry) =>
1794
+ * Option.match(entry, {
1795
+ * onNone: () => [],
1796
+ * onSome: ({ links }) => [`${Option.getOrElse(links.pull, () => links.commit)} Thanks ${Option.getOrElse(links.user, () => "")}`],
1797
+ * }),
1798
+ * );
1799
+ * });
1800
+ * ```
1801
+ *
1802
+ * @public
1803
+ */
1804
+ export declare class ChangelogInfo extends ChangelogInfo_base {
1805
+ /** The live service, built over a `GitHubClient`. */
1806
+ static readonly layer: Layer.Layer<ChangelogInfo, never, GitHubClient>;
1807
+ /** An in-memory double; an unstubbed member dies when run, naming itself. */
1808
+ static readonly makeTest: (overrides?: Partial<ChangelogInfoShape>) => ChangelogInfoShape;
1809
+ /** {@link ChangelogInfo.makeTest} behind a `Layer`. */
1810
+ static readonly layerTest: (overrides?: Partial<ChangelogInfoShape>) => Layer.Layer<ChangelogInfo>;
1811
+ }
1648
1812
  /** How a check run finished. @public */
1649
1813
  export declare const CheckConclusion: Schema.Literals<readonly ["success", "failure", "neutral", "cancelled", "timed_out", "action_required", "skipped"]>;
1650
1814
  /**
@@ -4141,6 +4305,383 @@ export declare class GitHubRepository extends GitHubRepository_base {
4141
4305
  /** {@link GitHubRepository.makeTest} behind a `Layer`. */
4142
4306
  static readonly layerTest: (overrides?: Partial<GitHubRepositoryShape>) => Layer.Layer<GitHubRepository>;
4143
4307
  }
4308
+ /**
4309
+ * Which `GitHubUserAuth` operation a failure came from.
4310
+ *
4311
+ * @public
4312
+ */
4313
+ export declare const GitHubUserAuthOperation: Schema.Literals<readonly ["exchange", "refresh", "revokeGrant"]>;
4314
+ /**
4315
+ * The decoded type of {@link (GitHubUserAuthOperation:variable)}.
4316
+ *
4317
+ * @public
4318
+ */
4319
+ export type GitHubUserAuthOperation = typeof GitHubUserAuthOperation.Type;
4320
+ declare const ExpiringUserTokens_base: Schema.Class<ExpiringUserTokens, Schema.Struct<{
4321
+ /** The discriminant: these tokens expire, and the refresh token renews them. */
4322
+ readonly expiry: Schema.tag<"expiring">;
4323
+ /** The user access token. Decodes to `Redacted`, encodes back to the raw string. */
4324
+ readonly accessToken: Schema.RedactedFromValue<Schema.String>;
4325
+ /** GitHub's `token_type`, `bearer` in practice. */
4326
+ readonly tokenType: Schema.String;
4327
+ /**
4328
+ * GitHub's `scope`, as sent: a comma-separated list for an OAuth App and
4329
+ * the empty string for a GitHub App, whose user tokens carry the app's
4330
+ * permissions instead of scopes.
4331
+ */
4332
+ readonly scope: Schema.String;
4333
+ /** When GitHub stops accepting the access token — eight hours out by default. */
4334
+ readonly expiresAt: Schema.DateTimeUtcFromString;
4335
+ /** The refresh token. Decodes to `Redacted`, encodes back to the raw string. */
4336
+ readonly refreshToken: Schema.RedactedFromValue<Schema.String>;
4337
+ /** When GitHub stops accepting the refresh token — six months out by default. */
4338
+ readonly refreshTokenExpiresAt: Schema.DateTimeUtcFromString;
4339
+ }>, {}>;
4340
+ /**
4341
+ * A user-to-server token pair that expires: what GitHub issues to a GitHub
4342
+ * App with "Expire user authorization tokens" turned on, which is the default.
4343
+ *
4344
+ * @remarks
4345
+ * Times are absolute instants, computed from GitHub's `expires_in` and
4346
+ * `refresh_token_expires_in` against `Clock` when the reply arrived, the same
4347
+ * way `InstallationToken.expiresAt` is.
4348
+ *
4349
+ * Encodable, like `InstallationToken`: `Schema.encodeUnknownEffect` over
4350
+ * {@link (GitHubUserTokens:variable)} produces JSON with both tokens as plain
4351
+ * strings and both times as ISO instants, which is how a caller persists a
4352
+ * user's grant. Encrypting it at rest is the caller's job.
4353
+ *
4354
+ * @public
4355
+ */
4356
+ export declare class ExpiringUserTokens extends ExpiringUserTokens_base {
4357
+ /**
4358
+ * Whether the access token is spent, `skew` before its stated expiry.
4359
+ *
4360
+ * @remarks
4361
+ * `skew` defaults to one minute, so a token is treated as spent slightly
4362
+ * early rather than answering 401 mid-request.
4363
+ */
4364
+ isExpired(nowMillis: number, skew?: Duration.Duration): boolean;
4365
+ /**
4366
+ * Whether the refresh token is spent, `skew` before its stated expiry. A
4367
+ * spent refresh token cannot renew the grant: the user has to authorize
4368
+ * again.
4369
+ */
4370
+ isRefreshExpired(nowMillis: number, skew?: Duration.Duration): boolean;
4371
+ }
4372
+ declare const NonExpiringUserTokens_base: Schema.Class<NonExpiringUserTokens, Schema.Struct<{
4373
+ /** The discriminant: this token does not expire and cannot be refreshed. */
4374
+ readonly expiry: Schema.tag<"non-expiring">;
4375
+ /** The user access token. Decodes to `Redacted`, encodes back to the raw string. */
4376
+ readonly accessToken: Schema.RedactedFromValue<Schema.String>;
4377
+ /** GitHub's `token_type`, `bearer` in practice. */
4378
+ readonly tokenType: Schema.String;
4379
+ /** GitHub's `scope`, as sent; see `ExpiringUserTokens.scope`. */
4380
+ readonly scope: Schema.String;
4381
+ }>, {}>;
4382
+ /**
4383
+ * A user access token that does not expire: what GitHub issues to an OAuth
4384
+ * App, or to a GitHub App with "Expire user authorization tokens" turned off.
4385
+ * It carries no refresh token and no expiry.
4386
+ *
4387
+ * @public
4388
+ */
4389
+ export declare class NonExpiringUserTokens extends NonExpiringUserTokens_base {}
4390
+ /**
4391
+ * What a code exchange answers, discriminated by `expiry`: `expiring` carries
4392
+ * a refresh token and both expiry instants, `non-expiring` carries neither.
4393
+ *
4394
+ * @remarks
4395
+ * **Construct the variant classes, never the union.** The union's inherited
4396
+ * `make` typechecks against both variants at once and reports a wrong field
4397
+ * as a two-branch error; {@link ExpiringUserTokens}`.make` and
4398
+ * {@link NonExpiringUserTokens}`.make` fill `expiry` themselves. The union is
4399
+ * a `Schema` so a stored grant decodes back into the right variant.
4400
+ *
4401
+ * @public
4402
+ */
4403
+ export declare const GitHubUserTokens: Schema.Union<readonly [typeof ExpiringUserTokens, typeof NonExpiringUserTokens]>;
4404
+ /**
4405
+ * The decoded type of {@link (GitHubUserTokens:variable)}:
4406
+ * {@link ExpiringUserTokens} `|` {@link NonExpiringUserTokens}.
4407
+ *
4408
+ * @public
4409
+ */
4410
+ export type GitHubUserTokens = typeof GitHubUserTokens.Type;
4411
+ declare const GitHubUserAuthFinal_base: Schema.Class<GitHubUserAuthFinal, Schema.TaggedStruct<"GitHubUserAuthFinal", {
4412
+ /** The operation GitHub refused. */
4413
+ readonly operation: Schema.Literals<readonly ["exchange", "refresh", "revokeGrant"]>;
4414
+ /** What has to change before the call can succeed. */
4415
+ readonly remedy: Schema.Literals<readonly ["reconnect", "reconfigure"]>;
4416
+ /** GitHub's `error` code, or `http_<status>`. */
4417
+ readonly code: Schema.String;
4418
+ /** GitHub's own explanation, scrubbed of this call's credentials. */
4419
+ readonly description: Schema.optionalKey<Schema.String>;
4420
+ /** The HTTP status GitHub answered with. */
4421
+ readonly status: Schema.Int;
4422
+ }>, import("effect/Cause").YieldableError>;
4423
+ /**
4424
+ * GitHub refused the call, and repeating it will not change the answer.
4425
+ *
4426
+ * @remarks
4427
+ * `remedy` says what has to change, and it is the field to branch on:
4428
+ *
4429
+ * - `"reconnect"` — the user's side is dead: the authorization code was
4430
+ * wrong, expired or already used (`bad_verification_code`), the refresh
4431
+ * token was revoked or expired (`bad_refresh_token`), or the grant is
4432
+ * already gone. Send the user through the authorization flow again, and
4433
+ * drop the tokens you hold for them.
4434
+ * - `"reconfigure"` — the app's side is wrong: its client id or secret
4435
+ * (`incorrect_client_credentials`), its callback URL
4436
+ * (`redirect_uri_mismatch`), refresh tokens being turned off for it
4437
+ * (`unsupported_grant_type`), or a code GitHub sent that this package does
4438
+ * not know. Nothing about the user's grant is learned, and reconnecting the
4439
+ * user does not help; an operator has to fix the app. A 401, 403 or 404
4440
+ * with no `error` code lands here too — but never a 403 whose message
4441
+ * names a rate limit (or GitHub's older "abuse detection" wording), which
4442
+ * is a {@link GitHubUserAuthTemporary}.
4443
+ *
4444
+ * **Never wipe a user's tokens on `GitHubUserAuthFinal` alone.** The obvious
4445
+ * handler, `Effect.catchTag("GitHubUserAuthFinal", () => forgetUser(id))`,
4446
+ * typechecks, runs and reports success, and on a rotated or mistyped client
4447
+ * secret it signs every user out at once, because every refresh then answers
4448
+ * `incorrect_client_credentials`. silk-app's hand-rolled flow carried this
4449
+ * exact rule as a comment before the kit had this error. Match on
4450
+ * `remedy === "reconnect"`.
4451
+ *
4452
+ * GitHub answers the token endpoint with HTTP 200 and an `error` body when it
4453
+ * refuses a code or a refresh token, so `status` is usually 200. `code` is
4454
+ * GitHub's `error` code when it sent one (an unrecognisable one reads
4455
+ * `unknown_error`), and `http_<status>` when GitHub answered a non-success
4456
+ * status with no error code. `description` is GitHub's `error_description`
4457
+ * (or the REST `message`), with any credential this call carried replaced by
4458
+ * `REDACTED`.
4459
+ *
4460
+ * @public
4461
+ */
4462
+ export declare class GitHubUserAuthFinal extends GitHubUserAuthFinal_base {
4463
+ get message(): string;
4464
+ }
4465
+ declare const GitHubUserAuthTemporary_base: Schema.Class<GitHubUserAuthTemporary, Schema.TaggedStruct<"GitHubUserAuthTemporary", {
4466
+ /** The operation that did not complete. */
4467
+ readonly operation: Schema.Literals<readonly ["exchange", "refresh", "revokeGrant"]>;
4468
+ /** Why it did not complete. */
4469
+ readonly kind: Schema.Literals<readonly ["network", "timeout", "status", "malformed"]>;
4470
+ /** The HTTP status, when a response arrived. */
4471
+ readonly status: Schema.optionalKey<Schema.Int>;
4472
+ /** A credential-free copy of what `fetch` threw, for `network`. */
4473
+ readonly cause: Schema.optionalKey<Schema.Defect>;
4474
+ }>, import("effect/Cause").YieldableError>;
4475
+ /**
4476
+ * The call did not get an answer GitHub meant: try it again later.
4477
+ *
4478
+ * @remarks
4479
+ * `kind` is the reason:
4480
+ *
4481
+ * - `"network"` — `fetch` threw, or the body could not be read;
4482
+ * - `"timeout"` — no complete answer within the layer's `timeout`;
4483
+ * - `"status"` — GitHub answered 5xx, 429 or 408, or a 403 whose message
4484
+ * names a rate limit or "abuse detection" (GitHub's primary REST rate
4485
+ * limit answers 403, and its secondary limits answer 403 or 429);
4486
+ * - `"malformed"` — a success status whose body is not a token reply, or a
4487
+ * refresh that answered a token with no refresh token.
4488
+ *
4489
+ * None of these is a refusal of the user's grant, so a caller keeps the
4490
+ * tokens it holds and retries later.
4491
+ *
4492
+ * One case does not leave the grant as it was. GitHub refresh tokens are
4493
+ * single-use and rotate when a refresh succeeds, so a refresh GitHub
4494
+ * processed has already spent the refresh token the caller sent: a
4495
+ * `"malformed"` with a 2xx `status` (GitHub answered, the reply was
4496
+ * rejected), or a `"network"` or `"timeout"` that ended after the request
4497
+ * reached GitHub. Retrying such a refresh with the same refresh token answers
4498
+ * `bad_refresh_token`, a {@link GitHubUserAuthFinal} with
4499
+ * `remedy: "reconnect"`. That is the expected consequence, not a second
4500
+ * fault: the user authorizes again.
4501
+ *
4502
+ * `cause` is a copy of what `fetch` threw, rebuilt with its message, stack
4503
+ * and primitive fields scrubbed of this call's credentials, never the
4504
+ * original: a custom `fetch` can put the request (and so the client secret)
4505
+ * in its error.
4506
+ *
4507
+ * @public
4508
+ */
4509
+ export declare class GitHubUserAuthTemporary extends GitHubUserAuthTemporary_base {
4510
+ get message(): string;
4511
+ }
4512
+ /**
4513
+ * Every failure of a `GitHubUserAuth` operation: final (reconnect or
4514
+ * reconfigure) or temporary (retry later).
4515
+ *
4516
+ * @public
4517
+ */
4518
+ type GitHubUserAuthError = GitHubUserAuthFinal | GitHubUserAuthTemporary;
4519
+ /**
4520
+ * How a {@link GitHubUserAuth} layer is built.
4521
+ *
4522
+ * @public
4523
+ */
4524
+ interface GitHubUserAuthOptions {
4525
+ /** The app's OAuth client id (`Iv1.…` or `Iv23…` for a GitHub App). */
4526
+ readonly clientId: string;
4527
+ /** The app's OAuth client secret. */
4528
+ readonly clientSecret: Redacted.Redacted<string>;
4529
+ /**
4530
+ * A replacement for the global `fetch`, for Workers, proxies and tests —
4531
+ * the same shape as `GitHubClientOptions.fetch`.
4532
+ *
4533
+ * @remarks
4534
+ * It receives an `AbortSignal` on every call, aborted when the call times
4535
+ * out or the caller is interrupted.
4536
+ */
4537
+ readonly fetch?: typeof globalThis.fetch | undefined;
4538
+ /**
4539
+ * The token endpoint. Defaults to
4540
+ * `https://github.com/login/oauth/access_token`; a GitHub Enterprise Server
4541
+ * app uses `https://<host>/login/oauth/access_token`.
4542
+ */
4543
+ readonly tokenUrl?: string | undefined;
4544
+ /**
4545
+ * The REST API root the grant revoke goes to. Defaults to
4546
+ * `https://api.github.com`; a GitHub Enterprise Server app uses
4547
+ * `https://<host>/api/v3`.
4548
+ */
4549
+ readonly apiUrl?: string | undefined;
4550
+ /**
4551
+ * The REST api-version the grant revoke pins, sent as
4552
+ * `x-github-api-version`. Defaults to the same version `GitHubClient`
4553
+ * pins; must be `YYYY-MM-DD`.
4554
+ */
4555
+ readonly apiVersion?: string | undefined;
4556
+ /** The `user-agent` every request sends. Defaults to `@effected/github`. */
4557
+ readonly userAgent?: string | undefined;
4558
+ /**
4559
+ * How long one call may take, request and body together, before it fails
4560
+ * as `GitHubUserAuthTemporary` with `kind: "timeout"`. Defaults to ten
4561
+ * seconds; must be finite and positive.
4562
+ */
4563
+ readonly timeout?: Duration.Input | undefined;
4564
+ }
4565
+ /**
4566
+ * The code a user brought back from GitHub's authorize page.
4567
+ *
4568
+ * @public
4569
+ */
4570
+ interface UserAuthExchangeRequest {
4571
+ /** The `code` query parameter GitHub redirected back with. */
4572
+ readonly code: string;
4573
+ /** The PKCE `code_verifier` whose S256 challenge the authorize URL carried. */
4574
+ readonly codeVerifier?: string | undefined;
4575
+ /** The `redirect_uri` the authorize URL carried, when it carried one. */
4576
+ readonly redirectUri?: string | undefined;
4577
+ }
4578
+ /**
4579
+ * A refresh token to renew.
4580
+ *
4581
+ * @public
4582
+ */
4583
+ interface UserAuthRefreshRequest {
4584
+ /** The refresh token from the last exchange or refresh. */
4585
+ readonly refreshToken: Redacted.Redacted<string>;
4586
+ }
4587
+ /**
4588
+ * A user's grant to revoke.
4589
+ *
4590
+ * @public
4591
+ */
4592
+ interface UserAuthRevokeRequest {
4593
+ /** Any live access token from the grant. */
4594
+ readonly accessToken: Redacted.Redacted<string>;
4595
+ }
4596
+ /**
4597
+ * The operations of {@link GitHubUserAuth}.
4598
+ *
4599
+ * @public
4600
+ */
4601
+ interface GitHubUserAuthShape {
4602
+ /**
4603
+ * Trade an authorization code (and its PKCE verifier) for the user's
4604
+ * tokens.
4605
+ */
4606
+ readonly exchange: (request: UserAuthExchangeRequest) => Effect.Effect<GitHubUserTokens, GitHubUserAuthError>;
4607
+ /**
4608
+ * Renew an expiring grant. GitHub rotates the refresh token, so store the
4609
+ * answer's `refreshToken` in place of the one you sent.
4610
+ */
4611
+ readonly refresh: (request: UserAuthRefreshRequest) => Effect.Effect<ExpiringUserTokens, GitHubUserAuthError>;
4612
+ /**
4613
+ * Revoke the user's whole grant to the app, every token it issued included:
4614
+ * `DELETE /applications/{client_id}/grant` with HTTP Basic client
4615
+ * authentication.
4616
+ *
4617
+ * @remarks
4618
+ * A grant that is already gone answers 422, which fails as
4619
+ * `GitHubUserAuthFinal` with `remedy: "reconnect"`; a caller that treats
4620
+ * revocation as idempotent recovers that case.
4621
+ */
4622
+ readonly revokeGrant: (request: UserAuthRevokeRequest) => Effect.Effect<void, GitHubUserAuthError>;
4623
+ }
4624
+ declare const GitHubUserAuth_base: Context.ServiceClass<GitHubUserAuth, "@effected/github/GitHubUserAuth", GitHubUserAuthShape>;
4625
+ /**
4626
+ * The OAuth web flow a GitHub App (or an OAuth App) uses to act as a user:
4627
+ * PKCE code exchange, refresh, and grant revoke.
4628
+ *
4629
+ * @remarks
4630
+ * None of these calls go through `GitHubClient`: the token endpoint lives on
4631
+ * the web host rather than the REST host, and the revoke authenticates as the
4632
+ * app's OAuth client with HTTP Basic rather than with a bearer token. So the
4633
+ * service speaks to `fetch` directly, and this module imports neither octokit
4634
+ * nor the JWT signer — a Worker that only signs users in links neither.
4635
+ *
4636
+ * Every failure is one of two errors, and the split is the point:
4637
+ * {@link GitHubUserAuthFinal} when GitHub refused (read its `remedy` before
4638
+ * dropping anything), {@link GitHubUserAuthTemporary} when no real answer
4639
+ * arrived. GitHub answers a refused code or refresh token with HTTP 200 and an
4640
+ * `error` body, which is read as the refusal it is.
4641
+ *
4642
+ * The client secret, the code, the verifier and both tokens appear in no
4643
+ * error message, no span annotation and no kept cause.
4644
+ *
4645
+ * @example
4646
+ * ```ts
4647
+ * import { GitHubUserAuth } from "@effected/github";
4648
+ * import { Effect, Redacted } from "effect";
4649
+ *
4650
+ * const UserAuth = GitHubUserAuth.layer({
4651
+ * clientId: "Iv23liExample",
4652
+ * clientSecret: Redacted.make("app-client-secret"),
4653
+ * });
4654
+ *
4655
+ * const signIn = (code: string, codeVerifier: string) =>
4656
+ * Effect.gen(function* () {
4657
+ * const auth = yield* GitHubUserAuth;
4658
+ * return yield* auth.exchange({ code, codeVerifier, redirectUri: "https://app.example/callback" });
4659
+ * });
4660
+ *
4661
+ * Effect.runPromise(signIn("code-from-query", "verifier").pipe(Effect.provide(UserAuth)));
4662
+ * ```
4663
+ *
4664
+ * @public
4665
+ */
4666
+ export declare class GitHubUserAuth extends GitHubUserAuth_base {
4667
+ /**
4668
+ * The live service over `fetch`.
4669
+ *
4670
+ * @remarks
4671
+ * Parameterized, so **bind the result to a `const`** and reuse it: each
4672
+ * call mints a fresh layer, and layers are memoized by reference.
4673
+ *
4674
+ * Bad wiring — an empty client id, a URL that does not parse or is not
4675
+ * `http(s)`, an api-version that is not `YYYY-MM-DD`, a timeout that is not
4676
+ * finite and positive — dies while the layer builds, with a defect naming
4677
+ * the option.
4678
+ */
4679
+ static readonly layer: (options: GitHubUserAuthOptions) => Layer.Layer<GitHubUserAuth>;
4680
+ /** An in-memory double; an unstubbed member dies when run, naming itself. */
4681
+ static readonly makeTest: (overrides?: Partial<GitHubUserAuthShape>) => GitHubUserAuthShape;
4682
+ /** {@link GitHubUserAuth.makeTest} behind a `Layer`. */
4683
+ static readonly layerTest: (overrides?: Partial<GitHubUserAuthShape>) => Layer.Layer<GitHubUserAuth>;
4684
+ }
4144
4685
  declare const TagRef_base: Schema.Class<TagRef, Schema.Struct<{
4145
4686
  /** The tag name, without `refs/tags/`. */
4146
4687
  readonly tag: Schema.NonEmptyString;
@@ -5232,5 +5773,5 @@ export declare class WorkflowDispatch extends WorkflowDispatch_base {
5232
5773
  /** {@link WorkflowDispatch.makeTest} behind a `Layer`. */
5233
5774
  static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
5234
5775
  }
5235
- export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ApplySettingsOptions, type ArtifactMetadataShape, type AttestationShape, type AuthenticatedAppShape, type BareLineReference, type BotUserRequest, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeliveriesOptions, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, type GitBranchShape, type GitCommitShape, type GitHubAppOptions, type GitHubAppShape, type GitHubClientOptions, type GitHubClientShape, type GitHubCommitShape, type GitHubContentShape, type GitHubIssueShape, type GitHubReleaseShape, type GitHubRepositoryShape, type GitTagShape, type InstallationTokenStoreShape, type IssueReference, type LatestSemverOptions, type ListCheckRunsOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositoryPatchExtra, type RepositoryPatchOptions, type RepositoryPatchReservedKey, type RepositorySecretShape, type RepositorySecurityShape, type RepositorySettings, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, type RetryableFailure, type RulesetInfo, type RulesetPayload, type RulesetShape, type SecretInfo, type SecretScope, type TokenRequest, type UpdateCheckRunOptions, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, type WorkflowDispatchShape, type WorkflowInfo, harvestIssueReferences, parseBareLineReference };
5776
+ export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ApplySettingsOptions, type ArtifactMetadataShape, type AttestationShape, type AuthenticatedAppShape, type BareLineReference, type BotUserRequest, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type ChangelogInfoShape, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeliveriesOptions, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, type GitBranchShape, type GitCommitShape, type GitHubAppOptions, type GitHubAppShape, type GitHubClientOptions, type GitHubClientShape, type GitHubCommitShape, type GitHubContentShape, type GitHubIssueShape, type GitHubReleaseShape, type GitHubRepositoryShape, type GitHubUserAuthError, type GitHubUserAuthOptions, type GitHubUserAuthShape, type GitTagShape, type InstallationTokenStoreShape, type IssueReference, type LatestSemverOptions, type ListCheckRunsOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositoryPatchExtra, type RepositoryPatchOptions, type RepositoryPatchReservedKey, type RepositorySecretShape, type RepositorySecurityShape, type RepositorySettings, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, type RetryableFailure, type RulesetInfo, type RulesetPayload, type RulesetShape, type SecretInfo, type SecretScope, type TokenRequest, type UpdateCheckRunOptions, type UpsertedPullRequest, type UserAuthExchangeRequest, type UserAuthRefreshRequest, type UserAuthRevokeRequest, type VariableInfo, type VersionFromTag, type WorkflowDispatchShape, type WorkflowInfo, harvestIssueReferences, parseBareLineReference };
5236
5777
  //# sourceMappingURL=index.d.ts.map
package/index.js CHANGED
@@ -2,6 +2,7 @@ import { ActionsOidc, ActionsOidcClaims, ActionsOidcClaimsFromWire } from "./Act
2
2
  import { ArtifactMetadata, StorageRecordInput } from "./ArtifactMetadata.js";
3
3
  import { Attestation, AttestationListEntry, AttestationRecord } from "./Attestation.js";
4
4
  import { AppInfo, AuthenticatedApp, DeliveryAttempt } from "./AuthenticatedApp.js";
5
+ import { ChangelogInfo, CommitChangelogInfo, InvalidChangelogRefError, PullRequestChangelogInfo } from "./ChangelogInfo.js";
5
6
  import { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CheckRunStatus, ReportedCheckConclusion, ReportedCheckRunOutput } from "./CheckRun.js";
6
7
  import { CodeScanning } from "./CodeScanning.js";
7
8
  import { DeploymentEnvironment } from "./DeploymentEnvironment.js";
@@ -15,6 +16,7 @@ import { GitHubError, GitHubErrorKind, GitHubValidationCode, GitHubValidationEnt
15
16
  import { CommentOnceResult, GitHubIssue, IssueInfo, LinkedIssue } from "./GitHubIssue.js";
16
17
  import { GitHubRelease, ReleaseAsset, ReleaseInfo } from "./GitHubRelease.js";
17
18
  import { GRAPHQL_ONLY_SETTINGS, GitHubRepository, SECURITY_ANALYSIS_STATUS_FIELDS, repositoryPatch, transformSecurityAndAnalysis } from "./GitHubRepository.js";
19
+ import { ExpiringUserTokens, GitHubUserAuth, GitHubUserAuthFinal, GitHubUserAuthOperation, GitHubUserAuthTemporary, GitHubUserTokens, NonExpiringUserTokens } from "./GitHubUserAuth.js";
18
20
  import { GitTag, SemverTag, TagRef, versionFromTag } from "./GitTag.js";
19
21
  import { GitHubGraphQLError, GraphQLDocument, GraphQLErrorEntry } from "./GraphQL.js";
20
22
  import { InstallationTokenStore } from "./InstallationTokenStore.js";
@@ -31,4 +33,4 @@ import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, Toke
31
33
  import { DispatchedRun, WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
32
34
  import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
33
35
 
34
- export { ActionsOidc, ActionsOidcClaims, ActionsOidcClaimsFromWire, Annotation, AnnotationLevel, AppIdentity, AppInfo, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, AuthenticatedApp, BotIdentity, BotUser, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CheckRunStatus, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, CreatedCommit, DeliveryAttempt, DeploymentEnvironment, DispatchedRun, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubFixtures, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InstallationTokenStore, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, RawFailure, ReleaseAsset, ReleaseInfo, Repo, RepoRef, ReportedCheckConclusion, ReportedCheckRunOutput, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, repositoryPatch, transformSecurityAndAnalysis, versionFromTag };
36
+ export { ActionsOidc, ActionsOidcClaims, ActionsOidcClaimsFromWire, Annotation, AnnotationLevel, AppIdentity, AppInfo, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, AuthenticatedApp, BotIdentity, BotUser, CLOSING_KEYWORDS, ChangelogInfo, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CheckRunStatus, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitChangelogInfo, CommitComparison, CommitFile, CommitRef, CommitSummary, CreatedCommit, DeliveryAttempt, DeploymentEnvironment, DispatchedRun, ExpiringUserTokens, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubFixtures, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitHubUserAuth, GitHubUserAuthFinal, GitHubUserAuthOperation, GitHubUserAuthTemporary, GitHubUserTokens, GitHubValidationCode, GitHubValidationEntry, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InstallationTokenStore, InvalidChangelogRefError, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, NonExpiringUserTokens, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestChangelogInfo, PullRequestComment, PullRequestInfo, RateLimitSnapshot, RawFailure, ReleaseAsset, ReleaseInfo, Repo, RepoRef, ReportedCheckConclusion, ReportedCheckRunOutput, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, repositoryPatch, transformSecurityAndAnalysis, versionFromTag };
@@ -0,0 +1,15 @@
1
+ // src/internal/apiVersion.ts
2
+ /**
3
+ * The REST api-version a client pins when its options name none.
4
+ *
5
+ * @internal
6
+ */
7
+ const DEFAULT_API_VERSION = "2026-03-10";
8
+ /**
9
+ * A calendar api-version: `YYYY-MM-DD`.
10
+ *
11
+ * @internal
12
+ */
13
+ const API_VERSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
14
+
15
+ export { API_VERSION_PATTERN, DEFAULT_API_VERSION };
@@ -8,8 +8,6 @@ import { Octokit } from "@octokit/core";
8
8
  import { composePaginateRest } from "@octokit/plugin-paginate-rest";
9
9
 
10
10
  // src/internal/octokit.ts
11
- /** The REST api-version a client pins when its options name none. */
12
- const DEFAULT_API_VERSION = "2026-03-10";
13
11
  const SILENT_LOG = {
14
12
  debug: () => {},
15
13
  info: () => {},
@@ -203,4 +201,4 @@ const readThrownHeaders = (error) => {
203
201
  return typeof headers === "object" && headers !== null ? headers : void 0;
204
202
  };
205
203
 
206
- export { DEFAULT_API_VERSION, expandOnDotcom, makeTransport };
204
+ export { expandOnDotcom, makeTransport };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/github",
3
- "version": "0.29.0",
3
+ "version": "0.31.0",
4
4
  "private": false,
5
5
  "description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
6
6
  "keywords": [
@@ -38,11 +38,11 @@
38
38
  "./package.json": "./package.json"
39
39
  },
40
40
  "dependencies": {
41
- "@effected/crypto": "^0.5.0",
41
+ "@effected/crypto": "^0.6.0",
42
42
  "@effected/github-references": "^0.14.0",
43
- "@effected/jwt": "^0.9.0",
43
+ "@effected/jwt": "^0.9.1",
44
44
  "@effected/oidc": "^0.4.0",
45
- "@effected/semver": "^0.22.0",
45
+ "@effected/semver": "^0.23.0",
46
46
  "@octokit/core": "^7.0.6",
47
47
  "@octokit/plugin-paginate-rest": "^16.0.0",
48
48
  "@octokit/types": "^18.0.0",