forges 0.0.0 → 0.1.0

package/dist/provider-CoZ7cCxp.d.mts

@@ -0,0 +1,1439 @@
+import { $ as CiRunQuery, $n as WebhookInput, At as GetManyResult, B as Actor, Bt as Notification, Ct as ForgeEvent, Dn as SecurityAlertListOptions, Dt as ForgeOrigin, En as SecurityAlertKind, Et as ForgeKind, Fn as Thread, Ft as LabelInput, G as Check, Gn as TreeOptions, Gt as Page, H as BaseOptions, Hn as ThreadUpdateInput, In as ThreadCreateInput, It as ListOptions, Jn as User, K as CheckRef, Kn as UpsertCommentInput, Kt as PageOptions, Ln as ThreadKind, Mn as Support, Mt as InstallationToken, Nn as Tag, Ot as ForgeWarning, Pn as TextLimits, Pt as Label, Q as CiRun, Qn as WebhookEventType, Qt as ReactionContent, Rn as ThreadQuery, Rt as MergeOptions, Tn as SecurityAlert, Tt as ForgeInstance, U as Branch, Un as TreeEntry, Ut as NotificationRef, V as ApproveAndMergeOptions, Vt as NotificationListOptions, W as ChangedFile, X as CiJob, Xn as WebhookDeliveryRecord, Yn as Webhook, Z as CiJobRef, Zn as WebhookDeliveryRef, Zt as Reaction, a as FetcherOptions, an as ReleaseUpdate, at as Comment, bn as ReviewInput, ct as CommitQuery, dn as RepoRef, en as Release, er as WebhookRef, et as CiRunRef, fn as RepoRole, ft as Comparison, gn as Review, hn as ResolvedThreadRef, in as ReleaseRef, it as Collaborator, jn as SubscriptionState, jt as Installation, n as FetchLike, nn as ReleaseAssetRef, nt as CodeMatch, on as Repo, ot as CommentRef, pn as RepoSearchQuery, q as CheckReportInput, qn as UpsertCommentResult, rn as ReleaseInput, rt as CodeSearchQuery, s as ForgeRequest, st as Commit, tr as WebhookUpdate, un as RepoQuery, ut as CommitSearchQuery, vt as FileContent, wn as SearchQuery, xn as ReviewRef, xt as FileOptions, yn as ReviewEvent, zn as ThreadRef, zt as Milestone } from "./fetch-D4pSRvvA.mjs";
+//#region src/capability-table.d.ts
+/**
+ * One row of the capability table: where a capability is declared on `ProviderSpec`,
+ * where it lands on `ForgeCapabilities`, and which `ForgeProvider` verbs it covers.
+ * `capabilitiesOf()`, `supports()` and the capability matrix derive from the table.
+ */
+interface CapabilityEntry {
+  /** Where the support lands on `ForgeCapabilities`, dot-separated. */
+  capability: string;
+  /** Where the verb is declared on `ProviderSpec`, dot-separated. */
+  spec?: string;
+  /** Verbs on `ForgeProvider` this capability covers. */
+  verbs?: readonly string[];
+  /** Support is declared per thread kind. */
+  perKind?: boolean;
+  /** The capability is computed by core rather than read from a declared verb. */
+  derived?: "experimental" | "poll" | "webhook" | "threadEvents" | "upsertComment" | "subscriptionSet" | "approve" | "approveAndMerge" | "alertKinds" | "eventKinds" | "authKinds" | "limits";
+  /** The verbs change state, so `readOnly` and anonymous providers reject them. */
+  write?: boolean;
+  /** The verbs need an account, so anonymous providers reject them. */
+  account?: boolean;
+}
+/**
+ * Rows omit what follows from the rest. `spec` defaults to the capability's
+ * path, with `writes.*` declared on `threads.*` and a `listing` declared as its
+ * page. `verbs` defaults to the `spec` path, plus its iterable when the path
+ * names a page (`repos.labelsPage` also covers `repos.labels`). An explicit
+ * `spec` marks a capability grouped apart from its verbs.
+ */
+declare const TABLE: readonly [{
+  readonly capability: "experimental";
+  readonly derived: "experimental";
+}, {
+  readonly capability: "sources.poll";
+  readonly derived: "poll";
+}, {
+  readonly capability: "sources.webhook";
+  readonly derived: "webhook";
+  readonly verbs: readonly ["webhooks.verify", "webhooks.ingest"];
+}, {
+  readonly capability: "sources.subscribe";
+}, {
+  readonly capability: "repos.get";
+}, {
+  readonly capability: "users.get";
+}, {
+  readonly capability: "users.me";
+  readonly account: true;
+}, {
+  readonly capability: "repos.list";
+  readonly account: true;
+  readonly listing: true;
+}, {
+  readonly capability: "repos.labels";
+  readonly listing: true;
+}, {
+  readonly capability: "repos.createLabel";
+  readonly write: true;
+}, {
+  readonly capability: "repos.milestones";
+  readonly listing: true;
+}, {
+  readonly capability: "repos.collaborators";
+  readonly listing: true;
+}, {
+  readonly capability: "repos.permissionFor";
+}, {
+  readonly capability: "repos.addCollaborator";
+  readonly write: true;
+}, {
+  readonly capability: "repos.assignableUsers";
+  readonly listing: true;
+}, {
+  readonly capability: "repos.reviewerCandidates";
+  readonly listing: true;
+}, {
+  readonly capability: "threads.get";
+  readonly perKind: true;
+}, {
+  readonly capability: "threads.list";
+  readonly listing: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "threads.getMany";
+}, {
+  readonly capability: "threads.events";
+  readonly spec: "threads.eventsPage";
+  readonly derived: "threadEvents";
+}, {
+  readonly capability: "comments.list";
+  readonly spec: "threads.commentsPage";
+  readonly perKind: true;
+}, {
+  readonly capability: "comments.edit";
+  readonly write: true;
+  readonly spec: "threads.editComment";
+  readonly perKind: true;
+}, {
+  readonly capability: "comments.delete";
+  readonly write: true;
+  readonly spec: "threads.deleteComment";
+  readonly perKind: true;
+}, {
+  readonly capability: "reactions.list";
+  readonly spec: "threads.reactionsPage";
+  readonly perKind: true;
+}, {
+  readonly capability: "notifications.list";
+  readonly account: true;
+  readonly listing: true;
+}, {
+  readonly capability: "notifications.markRead";
+  readonly account: true;
+  readonly write: true;
+}, {
+  readonly capability: "notifications.markDone";
+  readonly account: true;
+  readonly write: true;
+}, {
+  readonly capability: "notifications.unsubscribe";
+  readonly account: true;
+  readonly write: true;
+}, {
+  readonly capability: "notifications.markAllRead";
+  readonly account: true;
+  readonly write: true;
+}, {
+  readonly capability: "notifications.markAllDone";
+  readonly account: true;
+  readonly write: true;
+}, {
+  readonly capability: "notifications.unreadCount";
+  readonly account: true;
+}, {
+  readonly capability: "writes.comment";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.upsertComment";
+  readonly write: true;
+  readonly derived: "upsertComment";
+  readonly verbs: readonly ["threads.upsertComment"];
+}, {
+  readonly capability: "writes.close";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.reopen";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.create";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.update";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.setLabels";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.addLabels";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.removeLabels";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.setMilestone";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.react";
+  readonly write: true;
+  readonly spec: "threads.reactions";
+  readonly perKind: true;
+  readonly verbs: readonly ["threads.react", "threads.unreact"];
+}, {
+  readonly capability: "writes.setAssignees";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.requestReview";
+  readonly write: true;
+  readonly perKind: true;
+}, {
+  readonly capability: "writes.merge";
+  readonly write: true;
+}, {
+  readonly capability: "writes.approveAndMerge";
+  readonly write: true;
+  readonly derived: "approveAndMerge";
+  readonly verbs: readonly ["threads.approveAndMerge"];
+}, {
+  readonly capability: "writes.transfer";
+  readonly write: true;
+}, {
+  readonly capability: "writes.markDuplicate";
+  readonly write: true;
+}, {
+  readonly capability: "subscriptions.get";
+  readonly account: true;
+  readonly spec: "threads.subscriptions";
+  readonly perKind: true;
+  readonly verbs: readonly ["threads.subscription"];
+}, {
+  readonly capability: "subscriptions.set";
+  readonly write: true;
+  readonly derived: "subscriptionSet";
+  readonly verbs: readonly ["threads.subscribe", "threads.unsubscribe"];
+}, {
+  readonly capability: "installations";
+  readonly account: true;
+  readonly verbs: readonly ["installations.list", "installations.listPage", "installations.get", "installations.token", "installations.repos", "installations.reposPage", "installations.provider", "installations.providers"];
+}, {
+  readonly capability: "checks.thread";
+  readonly spec: "threads.checks";
+  readonly perKind: true;
+}, {
+  readonly capability: "checks.list";
+}, {
+  readonly capability: "checks.report";
+  readonly write: true;
+}, {
+  readonly capability: "checks.rerun";
+  readonly write: true;
+}, {
+  readonly capability: "ci.runs";
+  readonly listing: true;
+}, {
+  readonly capability: "ci.run";
+}, {
+  readonly capability: "ci.jobs";
+  readonly listing: true;
+}, {
+  readonly capability: "ci.log";
+}, {
+  readonly capability: "contents.file";
+}, {
+  readonly capability: "contents.tree";
+  readonly listing: true;
+}, {
+  readonly capability: "contents.branches";
+  readonly listing: true;
+}, {
+  readonly capability: "contents.tags";
+  readonly listing: true;
+}, {
+  readonly capability: "contents.resolveRef";
+}, {
+  readonly capability: "contents.commits";
+  readonly listing: true;
+}, {
+  readonly capability: "contents.commit";
+}, {
+  readonly capability: "contents.compare";
+}, {
+  readonly capability: "contents.threadFiles";
+  readonly spec: "threads.filesPage";
+}, {
+  readonly capability: "contents.threadCommits";
+  readonly spec: "threads.commitsPage";
+}, {
+  readonly capability: "reviews.list";
+  readonly spec: "threads.reviewsPage";
+}, {
+  readonly capability: "reviews.create";
+  readonly write: true;
+  readonly spec: "threads.createReview";
+}, {
+  readonly capability: "reviews.submit";
+  readonly write: true;
+  readonly spec: "threads.submitReview";
+}, {
+  readonly capability: "reviews.approve";
+  readonly write: true;
+  readonly spec: "threads.approve";
+  readonly derived: "approve";
+}, {
+  readonly capability: "reviews.resolveThread";
+  readonly write: true;
+  readonly spec: "threads.reviewThreads";
+  readonly verbs: readonly ["threads.resolveReviewThread", "threads.unresolveReviewThread"];
+}, {
+  readonly capability: "releases.list";
+  readonly listing: true;
+}, {
+  readonly capability: "releases.get";
+}, {
+  readonly capability: "releases.latest";
+}, {
+  readonly capability: "releases.getByTag";
+}, {
+  readonly capability: "releases.downloadAsset";
+}, {
+  readonly capability: "releases.create";
+  readonly write: true;
+}, {
+  readonly capability: "releases.update";
+  readonly write: true;
+}, {
+  readonly capability: "webhooks.list";
+  readonly account: true;
+  readonly listing: true;
+}, {
+  readonly capability: "webhooks.create";
+  readonly write: true;
+}, {
+  readonly capability: "webhooks.update";
+  readonly write: true;
+}, {
+  readonly capability: "webhooks.delete";
+  readonly write: true;
+}, {
+  readonly capability: "webhooks.rotateSecret";
+  readonly write: true;
+}, {
+  readonly capability: "webhooks.deliveries";
+  readonly account: true;
+  readonly listing: true;
+}, {
+  readonly capability: "webhooks.redeliver";
+  readonly write: true;
+}, {
+  readonly capability: "search.threads";
+  readonly listing: true;
+}, {
+  readonly capability: "search.repos";
+  readonly listing: true;
+}, {
+  readonly capability: "search.commits";
+  readonly listing: true;
+}, {
+  readonly capability: "search.code";
+  readonly listing: true;
+}, {
+  readonly capability: "securityAlerts";
+  readonly derived: "alertKinds";
+  readonly verbs: readonly ["securityAlerts.list", "securityAlerts.listPage"];
+}, {
+  readonly capability: "eventKinds";
+  readonly derived: "eventKinds";
+}, {
+  readonly capability: "authKinds";
+  readonly derived: "authKinds";
+}, {
+  readonly capability: "limits";
+  readonly derived: "limits";
+}];
+type DefaultSpec<C> = C extends `writes.${infer Name}` ? `threads.${Name}` : C;
+type SpecOf<R> = R extends {
+  spec: infer S extends string;
+} ? S : R extends {
+  derived: string;
+} ? never : R extends {
+  capability: infer C extends string;
+} ? R extends {
+  listing: true;
+} ? `${DefaultSpec<C>}Page` : DefaultSpec<C> : never;
+type WithIterable<S> = S extends `${infer Iterable}Page` ? Iterable | S : S;
+type VerbsOf<R> = R extends {
+  verbs: readonly (infer V extends string)[];
+} ? V : WithIterable<SpecOf<R>>;
+/** A provider verb, named by its path on `ForgeProvider`. */
+type ForgeVerb = VerbsOf<(typeof TABLE)[number]>;
+/**
+ * Every capability with the verbs it covers and the flags that gate it, in the order the capability matrix lists them.
+ */
+declare const CAPABILITY_TABLE: readonly CapabilityEntry[];
+//#endregion
+//#region src/web.d.ts
+/** Something with a web page. */
+type UrlTarget = {
+  repo: RepoRef;
+} | {
+  thread: ThreadRef;
+} | {
+  comment: CommentRef;
+} | {
+  release: ReleaseRef;
+} | {
+  file: {
+    repo: RepoRef;
+    path: string;
+    at: string;
+    line?: number;
+  };
+} | {
+  compare: {
+    repo: RepoRef;
+    base: string;
+    head: string;
+  };
+};
+/** What a forge web URL points at. `repo` is always set; the rest when the URL is that specific. */
+interface ParsedForgeUrl {
+  repo: RepoRef;
+  thread?: ThreadRef;
+  comment?: CommentRef;
+  release?: ReleaseRef;
+}
+/** Options for `provider.referenceTo()`. */
+interface ReferenceOptions {
+  /** Repository the reference is written in; a reference within it is the short form. */
+  from?: RepoRef;
+  /** Request the reference expanded to its title, where the forge supports it (GitLab's `+` suffix). */
+  expand?: boolean;
+}
+/**
+ * How a provider builds and reads its web URLs. Paths are relative to
+ * `origin`; any builder may return `undefined` when the forge has no such page.
+ */
+interface WebLinks {
+  /** The origin of the forge website, such as `https://github.com`. */
+  origin: string;
+  /** The page of a repository. */
+  repo: (repo: RepoRef) => string;
+  /** The page of an issue or pull request. */
+  thread: (ref: ResolvedThreadRef) => string | undefined;
+  /** The page of a comment, anchored on its thread. */
+  comment?: (ref: CommentRef & {
+    thread: ResolvedThreadRef;
+  }) => string | undefined;
+  /** The page of a release. */
+  release?: (ref: ReleaseRef) => string | undefined;
+  /** The page of a file at a revision, optionally at a line. */
+  file?: (repo: RepoRef, path: string, at: string, line?: number) => string | undefined;
+  /** The page that compares two revisions. */
+  compare?: (repo: RepoRef, base: string, head: string) => string | undefined;
+  /** Reads a URL already known to be on `origin`, split into path segments. */
+  parse: (segments: string[], url: URL, origin: ForgeOrigin) => ParsedForgeUrl | undefined;
+  /** The forge's cross-reference syntax; `undefined` falls back to the thread URL. */
+  reference?: (ref: ResolvedThreadRef, sameRepo: boolean, expand: boolean) => string | undefined;
+}
+/** How a forge that lays out its website like GitHub differs from GitHub. */
+interface GitHubShape {
+  /** The path segment of pull requests, such as `pull` or `pulls`. */
+  pull: string;
+  /** The forge has discussions, which are addressed like issues. */
+  discussions?: boolean;
+  /** Fragment for a comment id, for example `issuecomment-` or `note_`. */
+  commentFragment: string;
+  /** The path segment that leads to a file at a revision. */
+  file: (at: string) => string;
+  /** The URL fragment that selects a line of a file. */
+  lineFragment: (line: number) => string;
+  /** Reference prefix for pulls when it differs from issues. */
+  pullPrefix?: string;
+  /** Reserved owner segments. */
+  reserved?: readonly string[];
+}
+/** Web links for forges laid out like GitHub: `/{owner}/{name}/issues/{n}` and friends. */
+declare function githubShapedWeb(origin: string, shape: GitHubShape): WebLinks;
+/**
+ * Reads `url` with whichever of `providers` serves it.
+ * @param url The web URL to read.
+ * @param providers The providers to ask. The first that serves the URL answers.
+ */
+declare function parseForgeUrl(url: string | URL, providers: ReadonlyArray<{
+  parseUrl: (url: string | URL) => ParsedForgeUrl | undefined;
+}>): ParsedForgeUrl | undefined;
+//#endregion
+//#region src/provider.d.ts
+/** No credentials: public reads only. Every write, notifications and subscriptions are unsupported. */
+interface AnonymousAuth {
+  type: "anonymous";
+}
+/** A bearer or personal access token. */
+interface TokenAuth {
+  type: "token";
+  /**
+   * Personal access token or OAuth access token. A function is called before
+   * every request, so a refreshed token applies without a new provider.
+   */
+  token: string | (() => string | Promise<string>);
+}
+/** HTTP Basic credentials, for example a Bitbucket app password or Atlassian API token. */
+interface BasicAuth {
+  type: "basic";
+  username: string;
+  /** The password, app password or API token. */
+  password: string;
+}
+/** App credentials. Omit `installationId` to act as the app itself. */
+interface AppAuth {
+  type: "app";
+  appId: string | number;
+  /** PEM private key: RSA (PKCS#1 or PKCS#8) on GitHub, Ed25519 PKCS#8 on Cursor Origin. */
+  privateKey: string;
+  /** The installation to act as. Omit it to act as the app itself. */
+  installationId?: string | number;
+}
+/** The credential types that a provider can accept. */
+type AuthKind = "token" | "basic" | "app" | "app_password" | "oauth" | "anonymous";
+/** Options that every provider accepts. */
+interface ForgeOptionsBase {
+  /** API base URL. Defaults to the forge's public instance. */
+  baseUrl?: string;
+  /** Host used in refs and keys. Defaults to the host of `baseUrl`, with API subdomains mapped to the public host. */
+  instance?: string;
+  /** A `fetch` to use instead of the global one, for tests and for runtimes without one. */
+  fetch?: FetchLike;
+  /**
+   * Request timeout in milliseconds.
+   * @default 30000
+   */
+  timeout?: number;
+  /** Shared secret used to verify inbound webhook deliveries. */
+  webhookSecret?: string;
+  /**
+   * The `user-agent` header. Defaults to `forges`, except in a browser, which sends its own.
+   * Setting it in a browser can trigger a CORS preflight that some forges reject.
+   */
+  userAgent?: string;
+  /**
+   * Version of the forge instance, when the caller already knows it. Gates
+   * version-dependent capabilities without the network call
+   * `refreshCapabilities()` makes.
+   */
+  instanceVersion?: string;
+  /** Every write, including a mutating `request()`, rejects with `ReadOnlyError` and reports `false`. */
+  readOnly?: boolean;
+  /** Called before a request is retried after a secondary rate limit, with the wait in milliseconds. */
+  onRetry?: FetcherOptions["onRetry"];
+}
+/** Per-thread-kind support. `'other'` subjects have no verbs, so they have no entry. */
+type PerKind = Record<Exclude<ThreadKind, "other">, Support>;
+/** Support per security alert kind. */
+type AlertSupport = Record<"dependency" | "code_scanning" | "secret" | "advisory", Support>;
+/**
+ * What a provider supports, operation by operation. It is computed without a request, and
+ * `refreshCapabilities()` refines it with the instance version. Each group holds one entry per
+ * capability, and the [capability matrix](/reference/capability-matrix) lists them for every forge.
+ */
+interface ForgeCapabilities {
+  /** Instance version the capabilities were computed for, when known. */
+  version?: string;
+  /** The forge's API as a whole is unstable, so the provider can change with it. */
+  experimental?: true;
+  /** `subscribe` is a long-lived push stream; see {@link SourcesApi}. */
+  sources: Record<"poll" | "webhook" | "subscribe", Support>;
+  repos: {
+    /** Support for `repos.get()`. */
+    get: Support;
+    /** Support for `repos.list()` and `repos.listPage()`. */
+    list: Support;
+    /** Support for `repos.labels()` and `repos.labelsPage()`. */
+    labels: Support;
+    /** Support for `repos.createLabel()`. */
+    createLabel: Support;
+    /** Support for `repos.milestones()` and `repos.milestonesPage()`. */
+    milestones: Support;
+    /** Support for `repos.collaborators()` and `repos.collaboratorsPage()`. */
+    collaborators: Support;
+    /** Support for `repos.permissionFor()`. */
+    permissionFor: Support;
+    /** Support for `repos.addCollaborator()`. */
+    addCollaborator: Support;
+    /** Support for `repos.assignableUsers()` and `repos.assignableUsersPage()`. */
+    assignableUsers: Support;
+    /** Support for `repos.reviewerCandidates()` and `repos.reviewerCandidatesPage()`. */
+    reviewerCandidates: Support;
+  };
+  users: {
+    /** Support for `users.get()`. */
+    get: Support;
+    /** Support for `users.me()`. */
+    me: Support;
+  };
+  threads: {
+    /** Support for `threads.get()`, per thread kind. */
+    get: PerKind;
+    /** Support for `threads.list()` and `threads.listPage()`, per thread kind. */
+    list: PerKind;
+    /** Support for `threads.getMany()`. */
+    getMany: Support;
+    /** Support for `threads.events()` and `threads.eventsPage()`, per thread kind. */
+    events: PerKind;
+  };
+  comments: {
+    /** Support for `threads.comments()` and `threads.commentsPage()`, per thread kind. */
+    list: PerKind;
+    /** Support for `threads.editComment()`, per thread kind. */
+    edit: PerKind;
+    /** Support for `threads.deleteComment()`, per thread kind. */
+    delete: PerKind;
+  };
+  /** Listing the reactions on a thread or one of its comments, per thread kind. */
+  reactions: {
+    /** Support for `threads.reactions()` and `threads.reactionsPage()`, per thread kind. */
+    list: PerKind;
+  };
+  notifications: {
+    /** Support for `notifications.list()` and `notifications.listPage()`. */
+    list: Support;
+    /** Support for `notifications.markRead()`. */
+    markRead: Support;
+    /** Support for `notifications.markDone()`. */
+    markDone: Support;
+    /** Support for `notifications.unsubscribe()`. */
+    unsubscribe: Support;
+    /** Support for `notifications.markAllRead()`. */
+    markAllRead: Support;
+    /** Support for `notifications.markAllDone()`. */
+    markAllDone: Support;
+    /** Support for `notifications.unreadCount()`. */
+    unreadCount: Support;
+  };
+  /** Write verbs, per thread kind except `merge`, `approveAndMerge`, `transfer` and `markDuplicate`. */
+  writes: {
+    /** Support for `threads.comment()`, per thread kind. */
+    comment: PerKind;
+    /** Composed from `comment`, `comments.list` and `comments.edit`, so `'emulated'` where it works at all, or `'unverified'` where a part is. */
+    upsertComment: PerKind;
+    /** Support for `threads.close()`, per thread kind. */
+    close: PerKind;
+    /** Support for `threads.reopen()`, per thread kind. */
+    reopen: PerKind;
+    /** Support for `threads.create()`, per thread kind. */
+    create: PerKind;
+    /** Support for `threads.update()`, per thread kind. */
+    update: PerKind;
+    /** Support for `threads.setLabels()`, per thread kind. */
+    setLabels: PerKind;
+    /** Support for `threads.addLabels()`, per thread kind. */
+    addLabels: PerKind;
+    /** Support for `threads.removeLabels()`, per thread kind. */
+    removeLabels: PerKind;
+    /** Support for `threads.setMilestone()`, per thread kind. */
+    setMilestone: PerKind;
+    /** Support for `threads.react()` and `threads.unreact()`, per thread kind. */
+    react: PerKind;
+    /** Support for `threads.setAssignees()`, per thread kind. */
+    setAssignees: PerKind;
+    /** Support for `threads.requestReview()`, per thread kind. */
+    requestReview: PerKind;
+    /** Support for `threads.merge()`. */
+    merge: Support;
+    /** Composed from `merge` and `reviews.approve`. */
+    approveAndMerge: Support;
+    /** Support for `threads.transfer()`. */
+    transfer: Support;
+    /** Support for `threads.markDuplicate()`. */
+    markDuplicate: Support;
+  };
+  /** Reading a thread subscription (`get`) and changing it (`set`), per kind. Distinct from notification unsubscribe. */
+  subscriptions: {
+    /** Support for `threads.subscription()`, per thread kind. */
+    get: PerKind;
+    /** Support for `threads.subscribe()` and `threads.unsubscribe()`, per thread kind. */
+    set: PerKind;
+  };
+  /**
+   * `thread` covers `Thread.checks` and `threads.checks()` (pull requests
+   * only); the rest are the commit-level surface. `report` is a commit
+   * status unless the credential can write check runs.
+   */
+  checks: {
+    /** Support for `threads.checks()`, per thread kind. */
+    thread: PerKind;
+    /** Support for `checks.list()`. */
+    list: Support;
+    /** Support for `checks.report()`. */
+    report: Support;
+    /** Support for `checks.rerun()`. */
+    rerun: Support;
+  };
+  /** Read-only CI surface. `log` is `false` where job logs are not reachable over the API. */
+  ci: {
+    /** Support for `ci.runs()` and `ci.runsPage()`. */
+    runs: Support;
+    /** Support for `ci.run()`. */
+    run: Support;
+    /** Support for `ci.jobs()` and `ci.jobsPage()`. */
+    jobs: Support;
+    /** Support for `ci.log()`. */
+    log: Support;
+  };
+  /**
+   * Reviews on a pull request. `list` is `'emulated'` where reviews are
+   * synthesised from approvals or votes; `create` then covers only the events
+   * the forge's approval endpoint can express.
+   */
+  reviews: {
+    /** Support for `threads.reviews()` and `threads.reviewsPage()`. */
+    list: Support;
+    /** Support for `threads.createReview()`. */
+    create: Support;
+    /** Support for `threads.submitReview()`. */
+    submit: Support;
+    /** Support for `threads.approve()`. */
+    approve: Support;
+    /** Support for `threads.resolveReviewThread()` and `threads.unresolveReviewThread()`. */
+    resolveThread: Support;
+  };
+  /**
+   * Repository contents. `tree` is `'emulated'` where recursion is walked
+   * level by level rather than by the forge.
+   */
+  contents: {
+    /** Support for `contents.file()`. */
+    file: Support;
+    /** Support for `contents.tree()` and `contents.treePage()`. */
+    tree: Support;
+    /** Support for `contents.branches()` and `contents.branchesPage()`. */
+    branches: Support;
+    /** Support for `contents.tags()` and `contents.tagsPage()`. */
+    tags: Support;
+    /** Support for `contents.resolveRef()`. */
+    resolveRef: Support;
+    /** Support for `contents.commits()` and `contents.commitsPage()`. */
+    commits: Support;
+    /** Support for `contents.commit()`. */
+    commit: Support;
+    /** Support for `contents.compare()`. */
+    compare: Support;
+    /** `threads.files` and `threads.commits` on a pull request. */
+    threadFiles: Support;
+    /** Support for `threads.commits()` and `threads.commitsPage()`. */
+    threadCommits: Support;
+  };
+  /** Managing registered webhooks, beside receiving deliveries. */
+  webhooks: {
+    /** Support for `webhooks.list()` and `webhooks.listPage()`. */
+    list: Support;
+    /** Support for `webhooks.create()`. */
+    create: Support;
+    /** Support for `webhooks.update()`. */
+    update: Support;
+    /** Support for `webhooks.delete()`. */
+    delete: Support;
+    /** Support for `webhooks.rotateSecret()`. */
+    rotateSecret: Support;
+    /** Support for `webhooks.deliveries()` and `webhooks.deliveriesPage()`. */
+    deliveries: Support;
+    /** Support for `webhooks.redeliver()`. */
+    redeliver: Support;
+  };
+  releases: {
+    /** Support for `releases.list()` and `releases.listPage()`. */
+    list: Support;
+    /** Support for `releases.get()`. */
+    get: Support;
+    /** Support for `releases.latest()`. */
+    latest: Support;
+    /** Support for `releases.getByTag()`. */
+    getByTag: Support;
+    /** Support for `releases.downloadAsset()`. */
+    downloadAsset: Support;
+    /** Support for `releases.create()`. */
+    create: Support;
+    /** Support for `releases.update()`. */
+    update: Support;
+  };
+  /** Cross-repository search of issues and pull requests, repositories, commits and code. */
+  search: {
+    /** Support for `search.threads()` and `search.threadsPage()`. */
+    threads: Support;
+    /** Support for `search.repos()` and `search.reposPage()`. */
+    repos: Support;
+    /** Support for `search.commits()` and `search.commitsPage()`. */
+    commits: Support;
+    /** Support for `search.code()` and `search.codePage()`. */
+    code: Support;
+  };
+  /** Per alert kind, since each needs its own token scope on GitHub. */
+  securityAlerts: AlertSupport;
+  /** Enumerating app installations and deriving one provider per installation. */
+  installations: Support;
+  /**
+   * `'heuristic'` when event kinds are inferred from free text (GitLab system
+   * notes) rather than reported by the forge, so `kind` may be `'other'` or
+   * wrong for unrecognised wording; `kindRaw` and `payload` stay exact.
+   */
+  eventKinds: "native" | "heuristic";
+  /** Auth types the provider accepts. The type this provider was created with is `ForgeProvider.authKind`. */
+  authKinds: readonly AuthKind[];
+  /** Maximum text lengths the forge accepts. */
+  limits?: TextLimits;
+}
+/**
+ * An async iterable that also collects non-fatal warnings as it runs. Read
+ * `warnings` during or after iteration.
+ */
+interface ForgeIterable<T> extends AsyncIterable<T> {
+  /** The non-fatal warnings collected so far. Read it during or after iteration. */
+  readonly warnings: ForgeWarning[];
+}
+/** A webhook delivery as received: its headers, its raw body and, optionally, the secret to verify it with. */
+interface WebhookDelivery {
+  /** The request headers, which carry the signature and the event name. */
+  headers: Headers | Record<string, string>;
+  /** Raw body exactly as received; signatures are computed over these bytes. */
+  body: string | Uint8Array;
+  /** Overrides the provider-level `webhookSecret` for this delivery. */
+  secret?: string;
+}
+/** Options for `markAllRead()` and `markAllDone()`. */
+interface BulkNotificationOptions extends BaseOptions {
+  /** Limit to one repository. */
+  repo?: RepoRef;
+  /** Only notifications updated before this time. */
+  before?: Date;
+}
+/** Reading and clearing the notifications of the authenticated account. */
+interface NotificationsApi {
+  /** Lists the account's notifications. */
+  list: (options?: NotificationListOptions) => ForgeIterable<Notification>;
+  /** One page of `list()`. Pass the `cursor` of the previous page to read the next. */
+  listPage: (options?: NotificationListOptions) => Promise<Page<Notification>>;
+  /** Marks a notification as read. */
+  markRead: (ref: NotificationRef, options?: BaseOptions) => Promise<void>;
+  /** Marks a notification as done, which clears it from the inbox where the forge has that state. */
+  markDone: (ref: NotificationRef, options?: NotificationWriteOptions) => Promise<void>;
+  /** Stops notifications for the notification's thread, and on some forges also clears the notification. */
+  unsubscribe: (ref: NotificationRef, options?: NotificationWriteOptions) => Promise<void>;
+  /** Marks every notification as read, or those of one repository. */
+  markAllRead: (options?: BulkNotificationOptions) => Promise<void>;
+  /** Marks every notification as done, or those of one repository. */
+  markAllDone: (options?: BulkNotificationOptions) => Promise<void>;
+  /** The number of unread notifications. */
+  unreadCount: (options?: BaseOptions) => Promise<number>;
+}
+/** Options for changing one notification. */
+interface NotificationWriteOptions extends BaseOptions {
+  /**
+   * The thread the notification points at, when the caller already holds it.
+   * Providers that would otherwise look it up skip that request.
+   */
+  thread?: ThreadRef;
+}
+/** Why a thread was closed. */
+type CloseReason = "completed" | "not_planned" | "duplicate";
+/** Options for `threads.close()`. */
+interface CloseOptions extends BaseOptions {
+  /**
+   * Mapped to the forge's own reason where it has one; forges without close
+   * reasons close the thread without one.
+   */
+  reason?: CloseReason;
+  /** Forge-native reason, sent as is; takes precedence over `reason`. */
+  reasonRaw?: string;
+}
+/**
+ * Issues, pull requests and the other kinds of discussion: reading, creating, commenting, labelling,
+ * reviewing and merging them.
+ */
+interface ThreadsApi {
+  /**
+   * Reads an issue, pull request or discussion by its ref. Rejects with `NotFoundError` when it does not exist or the
+   * credential cannot see it.
+   */
+  get: (ref: ThreadRef, options?: BaseOptions) => Promise<Thread>;
+  /** Reads several threads, batched where the forge allows. Failures become per-item warnings. */
+  getMany: (refs: ThreadRef[], options?: BaseOptions) => Promise<GetManyResult[]>;
+  /** Lists the threads of a repository. */
+  list: (repo: RepoRef, query?: ThreadQuery) => ForgeIterable<Thread>;
+  /** One page of `list`; pass `cursor` back in `query` to read the next. */
+  listPage: (repo: RepoRef, query?: ThreadQuery) => Promise<Page<Thread>>;
+  /** Lists the events on a thread, such as comments, label changes and state changes. */
+  events: (ref: ThreadRef, options?: ListOptions) => ForgeIterable<ForgeEvent>;
+  /** One page of `events()`. */
+  eventsPage: (ref: ThreadRef, options?: ListOptions) => Promise<Page<ForgeEvent>>;
+  /** Conversation comments. Inline review comments are events, not comments. */
+  comments: (ref: ThreadRef, options?: ListOptions) => ForgeIterable<Comment>;
+  /** One page of `comments()`. */
+  commentsPage: (ref: ThreadRef, options?: ListOptions) => Promise<Page<Comment>>;
+  /** Adds a comment to a thread. */
+  comment: (ref: ThreadRef, body: string, options?: BaseOptions) => Promise<Comment>;
+  /**
+   * Creates the comment, or edits the one an earlier call with the same `key`
+   * left behind. The key is carried in the body as a hidden marker; see
+   * {@link commentMarker}. Composed from `comments`, `comment` and
+   * `editComment`, so it costs a listing on every call.
+   * @param ref The thread to comment on.
+   * @param input The `key` that identifies the comment across runs, and its `body`.
+   * @example
+   * ```ts
+   * await provider.threads.upsertComment(ref, { key: 'preview', body: 'Preview: https://pr-42.example.com' })
+   * ```
+   */
+  upsertComment: (ref: ThreadRef, input: UpsertCommentInput, options?: BaseOptions) => Promise<UpsertCommentResult>;
+  /** Replaces the body of a comment. */
+  editComment: (ref: CommentRef, body: string, options?: BaseOptions) => Promise<Comment>;
+  /** Deletes a comment. */
+  deleteComment: (ref: CommentRef, options?: BaseOptions) => Promise<void>;
+  /** Creates an issue, pull request or discussion. A pull request needs `head` and `base`. */
+  create: (repo: RepoRef, input: ThreadCreateInput, options?: BaseOptions) => Promise<Thread>;
+  /** Changes the title, body or other fields of a thread. Fields left out stay as they are. */
+  update: (ref: ThreadRef, input: ThreadUpdateInput, options?: BaseOptions) => Promise<Thread>;
+  /** Replaces the thread's labels. */
+  setLabels: (ref: ThreadRef, labels: string[], options?: BaseOptions) => Promise<void>;
+  /** Adds labels, leaving the rest in place. */
+  addLabels: (ref: ThreadRef, labels: string[], options?: BaseOptions) => Promise<void>;
+  /** Removes labels, leaving the rest in place. Labels the thread does not carry are ignored. */
+  removeLabels: (ref: ThreadRef, labels: string[], options?: BaseOptions) => Promise<void>;
+  /** Sets the thread's milestone, by milestone, id or title, or clears it with `undefined`. */
+  setMilestone: (ref: ThreadRef, milestone: Milestone | string | undefined, options?: BaseOptions) => Promise<void>;
+  /** Reactions left on the thread or on one of its comments. */
+  reactions: (target: ThreadRef | CommentRef, options?: ListOptions) => ForgeIterable<Reaction>;
+  /** One page of `reactions()`. */
+  reactionsPage: (target: ThreadRef | CommentRef, options?: ListOptions) => Promise<Page<Reaction>>;
+  /**
+   * Reacts as the authenticated account, to the thread or to one of its comments.
+   * @param target The thread or comment to react to.
+   * @param reaction The reaction to leave.
+   */
+  react: (target: ThreadRef | CommentRef, reaction: ReactionContent, options?: BaseOptions) => Promise<void>;
+  /** Removes the account's reaction from the thread or comment. */
+  unreact: (target: ThreadRef | CommentRef, reaction: ReactionContent, options?: BaseOptions) => Promise<void>;
+  /** Moves the thread to another repository, and returns its ref there. */
+  transfer: (ref: ThreadRef, repo: RepoRef, options?: BaseOptions) => Promise<ThreadRef>;
+  /** Marks the thread a duplicate of `canonical`, which must be in the same repository on most forges. */
+  markDuplicate: (ref: ThreadRef, canonical: ThreadRef, options?: BaseOptions) => Promise<void>;
+  /** Replaces the thread's assignees. */
+  setAssignees: (ref: ThreadRef, assignees: Array<string | Actor>, options?: BaseOptions) => Promise<void>;
+  /** Adds reviewers to a pull request. */
+  requestReview: (ref: ThreadRef, reviewers: Array<string | Actor>, options?: BaseOptions) => Promise<void>;
+  /** Closes a thread, optionally with a reason. */
+  close: (ref: ThreadRef, options?: CloseOptions) => Promise<void>;
+  /** Reopens a closed thread. */
+  reopen: (ref: ThreadRef, options?: BaseOptions) => Promise<void>;
+  /**
+   * Merges a pull request. Without a merge method, the repository must allow exactly one.
+   * @param ref The pull request to merge.
+   * @param options The merge method, the head `sha` to expect and the commit message.
+   * @example
+   * ```ts
+   * await provider.threads.merge(ref, { method: 'squash' })
+   * ```
+   */
+  merge: (ref: ThreadRef, options?: MergeOptions) => Promise<void>;
+  /** Approves, then merges. The merge method is checked before the approval is sent. */
+  approveAndMerge: (ref: ThreadRef, options?: ApproveAndMergeOptions) => Promise<void>;
+  /** The authenticated account's subscription to the thread. */
+  subscription: (ref: ThreadRef, options?: BaseOptions) => Promise<SubscriptionState>;
+  /** Subscribes the account to the notifications of a thread. */
+  subscribe: (ref: ThreadRef, options?: BaseOptions) => Promise<void>;
+  /** Stops the account's notifications for a thread, leaving existing notifications alone. */
+  unsubscribe: (ref: ThreadRef, options?: BaseOptions) => Promise<void>;
+  /** Every check on the pull's head, in one page; `warnings` names the sources that could not be read. */
+  checks: (ref: ThreadRef, options?: BaseOptions) => Promise<Page<Check>>;
+  /**
+   * Reviews on a pull request. Forges with approvals but no review objects
+   * (GitLab approvals, Azure DevOps votes, Bitbucket participants) synthesise
+   * one review per approver, with `comments: false`.
+   */
+  reviews: (ref: ThreadRef, options?: PageOptions) => ForgeIterable<Review>;
+  /** One page of `reviews()`. */
+  reviewsPage: (ref: ThreadRef, options?: PageOptions) => Promise<Page<Review>>;
+  /** Creates a review. Without `event` the review is pending where the forge has pending reviews. */
+  createReview: (ref: ThreadRef, input: ReviewInput, options?: BaseOptions) => Promise<Review>;
+  /** Submits a pending review. */
+  submitReview: (ref: ReviewRef, event: ReviewEvent, body?: string, options?: BaseOptions) => Promise<Review>;
+  /** Approves without merging; `createReview({ event: 'approve' })` with nothing else to say. */
+  approve: (ref: ThreadRef, body?: string, options?: BaseOptions) => Promise<void>;
+  /** Files a pull request changes, with a per-file `patch` where the forge returns one. */
+  files: (ref: ThreadRef, options?: PageOptions) => ForgeIterable<ChangedFile>;
+  /** One page of `files()`. */
+  filesPage: (ref: ThreadRef, options?: PageOptions) => Promise<Page<ChangedFile>>;
+  /** Commits on a pull request. */
+  commits: (ref: ThreadRef, options?: PageOptions) => ForgeIterable<Commit>;
+  /** One page of `commits()`. */
+  commitsPage: (ref: ThreadRef, options?: PageOptions) => Promise<Page<Commit>>;
+  /** Resolves a review conversation, by the id on {@link ReviewComment.thread} or {@link Comment.thread}. */
+  resolveReviewThread: (ref: ThreadRef, id: string, options?: BaseOptions) => Promise<void>;
+  /** Reopens a resolved review conversation, by the id on `ReviewComment.thread` or `Comment.thread`. */
+  unresolveReviewThread: (ref: ThreadRef, id: string, options?: BaseOptions) => Promise<void>;
+}
+/** Reading and reporting the checks on a commit. */
+interface ChecksApi {
+  /** Every check on a commit: check runs, commit statuses, jobs or policy evaluations. */
+  list: (repo: RepoRef, sha: string, options?: BaseOptions) => Promise<Page<Check>>;
+  /** Writes a commit status, or a check run where the credential can (GitHub app auth). */
+  report: (repo: RepoRef, sha: string, input: CheckReportInput, options?: BaseOptions) => Promise<Check>;
+  /** Re-runs a check. Rejects for a `CheckRef.type` the forge cannot re-run. */
+  rerun: (ref: CheckRef, options?: BaseOptions) => Promise<void>;
+}
+/** Reading CI runs and their jobs. CI is read-only. */
+interface CiApi {
+  /** Lists the CI runs of a repository. */
+  runs: (repo: RepoRef, query?: CiRunQuery) => ForgeIterable<CiRun>;
+  /** One page of `runs()`. */
+  runsPage: (repo: RepoRef, query?: CiRunQuery) => Promise<Page<CiRun>>;
+  /** Reads one CI run. */
+  run: (ref: CiRunRef, options?: BaseOptions) => Promise<CiRun>;
+  /** Lists the jobs of a CI run. */
+  jobs: (ref: CiRunRef, options?: PageOptions) => ForgeIterable<CiJob>;
+  /** One page of `jobs()`. */
+  jobsPage: (ref: CiRunRef, options?: PageOptions) => Promise<Page<CiJob>>;
+  /** The job's log as it arrives. There is no workflow dispatch: CI is read-only here. */
+  log: (ref: CiJobRef, options?: BaseOptions) => Promise<ReadableStream<Uint8Array>>;
+}
+/** Files, trees, branches, tags and commits of a repository. */
+interface ContentsApi {
+  /**
+   * One file's contents. Binary-safe: `content` is a `Uint8Array` unless the
+   * forge reports text and `as: 'text'` was asked for. Files past the forge's
+   * inline limit (1 MB on GitHub) are read from the raw or blob endpoint
+   * instead of failing.
+   * @param repo The repository to read from.
+   * @param path The path of the file from the repository root.
+   * @param options The revision to read, and whether to decode the content as text.
+   * @example
+   * ```ts
+   * const file = await provider.contents.file(repo, 'package.json', { as: 'text' })
+   * const manifest = JSON.parse(file.content as string)
+   * ```
+   */
+  file: (repo: RepoRef, path: string, options?: FileOptions) => Promise<FileContent>;
+  /** One level, or every descendant with `recursive`. Truncated listings carry a `tree_truncated` warning. */
+  tree: (repo: RepoRef, options?: TreeOptions) => ForgeIterable<TreeEntry>;
+  /** One page of `tree()`. */
+  treePage: (repo: RepoRef, options?: TreeOptions) => Promise<Page<TreeEntry>>;
+  /** Lists the branches of a repository. */
+  branches: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Branch>;
+  /** One page of `branches()`. */
+  branchesPage: (repo: RepoRef, options?: PageOptions) => Promise<Page<Branch>>;
+  /** Lists the tags of a repository. */
+  tags: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Tag>;
+  /** One page of `tags()`. */
+  tagsPage: (repo: RepoRef, options?: PageOptions) => Promise<Page<Tag>>;
+  /** Resolves a branch, tag or sha to a full commit sha; a full sha is returned as is. */
+  resolveRef: (repo: RepoRef, ref: string, options?: BaseOptions) => Promise<string>;
+  /** Lists the commits that lead to `ref`, or to the default branch. */
+  commits: (repo: RepoRef, query?: CommitQuery) => ForgeIterable<Commit>;
+  /** One page of `commits()`. */
+  commitsPage: (repo: RepoRef, query?: CommitQuery) => Promise<Page<Commit>>;
+  /** One commit, with its files and stats. */
+  commit: (repo: RepoRef, sha: string, options?: BaseOptions) => Promise<Commit>;
+  /** Commits and files between two refs. */
+  compare: (repo: RepoRef, base: string, head: string, options?: BaseOptions) => Promise<Comparison>;
+}
+/** Reading, creating and updating the releases of a repository, and downloading their assets. */
+interface ReleasesApi {
+  /** Lists the releases of a repository, including drafts and pre-releases where the credential can see them. */
+  list: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Release>;
+  /** One page of `list()`. */
+  listPage: (repo: RepoRef, options?: PageOptions) => Promise<Page<Release>>;
+  /** Reads a release by its ref. */
+  get: (ref: ReleaseRef, options?: BaseOptions) => Promise<Release>;
+  /** The release for a tag name. */
+  getByTag: (repo: RepoRef, tag: string, options?: BaseOptions) => Promise<Release>;
+  /**
+   * The asset's bytes as they arrive. A redirect to a CDN host is followed
+   * without the `Authorization` header, which those hosts reject.
+   */
+  downloadAsset: (ref: ReleaseAssetRef, options?: BaseOptions) => Promise<ReadableStream<Uint8Array>>;
+  /** The most recent published release that is not a draft or prerelease, if any. */
+  latest: (repo: RepoRef, options?: BaseOptions) => Promise<Release | undefined>;
+  /**
+   * Creates a release, and its tag from `target` when the tag does not exist yet.
+   * @param repo The repository to release.
+   * @param input The tag, the name, the notes and whether the release is a draft or a prerelease.
+   * @throws `UnsupportedOperationError` for `draft: true` or `prerelease: true` on a forge without drafts or prereleases.
+   * @example
+   * ```ts
+   * const release = await provider.releases.create(repo, { tag: 'v1.2.0', body: notes, draft: true })
+   * ```
+   */
+  create: (repo: RepoRef, input: ReleaseInput, options?: BaseOptions) => Promise<Release>;
+  /**
+   * Changes a release. Fields left out stay as they are, so `{ draft: false }` publishes a draft.
+   * @throws `UnsupportedOperationError` for a change the forge cannot make, such as a new tag on GitLab.
+   * @throws `ForbiddenError` with reason `immutable_release` when the forge refuses the write because the
+   * release is immutable (GitHub); its name, notes, prerelease and `latest` flags stay editable.
+   */
+  update: (ref: ReleaseRef, update: ReleaseUpdate, options?: BaseOptions) => Promise<Release>;
+}
+/** Searching issues and pull requests, repositories, commits and code across the forge. */
+interface SearchApi {
+  /**
+   * Issues and pull requests across repositories. Fields the forge cannot
+   * filter on come back as a `filter_unsupported` warning on the page.
+   */
+  threads: (query: SearchQuery) => ForgeIterable<Thread>;
+  /** One page of `threads()`. */
+  threadsPage: (query: SearchQuery) => Promise<Page<Thread>>;
+  /** Searches repositories. */
+  repos: (query: RepoSearchQuery) => ForgeIterable<Repo>;
+  /** One page of `repos()`. */
+  reposPage: (query: RepoSearchQuery) => Promise<Page<Repo>>;
+  /** Commits across repositories, where the forge indexes them. */
+  commits: (query: CommitSearchQuery) => ForgeIterable<Commit>;
+  /** One page of `commits()`. */
+  commitsPage: (query: CommitSearchQuery) => Promise<Page<Commit>>;
+  /** Searches the contents of files, where the forge indexes them. */
+  code: (query: CodeSearchQuery) => ForgeIterable<CodeMatch>;
+  /** One page of `code()`. */
+  codePage: (query: CodeSearchQuery) => Promise<Page<CodeMatch>>;
+}
+/** Reading the security alerts of a repository. */
+interface SecurityAlertsApi {
+  /** Lists the security alerts of a repository. */
+  list: (repo: RepoRef, options?: SecurityAlertListOptions) => ForgeIterable<SecurityAlert>;
+  /** One page of `list()`. */
+  listPage: (repo: RepoRef, options?: SecurityAlertListOptions) => Promise<Page<SecurityAlert>>;
+}
+/**
+ * Options for `repos.get()`.
+ */
+interface RepoGetOptions extends BaseOptions {
+  /**
+   * Includes the repository's licence in `Repo.licence`. GitLab reports it only on request, because detecting it
+   * scans the repository; other forges ignore this option.
+   */
+  licence?: boolean;
+}
+/** Repositories, and the labels, milestones and collaborators that belong to them. */
+interface ReposApi {
+  /**
+   * Reads a repository by its ref. Rejects with `NotFoundError` when it does not exist or the credential cannot see
+   * it.
+   */
+  get: (ref: RepoRef, options?: RepoGetOptions) => Promise<Repo>;
+  /** The authenticated account's repositories, or the installation's under app auth. */
+  list: (options?: RepoQuery) => ForgeIterable<Repo>;
+  /** One page of `list()`. */
+  listPage: (options?: RepoQuery) => Promise<Page<Repo>>;
+  /** Every label defined on the repository, whether or not a thread carries it. */
+  labels: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Label>;
+  /** One page of `labels()`. */
+  labelsPage: (repo: RepoRef, options?: PageOptions) => Promise<Page<Label>>;
+  /** Creates a label in a repository. */
+  createLabel: (repo: RepoRef, label: LabelInput, options?: BaseOptions) => Promise<Label>;
+  /** Lists the milestones of a repository. */
+  milestones: (repo: RepoRef, options?: MilestoneListOptions) => ForgeIterable<Milestone>;
+  /** One page of `milestones()`. */
+  milestonesPage: (repo: RepoRef, options?: MilestoneListOptions) => Promise<Page<Milestone>>;
+  /** Lists the collaborators of a repository, with their roles. */
+  collaborators: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Collaborator>;
+  /** One page of `collaborators()`. */
+  collaboratorsPage: (repo: RepoRef, options?: PageOptions) => Promise<Page<Collaborator>>;
+  /** One account's role on the repository; `'none'` when it has no access. */
+  permissionFor: (repo: RepoRef, actor: string | Actor, options?: BaseOptions) => Promise<RepoRole>;
+  /** Gives an account a role on a repository. */
+  addCollaborator: (repo: RepoRef, actor: string | Actor, role: RepoRole, options?: BaseOptions) => Promise<void>;
+  /** Accounts that can be assigned to a thread in the repository. */
+  assignableUsers: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Actor>;
+  /** One page of `assignableUsers()`. */
+  assignableUsersPage: (repo: RepoRef, options?: PageOptions) => Promise<Page<Actor>>;
+  /** Accounts that can be asked to review a given pull request. */
+  reviewerCandidates: (ref: ThreadRef, options?: PageOptions) => ForgeIterable<Actor>;
+  /** One page of `reviewerCandidates()`. */
+  reviewerCandidatesPage: (ref: ThreadRef, options?: PageOptions) => Promise<Page<Actor>>;
+}
+/** Options for `repos.milestones()`. */
+interface MilestoneListOptions extends PageOptions {
+  /**
+   * @default 'open'
+   */
+  state?: "open" | "closed" | "all";
+}
+/** The installations of the app that the provider authenticates as. */
+interface InstallationsApi {
+  /** Lists the installations of the app. */
+  list: (options?: PageOptions) => ForgeIterable<Installation>;
+  /** One page of `list()`. */
+  listPage: (options?: PageOptions) => Promise<Page<Installation>>;
+  /** Reads one installation. */
+  get: (installation: Installation | string, options?: BaseOptions) => Promise<Installation>;
+  /** Mints (or reuses a cached) installation token. */
+  token: (installation: Installation | string, options?: BaseOptions) => Promise<InstallationToken>;
+  /** Lists the repositories that an installation can access. */
+  repos: (installation: Installation | string, options?: PageOptions) => ForgeIterable<Repo>;
+  /** One page of `repos()`. */
+  reposPage: (installation: Installation | string, options?: PageOptions) => Promise<Page<Repo>>;
+  /** Provider authenticated as one installation, sharing this instance's app credentials. */
+  provider: (installation: Installation | string) => ForgeProvider;
+  /** One provider per installation. */
+  providers: () => AsyncIterable<{
+    installation: Installation;
+    provider: ForgeProvider;
+  }>;
+}
+/** Receiving webhook deliveries, and managing the hooks registered on the forge. */
+interface WebhooksApi {
+  /** Checks a delivery's signature or token against the secret. */
+  verify: (delivery: WebhookDelivery) => Promise<boolean>;
+  /**
+   * Verifies the delivery, then translates it into normalised events.
+   * @param delivery The headers and the raw body of the request, exactly as received.
+   * @example
+   * ```ts
+   * const events = await provider.webhooks.ingest({
+   *   headers: request.headers,
+   *   body: await request.text(),
+   * })
+   * ```
+   */
+  ingest: (delivery: WebhookDelivery) => Promise<ForgeEvent[]>;
+  /** Normalised kinds and actions this provider can deliver, whatever a hook is subscribed to. */
+  readonly events: WebhookEventType[];
+  /** Hooks on a repository, or on an organisation or workspace when `target` is a namespace ref. */
+  list: (target: RepoRef, options?: PageOptions) => ForgeIterable<Webhook>;
+  /** One page of `list()`. */
+  listPage: (target: RepoRef, options?: PageOptions) => Promise<Page<Webhook>>;
+  /** Registers a webhook. */
+  create: (target: RepoRef, input: WebhookInput, options?: BaseOptions) => Promise<Webhook>;
+  /** Changes a webhook. */
+  update: (ref: WebhookRef, update: WebhookUpdate, options?: BaseOptions) => Promise<Webhook>;
+  /** Deletes a webhook. */
+  delete: (ref: WebhookRef, options?: BaseOptions) => Promise<void>;
+  /** Replaces the signing secret in place. `false` where the forge can only do it by recreating the hook. */
+  rotateSecret: (ref: WebhookRef, secret: string, options?: BaseOptions) => Promise<Webhook>;
+  /** Lists the recent deliveries of a webhook. */
+  deliveries: (ref: WebhookRef, options?: PageOptions) => ForgeIterable<WebhookDeliveryRecord>;
+  /** One page of `deliveries()`. */
+  deliveriesPage: (ref: WebhookRef, options?: PageOptions) => Promise<Page<WebhookDeliveryRecord>>;
+  /** Sends a past delivery again. */
+  redeliver: (ref: WebhookDeliveryRef, options?: BaseOptions) => Promise<void>;
+}
+/**
+ * What a credential needs for a verb, as data. Nothing in the library reads
+ * it; it is there so a consumer can build a consent screen or explain a 403.
+ */
+interface VerbScopes {
+  /** OAuth or personal access token scopes. */
+  token?: string[];
+  /** Fine-grained token or app permissions, by permission name. */
+  permissions?: Record<string, "read" | "write" | "admin">;
+  /** How the forge expresses access where scopes do not apply. */
+  note?: string;
+}
+/** Options for `sources.subscribe()`. */
+interface SubscribeOptions {
+  /** Resume after this cursor, as yielded by an earlier {@link SubscriptionItem}. */
+  cursor?: string;
+  /** Aborting closes the connection and ends iteration without an error. */
+  signal?: AbortSignal;
+}
+/** One item from a push subscription. */
+interface SubscriptionItem {
+  event: ForgeEvent;
+  /** Opaque position after `event`; persist it and pass it back to resume. */
+  cursor: string;
+}
+/** Reading accounts. */
+interface UsersApi {
+  /** Reads an account by login, without needing a credential where the forge allows it. */
+  get: (login: string, options?: BaseOptions) => Promise<User>;
+  /**
+   * The account the provider's credential belongs to.
+   * @example
+   * ```ts
+   * const me = await provider.users.me()
+   * console.log(me.login)
+   * ```
+   */
+  me: (options?: BaseOptions) => Promise<User>;
+}
+/** Ways to receive events: polling, webhooks and push subscriptions. */
+interface SourcesApi {
+  /**
+   * Push delivery over a long-lived connection. Iteration ends when the signal
+   * aborts or the consumer stops iterating; a dropped connection throws
+   * `SubscriptionClosedError` carrying the last cursor. There is no automatic
+   * reconnection.
+   */
+  subscribe: (options?: SubscribeOptions) => AsyncIterable<SubscriptionItem>;
+}
+/** A connection to one forge, with its identity, its capabilities and the namespaces of operations. */
+interface ForgeProvider {
+  /**
+   * Requests endpoints relative to `baseUrl` or absolute HTTP(S) URLs.
+   * Other origins omit default headers and provider credentials; explicit headers apply.
+   */
+  readonly request: ForgeRequest;
+  /** The forge this provider sends requests to; matches `forge` on every ref it returns. */
+  readonly forge: ForgeKind;
+  readonly instance: ForgeInstance;
+  readonly baseUrl: string;
+  /** The `auth.type` the provider was created with; `'anonymous'` when it sends no credentials. */
+  readonly authKind: AuthKind;
+  /** Static, no-network capabilities until `refreshCapabilities()` resolves. */
+  readonly capabilities: ForgeCapabilities;
+  /**
+   * Re-derives capabilities from the instance version. The version is read
+   * once per provider (GHES `/meta`, GitLab, Forgejo and Gitea `/version`).
+   * Updates `capabilities` and returns it.
+   */
+  refreshCapabilities: () => Promise<ForgeCapabilities>;
+  /** Rewrites Markdown into the dialect the forge renders; returns it unchanged where the forge renders CommonMark. */
+  normaliseMarkdown: (body: string) => string;
+  readonly repos: ReposApi;
+  readonly notifications: NotificationsApi;
+  readonly sources: SourcesApi;
+  readonly threads: ThreadsApi;
+  readonly webhooks: WebhooksApi;
+  readonly installations: InstallationsApi;
+  readonly releases: ReleasesApi;
+  readonly contents: ContentsApi;
+  readonly checks: ChecksApi;
+  readonly ci: CiApi;
+  readonly users: UsersApi;
+  readonly search: SearchApi;
+  readonly securityAlerts: SecurityAlertsApi;
+  /**
+   * Whether `verb` is supported, for `kind` where support differs by kind,
+   * including version gates. Every verb is always present and rejects with
+   * `UnsupportedOperationError` when this is `false`: the capability is the
+   * question, the method is the action.
+   * @param verb The operation, named by its path on the provider, such as `threads.comment`.
+   * @param kind The thread kind, for an operation whose support differs by kind.
+   * @example
+   * ```ts
+   * if (provider.can('threads.merge')) {
+   *   await provider.threads.merge(ref)
+   * }
+   * ```
+   */
+  can: (verb: ForgeVerb, kind?: ThreadKind | SecurityAlertKind) => boolean;
+  /**
+   * How well `verb` is supported: `true`, `'experimental'`, `'emulated'`,
+   * `'unverified'` or `false`, for `kind` where support differs by kind. `can()` is `true` for
+   * every level but `false`. Without `kind`, a per-kind verb reports its
+   * strongest level across kinds.
+   * @param verb The operation, named by its path on the provider, such as `threads.comment`.
+   * @param kind The thread kind, for an operation whose support differs by kind.
+   */
+  support: (verb: ForgeVerb, kind?: ThreadKind | SecurityAlertKind) => Support;
+  /**
+   * The web page for `target`, built without a request; `undefined` when the forge has no such page.
+   * @param target What to link to: a repository, thread, comment, release, file or comparison.
+   */
+  urlFor: (target: UrlTarget) => string | undefined;
+  /**
+   * Token scopes or app permissions `verb` needs on this forge, as data for a
+   * consent screen or a 403 explanation. Nothing in the library reads it, and
+   * an unmapped verb returns `{}`.
+   * @param verb The operation, named by its path on the provider.
+   */
+  scopesFor: (verb: ForgeVerb) => VerbScopes;
+  /**
+   * Reads a web URL, clone URL or npm `repository` value (`git+https://`, `github:owner/name`) on this provider's instance into refs; `undefined` for anything else.
+   * @param url The URL to read.
+   */
+  parseUrl: (url: string | URL) => ParsedForgeUrl | undefined;
+  /**
+   * How to mention `ref` in Markdown on this forge (`#42`, `!42`,
+   * `acme/widgets#42`), short when written in `from`; the thread URL where the
+   * forge has no reference syntax.
+   * @param ref The thread to mention.
+   * @param options The repository the reference is written in, so that a reference within it is short.
+   */
+  referenceTo: (ref: ThreadRef, options?: ReferenceOptions) => string | undefined;
+}
+/**
+ * Lazily constructed provider. `createForges` calls `create()`; nothing
+ * touches the network before that.
+ */
+interface ForgeProviderFactory<T extends ForgeProvider = ForgeProvider> {
+  readonly forge: ForgeKind;
+  /** The provider has not reached parity; see `ForgeCapabilities.experimental`. */
+  readonly experimental?: true;
+  /** Creates the provider. Nothing touches the network before this. */
+  create: () => T;
+}
+/** A registry of providers that routes each ref to the provider it belongs to. */
+interface Forges {
+  readonly providers: ForgeProvider[];
+  /** First provider for `forge`, optionally narrowed to a single instance host. */
+  get: (forge: ForgeKind, instance?: ForgeInstance) => ForgeProvider | undefined;
+  /** Every provider for a forge. */
+  all: (forge: ForgeKind) => ForgeProvider[];
+  /** The provider a ref belongs to, by `forge` and `instance`. */
+  for: (ref: ForgeOrigin) => ForgeProvider | undefined;
+  /** The provider whose instance serves `url`. */
+  forUrl: (url: string | URL) => ForgeProvider | undefined;
+  /** Reads a web URL, clone URL or npm `repository` value on any registered instance. */
+  parseUrl: (url: string | URL) => (ParsedForgeUrl & {
+    provider: ForgeProvider;
+  }) | undefined;
+  /** Notifications from every registered provider, provider by provider. */
+  notifications: {
+    /** Lists the notifications of every provider, provider by provider. */
+    list: (options?: Omit<NotificationListOptions, "cursor">) => ForgeIterable<Notification>;
+  };
+  /** Reads routed to the provider each ref belongs to; an unregistered origin throws `UnknownForgeError`. */
+  repos: {
+    /** Reads a repository from the provider it belongs to. */
+    get: (ref: RepoRef, options?: RepoGetOptions) => Promise<Repo>;
+  };
+  threads: {
+    /** Reads a thread from the provider it belongs to. */
+    get: (ref: ThreadRef, options?: BaseOptions) => Promise<Thread>;
+    /** Grouped per provider, results in input order. An unregistered origin is a per-item warning. */
+    getMany: (refs: ThreadRef[], options?: BaseOptions) => Promise<GetManyResult[]>;
+  };
+  releases: {
+    /** Lists the releases of a repository. */
+    list: (repo: RepoRef, options?: PageOptions) => ForgeIterable<Release>;
+    /** The latest release of a repository, if any. */
+    latest: (repo: RepoRef, options?: BaseOptions) => Promise<Release | undefined>;
+  };
+  securityAlerts: {
+    list: SecurityAlertsApi["list"];
+  };
+  /**
+   * Searches every provider that supports search, reading pages as the
+   * iteration needs them and merging by `updatedAt`, or by `createdAt` with
+   * `sort: 'created'`, newest first unless `direction: 'asc'`. Each provider is
+   * asked to sort the same way; results from one that cannot are only in order
+   * within each page. A provider that rejects adds a `search_failed` warning
+   * and no further items.
+   */
+  search: {
+    /** Searches issues and pull requests on every provider that supports search. */
+    threads: (query?: Omit<SearchQuery, "cursor" | "sort"> & {
+      sort?: "created" | "updated";
+    }) => ForgeIterable<Thread>;
+    /** Searches repositories on every provider that supports search. */
+    repos: (query?: Omit<RepoSearchQuery, "cursor" | "sort"> & {
+      sort?: "created" | "updated";
+    }) => ForgeIterable<Repo>;
+  };
+}
+/**
+ * Combines providers into a registry. Pass factories such as `github()`, or providers that already exist.
+ * @param factories Factories such as `github()`, or providers that already exist.
+ * @example
+ * ```ts
+ * import { createForges, github, gitlab } from 'forges'
+ *
+ * const forges = createForges([
+ *   github({ auth: { type: 'token', token: process.env.GITHUB_TOKEN! } }),
+ *   gitlab(),
+ * ])
+ *
+ * const repo = await forges.repos.get({ forge: 'github', instance: 'github.com', owner: 'danielroe', name: 'forges' })
+ * ```
+ */
+declare function createForges(factories: Array<ForgeProviderFactory | ForgeProvider>): Forges;
+//#endregion
+export { SubscriptionItem as A, ReferenceOptions as B, ReleasesApi as C, SecurityAlertsApi as D, SearchApi as E, WebhookDelivery as F, CAPABILITY_TABLE as G, WebLinks as H, WebhooksApi as I, CapabilityEntry as K, createForges as L, TokenAuth as M, UsersApi as N, SourcesApi as O, VerbScopes as P, GitHubShape as R, PerKind as S, ReposApi as T, githubShapedWeb as U, UrlTarget as V, parseForgeUrl as W, Forges as _, BasicAuth as a, NotificationWriteOptions as b, CiApi as c, ContentsApi as d, ForgeCapabilities as f, ForgeProviderFactory as g, ForgeProvider as h, AuthKind as i, ThreadsApi as j, SubscribeOptions as k, CloseOptions as l, ForgeOptionsBase as m, AnonymousAuth as n, BulkNotificationOptions as o, ForgeIterable as p, ForgeVerb as q, AppAuth as r, ChecksApi as s, AlertSupport as t, CloseReason as u, InstallationsApi as v, RepoGetOptions as w, NotificationsApi as x, MilestoneListOptions as y, ParsedForgeUrl as z };