@theholocron/cli 5.0.0-alpha.278 → 5.0.0-alpha.279
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/dist/cli.mjs +212 -11
- package/dist/cli.mjs.map +1 -1
- package/dist/{index-4Xmvf7KG.d.mts → index-B59MneN-.d.mts} +1 -1
- package/dist/{index-D_HJGtOY.d.mts → index-aQ7iGTl7.d.mts} +315 -2
- package/dist/index.d.mts +2 -2
- package/dist/plugin/capabilities.d.mts +1 -1
- package/dist/plugin/capabilities.mjs +23 -0
- package/dist/presets.d.mts +1 -1
- package/package.json +6 -6
|
@@ -12,41 +12,70 @@ import { ProviderApiError } from "@theholocron/http-client";
|
|
|
12
12
|
* (issue: #74).
|
|
13
13
|
*/
|
|
14
14
|
type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "monitoring" | "wiki" | "workers";
|
|
15
|
+
/** How many providers a capability resolves to: one (`"single"`) or several at once (`"many"`). */
|
|
15
16
|
type Cardinality = "single" | "many";
|
|
17
|
+
/** What every capability implementation carries: which capability it is and which provider backs it. */
|
|
16
18
|
interface ProviderIdentity {
|
|
19
|
+
/** The capability this implementation provides. */
|
|
17
20
|
readonly key: CapabilityKey;
|
|
21
|
+
/** The provider's name, e.g. `github` or `vercel`. */
|
|
18
22
|
readonly providerName: string;
|
|
19
23
|
}
|
|
24
|
+
/** A repository ruleset as {@link Source.listRulesets} reports it. */
|
|
20
25
|
interface Ruleset {
|
|
26
|
+
/** The provider's numeric id for the ruleset. */
|
|
21
27
|
id: number;
|
|
28
|
+
/** The ruleset's name. */
|
|
22
29
|
name: string;
|
|
30
|
+
/** Whether the ruleset is enforced (`active`), only logged (`evaluate`) or off (`disabled`). */
|
|
23
31
|
enforcement: "active" | "evaluate" | "disabled";
|
|
32
|
+
/** What the ruleset applies to, e.g. `branch`; `undefined` when the provider does not say. */
|
|
24
33
|
target?: string;
|
|
25
34
|
}
|
|
35
|
+
/** The repository settings {@link Source.updateRepoSettings} can change; a field left out is left alone. */
|
|
26
36
|
interface RepoSettings {
|
|
37
|
+
/** Allow merging a pull request by squashing its commits. */
|
|
27
38
|
allow_squash_merge?: boolean;
|
|
39
|
+
/** Allow merging a pull request with a merge commit. */
|
|
28
40
|
allow_merge_commit?: boolean;
|
|
41
|
+
/** Allow merging a pull request by rebasing its commits. */
|
|
29
42
|
allow_rebase_merge?: boolean;
|
|
43
|
+
/** Allow a pull request to be set to merge itself once its checks pass. */
|
|
30
44
|
allow_auto_merge?: boolean;
|
|
31
45
|
/** Always suggest updating PR branches when the base branch has new commits. */
|
|
32
46
|
allow_update_branch?: boolean;
|
|
47
|
+
/** Delete a pull request's head branch once it is merged. */
|
|
33
48
|
delete_branch_on_merge?: boolean;
|
|
49
|
+
/** The branch a fresh clone checks out. */
|
|
34
50
|
default_branch?: string;
|
|
51
|
+
/** Whether the repository has an issue tracker. */
|
|
35
52
|
has_issues?: boolean;
|
|
53
|
+
/** Whether the repository has discussions. */
|
|
36
54
|
has_discussions?: boolean;
|
|
55
|
+
/** Whether the repository has project boards. */
|
|
37
56
|
has_projects?: boolean;
|
|
57
|
+
/** Whether the repository has a wiki. */
|
|
38
58
|
has_wiki?: boolean;
|
|
39
59
|
}
|
|
60
|
+
/** The repository a {@link Source} provider is scoped to. */
|
|
40
61
|
interface RepoRef {
|
|
62
|
+
/** The account or organization that owns the repository. */
|
|
41
63
|
owner: string;
|
|
64
|
+
/** The repository's name, without the owner. */
|
|
42
65
|
name: string;
|
|
66
|
+
/** The branch a fresh clone checks out. */
|
|
43
67
|
defaultBranch: string;
|
|
44
68
|
}
|
|
69
|
+
/** A repository label as the canonical set passed to {@link Source.syncLabels} defines it. */
|
|
45
70
|
interface LabelDef {
|
|
71
|
+
/** The label's name. */
|
|
46
72
|
readonly name: string;
|
|
73
|
+
/** The label's colour as a hex string. */
|
|
47
74
|
readonly color: string;
|
|
75
|
+
/** What the label is for; an empty string when it has none. */
|
|
48
76
|
readonly description: string;
|
|
49
77
|
}
|
|
78
|
+
/** The access level a team can hold on a repository, from least (`pull`) to most (`admin`). */
|
|
50
79
|
type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
|
|
51
80
|
/** Shorthand `"slug"` defaults to `push` permission. */
|
|
52
81
|
type TeamEntry = string | {
|
|
@@ -101,29 +130,41 @@ interface SourceTeamMember {
|
|
|
101
130
|
}
|
|
102
131
|
/** A file read by {@link Source.readFile}. */
|
|
103
132
|
interface SourceFile {
|
|
133
|
+
/** The file's text. */
|
|
104
134
|
content: string;
|
|
105
135
|
/** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
|
|
106
136
|
version: string;
|
|
107
137
|
}
|
|
138
|
+
/** Source hosting: the repository, its rulesets, settings, security features, workflow files and pull requests. */
|
|
108
139
|
interface Source extends ProviderIdentity {
|
|
140
|
+
/** Identifies this provider as the `source` capability. */
|
|
109
141
|
readonly key: "source";
|
|
110
142
|
/** Auth sanity-check. Throws ProviderApiError on auth failure. */
|
|
111
143
|
whoami(): Promise<{
|
|
112
144
|
login: string;
|
|
113
145
|
}>;
|
|
146
|
+
/** The repository this provider is scoped to: its owner, name and default branch. */
|
|
114
147
|
getRepo(): Promise<RepoRef>;
|
|
148
|
+
/** Every ruleset on the repository. */
|
|
115
149
|
listRulesets(): Promise<Ruleset[]>;
|
|
150
|
+
/** Create a ruleset from the provider's own payload shape and return it. */
|
|
116
151
|
createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
|
|
152
|
+
/** Replace the ruleset with the given id using the provider's own payload shape. */
|
|
117
153
|
updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
|
|
154
|
+
/** Change the repository's merge and feature settings; only the fields given are changed. */
|
|
118
155
|
updateRepoSettings(settings: RepoSettings): Promise<void>;
|
|
119
156
|
/**
|
|
120
157
|
* Classic branch protection — fallback for private repos on free plans
|
|
121
158
|
* where the Rulesets API (requires Team+) returns 403.
|
|
122
159
|
*/
|
|
123
160
|
protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
|
|
161
|
+
/** Turn on vulnerability alerts (dependency advisories) for the repository. */
|
|
124
162
|
enableVulnerabilityAlerts(): Promise<void>;
|
|
163
|
+
/** Turn on automated security updates, which open pull requests for vulnerable dependencies. */
|
|
125
164
|
enableAutomatedSecurityFixes(): Promise<void>;
|
|
165
|
+
/** Turn on secret scanning, and push protection with it. */
|
|
126
166
|
enableSecretScanning(): Promise<void>;
|
|
167
|
+
/** Turn on private vulnerability reporting, so people can report a vulnerability to the maintainers privately. */
|
|
127
168
|
enablePrivateVulnerabilityReporting(): Promise<void>;
|
|
128
169
|
/**
|
|
129
170
|
* Enables the dependency graph and automatic dependency snapshot
|
|
@@ -145,9 +186,13 @@ interface Source extends ProviderIdentity {
|
|
|
145
186
|
* while default setup is active.
|
|
146
187
|
*/
|
|
147
188
|
disableDefaultCodeScanning(): Promise<void>;
|
|
189
|
+
/** The file names in the workflow directory, sorted; empty when the directory does not exist. */
|
|
148
190
|
listWorkflowFiles(): Promise<string[]>;
|
|
191
|
+
/** The contents of one workflow file, or `null` when it does not exist. */
|
|
149
192
|
readWorkflowFile(name: string): Promise<string | null>;
|
|
193
|
+
/** Write one workflow file, creating the workflow directory if needed and replacing a file of that name. */
|
|
150
194
|
writeWorkflowFile(name: string, contents: string): Promise<void>;
|
|
195
|
+
/** Delete one workflow file; one that is already gone is not an error. */
|
|
151
196
|
removeWorkflowFile(name: string): Promise<void>;
|
|
152
197
|
/**
|
|
153
198
|
* Write an arbitrary file relative to the repo root. Used for
|
|
@@ -318,6 +363,7 @@ interface Source extends ProviderIdentity {
|
|
|
318
363
|
*/
|
|
319
364
|
configurePages?(config: PagesConfig, token: string): Promise<void>;
|
|
320
365
|
}
|
|
366
|
+
/** How GitHub Pages is set up for a repository, as {@link Source.configurePages} takes it. */
|
|
321
367
|
interface PagesConfig {
|
|
322
368
|
/** GitHub Pages build source. */
|
|
323
369
|
build: "workflow" | "branch";
|
|
@@ -337,8 +383,11 @@ interface SourceBranch {
|
|
|
337
383
|
/** The commit the branch points at. */
|
|
338
384
|
sha: string;
|
|
339
385
|
}
|
|
386
|
+
/** A pull request as {@link Source.getPullRequest} and {@link Source.listPullRequests} report it. */
|
|
340
387
|
interface PullRequest {
|
|
388
|
+
/** The pull request's number within the repository. */
|
|
341
389
|
number: number;
|
|
390
|
+
/** The pull request's title. */
|
|
342
391
|
title: string;
|
|
343
392
|
/** "open" | "closed" — GitHub marks merged PRs as "closed". */
|
|
344
393
|
state: "open" | "closed";
|
|
@@ -348,29 +397,49 @@ interface PullRequest {
|
|
|
348
397
|
branch: string;
|
|
349
398
|
/** The commit the head branch pointed at when the PR was last read. */
|
|
350
399
|
headSha?: string;
|
|
400
|
+
/** The address of the pull request's page. */
|
|
351
401
|
url: string;
|
|
352
402
|
}
|
|
403
|
+
/** Where a workflow run is in its life; a finished run carries its outcome (`success`, `failure`, ...). */
|
|
353
404
|
type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
|
|
405
|
+
/** One run of a CI workflow. */
|
|
354
406
|
interface CiRun {
|
|
407
|
+
/** The provider's id for the run. */
|
|
355
408
|
id: string | number;
|
|
409
|
+
/** The workflow's name, falling back to the run's display title. */
|
|
356
410
|
workflowName: string;
|
|
411
|
+
/** The branch the run was triggered on. */
|
|
357
412
|
branch: string;
|
|
413
|
+
/** The commit the run was for. */
|
|
358
414
|
sha: string;
|
|
415
|
+
/** Where the run is, or how it ended once finished. */
|
|
359
416
|
status: CiRunStatus;
|
|
417
|
+
/** The address of the run's page. */
|
|
360
418
|
url: string;
|
|
419
|
+
/** When the run started, as an ISO timestamp. */
|
|
361
420
|
startedAt: string;
|
|
421
|
+
/** When the run finished, as an ISO timestamp; `undefined` while it is still going. */
|
|
362
422
|
completedAt?: string;
|
|
363
423
|
}
|
|
424
|
+
/** What {@link Ci.listRuns} narrows its result by; a field left out does not filter. */
|
|
364
425
|
interface CiRunFilter {
|
|
426
|
+
/** Only runs on this branch. */
|
|
365
427
|
branch?: string;
|
|
428
|
+
/** Only runs in this state. */
|
|
366
429
|
status?: CiRunStatus;
|
|
430
|
+
/** The most runs to return. */
|
|
367
431
|
limit?: number;
|
|
368
432
|
}
|
|
433
|
+
/** CI history: lists workflow runs and reads one back, with no way to start or change one. */
|
|
369
434
|
interface Ci extends ProviderIdentity {
|
|
435
|
+
/** Identifies this provider as the `ci` capability. */
|
|
370
436
|
readonly key: "ci";
|
|
437
|
+
/** Recent workflow runs, narrowed by `filter` when given. */
|
|
371
438
|
listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
|
|
439
|
+
/** One workflow run by its id. */
|
|
372
440
|
getRun(id: string | number): Promise<CiRun>;
|
|
373
441
|
}
|
|
442
|
+
/** Where a secret lives: the repository, one of its environments, or the organization. */
|
|
374
443
|
type SecretScope = {
|
|
375
444
|
kind: "repo";
|
|
376
445
|
} | {
|
|
@@ -380,51 +449,81 @@ type SecretScope = {
|
|
|
380
449
|
kind: "organization";
|
|
381
450
|
name: string;
|
|
382
451
|
};
|
|
452
|
+
/** A destination for secrets (CI or platform secrets) that `holocron secrets sync` writes into. */
|
|
383
453
|
interface Secrets extends ProviderIdentity {
|
|
454
|
+
/** Identifies this provider as the `secrets` capability. */
|
|
384
455
|
readonly key: "secrets";
|
|
385
456
|
/** List secret NAMES (not values) at the given scope. */
|
|
386
457
|
listSecrets(scope: SecretScope): Promise<string[]>;
|
|
387
458
|
/** Idempotent upsert. Adapter handles encryption. */
|
|
388
459
|
setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
|
|
460
|
+
/** Remove a secret at the given scope. */
|
|
389
461
|
deleteSecret(scope: SecretScope, name: string): Promise<void>;
|
|
390
462
|
}
|
|
463
|
+
/** Someone whose approval a deployment to an environment needs. */
|
|
391
464
|
interface EnvironmentReviewer {
|
|
465
|
+
/** Whether the reviewer is a person (`User`) or a team (`Team`). */
|
|
392
466
|
type: "User" | "Team";
|
|
393
467
|
/** Numeric id — GitHub's reviewer API silently ignores login strings. */
|
|
394
468
|
id: number;
|
|
395
469
|
}
|
|
470
|
+
/** A named deployment environment and the protection rules on it. */
|
|
396
471
|
interface Environment {
|
|
472
|
+
/** The environment's name, e.g. `production`. */
|
|
397
473
|
name: string;
|
|
474
|
+
/** Who must approve a deployment to the environment. */
|
|
398
475
|
reviewers?: EnvironmentReviewer[];
|
|
476
|
+
/** Minutes a deployment waits before it proceeds. */
|
|
399
477
|
waitTimer?: number;
|
|
478
|
+
/** Whether the person who started a deployment is barred from approving it. */
|
|
400
479
|
preventSelfReview?: boolean;
|
|
401
480
|
}
|
|
481
|
+
/** Named deployment environments and their protection rules. */
|
|
402
482
|
interface Environments extends ProviderIdentity {
|
|
483
|
+
/** Identifies this provider as the `environments` capability. */
|
|
403
484
|
readonly key: "environments";
|
|
485
|
+
/** Every environment on the repository. */
|
|
404
486
|
listEnvironments(): Promise<Environment[]>;
|
|
487
|
+
/** Create the environment, or bring an existing one of that name in line with `env`. */
|
|
405
488
|
upsertEnvironment(env: Environment): Promise<void>;
|
|
489
|
+
/** Delete the environment with the given name. */
|
|
406
490
|
deleteEnvironment(name: string): Promise<void>;
|
|
407
491
|
}
|
|
492
|
+
/** A step in an issue's life that {@link Issues.transition} can move it to. */
|
|
408
493
|
type LifecycleSlot = "inProgress" | "inReview" | "done";
|
|
494
|
+
/** The tracker-neutral group a provider's own status names fall into. */
|
|
409
495
|
type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
|
|
496
|
+
/** A person in the issue tracker. */
|
|
410
497
|
interface TrackerUser {
|
|
498
|
+
/** The tracker's id for the person. */
|
|
411
499
|
id: string;
|
|
500
|
+
/** The name shown for the person. */
|
|
412
501
|
displayName: string;
|
|
502
|
+
/** Their email address, when the tracker shares it. */
|
|
413
503
|
emailAddress?: string;
|
|
414
504
|
}
|
|
505
|
+
/** An issue in the tracker, in a shape that does not depend on the provider. */
|
|
415
506
|
interface Issue {
|
|
416
507
|
/** Human-readable key — "#42" for GitHub, "RANDO-42" for Jira. */
|
|
417
508
|
key: string;
|
|
418
509
|
/** Internal opaque id. */
|
|
419
510
|
id: string;
|
|
511
|
+
/** The issue's title. */
|
|
420
512
|
summary: string;
|
|
513
|
+
/** The issue's description; `undefined` when the provider did not return one. */
|
|
421
514
|
body?: string;
|
|
515
|
+
/** The provider's own status name. */
|
|
422
516
|
status: string;
|
|
517
|
+
/** The group the status falls into. */
|
|
423
518
|
statusCategory: StatusCategory;
|
|
519
|
+
/** Who the issue is assigned to; `null` when nobody. */
|
|
424
520
|
assignee: TrackerUser | null;
|
|
521
|
+
/** When the issue last changed, as an ISO timestamp. */
|
|
425
522
|
updated: string;
|
|
523
|
+
/** The address of the issue's page, when the provider gives one. */
|
|
426
524
|
url?: string;
|
|
427
525
|
}
|
|
526
|
+
/** What {@link Issues.search} narrows its result by; a field left out does not filter. */
|
|
428
527
|
interface IssueSearchFilter {
|
|
429
528
|
/** Restrict to issues assigned to a specific id, or 'currentUser'. */
|
|
430
529
|
assignee?: string | "currentUser";
|
|
@@ -433,6 +532,7 @@ interface IssueSearchFilter {
|
|
|
433
532
|
/** Max number of issues to return. Adapters apply a sensible default. */
|
|
434
533
|
limit?: number;
|
|
435
534
|
}
|
|
535
|
+
/** What {@link Issues.transition} did. */
|
|
436
536
|
interface LifecycleResult {
|
|
437
537
|
/** False when no API write happened (already at target state). */
|
|
438
538
|
transitioned: boolean;
|
|
@@ -441,6 +541,7 @@ interface LifecycleResult {
|
|
|
441
541
|
/** Adapter-specific note (e.g., "label set" / "closed (completed)"). */
|
|
442
542
|
via?: string;
|
|
443
543
|
}
|
|
544
|
+
/** What {@link Issues.doctor} found about the tracker connection, for `holocron doctor` to print. */
|
|
444
545
|
interface TrackerDoctorReport {
|
|
445
546
|
/** "Authenticated as ..." subject for the spinner. */
|
|
446
547
|
authedAs: string;
|
|
@@ -463,12 +564,17 @@ interface TrackerDoctorReport {
|
|
|
463
564
|
note: string;
|
|
464
565
|
}>;
|
|
465
566
|
}
|
|
567
|
+
/** An issue tracker: finds, reads, creates, moves and comments on issues. */
|
|
466
568
|
interface Issues extends ProviderIdentity {
|
|
569
|
+
/** Identifies this provider as the `issues` capability. */
|
|
467
570
|
readonly key: "issues";
|
|
468
571
|
/** Currently-authenticated user. */
|
|
469
572
|
getMyself(): Promise<TrackerUser>;
|
|
573
|
+
/** Issues matching `filter`. */
|
|
470
574
|
search(filter: IssueSearchFilter): Promise<Issue[]>;
|
|
575
|
+
/** One issue by its human-readable key (e.g. `#42`). */
|
|
471
576
|
get(key: string): Promise<Issue>;
|
|
577
|
+
/** Open a new issue and return its key. */
|
|
472
578
|
create(input: {
|
|
473
579
|
summary: string;
|
|
474
580
|
body?: string;
|
|
@@ -480,7 +586,9 @@ interface Issues extends ProviderIdentity {
|
|
|
480
586
|
}>;
|
|
481
587
|
/** Idempotent — `transitioned: false` if the issue is already at the target. */
|
|
482
588
|
transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
|
|
589
|
+
/** Add a comment to the issue. */
|
|
483
590
|
comment(key: string, body: string): Promise<void>;
|
|
591
|
+
/** Check the tracker connection and how the lifecycle slots map onto the tracker's statuses. */
|
|
484
592
|
doctor(): Promise<TrackerDoctorReport>;
|
|
485
593
|
}
|
|
486
594
|
/** Env-var scope on the deploy platform. */
|
|
@@ -490,28 +598,40 @@ type DeploymentTarget = "development" | "preview" | "production";
|
|
|
490
598
|
* preview (no named environment).
|
|
491
599
|
*/
|
|
492
600
|
type DeploymentTrigger = "production" | "staging";
|
|
601
|
+
/** A project on the deployment platform. */
|
|
493
602
|
interface DeploymentProject {
|
|
603
|
+
/** The platform's id for the project. */
|
|
494
604
|
id: string;
|
|
605
|
+
/** The project's name. */
|
|
495
606
|
name: string;
|
|
607
|
+
/** The framework preset the project uses, when the platform reports one. */
|
|
496
608
|
framework?: string;
|
|
497
609
|
/** True when the project is linked to a Git provider. */
|
|
498
610
|
gitLinked?: boolean;
|
|
611
|
+
/** The directory in the repository the project builds from; `null` or `undefined` for the repository root. */
|
|
499
612
|
rootDirectory?: string | null;
|
|
500
613
|
}
|
|
614
|
+
/** The project settings {@link Deployment.updateProjectSettings} can change; a field left out is left alone. */
|
|
501
615
|
interface DeploymentProjectSettings {
|
|
616
|
+
/** Turn off preview deployments for the project. */
|
|
502
617
|
previewDeploymentsDisabled?: boolean;
|
|
503
618
|
/** Vercel-specific: whether the GitHub integration creates deployments
|
|
504
619
|
* for every push (false → only on-demand triggers). */
|
|
505
620
|
gitProviderCreateDeployments?: boolean;
|
|
506
621
|
}
|
|
622
|
+
/** One deployment on the platform. */
|
|
507
623
|
interface DeploymentRecord {
|
|
624
|
+
/** The platform's id for the deployment. */
|
|
508
625
|
id: string;
|
|
626
|
+
/** The address the deployment is served at. */
|
|
509
627
|
url: string;
|
|
510
628
|
/** Branch this deployment was made from (null if not git-sourced). */
|
|
511
629
|
branch: string | null;
|
|
512
630
|
/** Named environment if one was targeted; undefined for branch previews. */
|
|
513
631
|
target?: DeploymentTrigger;
|
|
632
|
+
/** Where the deployment is in its build. */
|
|
514
633
|
status: "queued" | "building" | "ready" | "error" | "cancelled";
|
|
634
|
+
/** When the deployment was created, as an ISO timestamp. */
|
|
515
635
|
createdAt?: string;
|
|
516
636
|
/** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
|
|
517
637
|
errorMessage?: string;
|
|
@@ -530,11 +650,16 @@ interface DeployFunctionConfig {
|
|
|
530
650
|
*/
|
|
531
651
|
target?: DeploymentTrigger;
|
|
532
652
|
}
|
|
653
|
+
/** What {@link Deployment.deployFunction} made. */
|
|
533
654
|
interface DeployFunctionResult {
|
|
655
|
+
/** The platform's id for the new deployment. */
|
|
534
656
|
deploymentId: string;
|
|
657
|
+
/** The address the deployment is served at. */
|
|
535
658
|
url: string;
|
|
536
659
|
}
|
|
660
|
+
/** A deployment platform: projects, environment variables and deployments. */
|
|
537
661
|
interface Deployment extends ProviderIdentity {
|
|
662
|
+
/** Identifies this provider as the `deployment` capability. */
|
|
538
663
|
readonly key: "deployment";
|
|
539
664
|
/**
|
|
540
665
|
* Custom domain declared in the deployment provider's configuration.
|
|
@@ -542,6 +667,7 @@ interface Deployment extends ProviderIdentity {
|
|
|
542
667
|
* returned verification record to the `dns` capability.
|
|
543
668
|
*/
|
|
544
669
|
readonly domain?: string;
|
|
670
|
+
/** Every project the account can see. */
|
|
545
671
|
listProjects(): Promise<DeploymentProject[]>;
|
|
546
672
|
/** Create if missing, otherwise return existing. Idempotent. */
|
|
547
673
|
ensureProject(input: {
|
|
@@ -551,8 +677,11 @@ interface Deployment extends ProviderIdentity {
|
|
|
551
677
|
repo?: string;
|
|
552
678
|
rootDirectory?: string;
|
|
553
679
|
}): Promise<DeploymentProject>;
|
|
680
|
+
/** Change the project's settings; only the fields given are changed. Returns the project afterwards. */
|
|
554
681
|
updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
|
|
682
|
+
/** The names (not values) of the environment variables set on the project for `target`. */
|
|
555
683
|
listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
|
|
684
|
+
/** Set an environment variable on the project for `target`, replacing any existing value. */
|
|
556
685
|
setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
|
|
557
686
|
/**
|
|
558
687
|
* Kick off a deployment of the given branch. Omit `target` for a
|
|
@@ -564,6 +693,7 @@ interface Deployment extends ProviderIdentity {
|
|
|
564
693
|
branch: string;
|
|
565
694
|
target?: DeploymentTrigger;
|
|
566
695
|
}): Promise<DeploymentRecord>;
|
|
696
|
+
/** One deployment by its id. */
|
|
567
697
|
getDeployment(deploymentId: string): Promise<DeploymentRecord>;
|
|
568
698
|
/**
|
|
569
699
|
* Deploy (or update) a project directly from source files, bypassing
|
|
@@ -600,18 +730,25 @@ interface Deployment extends ProviderIdentity {
|
|
|
600
730
|
*/
|
|
601
731
|
ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
|
|
602
732
|
}
|
|
733
|
+
/** A branch of a database or other store, as {@link Storage.listBranches} reports it. */
|
|
603
734
|
interface StorageBranch {
|
|
735
|
+
/** The provider's id for the branch. */
|
|
604
736
|
id: string;
|
|
737
|
+
/** The branch's name. */
|
|
605
738
|
name: string;
|
|
606
739
|
/** Parent branch id; null for the root/main branch. */
|
|
607
740
|
parentId: string | null;
|
|
741
|
+
/** When the branch was created, as an ISO timestamp. */
|
|
608
742
|
createdAt: string;
|
|
609
743
|
}
|
|
744
|
+
/** Options for {@link Storage.getConnectionString}. */
|
|
610
745
|
interface ConnectionStringOptions {
|
|
611
746
|
/** Use the pooled (PgBouncer) URL when available. Defaults to false. */
|
|
612
747
|
pooled?: boolean;
|
|
613
748
|
}
|
|
749
|
+
/** A database or file store: connection strings and, for providers that have them, branches. */
|
|
614
750
|
interface Storage extends ProviderIdentity {
|
|
751
|
+
/** Identifies this provider as the `storage` capability. */
|
|
615
752
|
readonly key: "storage";
|
|
616
753
|
/**
|
|
617
754
|
* Connection string for the given scope. Scope is provider-specific:
|
|
@@ -624,11 +761,14 @@ interface Storage extends ProviderIdentity {
|
|
|
624
761
|
* a scope; the storage plugin doesn't own that mapping.
|
|
625
762
|
*/
|
|
626
763
|
getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
|
|
764
|
+
/** Every branch of the store. */
|
|
627
765
|
listBranches?(): Promise<StorageBranch[]>;
|
|
766
|
+
/** Create a branch named `name`, copied from the `from` branch when given. */
|
|
628
767
|
createBranch?(input: {
|
|
629
768
|
name: string;
|
|
630
769
|
from?: string;
|
|
631
770
|
}): Promise<StorageBranch>;
|
|
771
|
+
/** Delete the branch (by name or id). */
|
|
632
772
|
destroyBranch?(branch: string): Promise<void>;
|
|
633
773
|
/** Restore one branch to match another (e.g., reset preview → main). */
|
|
634
774
|
resetBranch?(input: {
|
|
@@ -644,30 +784,46 @@ interface Storage extends ProviderIdentity {
|
|
|
644
784
|
extension: string;
|
|
645
785
|
}): Promise<void>;
|
|
646
786
|
}
|
|
787
|
+
/** What the auth provider needs the app to be given at runtime. */
|
|
647
788
|
interface AuthDescription {
|
|
789
|
+
/** The provider's name. */
|
|
648
790
|
provider: string;
|
|
649
791
|
/** Env-var names the app needs at runtime (CLERK_PUBLISHABLE_KEY, etc.). */
|
|
650
792
|
envKeys: string[];
|
|
651
793
|
}
|
|
794
|
+
/** What {@link Auth.whoami} found out about the configured credentials. */
|
|
652
795
|
interface AuthIdentity {
|
|
796
|
+
/** The provider's name. */
|
|
653
797
|
provider: string;
|
|
654
798
|
/** Provider-specific health signal (user count, role, account name, etc.). */
|
|
655
799
|
details?: Record<string, unknown>;
|
|
656
800
|
}
|
|
801
|
+
/** A user in the auth provider. */
|
|
657
802
|
interface AuthUser {
|
|
803
|
+
/** The provider's id for the user. */
|
|
658
804
|
id: string;
|
|
805
|
+
/** The user's email address. */
|
|
659
806
|
email: string;
|
|
660
807
|
}
|
|
808
|
+
/** What {@link Auth.createUser} needs to make a user. */
|
|
661
809
|
interface CreateAuthUserInput {
|
|
810
|
+
/** The new user's email address. */
|
|
662
811
|
email: string;
|
|
812
|
+
/** The new user's password. */
|
|
663
813
|
password: string;
|
|
814
|
+
/** The new user's first name. */
|
|
664
815
|
firstName?: string;
|
|
816
|
+
/** The new user's last name. */
|
|
665
817
|
lastName?: string;
|
|
666
818
|
}
|
|
819
|
+
/** Where to configure the auth provider's webhooks. */
|
|
667
820
|
interface WebhookDashboardInfo {
|
|
821
|
+
/** The address of the provider's webhook settings page. */
|
|
668
822
|
url: string;
|
|
669
823
|
}
|
|
824
|
+
/** An identity provider: describes what an app needs from it, proves the credentials work and, where the provider allows, manages users and webhooks. */
|
|
670
825
|
interface Auth extends ProviderIdentity {
|
|
826
|
+
/** Identifies this provider as the `auth` capability. */
|
|
671
827
|
readonly key: "auth";
|
|
672
828
|
/** Env-var keys the runtime app needs. */
|
|
673
829
|
describe(): Promise<AuthDescription>;
|
|
@@ -687,21 +843,31 @@ interface Auth extends ProviderIdentity {
|
|
|
687
843
|
secretRef: string;
|
|
688
844
|
}): Promise<void>;
|
|
689
845
|
}
|
|
846
|
+
/** What happened to a user, in a form that does not depend on the auth provider. */
|
|
690
847
|
type AuthEventType = "user.created" | "user.updated" | "user.deleted";
|
|
848
|
+
/** A user as a webhook event reports it, in a form that does not depend on the auth provider. */
|
|
691
849
|
interface NormalizedAuthUser {
|
|
850
|
+
/** The provider's id for the user. */
|
|
692
851
|
id: string;
|
|
852
|
+
/** The user's email address. */
|
|
693
853
|
email: string;
|
|
854
|
+
/** The user's first name; `null` or `undefined` when none is set. */
|
|
694
855
|
firstName?: string | null;
|
|
856
|
+
/** The user's last name; `null` or `undefined` when none is set. */
|
|
695
857
|
lastName?: string | null;
|
|
696
858
|
/** Provider-native fields preserved verbatim for consumers that need them. */
|
|
697
859
|
raw?: Record<string, unknown>;
|
|
698
860
|
}
|
|
861
|
+
/** A webhook event from the auth provider, in a form that does not depend on the provider. */
|
|
699
862
|
interface AuthEvent {
|
|
863
|
+
/** What happened to the user. */
|
|
700
864
|
type: AuthEventType;
|
|
865
|
+
/** The user the event is about. */
|
|
701
866
|
user: NormalizedAuthUser;
|
|
702
867
|
/** ISO timestamp of when the event occurred. */
|
|
703
868
|
occurredAt: string;
|
|
704
869
|
}
|
|
870
|
+
/** What a plugin's `parseWebhook` needs to verify and translate an incoming webhook request. */
|
|
705
871
|
interface ParseWebhookInput {
|
|
706
872
|
/** Raw request body (string or Buffer). */
|
|
707
873
|
body: string | Buffer;
|
|
@@ -710,11 +876,14 @@ interface ParseWebhookInput {
|
|
|
710
876
|
/** The signing secret the auth provider issued for this webhook endpoint. */
|
|
711
877
|
signingSecret: string;
|
|
712
878
|
}
|
|
879
|
+
/** The outcome of an idempotent `ensure*` call that creates a container. */
|
|
713
880
|
interface EnsureResult {
|
|
714
881
|
/** True when the resource already existed (idempotent no-op). */
|
|
715
882
|
alreadyExists: boolean;
|
|
716
883
|
}
|
|
884
|
+
/** A secret store, the source of truth that `holocron secrets sync` reads from. */
|
|
717
885
|
interface Vault extends ProviderIdentity {
|
|
886
|
+
/** Identifies this provider as the `vault` capability. */
|
|
718
887
|
readonly key: "vault";
|
|
719
888
|
/**
|
|
720
889
|
* Read a secret by reference. The reference format is
|
|
@@ -758,14 +927,23 @@ interface Vault extends ProviderIdentity {
|
|
|
758
927
|
*/
|
|
759
928
|
ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
|
|
760
929
|
}
|
|
930
|
+
/** The DNS record types a provider can manage. */
|
|
761
931
|
type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
|
|
932
|
+
/** A DNS record. */
|
|
762
933
|
interface DnsRecord {
|
|
934
|
+
/** The provider's id for the record; absent on a record not yet created. */
|
|
763
935
|
id?: string;
|
|
936
|
+
/** The record's type. */
|
|
764
937
|
type: DnsRecordType;
|
|
938
|
+
/** The record's name (the host it answers for). */
|
|
765
939
|
name: string;
|
|
940
|
+
/** The record's value, e.g. an address for `A` or a target host for `CNAME`. */
|
|
766
941
|
content: string;
|
|
942
|
+
/** Time to live in seconds; the provider's default when absent. */
|
|
767
943
|
ttl?: number;
|
|
944
|
+
/** Priority, for the record types that have one (`MX`, `SRV`). */
|
|
768
945
|
priority?: number;
|
|
946
|
+
/** Whether traffic goes through the provider's proxy; only providers that offer one use it. */
|
|
769
947
|
proxied?: boolean;
|
|
770
948
|
}
|
|
771
949
|
/**
|
|
@@ -777,12 +955,18 @@ interface DnsRecord {
|
|
|
777
955
|
interface DnsRecordRequest {
|
|
778
956
|
/** Zone apex passed as the first argument to `dns.upsertRecord`. */
|
|
779
957
|
zone: string;
|
|
958
|
+
/** The record to create or update. */
|
|
780
959
|
record: DnsRecord;
|
|
781
960
|
}
|
|
961
|
+
/** DNS record management for a domain. */
|
|
782
962
|
interface Dns extends ProviderIdentity {
|
|
963
|
+
/** Identifies this provider as the `dns` capability. */
|
|
783
964
|
readonly key: "dns";
|
|
965
|
+
/** Every record in the domain's zone. */
|
|
784
966
|
listRecords(domain: string): Promise<DnsRecord[]>;
|
|
967
|
+
/** Create the record, or update the existing one that matches it, and return the result. */
|
|
785
968
|
upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
|
|
969
|
+
/** Delete the record with the given id from the domain's zone. */
|
|
786
970
|
deleteRecord(domain: string, id: string): Promise<void>;
|
|
787
971
|
/**
|
|
788
972
|
* A `holocron doctor` smoke check with no specific domain to ask about —
|
|
@@ -794,7 +978,9 @@ interface Dns extends ProviderIdentity {
|
|
|
794
978
|
zones: number;
|
|
795
979
|
}>;
|
|
796
980
|
}
|
|
981
|
+
/** Error tracking: describes what an app needs at runtime and, where the provider allows, creates projects and relays alerts. */
|
|
797
982
|
interface Errors extends ProviderIdentity {
|
|
983
|
+
/** Identifies this provider as the `errors` capability. */
|
|
798
984
|
readonly key: "errors";
|
|
799
985
|
/** Returns the env var names the app reads at runtime for this provider. */
|
|
800
986
|
describe(): Promise<{
|
|
@@ -812,6 +998,7 @@ interface Errors extends ProviderIdentity {
|
|
|
812
998
|
whoami?(): Promise<{
|
|
813
999
|
org: string;
|
|
814
1000
|
} | null>;
|
|
1001
|
+
/** Create the project if it is missing and return its DSN; `alreadyExists` is true when it was already there. */
|
|
815
1002
|
ensureProject?(input: {
|
|
816
1003
|
name: string;
|
|
817
1004
|
platform?: string;
|
|
@@ -834,6 +1021,7 @@ interface Errors extends ProviderIdentity {
|
|
|
834
1021
|
*/
|
|
835
1022
|
inspectRelay?(input: InspectRelayInput): Promise<RelayState>;
|
|
836
1023
|
}
|
|
1024
|
+
/** What {@link Errors.ensureRelay} sets up at the error tracker. */
|
|
837
1025
|
interface EnsureRelayInput {
|
|
838
1026
|
/** The integration's name at the provider (also how an existing one is found). */
|
|
839
1027
|
name: string;
|
|
@@ -843,7 +1031,9 @@ interface EnsureRelayInput {
|
|
|
843
1031
|
projects: string[];
|
|
844
1032
|
/** The alert rule: its name, and the minutes between two notifications for one issue (default 5). */
|
|
845
1033
|
rule: {
|
|
1034
|
+
/** The alert rule's name at the provider (also how an existing one is found). */
|
|
846
1035
|
name: string;
|
|
1036
|
+
/** Minutes between two notifications for one issue; 5 when absent. */
|
|
847
1037
|
frequency?: number;
|
|
848
1038
|
};
|
|
849
1039
|
}
|
|
@@ -879,18 +1069,28 @@ interface RelayState {
|
|
|
879
1069
|
sends: boolean;
|
|
880
1070
|
}>;
|
|
881
1071
|
}
|
|
1072
|
+
/** What {@link Errors.ensureRelay} did. */
|
|
882
1073
|
interface EnsureRelayResult {
|
|
1074
|
+
/** The integration that posts to the relay. */
|
|
883
1075
|
integration: {
|
|
1076
|
+
/** Whether it was made now rather than adopted. */
|
|
884
1077
|
created: boolean;
|
|
1078
|
+
/** For one adopted, the settings that differed and were changed. */
|
|
885
1079
|
updated: string[];
|
|
886
1080
|
};
|
|
1081
|
+
/** The alert rule that sends through the integration. */
|
|
887
1082
|
rule: {
|
|
1083
|
+
/** Whether it was made now rather than adopted. */
|
|
888
1084
|
created: boolean;
|
|
1085
|
+
/** For one adopted, the settings that differed and were changed. */
|
|
889
1086
|
updated: string[];
|
|
890
1087
|
};
|
|
1088
|
+
/** The integration's signing secret, for the relay to verify alerts with. A credential: never print or store it. */
|
|
891
1089
|
clientSecret?: string;
|
|
892
1090
|
}
|
|
1091
|
+
/** Log aggregation: describes what an app needs at runtime and, where the provider allows, creates the dataset. */
|
|
893
1092
|
interface Logs extends ProviderIdentity {
|
|
1093
|
+
/** Identifies this provider as the `logs` capability. */
|
|
894
1094
|
readonly key: "logs";
|
|
895
1095
|
/** Returns the env var names the app reads at runtime for this provider. */
|
|
896
1096
|
describe(): Promise<{
|
|
@@ -907,24 +1107,36 @@ interface Logs extends ProviderIdentity {
|
|
|
907
1107
|
alreadyExists: boolean;
|
|
908
1108
|
}>;
|
|
909
1109
|
}
|
|
1110
|
+
/** What part of a response a {@link MonitoringAssertion} looks at. */
|
|
910
1111
|
type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
|
|
1112
|
+
/** How a {@link MonitoringAssertion} compares the part of the response with its target. */
|
|
911
1113
|
type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
|
|
1114
|
+
/** A condition a monitoring check's response must meet to pass. */
|
|
912
1115
|
interface MonitoringAssertion {
|
|
1116
|
+
/** The part of the response to look at. */
|
|
913
1117
|
source: MonitoringAssertionSource;
|
|
1118
|
+
/** How to compare it with `target`. */
|
|
914
1119
|
comparison: MonitoringAssertionComparison;
|
|
915
1120
|
/** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
|
|
916
1121
|
property?: string;
|
|
1122
|
+
/** The value to compare against. */
|
|
917
1123
|
target?: string;
|
|
918
1124
|
}
|
|
1125
|
+
/** The HTTP methods a monitoring check can use. */
|
|
919
1126
|
type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
|
|
1127
|
+
/** A monitoring check, in a form that does not depend on the provider. */
|
|
920
1128
|
interface MonitoringCheckInput {
|
|
921
1129
|
/** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
|
|
922
1130
|
name: string;
|
|
1131
|
+
/** The address to request. */
|
|
923
1132
|
url: string;
|
|
1133
|
+
/** The HTTP method; the provider's default when absent. */
|
|
924
1134
|
method?: MonitoringHttpMethod;
|
|
925
1135
|
/** Minutes between runs. Adapters round to their own supported values. */
|
|
926
1136
|
frequency?: number;
|
|
1137
|
+
/** Conditions the response must meet; the provider's default check when absent. */
|
|
927
1138
|
assertions?: MonitoringAssertion[];
|
|
1139
|
+
/** Whether the check runs; the provider's default when absent. */
|
|
928
1140
|
activated?: boolean;
|
|
929
1141
|
/**
|
|
930
1142
|
* Provider-specific region/datacenter ids to run the check from (e.g.
|
|
@@ -951,8 +1163,11 @@ interface MonitoringCheckInput {
|
|
|
951
1163
|
*/
|
|
952
1164
|
body?: string;
|
|
953
1165
|
}
|
|
1166
|
+
/** A check as the provider holds it. */
|
|
954
1167
|
interface MonitoringCheck {
|
|
1168
|
+
/** The provider's id for the check. */
|
|
955
1169
|
id: string;
|
|
1170
|
+
/** The check's name. */
|
|
956
1171
|
name: string;
|
|
957
1172
|
}
|
|
958
1173
|
/** A place the monitoring provider sends its alerts: a webhook that posts into a chat channel. */
|
|
@@ -968,7 +1183,9 @@ interface MonitoringAlertChannelInput {
|
|
|
968
1183
|
*/
|
|
969
1184
|
url?: string;
|
|
970
1185
|
}
|
|
1186
|
+
/** What {@link Monitoring.ensureAlertChannel} did. */
|
|
971
1187
|
interface MonitoringAlertChannelResult {
|
|
1188
|
+
/** Whether the channel was made now rather than already existing. */
|
|
972
1189
|
created: boolean;
|
|
973
1190
|
/** For an existing channel, what was brought in line (`"url"`, `"subscriptions"`). */
|
|
974
1191
|
updated: string[];
|
|
@@ -991,7 +1208,9 @@ interface MonitoringAlertChannelState {
|
|
|
991
1208
|
/** Names of the checks the channel is subscribed to but has switched off. */
|
|
992
1209
|
deactivated: string[];
|
|
993
1210
|
}
|
|
1211
|
+
/** External uptime and synthetic checks run from the provider's infrastructure against a deployed URL. */
|
|
994
1212
|
interface Monitoring extends ProviderIdentity {
|
|
1213
|
+
/** Identifies this provider as the `monitoring` capability. */
|
|
995
1214
|
readonly key: "monitoring";
|
|
996
1215
|
/**
|
|
997
1216
|
* Checks this provider is configured to ensure exist — populated from
|
|
@@ -1006,7 +1225,9 @@ interface Monitoring extends ProviderIdentity {
|
|
|
1006
1225
|
* image itself as a `data:` URI for when that cannot be reached. Used when the config names no picture of its own.
|
|
1007
1226
|
*/
|
|
1008
1227
|
readonly icon?: {
|
|
1228
|
+
/** Where to fetch the picture. */
|
|
1009
1229
|
url?: string;
|
|
1230
|
+
/** The picture itself as a `data:` URI, for when `url` cannot be reached. */
|
|
1010
1231
|
dataUri?: string;
|
|
1011
1232
|
};
|
|
1012
1233
|
/** Auth sanity-check. Throws ProviderApiError on auth failure. */
|
|
@@ -1036,25 +1257,34 @@ interface Monitoring extends ProviderIdentity {
|
|
|
1036
1257
|
*/
|
|
1037
1258
|
inspectAlertChannel?(name: string): Promise<MonitoringAlertChannelState>;
|
|
1038
1259
|
}
|
|
1260
|
+
/** What {@link Tooling.doctor} found. */
|
|
1039
1261
|
interface ToolingDoctorReport {
|
|
1262
|
+
/** Whether the tool is in a good state. */
|
|
1040
1263
|
ok: boolean;
|
|
1264
|
+
/** What to show the person: what was found, or what is wrong. */
|
|
1041
1265
|
message: string;
|
|
1042
1266
|
}
|
|
1267
|
+
/** A developer tool kept in step with the repo; several can be active at once. */
|
|
1043
1268
|
interface Tooling extends ProviderIdentity {
|
|
1269
|
+
/** Identifies this provider as the `tooling` capability. */
|
|
1044
1270
|
readonly key: "tooling";
|
|
1045
1271
|
/** Sync the tool's authoritative state from the repo. */
|
|
1046
1272
|
sync(): Promise<void>;
|
|
1273
|
+
/** Check the tool is set up and working, and report what was found. */
|
|
1047
1274
|
doctor(): Promise<ToolingDoctorReport>;
|
|
1048
1275
|
}
|
|
1049
1276
|
/** What an `ensure*` call found or made. `created: false` means it already existed. */
|
|
1050
1277
|
interface EnsuredResource {
|
|
1278
|
+
/** The provider's id for the resource. */
|
|
1051
1279
|
id: string;
|
|
1280
|
+
/** Whether the resource was made now rather than already existing. */
|
|
1052
1281
|
created: boolean;
|
|
1053
1282
|
/** For something that already existed: the settings that disagreed with the layout and were changed. */
|
|
1054
1283
|
updated?: string[];
|
|
1055
1284
|
}
|
|
1056
1285
|
/** A webhook (or equivalent inbound URL) for a channel. */
|
|
1057
1286
|
interface EnsureWebhookResult {
|
|
1287
|
+
/** Whether the webhook was made now rather than already existing. */
|
|
1058
1288
|
created: boolean;
|
|
1059
1289
|
/**
|
|
1060
1290
|
* The posting URL — a credential. Absent when the webhook already existed and
|
|
@@ -1080,7 +1310,9 @@ interface NotificationsAccess {
|
|
|
1080
1310
|
}
|
|
1081
1311
|
/** One channel in a {@link NotificationsLayout}. */
|
|
1082
1312
|
interface NotificationsChannelLayout {
|
|
1313
|
+
/** The channel's name. */
|
|
1083
1314
|
name: string;
|
|
1315
|
+
/** The channel's topic text. */
|
|
1084
1316
|
topic?: string;
|
|
1085
1317
|
/** Who may see and post. Overrides the category's, field by field. */
|
|
1086
1318
|
access?: NotificationsAccess;
|
|
@@ -1185,6 +1417,7 @@ interface NotificationsOnboardingLayout {
|
|
|
1185
1417
|
enabled?: boolean;
|
|
1186
1418
|
/** Channels every member starts with, by name. */
|
|
1187
1419
|
defaultChannels?: string[];
|
|
1420
|
+
/** The questions asked, in order. */
|
|
1188
1421
|
prompts?: Array<{
|
|
1189
1422
|
title: string;
|
|
1190
1423
|
/** One answer only (`true`) or any number. Defaults to `false`. */
|
|
@@ -1213,7 +1446,9 @@ interface NotificationsApplicationLayout {
|
|
|
1213
1446
|
tags?: string[];
|
|
1214
1447
|
/** The default install link: what the bot is added with. Permissions are named, as in a role's. */
|
|
1215
1448
|
install?: {
|
|
1449
|
+
/** The OAuth2 scopes the install link asks for. */
|
|
1216
1450
|
scopes: string[];
|
|
1451
|
+
/** The permissions the bot is added with, named as in a role's. */
|
|
1217
1452
|
permissions: string[];
|
|
1218
1453
|
};
|
|
1219
1454
|
/** `https://` link to the terms of service. */
|
|
@@ -1227,6 +1462,7 @@ interface NotificationsApplicationLayout {
|
|
|
1227
1462
|
* find who holds a role. `true` switches it on from code; `false` switches it off.
|
|
1228
1463
|
*/
|
|
1229
1464
|
intents?: {
|
|
1465
|
+
/** The server members intent: lets the bot list who is in the server. */
|
|
1230
1466
|
members?: boolean;
|
|
1231
1467
|
};
|
|
1232
1468
|
/**
|
|
@@ -1300,9 +1536,13 @@ interface NotificationsLayout {
|
|
|
1300
1536
|
* `Errors to Discord (Comlink)`) and throttle in minutes (default 5). Left out, nothing is done at the tracker.
|
|
1301
1537
|
*/
|
|
1302
1538
|
errors?: {
|
|
1539
|
+
/** The tracker projects whose issues are sent. */
|
|
1303
1540
|
projects: string[];
|
|
1541
|
+
/** The integration's name at the tracker; `Comlink` when absent. */
|
|
1304
1542
|
integration?: string;
|
|
1543
|
+
/** The alert rule's name; `Errors to Discord (Comlink)` when absent. */
|
|
1305
1544
|
rule?: string;
|
|
1545
|
+
/** Minutes between two notifications for one issue; 5 when absent. */
|
|
1306
1546
|
frequency?: number;
|
|
1307
1547
|
};
|
|
1308
1548
|
};
|
|
@@ -1317,11 +1557,13 @@ interface NotificationsLayout {
|
|
|
1317
1557
|
pinned?: NotificationsPinnedLayout[];
|
|
1318
1558
|
/** Settings of the server itself, applied after its channels exist. */
|
|
1319
1559
|
server?: NotificationsServerLayout;
|
|
1560
|
+
/** The categories to create, each with the channels under it. */
|
|
1320
1561
|
categories?: Array<{
|
|
1321
1562
|
name: string;
|
|
1322
1563
|
access?: NotificationsAccess;
|
|
1323
1564
|
channels?: NotificationsChannelLayout[];
|
|
1324
1565
|
}>;
|
|
1566
|
+
/** The roles to create. */
|
|
1325
1567
|
roles?: Array<{
|
|
1326
1568
|
name: string;
|
|
1327
1569
|
mentionable?: boolean;
|
|
@@ -1361,6 +1603,7 @@ interface ServerInspection {
|
|
|
1361
1603
|
applicationError?: string;
|
|
1362
1604
|
/** What everyone may do, by permission name, when the layout declares `everyone`. */
|
|
1363
1605
|
everyone?: {
|
|
1606
|
+
/** The permissions everyone holds now, by name. */
|
|
1364
1607
|
permissions: string[];
|
|
1365
1608
|
};
|
|
1366
1609
|
/** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
|
|
@@ -1384,12 +1627,14 @@ interface ServerInspection {
|
|
|
1384
1627
|
server?: NotificationsServerLayout;
|
|
1385
1628
|
/** Set when reading the server's settings failed; `server` is then absent and means nothing. */
|
|
1386
1629
|
serverError?: string;
|
|
1630
|
+
/** Names of the categories on the server. */
|
|
1387
1631
|
categories: string[];
|
|
1388
1632
|
/**
|
|
1389
1633
|
* Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
|
|
1390
1634
|
* can state (a role-specific deny, a member overwrite, only some of the posting permissions).
|
|
1391
1635
|
*/
|
|
1392
1636
|
categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
|
|
1637
|
+
/** The channels the layout asks about, as the server has them. */
|
|
1393
1638
|
channels: Array<{
|
|
1394
1639
|
name: string;
|
|
1395
1640
|
/** The category it sits under, if any. */
|
|
@@ -1406,6 +1651,7 @@ interface ServerInspection {
|
|
|
1406
1651
|
/** Who can see and post; `"custom"` as for `categoryAccess`. */
|
|
1407
1652
|
access?: Required<NotificationsAccess> | "custom";
|
|
1408
1653
|
}>;
|
|
1654
|
+
/** The roles on the server. */
|
|
1409
1655
|
roles: Array<{
|
|
1410
1656
|
name: string;
|
|
1411
1657
|
id: string;
|
|
@@ -1422,15 +1668,19 @@ interface ServerInspection {
|
|
|
1422
1668
|
interface NotificationsSignedIn {
|
|
1423
1669
|
/** Their id on the provider; for Discord, the user id. */
|
|
1424
1670
|
member: string;
|
|
1671
|
+
/** Their name on the provider, when it gives one. */
|
|
1425
1672
|
name?: string;
|
|
1426
1673
|
/** The GitHub account the provider has verified they own; absent when they have none linked. */
|
|
1427
1674
|
github?: {
|
|
1675
|
+
/** The GitHub user id, as a string. */
|
|
1428
1676
|
id: string;
|
|
1677
|
+
/** The GitHub login. */
|
|
1429
1678
|
login: string;
|
|
1430
1679
|
};
|
|
1431
1680
|
}
|
|
1432
1681
|
/** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
|
|
1433
1682
|
interface NotificationsSignIn {
|
|
1683
|
+
/** The address of the provider's sign-in page, carrying the redirect address and state given. */
|
|
1434
1684
|
authorizeUrl(input: {
|
|
1435
1685
|
redirectUri: string;
|
|
1436
1686
|
state: string;
|
|
@@ -1441,23 +1691,29 @@ interface NotificationsSignIn {
|
|
|
1441
1691
|
code: string;
|
|
1442
1692
|
}): Promise<NotificationsSignedIn>;
|
|
1443
1693
|
}
|
|
1444
|
-
/** A member of the server, as {@link Notifications.roleMembers} reports it. */
|
|
1445
1694
|
/** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
|
|
1446
1695
|
interface NotificationsDelivery {
|
|
1696
|
+
/** The message was posted through the channel's webhook. */
|
|
1447
1697
|
posted: boolean;
|
|
1698
|
+
/** The message was found in the channel afterwards. */
|
|
1448
1699
|
readBack: boolean;
|
|
1700
|
+
/** The message was deleted again. */
|
|
1449
1701
|
removed: boolean;
|
|
1450
1702
|
/** Set when the message was deliberately left in the channel (`keep`), so `removed` is false on purpose. */
|
|
1451
1703
|
kept?: boolean;
|
|
1704
|
+
/** What went wrong at each failed step; empty when delivery worked. */
|
|
1452
1705
|
problems: string[];
|
|
1453
1706
|
}
|
|
1707
|
+
/** A member of the server, as {@link Notifications.roleMembers} reports it. */
|
|
1454
1708
|
interface NotificationsMember {
|
|
1455
1709
|
/** The provider's id for them; for Discord, the user id. */
|
|
1456
1710
|
id: string;
|
|
1457
1711
|
/** A display name for reports; absent when the provider does not give one. */
|
|
1458
1712
|
name?: string;
|
|
1459
1713
|
}
|
|
1714
|
+
/** Chat notifications: posts messages and, where the provider allows, builds the server a layout describes. */
|
|
1460
1715
|
interface Notifications extends ProviderIdentity {
|
|
1716
|
+
/** Identifies this provider as the `notifications` capability. */
|
|
1461
1717
|
readonly key: "notifications";
|
|
1462
1718
|
/**
|
|
1463
1719
|
* Send a message. `channel` is provider-specific (Slack channel id,
|
|
@@ -1477,12 +1733,14 @@ interface Notifications extends ProviderIdentity {
|
|
|
1477
1733
|
ensureCategory?(name: string, opts?: {
|
|
1478
1734
|
access?: NotificationsAccess;
|
|
1479
1735
|
}): Promise<EnsuredResource>;
|
|
1736
|
+
/** Find or create a channel, under its category when named, with its topic and access. */
|
|
1480
1737
|
ensureChannel?(input: {
|
|
1481
1738
|
name: string;
|
|
1482
1739
|
category?: string;
|
|
1483
1740
|
topic?: string;
|
|
1484
1741
|
access?: NotificationsAccess;
|
|
1485
1742
|
}): Promise<EnsuredResource>;
|
|
1743
|
+
/** Find or create a webhook named `name` on the channel, creating the channel first if it is missing. */
|
|
1486
1744
|
ensureWebhook?(input: {
|
|
1487
1745
|
channel: string;
|
|
1488
1746
|
name: string;
|
|
@@ -1539,6 +1797,7 @@ interface Notifications extends ProviderIdentity {
|
|
|
1539
1797
|
removeRoleMember?(roleName: string, memberId: string): Promise<void>;
|
|
1540
1798
|
/** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
|
|
1541
1799
|
signIn?(): NotificationsSignIn;
|
|
1800
|
+
/** Find or create a role; one that exists has its settings brought in line. */
|
|
1542
1801
|
ensureRole?(input: {
|
|
1543
1802
|
name: string;
|
|
1544
1803
|
mentionable?: boolean;
|
|
@@ -1604,21 +1863,26 @@ interface Notifications extends ProviderIdentity {
|
|
|
1604
1863
|
*/
|
|
1605
1864
|
inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
|
|
1606
1865
|
}
|
|
1866
|
+
/** Product analytics: describes what an app needs at runtime and, where the provider allows, creates projects. */
|
|
1607
1867
|
interface Analytics extends ProviderIdentity {
|
|
1868
|
+
/** Identifies this provider as the `analytics` capability. */
|
|
1608
1869
|
readonly key: "analytics";
|
|
1609
1870
|
/** Returns the env var names the app reads at runtime for this provider. */
|
|
1610
1871
|
describe(): Promise<{
|
|
1611
1872
|
provider: string;
|
|
1612
1873
|
envKeys: string[];
|
|
1613
1874
|
}>;
|
|
1875
|
+
/** Reachability probe: proves the credentials work and names the organization they belong to. */
|
|
1614
1876
|
whoami?(): Promise<{
|
|
1615
1877
|
org: string;
|
|
1616
1878
|
}>;
|
|
1879
|
+
/** Create the project if it is missing and return its ingestion token; `alreadyExists` is true when it was there. */
|
|
1617
1880
|
ensureProject?(name: string): Promise<{
|
|
1618
1881
|
token: string;
|
|
1619
1882
|
alreadyExists: boolean;
|
|
1620
1883
|
}>;
|
|
1621
1884
|
}
|
|
1885
|
+
/** Options for {@link Wiki.provision}. */
|
|
1622
1886
|
interface WikiProvisionOpts {
|
|
1623
1887
|
/** Project display name used in the wiki title (e.g. "Holocron"). */
|
|
1624
1888
|
name?: string;
|
|
@@ -1643,6 +1907,7 @@ interface WikiProxyConfig {
|
|
|
1643
1907
|
* providers (github) make API calls.
|
|
1644
1908
|
*/
|
|
1645
1909
|
interface Wiki extends ProviderIdentity {
|
|
1910
|
+
/** Identifies this provider as the `wiki` capability. */
|
|
1646
1911
|
readonly key: "wiki";
|
|
1647
1912
|
/** Provision the wiki — write config files or call the provider API. */
|
|
1648
1913
|
provision(opts?: WikiProvisionOpts): Promise<string>;
|
|
@@ -1695,6 +1960,7 @@ interface WorkerScriptState {
|
|
|
1695
1960
|
/** The names of the secrets bound to the script. */
|
|
1696
1961
|
bindingNames: string[];
|
|
1697
1962
|
}
|
|
1963
|
+
/** What {@link Workers.deployScript} made. */
|
|
1698
1964
|
interface DeployScriptResult {
|
|
1699
1965
|
/** The deployed script's name at the provider. */
|
|
1700
1966
|
scriptName: string;
|
|
@@ -1709,6 +1975,7 @@ interface DeployScriptResult {
|
|
|
1709
1975
|
* receiver, for instance).
|
|
1710
1976
|
*/
|
|
1711
1977
|
interface Workers extends ProviderIdentity {
|
|
1978
|
+
/** Identifies this provider as the `workers` capability. */
|
|
1712
1979
|
readonly key: "workers";
|
|
1713
1980
|
/**
|
|
1714
1981
|
* Deploy (or update) a reverse-proxy Worker for `hostname`.
|
|
@@ -1741,47 +2008,86 @@ interface Workers extends ProviderIdentity {
|
|
|
1741
2008
|
scripts: number;
|
|
1742
2009
|
}>;
|
|
1743
2010
|
}
|
|
2011
|
+
/** Maps each capability key to the interface its provider implements. */
|
|
1744
2012
|
interface CapabilityImpls {
|
|
2013
|
+
/** The `source` provider. */
|
|
1745
2014
|
source: Source;
|
|
2015
|
+
/** The `ci` provider. */
|
|
1746
2016
|
ci: Ci;
|
|
2017
|
+
/** The `secrets` provider. */
|
|
1747
2018
|
secrets: Secrets;
|
|
2019
|
+
/** The `environments` provider. */
|
|
1748
2020
|
environments: Environments;
|
|
2021
|
+
/** The `issues` provider. */
|
|
1749
2022
|
issues: Issues;
|
|
2023
|
+
/** The `deployment` provider. */
|
|
1750
2024
|
deployment: Deployment;
|
|
2025
|
+
/** The `storage` provider. */
|
|
1751
2026
|
storage: Storage;
|
|
2027
|
+
/** The `auth` provider. */
|
|
1752
2028
|
auth: Auth;
|
|
2029
|
+
/** The `vault` provider. */
|
|
1753
2030
|
vault: Vault;
|
|
2031
|
+
/** The `dns` provider. */
|
|
1754
2032
|
dns: Dns;
|
|
2033
|
+
/** The `tooling` provider. */
|
|
1755
2034
|
tooling: Tooling;
|
|
2035
|
+
/** The `notifications` provider. */
|
|
1756
2036
|
notifications: Notifications;
|
|
2037
|
+
/** The `analytics` provider. */
|
|
1757
2038
|
analytics: Analytics;
|
|
2039
|
+
/** The `errors` provider. */
|
|
1758
2040
|
errors: Errors;
|
|
2041
|
+
/** The `logs` provider. */
|
|
1759
2042
|
logs: Logs;
|
|
2043
|
+
/** The `monitoring` provider. */
|
|
1760
2044
|
monitoring: Monitoring;
|
|
2045
|
+
/** The `wiki` provider. */
|
|
1761
2046
|
wiki: Wiki;
|
|
2047
|
+
/** The `workers` provider. */
|
|
1762
2048
|
workers: Workers;
|
|
1763
2049
|
}
|
|
2050
|
+
/** The cardinality (`"single"` or `"many"`) of the capability `K`. */
|
|
1764
2051
|
type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
|
|
1765
2052
|
/** Resolved runtime shape: single → one impl; many → array. */
|
|
1766
2053
|
type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
|
|
2054
|
+
/** How many providers each capability resolves to: one (`"single"`) or several active at once (`"many"`). */
|
|
1767
2055
|
declare const CARDINALITY: {
|
|
2056
|
+
/** `source` has exactly one provider. */
|
|
1768
2057
|
readonly source: "single";
|
|
2058
|
+
/** `ci` has exactly one provider. */
|
|
1769
2059
|
readonly ci: "single";
|
|
2060
|
+
/** `secrets` has exactly one provider. */
|
|
1770
2061
|
readonly secrets: "single";
|
|
2062
|
+
/** `environments` has exactly one provider. */
|
|
1771
2063
|
readonly environments: "single";
|
|
2064
|
+
/** `issues` has exactly one provider. */
|
|
1772
2065
|
readonly issues: "single";
|
|
2066
|
+
/** `deployment` has exactly one provider. */
|
|
1773
2067
|
readonly deployment: "single";
|
|
2068
|
+
/** `storage` has exactly one provider. */
|
|
1774
2069
|
readonly storage: "single";
|
|
2070
|
+
/** `auth` has exactly one provider. */
|
|
1775
2071
|
readonly auth: "single";
|
|
2072
|
+
/** `vault` has exactly one provider. */
|
|
1776
2073
|
readonly vault: "single";
|
|
2074
|
+
/** `dns` has exactly one provider. */
|
|
1777
2075
|
readonly dns: "single";
|
|
2076
|
+
/** `tooling` can have several providers active at once. */
|
|
1778
2077
|
readonly tooling: "many";
|
|
2078
|
+
/** `notifications` can have several providers active at once. */
|
|
1779
2079
|
readonly notifications: "many";
|
|
2080
|
+
/** `analytics` can have several providers active at once. */
|
|
1780
2081
|
readonly analytics: "many";
|
|
2082
|
+
/** `errors` has exactly one provider. */
|
|
1781
2083
|
readonly errors: "single";
|
|
2084
|
+
/** `logs` has exactly one provider. */
|
|
1782
2085
|
readonly logs: "single";
|
|
2086
|
+
/** `monitoring` has exactly one provider. */
|
|
1783
2087
|
readonly monitoring: "single";
|
|
2088
|
+
/** `wiki` has exactly one provider. */
|
|
1784
2089
|
readonly wiki: "single";
|
|
2090
|
+
/** `workers` has exactly one provider. */
|
|
1785
2091
|
readonly workers: "single";
|
|
1786
2092
|
};
|
|
1787
2093
|
/**
|
|
@@ -1795,6 +2101,7 @@ declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
|
|
|
1795
2101
|
* needs to give it for one run and take it away again, so `setup` can walk them through it.
|
|
1796
2102
|
*/
|
|
1797
2103
|
declare class ElevationRequiredError extends Error {
|
|
2104
|
+
/** What a person must approve to give the permission for one run and to take it away again. */
|
|
1798
2105
|
readonly elevation: {
|
|
1799
2106
|
/** The permission, in the provider's own name for it. */
|
|
1800
2107
|
permission: string;
|
|
@@ -1809,8 +2116,11 @@ declare class ElevationRequiredError extends Error {
|
|
|
1809
2116
|
/** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
|
|
1810
2117
|
applied?: string[];
|
|
1811
2118
|
};
|
|
2119
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
1812
2120
|
name: string;
|
|
1813
|
-
constructor(message: string,
|
|
2121
|
+
constructor(message: string,
|
|
2122
|
+
/** What a person must approve to give the permission for one run and to take it away again. */
|
|
2123
|
+
elevation: {
|
|
1814
2124
|
/** The permission, in the provider's own name for it. */
|
|
1815
2125
|
permission: string;
|
|
1816
2126
|
/** Where to approve giving it; absent when the provider could not build one. */
|
|
@@ -1833,8 +2143,11 @@ declare class MissingTokenError extends Error {
|
|
|
1833
2143
|
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
1834
2144
|
name: string;
|
|
1835
2145
|
}
|
|
2146
|
+
/** A webhook payload failed signature verification, so it must not be trusted. */
|
|
1836
2147
|
declare class WebhookVerificationError extends Error {
|
|
2148
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
1837
2149
|
name: string;
|
|
1838
2150
|
}
|
|
2151
|
+
/** Whether `key` is a capability that can have several providers active at once. */
|
|
1839
2152
|
declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
|
|
1840
2153
|
export { LifecycleResult as $, ToolingDoctorReport as $t, DeploymentProject as A, ProviderIdentity as At, EnsureRelayResult as B, Source as Bt, ConnectionStringOptions as C, NotificationsPinnedLayout as Ct, DeployScriptConfig as D, NotificationsWelcomeLayout as Dt, DeployFunctionResult as E, NotificationsSignedIn as Et, Dns as F, ResolvedCapability as Ft, EnvironmentReviewer as G, SourceSecurity as Gt, EnsureWebhookResult as H, SourceFile as Ht, DnsRecord as I, Ruleset as It, InspectRelayInput as J, Storage as Jt, Environments as K, SourceTeamMember as Kt, DnsRecordRequest as L, SecretScope as Lt, DeploymentRecord as M, RelayState as Mt, DeploymentTarget as N, RepoRef as Nt, DeployScriptResult as O, PagesConfig as Ot, DeploymentTrigger as P, RepoSettings as Pt, LabelDef as Q, Tooling as Qt, DnsRecordType as R, Secrets as Rt, CiRunStatus as S, NotificationsOnboardingLayout as St, DeployFunctionConfig as T, NotificationsSignIn as Tt, EnsuredResource as U, SourceRepoInfo as Ut, EnsureResult as V, SourceBranch as Vt, Environment as W, SourceRulesetDetail as Wt, IssueSearchFilter as X, TeamEntry as Xt, Issue as Y, StorageBranch as Yt, Issues as Z, TeamPermission as Zt, Cardinality as _, NotificationsDelivery as _t, REQUIRED_CAPABILITIES as a, WikiProvisionOpts as an, MonitoringAlertChannelState as at, CiRun as b, NotificationsLinksLayout as bt, Analytics as c, Workers as cn, MonitoringAssertionSource as ct, AuthEvent as d, MonitoringHttpMethod as dt, TrackerDoctorReport as en, LifecycleSlot as et, AuthEventType as f, NormalizedAuthUser as ft, CapabilityKey as g, NotificationsChannelLayout as gt, CapabilityImpls as h, NotificationsApplicationLayout as ht, ProviderApiError as i, Wiki as in, MonitoringAlertChannelResult as it, DeploymentProjectSettings as j, PullRequest as jt, Deployment as k, ParseWebhookInput as kt, Auth as l, MonitoringCheck as lt, AuthUser as m, NotificationsAccess as mt, ElevationRequiredError as n, Vault as nn, Monitoring as nt, WebhookVerificationError as o, WikiProxyConfig as on, MonitoringAssertion as ot, AuthIdentity as p, Notifications as pt, Errors as q, StatusCategory as qt, MissingTokenError as r, WebhookDashboardInfo as rn, MonitoringAlertChannelInput as rt, isMulti as s, WorkerScriptState as sn, MonitoringAssertionComparison as st, CARDINALITY as t, TrackerUser as tn, Logs as tt, AuthDescription as u, MonitoringCheckInput as ut, CardinalityFor as v, NotificationsEveryoneLayout as vt, CreateAuthUserInput as w, NotificationsServerLayout as wt, CiRunFilter as x, NotificationsMember as xt, Ci as y, NotificationsLayout as yt, EnsureRelayInput as z, ServerInspection as zt };
|