@effected/github 0.28.0 → 0.30.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/GitCommit.js +73 -39
- package/GitHubClient.js +2 -3
- package/GitHubUserAuth.js +581 -0
- package/README.md +33 -1
- package/index.d.ts +425 -1
- package/index.js +3 -2
- package/internal/apiVersion.js +15 -0
- package/internal/octokit.js +1 -3
- package/package.json +4 -4
package/index.d.ts
CHANGED
|
@@ -805,6 +805,12 @@ interface GitHubClientShape {
|
|
|
805
805
|
* route that resolves to another origin, fails `kind: "rejected"` with no
|
|
806
806
|
* status and nothing sent.
|
|
807
807
|
*
|
|
808
|
+
* **Interrupting aborts the fetch.** The fiber's `AbortSignal` reaches the
|
|
809
|
+
* fetch, so an interrupt (an `Effect.timeout`, a cancelled caller) cancels the
|
|
810
|
+
* in-flight HTTP request, a body read included, and the attempt is not
|
|
811
|
+
* retried. A `fetch` option that ignores its signal still releases the caller
|
|
812
|
+
* at once, while that request runs on.
|
|
813
|
+
*
|
|
808
814
|
* @example
|
|
809
815
|
* ```ts
|
|
810
816
|
* import { GitHubClient } from "@effected/github";
|
|
@@ -852,6 +858,12 @@ interface GitHubClientShape {
|
|
|
852
858
|
* header whose next page names another origin fails the walk
|
|
853
859
|
* `kind: "rejected"` before that page is requested, rather than sending the
|
|
854
860
|
* token there or ending the walk early as if the collection were complete.
|
|
861
|
+
*
|
|
862
|
+
* **Interrupting aborts the fetch.** The fiber's `AbortSignal` reaches the
|
|
863
|
+
* fetch, so an interrupt (an `Effect.timeout`, a cancelled caller) cancels the
|
|
864
|
+
* in-flight HTTP request, a body read included, and the attempt is not
|
|
865
|
+
* retried. A `fetch` option that ignores its signal still releases the caller
|
|
866
|
+
* at once, while that request runs on.
|
|
855
867
|
*/
|
|
856
868
|
readonly paginate: <R extends PaginatingRoute>(route: R, params: Params<R>, options?: PageOptions) => Effect.Effect<ReadonlyArray<Item<R>>, GitHubError>;
|
|
857
869
|
/**
|
|
@@ -861,6 +873,12 @@ interface GitHubClientShape {
|
|
|
861
873
|
* Lazy in requests: a downstream `Stream.take` stops the walk rather than
|
|
862
874
|
* filtering pages that were already fetched. Confined to the configured
|
|
863
875
|
* host exactly as {@link GitHubClientShape.paginate} is.
|
|
876
|
+
*
|
|
877
|
+
* **Interrupting aborts the fetch.** The fiber's `AbortSignal` reaches the
|
|
878
|
+
* fetch, so an interrupt (an `Effect.timeout`, a cancelled caller) cancels the
|
|
879
|
+
* in-flight HTTP request, a body read included, and the attempt is not
|
|
880
|
+
* retried. A `fetch` option that ignores its signal still releases the caller
|
|
881
|
+
* at once, while that request runs on.
|
|
864
882
|
*/
|
|
865
883
|
readonly paginateStream: <R extends PaginatingRoute>(route: R, params: Params<R>, options?: PageOptions) => Stream.Stream<Item<R>, GitHubError>;
|
|
866
884
|
/** Run an owned GraphQL document and decode its answer. */
|
|
@@ -2381,6 +2399,23 @@ declare const CommitRef_base: Schema.Class<CommitRef, Schema.Struct<{
|
|
|
2381
2399
|
* @public
|
|
2382
2400
|
*/
|
|
2383
2401
|
export declare class CommitRef extends CommitRef_base {}
|
|
2402
|
+
declare const CreatedCommit_base: Schema.Class<CreatedCommit, Schema.Struct<{
|
|
2403
|
+
/** The new commit's sha. */
|
|
2404
|
+
readonly sha: Schema.String;
|
|
2405
|
+
/** The commit's web URL, as GitHub reported it. */
|
|
2406
|
+
readonly htmlUrl: Schema.String;
|
|
2407
|
+
}>, {}>;
|
|
2408
|
+
/**
|
|
2409
|
+
* A commit just created through the Git Database API: its sha and the URL
|
|
2410
|
+
* GitHub reports for viewing it.
|
|
2411
|
+
*
|
|
2412
|
+
* @remarks
|
|
2413
|
+
* `htmlUrl` is the `html_url` of the creation reply, so it carries the right
|
|
2414
|
+
* host on GitHub Enterprise Server with no host arithmetic.
|
|
2415
|
+
*
|
|
2416
|
+
* @public
|
|
2417
|
+
*/
|
|
2418
|
+
export declare class CreatedCommit extends CreatedCommit_base {}
|
|
2384
2419
|
/**
|
|
2385
2420
|
* Commits and trees in GitHub's Git Database API.
|
|
2386
2421
|
*
|
|
@@ -2400,6 +2435,12 @@ interface GitCommitShape {
|
|
|
2400
2435
|
readonly tree: string;
|
|
2401
2436
|
readonly parents: ReadonlyArray<string>;
|
|
2402
2437
|
}) => Effect.Effect<string, GitHubError, Repo>;
|
|
2438
|
+
/** {@link GitCommitShape.createCommit}, also returning the commit's `html_url`. */
|
|
2439
|
+
readonly createCommitWithUrl: (options: {
|
|
2440
|
+
readonly message: string;
|
|
2441
|
+
readonly tree: string;
|
|
2442
|
+
readonly parents: ReadonlyArray<string>;
|
|
2443
|
+
}) => Effect.Effect<CreatedCommit, GitHubError, Repo>;
|
|
2403
2444
|
/**
|
|
2404
2445
|
* Write `changes` onto `branch` as one commit, returning its sha.
|
|
2405
2446
|
*
|
|
@@ -2425,6 +2466,12 @@ interface GitCommitShape {
|
|
|
2425
2466
|
readonly message: string;
|
|
2426
2467
|
readonly changes: ReadonlyArray<FileChange>;
|
|
2427
2468
|
}) => Effect.Effect<string, GitHubError, Repo>;
|
|
2469
|
+
/** {@link GitCommitShape.commitFiles}, also returning the commit's `html_url`. */
|
|
2470
|
+
readonly commitFilesWithUrl: (options: {
|
|
2471
|
+
readonly branch: string;
|
|
2472
|
+
readonly message: string;
|
|
2473
|
+
readonly changes: ReadonlyArray<FileChange>;
|
|
2474
|
+
}) => Effect.Effect<CreatedCommit, GitHubError, Repo>;
|
|
2428
2475
|
}
|
|
2429
2476
|
declare const GitCommit_base: Context.ServiceClass<GitCommit, "@effected/github/GitCommit", GitCommitShape>;
|
|
2430
2477
|
/**
|
|
@@ -4094,6 +4141,383 @@ export declare class GitHubRepository extends GitHubRepository_base {
|
|
|
4094
4141
|
/** {@link GitHubRepository.makeTest} behind a `Layer`. */
|
|
4095
4142
|
static readonly layerTest: (overrides?: Partial<GitHubRepositoryShape>) => Layer.Layer<GitHubRepository>;
|
|
4096
4143
|
}
|
|
4144
|
+
/**
|
|
4145
|
+
* Which `GitHubUserAuth` operation a failure came from.
|
|
4146
|
+
*
|
|
4147
|
+
* @public
|
|
4148
|
+
*/
|
|
4149
|
+
export declare const GitHubUserAuthOperation: Schema.Literals<readonly ["exchange", "refresh", "revokeGrant"]>;
|
|
4150
|
+
/**
|
|
4151
|
+
* The decoded type of {@link (GitHubUserAuthOperation:variable)}.
|
|
4152
|
+
*
|
|
4153
|
+
* @public
|
|
4154
|
+
*/
|
|
4155
|
+
export type GitHubUserAuthOperation = typeof GitHubUserAuthOperation.Type;
|
|
4156
|
+
declare const ExpiringUserTokens_base: Schema.Class<ExpiringUserTokens, Schema.Struct<{
|
|
4157
|
+
/** The discriminant: these tokens expire, and the refresh token renews them. */
|
|
4158
|
+
readonly expiry: Schema.tag<"expiring">;
|
|
4159
|
+
/** The user access token. Decodes to `Redacted`, encodes back to the raw string. */
|
|
4160
|
+
readonly accessToken: Schema.RedactedFromValue<Schema.String>;
|
|
4161
|
+
/** GitHub's `token_type`, `bearer` in practice. */
|
|
4162
|
+
readonly tokenType: Schema.String;
|
|
4163
|
+
/**
|
|
4164
|
+
* GitHub's `scope`, as sent: a comma-separated list for an OAuth App and
|
|
4165
|
+
* the empty string for a GitHub App, whose user tokens carry the app's
|
|
4166
|
+
* permissions instead of scopes.
|
|
4167
|
+
*/
|
|
4168
|
+
readonly scope: Schema.String;
|
|
4169
|
+
/** When GitHub stops accepting the access token — eight hours out by default. */
|
|
4170
|
+
readonly expiresAt: Schema.DateTimeUtcFromString;
|
|
4171
|
+
/** The refresh token. Decodes to `Redacted`, encodes back to the raw string. */
|
|
4172
|
+
readonly refreshToken: Schema.RedactedFromValue<Schema.String>;
|
|
4173
|
+
/** When GitHub stops accepting the refresh token — six months out by default. */
|
|
4174
|
+
readonly refreshTokenExpiresAt: Schema.DateTimeUtcFromString;
|
|
4175
|
+
}>, {}>;
|
|
4176
|
+
/**
|
|
4177
|
+
* A user-to-server token pair that expires: what GitHub issues to a GitHub
|
|
4178
|
+
* App with "Expire user authorization tokens" turned on, which is the default.
|
|
4179
|
+
*
|
|
4180
|
+
* @remarks
|
|
4181
|
+
* Times are absolute instants, computed from GitHub's `expires_in` and
|
|
4182
|
+
* `refresh_token_expires_in` against `Clock` when the reply arrived, the same
|
|
4183
|
+
* way `InstallationToken.expiresAt` is.
|
|
4184
|
+
*
|
|
4185
|
+
* Encodable, like `InstallationToken`: `Schema.encodeUnknownEffect` over
|
|
4186
|
+
* {@link (GitHubUserTokens:variable)} produces JSON with both tokens as plain
|
|
4187
|
+
* strings and both times as ISO instants, which is how a caller persists a
|
|
4188
|
+
* user's grant. Encrypting it at rest is the caller's job.
|
|
4189
|
+
*
|
|
4190
|
+
* @public
|
|
4191
|
+
*/
|
|
4192
|
+
export declare class ExpiringUserTokens extends ExpiringUserTokens_base {
|
|
4193
|
+
/**
|
|
4194
|
+
* Whether the access token is spent, `skew` before its stated expiry.
|
|
4195
|
+
*
|
|
4196
|
+
* @remarks
|
|
4197
|
+
* `skew` defaults to one minute, so a token is treated as spent slightly
|
|
4198
|
+
* early rather than answering 401 mid-request.
|
|
4199
|
+
*/
|
|
4200
|
+
isExpired(nowMillis: number, skew?: Duration.Duration): boolean;
|
|
4201
|
+
/**
|
|
4202
|
+
* Whether the refresh token is spent, `skew` before its stated expiry. A
|
|
4203
|
+
* spent refresh token cannot renew the grant: the user has to authorize
|
|
4204
|
+
* again.
|
|
4205
|
+
*/
|
|
4206
|
+
isRefreshExpired(nowMillis: number, skew?: Duration.Duration): boolean;
|
|
4207
|
+
}
|
|
4208
|
+
declare const NonExpiringUserTokens_base: Schema.Class<NonExpiringUserTokens, Schema.Struct<{
|
|
4209
|
+
/** The discriminant: this token does not expire and cannot be refreshed. */
|
|
4210
|
+
readonly expiry: Schema.tag<"non-expiring">;
|
|
4211
|
+
/** The user access token. Decodes to `Redacted`, encodes back to the raw string. */
|
|
4212
|
+
readonly accessToken: Schema.RedactedFromValue<Schema.String>;
|
|
4213
|
+
/** GitHub's `token_type`, `bearer` in practice. */
|
|
4214
|
+
readonly tokenType: Schema.String;
|
|
4215
|
+
/** GitHub's `scope`, as sent; see `ExpiringUserTokens.scope`. */
|
|
4216
|
+
readonly scope: Schema.String;
|
|
4217
|
+
}>, {}>;
|
|
4218
|
+
/**
|
|
4219
|
+
* A user access token that does not expire: what GitHub issues to an OAuth
|
|
4220
|
+
* App, or to a GitHub App with "Expire user authorization tokens" turned off.
|
|
4221
|
+
* It carries no refresh token and no expiry.
|
|
4222
|
+
*
|
|
4223
|
+
* @public
|
|
4224
|
+
*/
|
|
4225
|
+
export declare class NonExpiringUserTokens extends NonExpiringUserTokens_base {}
|
|
4226
|
+
/**
|
|
4227
|
+
* What a code exchange answers, discriminated by `expiry`: `expiring` carries
|
|
4228
|
+
* a refresh token and both expiry instants, `non-expiring` carries neither.
|
|
4229
|
+
*
|
|
4230
|
+
* @remarks
|
|
4231
|
+
* **Construct the variant classes, never the union.** The union's inherited
|
|
4232
|
+
* `make` typechecks against both variants at once and reports a wrong field
|
|
4233
|
+
* as a two-branch error; {@link ExpiringUserTokens}`.make` and
|
|
4234
|
+
* {@link NonExpiringUserTokens}`.make` fill `expiry` themselves. The union is
|
|
4235
|
+
* a `Schema` so a stored grant decodes back into the right variant.
|
|
4236
|
+
*
|
|
4237
|
+
* @public
|
|
4238
|
+
*/
|
|
4239
|
+
export declare const GitHubUserTokens: Schema.Union<readonly [typeof ExpiringUserTokens, typeof NonExpiringUserTokens]>;
|
|
4240
|
+
/**
|
|
4241
|
+
* The decoded type of {@link (GitHubUserTokens:variable)}:
|
|
4242
|
+
* {@link ExpiringUserTokens} `|` {@link NonExpiringUserTokens}.
|
|
4243
|
+
*
|
|
4244
|
+
* @public
|
|
4245
|
+
*/
|
|
4246
|
+
export type GitHubUserTokens = typeof GitHubUserTokens.Type;
|
|
4247
|
+
declare const GitHubUserAuthFinal_base: Schema.Class<GitHubUserAuthFinal, Schema.TaggedStruct<"GitHubUserAuthFinal", {
|
|
4248
|
+
/** The operation GitHub refused. */
|
|
4249
|
+
readonly operation: Schema.Literals<readonly ["exchange", "refresh", "revokeGrant"]>;
|
|
4250
|
+
/** What has to change before the call can succeed. */
|
|
4251
|
+
readonly remedy: Schema.Literals<readonly ["reconnect", "reconfigure"]>;
|
|
4252
|
+
/** GitHub's `error` code, or `http_<status>`. */
|
|
4253
|
+
readonly code: Schema.String;
|
|
4254
|
+
/** GitHub's own explanation, scrubbed of this call's credentials. */
|
|
4255
|
+
readonly description: Schema.optionalKey<Schema.String>;
|
|
4256
|
+
/** The HTTP status GitHub answered with. */
|
|
4257
|
+
readonly status: Schema.Int;
|
|
4258
|
+
}>, import("effect/Cause").YieldableError>;
|
|
4259
|
+
/**
|
|
4260
|
+
* GitHub refused the call, and repeating it will not change the answer.
|
|
4261
|
+
*
|
|
4262
|
+
* @remarks
|
|
4263
|
+
* `remedy` says what has to change, and it is the field to branch on:
|
|
4264
|
+
*
|
|
4265
|
+
* - `"reconnect"` — the user's side is dead: the authorization code was
|
|
4266
|
+
* wrong, expired or already used (`bad_verification_code`), the refresh
|
|
4267
|
+
* token was revoked or expired (`bad_refresh_token`), or the grant is
|
|
4268
|
+
* already gone. Send the user through the authorization flow again, and
|
|
4269
|
+
* drop the tokens you hold for them.
|
|
4270
|
+
* - `"reconfigure"` — the app's side is wrong: its client id or secret
|
|
4271
|
+
* (`incorrect_client_credentials`), its callback URL
|
|
4272
|
+
* (`redirect_uri_mismatch`), refresh tokens being turned off for it
|
|
4273
|
+
* (`unsupported_grant_type`), or a code GitHub sent that this package does
|
|
4274
|
+
* not know. Nothing about the user's grant is learned, and reconnecting the
|
|
4275
|
+
* user does not help; an operator has to fix the app. A 401, 403 or 404
|
|
4276
|
+
* with no `error` code lands here too — but never a 403 whose message
|
|
4277
|
+
* names a rate limit (or GitHub's older "abuse detection" wording), which
|
|
4278
|
+
* is a {@link GitHubUserAuthTemporary}.
|
|
4279
|
+
*
|
|
4280
|
+
* **Never wipe a user's tokens on `GitHubUserAuthFinal` alone.** The obvious
|
|
4281
|
+
* handler, `Effect.catchTag("GitHubUserAuthFinal", () => forgetUser(id))`,
|
|
4282
|
+
* typechecks, runs and reports success, and on a rotated or mistyped client
|
|
4283
|
+
* secret it signs every user out at once, because every refresh then answers
|
|
4284
|
+
* `incorrect_client_credentials`. silk-app's hand-rolled flow carried this
|
|
4285
|
+
* exact rule as a comment before the kit had this error. Match on
|
|
4286
|
+
* `remedy === "reconnect"`.
|
|
4287
|
+
*
|
|
4288
|
+
* GitHub answers the token endpoint with HTTP 200 and an `error` body when it
|
|
4289
|
+
* refuses a code or a refresh token, so `status` is usually 200. `code` is
|
|
4290
|
+
* GitHub's `error` code when it sent one (an unrecognisable one reads
|
|
4291
|
+
* `unknown_error`), and `http_<status>` when GitHub answered a non-success
|
|
4292
|
+
* status with no error code. `description` is GitHub's `error_description`
|
|
4293
|
+
* (or the REST `message`), with any credential this call carried replaced by
|
|
4294
|
+
* `REDACTED`.
|
|
4295
|
+
*
|
|
4296
|
+
* @public
|
|
4297
|
+
*/
|
|
4298
|
+
export declare class GitHubUserAuthFinal extends GitHubUserAuthFinal_base {
|
|
4299
|
+
get message(): string;
|
|
4300
|
+
}
|
|
4301
|
+
declare const GitHubUserAuthTemporary_base: Schema.Class<GitHubUserAuthTemporary, Schema.TaggedStruct<"GitHubUserAuthTemporary", {
|
|
4302
|
+
/** The operation that did not complete. */
|
|
4303
|
+
readonly operation: Schema.Literals<readonly ["exchange", "refresh", "revokeGrant"]>;
|
|
4304
|
+
/** Why it did not complete. */
|
|
4305
|
+
readonly kind: Schema.Literals<readonly ["network", "timeout", "status", "malformed"]>;
|
|
4306
|
+
/** The HTTP status, when a response arrived. */
|
|
4307
|
+
readonly status: Schema.optionalKey<Schema.Int>;
|
|
4308
|
+
/** A credential-free copy of what `fetch` threw, for `network`. */
|
|
4309
|
+
readonly cause: Schema.optionalKey<Schema.Defect>;
|
|
4310
|
+
}>, import("effect/Cause").YieldableError>;
|
|
4311
|
+
/**
|
|
4312
|
+
* The call did not get an answer GitHub meant: try it again later.
|
|
4313
|
+
*
|
|
4314
|
+
* @remarks
|
|
4315
|
+
* `kind` is the reason:
|
|
4316
|
+
*
|
|
4317
|
+
* - `"network"` — `fetch` threw, or the body could not be read;
|
|
4318
|
+
* - `"timeout"` — no complete answer within the layer's `timeout`;
|
|
4319
|
+
* - `"status"` — GitHub answered 5xx, 429 or 408, or a 403 whose message
|
|
4320
|
+
* names a rate limit or "abuse detection" (GitHub's primary REST rate
|
|
4321
|
+
* limit answers 403, and its secondary limits answer 403 or 429);
|
|
4322
|
+
* - `"malformed"` — a success status whose body is not a token reply, or a
|
|
4323
|
+
* refresh that answered a token with no refresh token.
|
|
4324
|
+
*
|
|
4325
|
+
* None of these is a refusal of the user's grant, so a caller keeps the
|
|
4326
|
+
* tokens it holds and retries later.
|
|
4327
|
+
*
|
|
4328
|
+
* One case does not leave the grant as it was. GitHub refresh tokens are
|
|
4329
|
+
* single-use and rotate when a refresh succeeds, so a refresh GitHub
|
|
4330
|
+
* processed has already spent the refresh token the caller sent: a
|
|
4331
|
+
* `"malformed"` with a 2xx `status` (GitHub answered, the reply was
|
|
4332
|
+
* rejected), or a `"network"` or `"timeout"` that ended after the request
|
|
4333
|
+
* reached GitHub. Retrying such a refresh with the same refresh token answers
|
|
4334
|
+
* `bad_refresh_token`, a {@link GitHubUserAuthFinal} with
|
|
4335
|
+
* `remedy: "reconnect"`. That is the expected consequence, not a second
|
|
4336
|
+
* fault: the user authorizes again.
|
|
4337
|
+
*
|
|
4338
|
+
* `cause` is a copy of what `fetch` threw, rebuilt with its message, stack
|
|
4339
|
+
* and primitive fields scrubbed of this call's credentials, never the
|
|
4340
|
+
* original: a custom `fetch` can put the request (and so the client secret)
|
|
4341
|
+
* in its error.
|
|
4342
|
+
*
|
|
4343
|
+
* @public
|
|
4344
|
+
*/
|
|
4345
|
+
export declare class GitHubUserAuthTemporary extends GitHubUserAuthTemporary_base {
|
|
4346
|
+
get message(): string;
|
|
4347
|
+
}
|
|
4348
|
+
/**
|
|
4349
|
+
* Every failure of a `GitHubUserAuth` operation: final (reconnect or
|
|
4350
|
+
* reconfigure) or temporary (retry later).
|
|
4351
|
+
*
|
|
4352
|
+
* @public
|
|
4353
|
+
*/
|
|
4354
|
+
type GitHubUserAuthError = GitHubUserAuthFinal | GitHubUserAuthTemporary;
|
|
4355
|
+
/**
|
|
4356
|
+
* How a {@link GitHubUserAuth} layer is built.
|
|
4357
|
+
*
|
|
4358
|
+
* @public
|
|
4359
|
+
*/
|
|
4360
|
+
interface GitHubUserAuthOptions {
|
|
4361
|
+
/** The app's OAuth client id (`Iv1.…` or `Iv23…` for a GitHub App). */
|
|
4362
|
+
readonly clientId: string;
|
|
4363
|
+
/** The app's OAuth client secret. */
|
|
4364
|
+
readonly clientSecret: Redacted.Redacted<string>;
|
|
4365
|
+
/**
|
|
4366
|
+
* A replacement for the global `fetch`, for Workers, proxies and tests —
|
|
4367
|
+
* the same shape as `GitHubClientOptions.fetch`.
|
|
4368
|
+
*
|
|
4369
|
+
* @remarks
|
|
4370
|
+
* It receives an `AbortSignal` on every call, aborted when the call times
|
|
4371
|
+
* out or the caller is interrupted.
|
|
4372
|
+
*/
|
|
4373
|
+
readonly fetch?: typeof globalThis.fetch | undefined;
|
|
4374
|
+
/**
|
|
4375
|
+
* The token endpoint. Defaults to
|
|
4376
|
+
* `https://github.com/login/oauth/access_token`; a GitHub Enterprise Server
|
|
4377
|
+
* app uses `https://<host>/login/oauth/access_token`.
|
|
4378
|
+
*/
|
|
4379
|
+
readonly tokenUrl?: string | undefined;
|
|
4380
|
+
/**
|
|
4381
|
+
* The REST API root the grant revoke goes to. Defaults to
|
|
4382
|
+
* `https://api.github.com`; a GitHub Enterprise Server app uses
|
|
4383
|
+
* `https://<host>/api/v3`.
|
|
4384
|
+
*/
|
|
4385
|
+
readonly apiUrl?: string | undefined;
|
|
4386
|
+
/**
|
|
4387
|
+
* The REST api-version the grant revoke pins, sent as
|
|
4388
|
+
* `x-github-api-version`. Defaults to the same version `GitHubClient`
|
|
4389
|
+
* pins; must be `YYYY-MM-DD`.
|
|
4390
|
+
*/
|
|
4391
|
+
readonly apiVersion?: string | undefined;
|
|
4392
|
+
/** The `user-agent` every request sends. Defaults to `@effected/github`. */
|
|
4393
|
+
readonly userAgent?: string | undefined;
|
|
4394
|
+
/**
|
|
4395
|
+
* How long one call may take, request and body together, before it fails
|
|
4396
|
+
* as `GitHubUserAuthTemporary` with `kind: "timeout"`. Defaults to ten
|
|
4397
|
+
* seconds; must be finite and positive.
|
|
4398
|
+
*/
|
|
4399
|
+
readonly timeout?: Duration.Input | undefined;
|
|
4400
|
+
}
|
|
4401
|
+
/**
|
|
4402
|
+
* The code a user brought back from GitHub's authorize page.
|
|
4403
|
+
*
|
|
4404
|
+
* @public
|
|
4405
|
+
*/
|
|
4406
|
+
interface UserAuthExchangeRequest {
|
|
4407
|
+
/** The `code` query parameter GitHub redirected back with. */
|
|
4408
|
+
readonly code: string;
|
|
4409
|
+
/** The PKCE `code_verifier` whose S256 challenge the authorize URL carried. */
|
|
4410
|
+
readonly codeVerifier?: string | undefined;
|
|
4411
|
+
/** The `redirect_uri` the authorize URL carried, when it carried one. */
|
|
4412
|
+
readonly redirectUri?: string | undefined;
|
|
4413
|
+
}
|
|
4414
|
+
/**
|
|
4415
|
+
* A refresh token to renew.
|
|
4416
|
+
*
|
|
4417
|
+
* @public
|
|
4418
|
+
*/
|
|
4419
|
+
interface UserAuthRefreshRequest {
|
|
4420
|
+
/** The refresh token from the last exchange or refresh. */
|
|
4421
|
+
readonly refreshToken: Redacted.Redacted<string>;
|
|
4422
|
+
}
|
|
4423
|
+
/**
|
|
4424
|
+
* A user's grant to revoke.
|
|
4425
|
+
*
|
|
4426
|
+
* @public
|
|
4427
|
+
*/
|
|
4428
|
+
interface UserAuthRevokeRequest {
|
|
4429
|
+
/** Any live access token from the grant. */
|
|
4430
|
+
readonly accessToken: Redacted.Redacted<string>;
|
|
4431
|
+
}
|
|
4432
|
+
/**
|
|
4433
|
+
* The operations of {@link GitHubUserAuth}.
|
|
4434
|
+
*
|
|
4435
|
+
* @public
|
|
4436
|
+
*/
|
|
4437
|
+
interface GitHubUserAuthShape {
|
|
4438
|
+
/**
|
|
4439
|
+
* Trade an authorization code (and its PKCE verifier) for the user's
|
|
4440
|
+
* tokens.
|
|
4441
|
+
*/
|
|
4442
|
+
readonly exchange: (request: UserAuthExchangeRequest) => Effect.Effect<GitHubUserTokens, GitHubUserAuthError>;
|
|
4443
|
+
/**
|
|
4444
|
+
* Renew an expiring grant. GitHub rotates the refresh token, so store the
|
|
4445
|
+
* answer's `refreshToken` in place of the one you sent.
|
|
4446
|
+
*/
|
|
4447
|
+
readonly refresh: (request: UserAuthRefreshRequest) => Effect.Effect<ExpiringUserTokens, GitHubUserAuthError>;
|
|
4448
|
+
/**
|
|
4449
|
+
* Revoke the user's whole grant to the app, every token it issued included:
|
|
4450
|
+
* `DELETE /applications/{client_id}/grant` with HTTP Basic client
|
|
4451
|
+
* authentication.
|
|
4452
|
+
*
|
|
4453
|
+
* @remarks
|
|
4454
|
+
* A grant that is already gone answers 422, which fails as
|
|
4455
|
+
* `GitHubUserAuthFinal` with `remedy: "reconnect"`; a caller that treats
|
|
4456
|
+
* revocation as idempotent recovers that case.
|
|
4457
|
+
*/
|
|
4458
|
+
readonly revokeGrant: (request: UserAuthRevokeRequest) => Effect.Effect<void, GitHubUserAuthError>;
|
|
4459
|
+
}
|
|
4460
|
+
declare const GitHubUserAuth_base: Context.ServiceClass<GitHubUserAuth, "@effected/github/GitHubUserAuth", GitHubUserAuthShape>;
|
|
4461
|
+
/**
|
|
4462
|
+
* The OAuth web flow a GitHub App (or an OAuth App) uses to act as a user:
|
|
4463
|
+
* PKCE code exchange, refresh, and grant revoke.
|
|
4464
|
+
*
|
|
4465
|
+
* @remarks
|
|
4466
|
+
* None of these calls go through `GitHubClient`: the token endpoint lives on
|
|
4467
|
+
* the web host rather than the REST host, and the revoke authenticates as the
|
|
4468
|
+
* app's OAuth client with HTTP Basic rather than with a bearer token. So the
|
|
4469
|
+
* service speaks to `fetch` directly, and this module imports neither octokit
|
|
4470
|
+
* nor the JWT signer — a Worker that only signs users in links neither.
|
|
4471
|
+
*
|
|
4472
|
+
* Every failure is one of two errors, and the split is the point:
|
|
4473
|
+
* {@link GitHubUserAuthFinal} when GitHub refused (read its `remedy` before
|
|
4474
|
+
* dropping anything), {@link GitHubUserAuthTemporary} when no real answer
|
|
4475
|
+
* arrived. GitHub answers a refused code or refresh token with HTTP 200 and an
|
|
4476
|
+
* `error` body, which is read as the refusal it is.
|
|
4477
|
+
*
|
|
4478
|
+
* The client secret, the code, the verifier and both tokens appear in no
|
|
4479
|
+
* error message, no span annotation and no kept cause.
|
|
4480
|
+
*
|
|
4481
|
+
* @example
|
|
4482
|
+
* ```ts
|
|
4483
|
+
* import { GitHubUserAuth } from "@effected/github";
|
|
4484
|
+
* import { Effect, Redacted } from "effect";
|
|
4485
|
+
*
|
|
4486
|
+
* const UserAuth = GitHubUserAuth.layer({
|
|
4487
|
+
* clientId: "Iv23liExample",
|
|
4488
|
+
* clientSecret: Redacted.make("app-client-secret"),
|
|
4489
|
+
* });
|
|
4490
|
+
*
|
|
4491
|
+
* const signIn = (code: string, codeVerifier: string) =>
|
|
4492
|
+
* Effect.gen(function* () {
|
|
4493
|
+
* const auth = yield* GitHubUserAuth;
|
|
4494
|
+
* return yield* auth.exchange({ code, codeVerifier, redirectUri: "https://app.example/callback" });
|
|
4495
|
+
* });
|
|
4496
|
+
*
|
|
4497
|
+
* Effect.runPromise(signIn("code-from-query", "verifier").pipe(Effect.provide(UserAuth)));
|
|
4498
|
+
* ```
|
|
4499
|
+
*
|
|
4500
|
+
* @public
|
|
4501
|
+
*/
|
|
4502
|
+
export declare class GitHubUserAuth extends GitHubUserAuth_base {
|
|
4503
|
+
/**
|
|
4504
|
+
* The live service over `fetch`.
|
|
4505
|
+
*
|
|
4506
|
+
* @remarks
|
|
4507
|
+
* Parameterized, so **bind the result to a `const`** and reuse it: each
|
|
4508
|
+
* call mints a fresh layer, and layers are memoized by reference.
|
|
4509
|
+
*
|
|
4510
|
+
* Bad wiring — an empty client id, a URL that does not parse or is not
|
|
4511
|
+
* `http(s)`, an api-version that is not `YYYY-MM-DD`, a timeout that is not
|
|
4512
|
+
* finite and positive — dies while the layer builds, with a defect naming
|
|
4513
|
+
* the option.
|
|
4514
|
+
*/
|
|
4515
|
+
static readonly layer: (options: GitHubUserAuthOptions) => Layer.Layer<GitHubUserAuth>;
|
|
4516
|
+
/** An in-memory double; an unstubbed member dies when run, naming itself. */
|
|
4517
|
+
static readonly makeTest: (overrides?: Partial<GitHubUserAuthShape>) => GitHubUserAuthShape;
|
|
4518
|
+
/** {@link GitHubUserAuth.makeTest} behind a `Layer`. */
|
|
4519
|
+
static readonly layerTest: (overrides?: Partial<GitHubUserAuthShape>) => Layer.Layer<GitHubUserAuth>;
|
|
4520
|
+
}
|
|
4097
4521
|
declare const TagRef_base: Schema.Class<TagRef, Schema.Struct<{
|
|
4098
4522
|
/** The tag name, without `refs/tags/`. */
|
|
4099
4523
|
readonly tag: Schema.NonEmptyString;
|
|
@@ -5185,5 +5609,5 @@ export declare class WorkflowDispatch extends WorkflowDispatch_base {
|
|
|
5185
5609
|
/** {@link WorkflowDispatch.makeTest} behind a `Layer`. */
|
|
5186
5610
|
static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
|
|
5187
5611
|
}
|
|
5188
|
-
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 };
|
|
5612
|
+
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 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 };
|
|
5189
5613
|
//# sourceMappingURL=index.d.ts.map
|
package/index.js
CHANGED
|
@@ -6,7 +6,7 @@ import { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput,
|
|
|
6
6
|
import { CodeScanning } from "./CodeScanning.js";
|
|
7
7
|
import { DeploymentEnvironment } from "./DeploymentEnvironment.js";
|
|
8
8
|
import { GitBranch } from "./GitBranch.js";
|
|
9
|
-
import { CommitRef, FileChange, FileContent, FileDeletion, FileMode, GitCommit } from "./GitCommit.js";
|
|
9
|
+
import { CommitRef, CreatedCommit, FileChange, FileContent, FileDeletion, FileMode, GitCommit } from "./GitCommit.js";
|
|
10
10
|
import { AppIdentity, BotIdentity, BotUser, GitHubApp, GitHubAppError, Installation, InstallationToken } from "./GitHubApp.js";
|
|
11
11
|
import { GitHubClient, GitHubFixtures, RawFailure } from "./GitHubClient.js";
|
|
12
12
|
import { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit } from "./GitHubCommit.js";
|
|
@@ -15,6 +15,7 @@ import { GitHubError, GitHubErrorKind, GitHubValidationCode, GitHubValidationEnt
|
|
|
15
15
|
import { CommentOnceResult, GitHubIssue, IssueInfo, LinkedIssue } from "./GitHubIssue.js";
|
|
16
16
|
import { GitHubRelease, ReleaseAsset, ReleaseInfo } from "./GitHubRelease.js";
|
|
17
17
|
import { GRAPHQL_ONLY_SETTINGS, GitHubRepository, SECURITY_ANALYSIS_STATUS_FIELDS, repositoryPatch, transformSecurityAndAnalysis } from "./GitHubRepository.js";
|
|
18
|
+
import { ExpiringUserTokens, GitHubUserAuth, GitHubUserAuthFinal, GitHubUserAuthOperation, GitHubUserAuthTemporary, GitHubUserTokens, NonExpiringUserTokens } from "./GitHubUserAuth.js";
|
|
18
19
|
import { GitTag, SemverTag, TagRef, versionFromTag } from "./GitTag.js";
|
|
19
20
|
import { GitHubGraphQLError, GraphQLDocument, GraphQLErrorEntry } from "./GraphQL.js";
|
|
20
21
|
import { InstallationTokenStore } from "./InstallationTokenStore.js";
|
|
@@ -31,4 +32,4 @@ import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, Toke
|
|
|
31
32
|
import { DispatchedRun, WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
|
|
32
33
|
import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
|
|
33
34
|
|
|
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, 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 };
|
|
35
|
+
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, 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, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, NonExpiringUserTokens, 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 };
|
|
@@ -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 };
|
package/internal/octokit.js
CHANGED
|
@@ -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 {
|
|
204
|
+
export { expandOnDotcom, makeTransport };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@effected/github",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.30.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.
|
|
41
|
+
"@effected/crypto": "^0.6.0",
|
|
42
42
|
"@effected/github-references": "^0.14.0",
|
|
43
|
-
"@effected/jwt": "^0.9.
|
|
43
|
+
"@effected/jwt": "^0.9.1",
|
|
44
44
|
"@effected/oidc": "^0.4.0",
|
|
45
|
-
"@effected/semver": "^0.
|
|
45
|
+
"@effected/semver": "^0.22.0",
|
|
46
46
|
"@octokit/core": "^7.0.6",
|
|
47
47
|
"@octokit/plugin-paginate-rest": "^16.0.0",
|
|
48
48
|
"@octokit/types": "^18.0.0",
|