forges 0.0.0 → 0.1.0

package/dist/fetch-D4pSRvvA.d.mts

@@ -0,0 +1,1723 @@
+//#region src/model.d.ts
+/**
+ * Every public type in this module is JSON-serialisable except `Date`, which
+ * serialises to an ISO 8601 string through `JSON.stringify`, and the bytes of
+ * a binary {@link FileContent}. `raw` and `payload` fields hold the forge's
+ * own JSON.
+ */
+/**
+ * Identifier of a forge implementation. Unknown forges are permitted so that
+ * third-party providers can be registered without a core release.
+ */
+type ForgeKind = KnownForgeKind | (string & {});
+/** The forges this package ships providers for. */
+type KnownForgeKind = "github" | "gitlab" | "bitbucket" | "forgejo" | "gitea" | "tangled" | "gitee" | "azure-devops" | "cursor-origin" | "pushin";
+/**
+ * Capability flag. Every value other than `false` means the operation is
+ * available:
+ *
+ * - `true`: native, and verified against the forge's responses.
+ * - `'experimental'`: native and verified, but built on an API the forge marks
+ *   unstable, so it can change.
+ * - `'emulated'`: composed from other calls, so the result is approximate.
+ * - `'unverified'`: implemented, but not yet verified against the forge's
+ *   responses, so it may not work.
+ */
+type Support = boolean | "emulated" | "experimental" | "unverified";
+/** Host of a single forge deployment, for example `github.com` or `codeberg.org`. */
+type ForgeInstance = string;
+/** Where an object comes from: the forge and the instance of that forge. */
+interface ForgeOrigin {
+  forge: ForgeKind;
+  /** The host of the instance, such as `github.com` or `git.example.com`. */
+  instance: ForgeInstance;
+}
+/** Addresses a repository by its forge, instance, owner and name. */
+interface RepoRef extends ForgeOrigin {
+  /**
+   * Full namespace path. On forges with nested groups (GitLab) this contains
+   * slashes, for example `acme/platform`; `name` never does.
+   */
+  owner: string;
+  /** Repository name. Empty for namespace-scoped refs. */
+  name: string;
+  /**
+   * `'namespace'` for subjects that belong to a group rather than a repository
+   * (GitLab epics). Absent means a repository.
+   */
+  kind?: "repo" | "namespace";
+  /**
+   * Stable forge-native identifier that survives renames and transfers: a
+   * GitHub, Forgejo or Gitea numeric id, a GitLab project or group id, a
+   * Bitbucket UUID or a Tangled repo DID. {@link repoKey} prefers it over
+   * `owner` and `name`.
+   */
+  externalId?: string;
+}
+/** Who can see a repository. */
+type RepoVisibility = "public" | "private" | "internal";
+/** The authenticated account's access to a repository. */
+interface RepoPermissions {
+  /** Full administrative access. */
+  admin: boolean;
+  /** Manage the repository without access to sensitive or destructive settings. */
+  maintain: boolean;
+  push: boolean;
+  /** Manage issues and pull requests without write access. */
+  triage: boolean;
+  /** Read and clone the repository. */
+  pull: boolean;
+}
+/** Which subjects a repository has switched on, where the forge makes them per repository. */
+interface RepoFeatures {
+  issues: boolean;
+  pullRequests: boolean;
+  discussions: boolean;
+  wiki: boolean;
+  projects: boolean;
+  releases: boolean;
+}
+/** A collaborator's role, highest first. `'none'` is an explicit absence of access. */
+type RepoRole = "admin" | "maintain" | "write" | "triage" | "read" | "none";
+/** An account with a role on a repository. */
+interface Collaborator {
+  actor: Actor;
+  role: RepoRole;
+  /** Forge-native role name, for example `maintainer` or `reporter`. */
+  roleRaw?: string;
+  /** What the role allows. */
+  permissions?: RepoPermissions;
+  raw: unknown;
+}
+/** A repository as every forge reports it. Fields that not every forge has, such as `openPullCount`, are optional. */
+interface Repo {
+  ref: RepoRef;
+  /** The repository's name where `ref.name` is an identifier rather than the name (a Tangled record key). */
+  displayName?: string;
+  description?: string;
+  defaultBranch?: string;
+  /** Who can see the repository. */
+  visibility: RepoVisibility;
+  visibilityRaw?: string;
+  isFork: boolean;
+  /** The repository is archived and read-only. */
+  isArchived: boolean;
+  /** The repository that this one was forked from. */
+  parent?: RepoRef;
+  /** Topics, also called tags, that describe the repository. */
+  topics: string[];
+  url?: string;
+  /** Git remotes. Tangled maps the hosting knot to its SSH host. */
+  cloneUrls?: {
+    https?: string;
+    ssh?: string;
+  };
+  createdAt?: Date;
+  updatedAt?: Date;
+  /** Last push, where the listing endpoint reports it. */
+  pushedAt?: Date;
+  /**
+   * Open issues only, never combined with pull requests. Absent where the
+   * forge reports only the combined count (GitHub).
+   */
+  openIssueCount?: number;
+  /** The number of open pull requests, where the forge reports it. */
+  openPullCount?: number;
+  /** The account or organisation that owns the repository, where the forge reports one. */
+  owner?: Actor;
+  /** Primary language, as the forge detects it. */
+  language?: string;
+  /** Project website, apart from the repository's own `url`. */
+  homepage?: string;
+  /**
+   * SPDX identifier of the licence the forge detects, for example `MIT`. SPDX identifiers are case-insensitive, and
+   * GitLab reports them in lower case, such as `mit`.
+   */
+  licence?: string;
+  stars?: number;
+  forks?: number;
+  /** Accounts watching the repository's activity, apart from stars. */
+  watchers?: number;
+  /** What the authenticated account may do. */
+  permissions?: RepoPermissions;
+  /** Merge methods the repository allows, where the forge reports them. Empty means the forge reported none. */
+  mergeMethods?: MergeMethod[];
+  features?: RepoFeatures;
+  raw: unknown;
+}
+/**
+ * Kind of thread. `'other'` holds forge-specific subjects with no shared kind
+ * (check suites, epics); `ThreadRef.typeRaw` names them.
+ */
+type ThreadKind = "issue" | "pull_request" | "discussion" | "commit" | "other";
+/**
+ * Reference to a thread. A thread `number` is unique only within its repo, so
+ * the repo is always carried alongside it.
+ */
+interface ThreadRef extends ForgeOrigin {
+  repo: RepoRef;
+  kind: ThreadKind;
+  /** Forge-native subject type, for example `PullRequest` or `MergeRequest`. */
+  typeRaw?: string;
+  /**
+   * Per-repo thread number, the commit sha for `kind: 'commit'`, or the
+   * forge-native id for `kind: 'other'`. Absent when the forge did not
+   * identify the thread; such a ref cannot be fetched or keyed until enriched.
+   */
+  number?: string;
+  /**
+   * Human-facing per-repo number, when it differs from `number`. Tangled
+   * identifies threads by AT-URI but shows numbers in its UI and webhooks.
+   */
+  displayNumber?: string;
+  /**
+   * Globally unique forge-native identifier, where one exists: a GitHub
+   * `node_id`, a GitLab global id, or an atproto record URI.
+   */
+  externalId?: string;
+}
+/** A release, as a notification subject or event target. */
+interface ReleaseRef extends ForgeOrigin {
+  repo: RepoRef;
+  /** Forge-native release id; the tag name on forges that key releases by tag. */
+  id: string;
+  tag?: string;
+}
+/**
+ * Reference to a registered webhook. `target` is the repository, or a
+ * namespace ref (`kind: 'namespace'`, empty `name`) for an organisation or
+ * workspace hook.
+ */
+interface WebhookRef extends ForgeOrigin {
+  /** The repository or namespace that the hook is registered on. */
+  target: RepoRef;
+  /** Forge-native hook id. */
+  id: string;
+}
+/** Reference to one delivery of a webhook. */
+interface WebhookDeliveryRef extends ForgeOrigin {
+  hook: WebhookRef;
+  id: string;
+  /** Delivery guid, where the forge needs it to redeliver. */
+  guid?: string;
+}
+/** A normalised event a provider can deliver, optionally narrowed to one action. */
+interface WebhookEventType {
+  kind: EventKind;
+  action?: EventAction;
+}
+/** A registered webhook. The secret is never readable, so it is never returned. */
+interface Webhook {
+  ref: WebhookRef;
+  url: string;
+  /** Normalised kinds the subscription covers, derived from `nativeEvents`. */
+  events: EventKind[];
+  /** Forge-native event names exactly as the forge stores them. */
+  nativeEvents: string[];
+  active: boolean;
+  /** `'json'` or `'form'` where the forge offers a choice. */
+  contentType?: "json" | "form";
+  createdAt?: Date;
+  updatedAt?: Date;
+  /** Never returned: no forge reads a webhook secret back. */
+  secret?: never;
+  raw: unknown;
+}
+/** What `webhooks.create()` needs to register a hook. */
+interface WebhookInput {
+  url: string;
+  /** Normalised kinds, translated to the forge's own event names. */
+  events?: EventKind[];
+  /** Forge-native event names, sent as given and merged with the translation of `events`. */
+  nativeEvents?: string[];
+  /** The secret that signs the deliveries. */
+  secret?: string;
+  /** How to encode the delivery body. */
+  contentType?: "json" | "form";
+  /**
+   * @default true
+   */
+  active?: boolean;
+}
+/** A change to a registered webhook. Fields left out are left as they are. */
+type WebhookUpdate = Partial<WebhookInput>;
+/** One recorded delivery attempt. */
+interface WebhookDeliveryRecord {
+  ref: WebhookDeliveryRef;
+  /** Forge-native event name of the delivery. */
+  event: string;
+  /** The HTTP status that the receiver answered with. */
+  status: number;
+  /** `true` when the forge considered the delivery successful. */
+  ok: boolean;
+  deliveredAt?: Date;
+  /** Round trip in milliseconds, where the forge reports it. */
+  duration?: number;
+  raw: unknown;
+}
+/** What an alert is about. `other` is a kind that the model does not name. */
+type SecurityAlertKind = "dependency" | "code_scanning" | "secret" | "advisory" | "other";
+/** A security alert: a vulnerable dependency, a code scanning result, a leaked secret or an advisory. */
+interface SecurityAlertRef extends ForgeOrigin {
+  repo: RepoRef;
+  /** Forge-native alert id. GitHub numbers each alert kind separately, so `kind` is needed to address one. */
+  id: string;
+  kind?: SecurityAlertKind;
+  severityRaw?: string;
+}
+/** One check run, commit status or CI job. */
+interface CheckRef extends ForgeOrigin {
+  repo: RepoRef;
+  id: string;
+  /** What the id addresses: a check run, a commit status, a CI job, or a branch policy evaluation. */
+  type: "check_run" | "status" | "job" | "policy";
+}
+/**
+ * Reference to a notification. Distinct from {@link ThreadRef}: a notification
+ * is a per-user delivery record whose lifetime and identity are independent of
+ * the thread it points at.
+ */
+interface NotificationRef extends ForgeOrigin {
+  /** Forge-native notification identifier, used for read/done/unsubscribe writes. */
+  id: string;
+}
+/** An account: a user, an organisation or a bot. */
+interface Actor extends ForgeOrigin {
+  login: string;
+  id: string;
+  name?: string;
+  avatarUrl?: string;
+  url?: string;
+  /** Forge-reported account type, retained verbatim for callers that classify further. */
+  typeRaw?: string;
+  /**
+   * Hint derived from forge metadata that the actor is automation. Callers own
+   * the classification policy.
+   */
+  isBotHint: boolean;
+  /** The app behind a bot account, where the forge ties one to it (GitHub Apps' `slug[bot]` users). */
+  app?: {
+    slug: string;
+    id?: string;
+  };
+}
+/** A user or organisation account, as `users.get()` reads it. */
+interface User extends Actor {
+  bio?: string;
+  company?: string;
+  location?: string;
+  websiteUrl?: string;
+  createdAt?: Date;
+  followers?: number;
+  following?: number;
+  publicRepos?: number;
+  raw: unknown;
+}
+/** A label that a repository defines. */
+interface Label {
+  name: string;
+  /** The colour as hex digits, without a leading `#`. */
+  colour?: string;
+  description?: string;
+}
+/** What a label is created or updated with. */
+interface LabelInput {
+  name: string;
+  /** Six-digit hex, without the leading `#`. */
+  colour?: string;
+  description?: string;
+}
+/** Every name {@link ReactionContent} covers. */
+declare const REACTION_CONTENTS: readonly ["+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes"];
+/**
+ * The reactions every forge with reactions has in common, named as GitHub
+ * names them. A {@link Reaction} whose forge-native name has no entry here
+ * has `content: 'other'`, with the forge-native name in `contentRaw`.
+ */
+type ReactionContent = (typeof REACTION_CONTENTS)[number];
+/** The normalised name for a forge-native reaction name, or `'other'` where there is none. */
+declare function reactionContent(raw: string): ReactionContent | "other";
+/** One reaction left on a thread or a comment, as `threads.reactions()` lists them. */
+interface Reaction {
+  /** `'other'` where the forge's name has no entry in {@link ReactionContent}. */
+  content: ReactionContent | "other";
+  /** The forge's own name for the reaction, such as a GitLab award emoji or a Forgejo emoji. */
+  contentRaw: string;
+  actor: Actor;
+  createdAt?: Date;
+  raw: unknown;
+}
+/** The reactions on a thread or comment, counted. */
+interface ReactionSummary {
+  /** The number of reactions of every kind. */
+  total: number;
+  /** The number of reactions of each kind. A reaction with no {@link ReactionContent} entry has no key here. */
+  counts: Partial<Record<ReactionContent, number>>;
+  /** Reactions the authenticated account has left. Absent when the forge does not report them. */
+  viewerReacted?: ReactionContent[];
+}
+/** A milestone that groups threads. */
+interface Milestone {
+  /** Forge-native milestone id, as `threads.setMilestone` takes it. */
+  id: string;
+  title: string;
+  state: "open" | "closed";
+  description?: string;
+  dueOn?: Date;
+  url?: string;
+  raw: unknown;
+}
+/**
+ * Thread state. `'unknown'` is distinct from any real state and signals that
+ * the value was not present in the payload, so the caller may enrich it with
+ * `threads.get()`. Draft status is orthogonal; see `Thread.isDraft`.
+ */
+type ThreadState = "open" | "closed" | "merged" | "unknown";
+/** What a review or a reviewer says about a pull request. `unknown` is a state that the model does not name. */
+type ReviewState = "approved" | "changes_requested" | "commented" | "pending" | "dismissed" | "unknown";
+/** Reference to a review on a pull request. */
+interface ReviewRef extends ForgeOrigin {
+  thread: ThreadRef;
+  /** Forge-native review id; a synthesised `approval:<login>` where the forge has approvals but no review objects. */
+  id: string;
+}
+/** A comment left on a line of the diff as part of a review. */
+interface ReviewComment {
+  ref?: CommentRef;
+  body: string;
+  author?: Actor;
+  path?: string;
+  /** Line in the file the comment is anchored to, in the side it is anchored to. */
+  line?: number;
+  /** `'left'` is the base of the diff, `'right'` the head. */
+  side?: "left" | "right";
+  /** Forge-native id of the comment this one replies to. */
+  inReplyTo?: string;
+  /** The resolvable conversation the comment belongs to, where the forge has one. */
+  thread?: {
+    id: string;
+    resolved: boolean;
+  };
+  createdAt?: Date;
+  url?: string;
+  raw: unknown;
+}
+/** A review of a pull request. */
+interface Review {
+  ref: ReviewRef;
+  author?: Actor;
+  state: ReviewState;
+  stateRaw?: string;
+  body?: string;
+  submittedAt?: Date;
+  /**
+   * Inline comments submitted with the review. `false` where the forge has
+   * approvals but no review objects to hang comments on.
+   */
+  comments: ReviewComment[] | false;
+  url?: string;
+  raw: unknown;
+}
+/** What a review does when it is submitted. Omitted creates a pending review where the forge has them. */
+type ReviewEvent = "approve" | "request_changes" | "comment";
+/** An inline comment to send with a review. */
+interface ReviewCommentInput {
+  path: string;
+  /** Line in the diff, in `side`. */
+  line?: number;
+  side?: "left" | "right";
+  /** First line of a multi-line comment. */
+  startLine?: number;
+  body: string;
+}
+/** What `threads.createReview()` needs. */
+interface ReviewInput {
+  /** Omitted creates a pending review, where the forge has them; submit it with `submitReview`. */
+  event?: ReviewEvent;
+  body?: string;
+  /** Inline comments to send with the review. */
+  comments?: ReviewCommentInput[];
+}
+/** A reviewer who was asked to review a pull request, and what they said. */
+interface Reviewer {
+  actor: Actor;
+  state: ReviewState;
+  stateRaw?: string;
+  /** True when the reviewer is a team rather than an account. */
+  isTeam?: boolean;
+}
+/** The branches of a pull request. */
+interface PullBranches {
+  /** `sha` is absent on forges where a pull is a patch rather than a branch (Tangled). */
+  head: {
+    ref: string;
+    sha?: string;
+    /** The repository that holds the head branch, which differs for a fork. */
+    repo?: RepoRef;
+  };
+  base: {
+    ref: string;
+    sha?: string;
+  };
+  /** The merge commit, once the pull request is merged. */
+  mergeCommitSha?: string;
+}
+/** Where a pull request sits in a stack of pull requests. */
+interface ThreadStack {
+  /** Forge-native stack id, where the forge names stacks. */
+  id?: string;
+  /** The pull request this one is stacked on. Absent for the root of the stack. */
+  parent?: ThreadRef;
+}
+/**
+ * Combined state of the checks on a pull request's head commit. `failure`
+ * when any check failed, else `pending` while any runs, else `success`.
+ */
+interface ChecksSummary {
+  state: "pending" | "success" | "failure" | "unknown";
+  stateRaw?: string;
+  /** Absent when the forge reports only a combined state. */
+  total?: number;
+  failed?: number;
+  url?: string;
+}
+/** `neutral` covers skipped and informational results, which neither pass nor fail. */
+type CheckState = "pending" | "success" | "failure" | "neutral" | "unknown";
+/** One check on a commit: a check run, a commit status, a job or a policy evaluation. */
+interface Check {
+  ref: CheckRef;
+  name: string;
+  state: CheckState;
+  /** Forge-native status, for example `in_progress` or `running`. */
+  stateRaw: string;
+  /** Forge-native conclusion, where the forge reports one apart from the status. */
+  conclusionRaw?: string;
+  url?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+  raw: unknown;
+}
+/** What `checks.report` writes: a commit status everywhere, a check run on GitHub under app auth. */
+interface CheckReportInput {
+  /** Status context or check run name. */
+  name: string;
+  state: Exclude<CheckState, "unknown">;
+  /** A short description of the state. */
+  description?: string;
+  /** Where a person goes to see the detail. */
+  url?: string;
+  /** The caller's own id for the check, where the forge stores one. */
+  externalId?: string;
+}
+/** A CI run: a workflow run, a pipeline, or a build. */
+interface CiRunRef extends ForgeOrigin {
+  repo: RepoRef;
+  id: string;
+}
+/** One job inside a run. `run` is absent when the job was addressed on its own. */
+interface CiJobRef extends ForgeOrigin {
+  repo: RepoRef;
+  id: string;
+  run?: CiRunRef;
+}
+/** A CI run, such as a workflow run or a pipeline. */
+interface CiRun {
+  ref: CiRunRef;
+  name: string;
+  state: CheckState;
+  stateRaw: string;
+  /** Per-repo run number, where the forge has one. */
+  number?: string;
+  /** What triggered the run, as the forge names it. */
+  eventRaw?: string;
+  branch?: string;
+  /** The commit that the run ran on. */
+  sha?: string;
+  url?: string;
+  actor?: Actor;
+  createdAt?: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  raw: unknown;
+}
+/** One job of a CI run. */
+interface CiJob {
+  ref: CiJobRef;
+  name: string;
+  state: CheckState;
+  stateRaw: string;
+  /** Stage or group the job belongs to, where the forge has one. */
+  stage?: string;
+  url?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+  raw: unknown;
+}
+/** Filters for `ci.runs()`. */
+interface CiRunQuery extends PageOptions {
+  branch?: string;
+  /** Normalised state; forges that filter on their own names translate it. */
+  state?: Exclude<CheckState, "unknown">;
+}
+/** A commit addressed by its full sha. */
+interface CommitRef extends ForgeOrigin {
+  repo: RepoRef;
+  /** The full sha of the commit. */
+  sha: string;
+}
+/** `'binary'` carries bytes; `'utf-8'` carries text the forge reported as text. */
+type FileEncoding = "utf-8" | "binary";
+/** What a forge reports about a file, apart from its content. */
+interface FileMetadata {
+  /** The path from the repository root. */
+  path: string;
+  /** Blob sha, where the forge reports one. */
+  sha?: string;
+  size?: number;
+  /** Web page for the file at this ref, where the forge has one. */
+  url?: string;
+}
+/** A file's contents. Narrow on `encoding` to get text or bytes. */
+type FileContent = FileMetadata & {
+  encoding: "utf-8";
+  content: string;
+} | FileMetadata & {
+  encoding: "binary";
+  content: Uint8Array;
+};
+/** Options for `contents.file()`. */
+interface FileOptions extends BaseOptions {
+  /** Branch, tag or sha. Defaults to the repository's default branch. */
+  ref?: string;
+  /**
+   * `'text'` decodes as UTF-8 and rejects with {@link ContentNotTextError} when the bytes are not text.
+   * @default 'binary'
+   */
+  as?: "text" | "binary";
+}
+/** What a tree entry is. */
+type TreeEntryType = "file" | "directory" | "symlink" | "submodule";
+/** One entry of a repository tree. */
+interface TreeEntry {
+  /** Path from the repository root, without a leading slash. */
+  path: string;
+  type: TreeEntryType;
+  sha?: string;
+  /** The size in bytes, for a file. */
+  size?: number;
+  /** POSIX mode as the forge reports it, for example `100644`. */
+  mode?: string;
+  url?: string;
+}
+/** Options for `contents.tree()`. */
+interface TreeOptions extends PageOptions {
+  /** Branch, tag or sha. Defaults to the repository's default branch. */
+  ref?: string;
+  /** Subdirectory to list; the root when omitted. */
+  path?: string;
+  /** Every descendant rather than one level. Unsupported on some forges, which then warn. */
+  recursive?: boolean;
+}
+/** A branch of a repository. */
+interface Branch {
+  name: string;
+  /** The commit that the branch points at. */
+  sha: string;
+  isDefault?: boolean;
+  isProtected?: boolean;
+  url?: string;
+  raw: unknown;
+}
+/** A tag of a repository. */
+interface Tag {
+  name: string;
+  /** Commit the tag points at, after dereferencing an annotated tag where the forge does so. */
+  sha: string;
+  url?: string;
+  raw: unknown;
+}
+/** Git authorship, with the forge account behind it where the forge matched one. */
+interface CommitSignature {
+  /** The account, where the forge can match it. */
+  actor?: Actor;
+  name?: string;
+  email?: string;
+  /** When the commit was authored or committed. */
+  date?: Date;
+}
+/** How a commit or pull request changed a file. */
+type FileStatus = "added" | "modified" | "removed" | "renamed" | "copied" | "changed";
+/** A file that a commit or pull request changed. */
+interface ChangedFile {
+  path: string;
+  /** Path before a rename or copy. */
+  previousPath?: string;
+  status: FileStatus;
+  statusRaw?: string;
+  additions?: number;
+  deletions?: number;
+  /** Unified diff for the file, where the forge returns one inline. */
+  patch?: string;
+  /** Blob sha after the change. */
+  sha?: string;
+  /** The file is binary, so it has no patch. */
+  isBinary?: boolean;
+}
+/** A commit. */
+interface Commit {
+  ref: CommitRef;
+  /** The full sha. */
+  sha: string;
+  message: string;
+  /** Who wrote the change. */
+  author?: CommitSignature;
+  /** Who recorded the change. */
+  committer?: CommitSignature;
+  parents: string[];
+  url?: string;
+  stats?: {
+    additions: number;
+    deletions: number;
+    total?: number;
+  };
+  /** Present on `contents.commit`; absent from listings. */
+  files?: ChangedFile[];
+  raw: unknown;
+}
+/** Filters for `contents.commits()`. */
+interface CommitQuery extends PageOptions {
+  /** Branch, tag or sha to walk back from. */
+  ref?: string;
+  /** Only commits at or after this time. */
+  since?: Date;
+  /** Only commits at or before this time. */
+  until?: Date;
+  /** Only commits touching this path. */
+  path?: string;
+  /** Login or email, as the forge matches it. */
+  author?: string;
+}
+/** The difference between two revisions. */
+interface Comparison {
+  /** The revision that the comparison starts from. */
+  base: string;
+  /** The revision that the comparison ends at. */
+  head: string;
+  /** The number of commits that `head` has and `base` lacks. */
+  aheadBy?: number;
+  /** The number of commits that `base` has and `head` lacks. */
+  behindBy?: number;
+  /** The commits between the two revisions. */
+  commits: Commit[];
+  files: ChangedFile[];
+  /** The merge base, where the forge reports it. */
+  mergeBaseSha?: string;
+  raw: unknown;
+}
+/** A file that a code search found. A file whose excerpts span two pages comes back on both. */
+interface CodeMatch {
+  repo: RepoRef;
+  path: string;
+  /** The branch, tag or sha the forge searched, where it reports one. */
+  ref?: string;
+  /** The excerpts of the file that matched. */
+  fragments: CodeFragment[];
+  url?: string;
+  raw: unknown;
+}
+/** An excerpt of a file that matched a code search. */
+interface CodeFragment {
+  text: string;
+  /** The line the excerpt starts on, where the forge reports it. */
+  line?: number;
+}
+/** A release asset, addressable for download with `releases.downloadAsset`. */
+interface ReleaseAssetRef extends ForgeOrigin {
+  repo: RepoRef;
+  release: ReleaseRef;
+  /** Forge-native asset id; the asset name, or the link id, on forges that have no asset id. */
+  id: string;
+}
+/** A file attached to a release. */
+interface ReleaseAsset {
+  /** Absent where the forge publishes a download URL but nothing to address the asset by. */
+  ref?: ReleaseAssetRef;
+  name: string;
+  url: string;
+  size?: number;
+  downloadCount?: number;
+  /** The media type. */
+  contentType?: string;
+}
+/** A release of a repository. */
+interface Release {
+  ref: ReleaseRef;
+  name?: string;
+  tag: string;
+  /** The release notes. */
+  body?: string;
+  isDraft: boolean;
+  isPrerelease: boolean;
+  /**
+   * The release is immutable: its tag and assets are locked. `true` where the
+   * forge supports immutable releases and this one is published as immutable
+   * (GitHub). The name, notes, prerelease and latest flags stay editable.
+   */
+  immutable?: boolean;
+  author?: Actor;
+  publishedAt?: Date;
+  createdAt?: Date;
+  url?: string;
+  assets?: ReleaseAsset[];
+  raw: unknown;
+}
+/** The fields that `releases.create()` sets. */
+interface ReleaseInput {
+  /** The tag to release. The forge creates it from `target` when it does not exist yet. */
+  tag: string;
+  name?: string;
+  /** The release notes. */
+  body?: string;
+  /** Saves the release unpublished. `true` rejects with `UnsupportedOperationError` on a forge without drafts. */
+  draft?: boolean;
+  /** Marks the release as a prerelease. `true` rejects with `UnsupportedOperationError` on a forge without prereleases. */
+  prerelease?: boolean;
+  /**
+   * The branch or commit sha to create the tag from when it does not exist yet. GitHub, Forgejo and Gitea
+   * default to the default branch; GitLab requires it for a new tag.
+   */
+  target?: string;
+}
+/** The fields that `releases.update()` changes. Fields left out stay as they are. */
+type ReleaseUpdate = Partial<ReleaseInput>;
+/** How severe an alert is. `unknown` is a level that the model does not name. */
+type SecuritySeverity = "critical" | "high" | "medium" | "low" | "unknown";
+/** A security alert on a repository. */
+interface SecurityAlert {
+  ref: SecurityAlertRef;
+  kind: SecurityAlertKind;
+  kindRaw: string;
+  severity: SecuritySeverity;
+  severityRaw?: string;
+  state: "open" | "fixed" | "dismissed" | "unknown";
+  stateRaw: string;
+  /** A short description of the problem. */
+  title: string;
+  /** `ecosystem` is absent where the forge reports only the package name. */
+  package?: {
+    ecosystem?: string;
+    name: string;
+    vulnerableRange?: string;
+    fixedIn?: string;
+  };
+  url?: string;
+  createdAt?: Date;
+  updatedAt?: Date;
+  dismissedAt?: Date;
+  raw: unknown;
+}
+/** Filters for `securityAlerts.list()`. */
+interface SecurityAlertListOptions extends PageOptions {
+  /** Omitted lists every kind the provider can read, one after another. */
+  kind?: Exclude<SecurityAlertKind, "other">;
+  /**
+   * `'closed'` is fixed or dismissed.
+   * @default 'open'
+   */
+  state?: "open" | "closed" | "all";
+}
+/** The warning codes providers emit; providers may add codes in a minor release. */
+type ForgeWarningCode = "checks_unreadable" | "collaborators_unreachable" | "discussion_unresolved" | "filter_unsupported" | "index_possibly_stale" | "insufficient_scope" | "kind_unsupported" | "notifications_failed" | "record_unreachable" | "recursive_unsupported" | "search_failed" | "search_incomplete" | "sort_unsupported" | "state_record_unreachable" | "thread_unreadable" | "thread_unresolved" | "tree_truncated" | (string & {});
+/** A non-fatal problem encountered while producing a result. */
+interface ForgeWarning {
+  /** Stable machine-readable code. */
+  code: ForgeWarningCode;
+  /** A description of the problem, for a person. */
+  message: string;
+  /** Key or URI of the item the warning concerns, when it concerns one. */
+  subject?: string;
+  cause?: {
+    name: string;
+    message: string;
+    status?: number;
+  };
+}
+/** An issue, pull request, discussion or commit conversation. */
+interface Thread {
+  ref: ThreadRef;
+  kind: ThreadKind;
+  title: string;
+  body?: string;
+  state: ThreadState;
+  /** Forge-native state string the normalised `state` was derived from. */
+  stateRaw?: string;
+  /** Forge-native state qualifier, for example `completed` or `not_planned`. */
+  stateReason?: string;
+  isDraft: boolean;
+  author?: Actor;
+  assignees: Actor[];
+  /**
+   * Reviewers the thread read reports. Some forges report outstanding requests
+   * only, others each reviewer's verdict; `threads.reviews()` has every
+   * submitted review.
+   */
+  reviewers: Reviewer[];
+  labels: Label[];
+  url?: string;
+  createdAt?: Date;
+  updatedAt?: Date;
+  closedAt?: Date;
+  /** Latest activity the forge reports for the thread. */
+  lastActivityAt?: Date;
+  locked?: boolean;
+  commentCount?: number;
+  /** Everyone who authored or commented on the thread, where the forge reports them. */
+  participants?: Actor[];
+  /** Whether the authenticated account has read the thread, where the forge tracks it per thread. */
+  readState?: "read" | "unread";
+  /** The authenticated account's subscription, where the thread read already carries it. */
+  subscription?: SubscriptionState;
+  milestone?: Milestone;
+  reactions?: ReactionSummary;
+  /** Pull requests only. */
+  branches?: PullBranches;
+  /** Pull requests only. */
+  checks?: ChecksSummary;
+  /** Pull requests in a stack: a chain of dependent pull requests, each based on the one before. */
+  stack?: ThreadStack;
+  /** Non-fatal problems hit while reading the thread, for example an unreachable record. */
+  warnings?: ForgeWarning[];
+  /** Unnormalised forge payload, retained for fidelity. */
+  raw: unknown;
+}
+/** Reference to a comment on a thread. */
+interface CommentRef extends ForgeOrigin {
+  thread: ThreadRef;
+  /** Forge-native comment id; an AT-URI on Tangled. */
+  id: string;
+}
+/** A comment on a thread. */
+interface Comment {
+  ref: CommentRef;
+  body: string;
+  author?: Actor;
+  createdAt?: Date;
+  updatedAt?: Date;
+  url?: string;
+  reactions?: ReactionSummary;
+  /** The resolvable conversation the comment belongs to, where the forge has one; `resolveReviewThread()` takes its id. */
+  thread?: {
+    id: string;
+    resolved: boolean;
+  };
+  raw: unknown;
+}
+/** Whether the account gets notifications for a thread. */
+type SubscriptionState = "subscribed" | "ignored" | "none";
+/** What an event is about. */
+type EventKind = "comment" | "review" | "review_comment" | "commit" | "label" | "state_change" | "assignment" | "mention" | "referenced" | "reaction" | "push" | "ref" | "repo" | "installation" | "membership" | "release" | "other";
+/** A commit as a push delivery reports it. */
+interface PushCommit {
+  sha: string;
+  message?: string;
+  author?: string;
+  url?: string;
+}
+/**
+ * What happened, independent of `kind`, so "anything that closed" is
+ * `action === 'closed'` whatever the subject.
+ */
+type EventAction = "opened" | "closed" | "reopened" | "merged" | "edited" | "created" | "deleted" | "submitted" | "labelled" | "unlabelled" | "assigned" | "unassigned" | "review_requested" | "synchronised" | "ready_for_review" | "converted_to_draft" | "published" | "renamed" | "transferred" | "archived" | "unarchived" | "added" | "removed" | "other";
+/** Typed detail for an event. Discriminated by `type`. */
+type EventDetail = {
+  type: "comment";
+  comment?: CommentRef;
+  body?: string;
+} | {
+  type: "review_comment";
+  comment?: CommentRef;
+  body?: string;
+  path?: string;
+  line?: number;
+} | {
+  type: "review";
+  state: ReviewState;
+  stateRaw?: string;
+  body?: string;
+} | {
+  type: "state_change";
+  state?: ThreadState;
+  draft?: boolean;
+} | {
+  type: "label";
+  label: string;
+} | {
+  type: "assignment";
+  assignee?: Actor;
+} | {
+  type: "push";
+  ref: string;
+  before?: string;
+  after?: string;
+  commitCount: number;
+  forced: boolean;
+  commits: PushCommit[];
+} | {
+  type: "ref";
+  ref: string;
+  refType: "branch" | "tag" | (string & {});
+} | {
+  type: "repo_renamed";
+  from: string;
+  to: string;
+} | {
+  type: "repo_transferred";
+  fromOwner?: string;
+  toOwner?: string;
+} | {
+  type: "repo_archived";
+  archived: boolean;
+} | {
+  type: "installation";
+  actionRaw: string;
+  installationId?: string;
+  added: RepoRef[];
+  removed: RepoRef[];
+} | {
+  type: "membership";
+  actionRaw: string;
+  member?: Actor;
+} | {
+  type: "release";
+  release: ReleaseRef;
+  name?: string;
+} | {
+  type: "referenced";
+  from?: ThreadRef | CommitRef;
+  fromRepo?: RepoRef;
+  text?: string;
+};
+/** An event on a forge, such as a comment, a state change or a push. */
+interface ForgeEvent extends ForgeOrigin {
+  id: string;
+  kind: EventKind;
+  /** Forge-native event name the normalised `kind` was derived from. */
+  kindRaw?: string;
+  /** Normalised verb; `other` when the forge's wording has no equivalent. */
+  action: EventAction;
+  /** Forge-native verb `action` was derived from. */
+  actionRaw?: string;
+  /** Single line describing the event, suitable for a list row. */
+  summary: string;
+  occurredAt: Date;
+  actor?: Actor;
+  repo?: RepoRef;
+  thread?: ThreadRef;
+  /** The details that belong to the kind of event. */
+  detail?: EventDetail;
+  /** App installation the delivery belongs to, for app webhooks. */
+  installationId?: string;
+  /** Delivery mechanism the event arrived through. */
+  source: SourceKind;
+  /** Unnormalised forge payload, retained for fidelity. */
+  payload: unknown;
+}
+/** A {@link ForgeEvent} as a provider builds it; core derives `action` when it is absent. */
+type ForgeEventInput = Omit<ForgeEvent, "action"> & {
+  action?: EventAction;
+};
+/** How an event reached the caller. */
+type SourceKind = "poll" | "webhook" | "subscribe";
+/**
+ * Why a notification was delivered. `'unknown'` covers forges that report no
+ * reason and native reasons with no normalised equivalent; `reasonRaw` keeps
+ * the original.
+ */
+type NotificationReason = "access_requested" | "approval_requested" | "assigned" | "author" | "ci_activity" | "comment" | "followed" | "invitation" | "manual" | "mention" | "merge_blocked" | "review_requested" | "review_submitted" | "security_alert" | "starred" | "state_change" | "subscribed" | "team_mention" | "unknown";
+/** What a notification is about. Not every notification concerns a thread. */
+type NotificationSubject = {
+  type: "thread";
+  thread: ThreadRef;
+} | {
+  type: "repo";
+  repo: RepoRef;
+} | {
+  type: "actor";
+  actor: Actor;
+} | {
+  type: "release";
+  release: ReleaseRef;
+} | {
+  type: "security_alert";
+  alert: SecurityAlertRef;
+} | {
+  type: "other";
+  typeRaw: string;
+  repo?: RepoRef;
+  id?: string;
+  url?: string;
+};
+/** A notification of the authenticated account. */
+interface Notification {
+  ref: NotificationRef;
+  subject: NotificationSubject;
+  /** Why the account got the notification. */
+  reason: NotificationReason;
+  /** Forge-native reason string. Absent when the forge reports no reason at all. */
+  reasonRaw?: string;
+  /** Forge-native subject type, for example `PullRequest`, `Release` or `followed`. */
+  subjectTypeRaw?: string;
+  unread: boolean;
+  title: string;
+  /** State of a thread subject as reported by the notification payload. */
+  subjectState: ThreadState;
+  subjectStateRaw?: string;
+  updatedAt: Date;
+  lastReadAt?: Date;
+  url?: string;
+  /** Unnormalised forge payload, retained for fidelity. */
+  raw: unknown;
+}
+/**
+ * Opaque-ish resumption token. Fields are optional because forges differ in
+ * what they support; callers should persist the whole object and hand it back.
+ */
+interface Cursor {
+  /** Absolute URL of the next page, from a `Link` header or the body, on the requested origin. */
+  nextUrl?: string;
+  /** A validator for a conditional request. */
+  etag?: string;
+  /** Opaque forge-native cursor, for example a GraphQL `endCursor`. */
+  token?: string;
+}
+/** Request budget the forge reported on the response, where it reports one. */
+interface RateLimit {
+  /** The size of the request budget. */
+  limit?: number;
+  /** The number of requests left in the budget. */
+  remaining?: number;
+  /** When `remaining` resets. */
+  resetAt?: Date;
+}
+/**
+ * One page of a listing: its `items`, and the `cursor` to pass back for the next page. The cursor is absent on the
+ * last page.
+ */
+interface Page<T> {
+  items: T[];
+  /** From the response headers of the request behind this page. */
+  rateLimit?: RateLimit;
+  /** Absent when the listing is exhausted. */
+  cursor?: Cursor;
+  /**
+   * Validator of the first page, where the forge supports conditional
+   * requests. Pass it back as `cursor: { etag }` to read the first page again.
+   */
+  etag?: string;
+  /** True when the forge reported no change since `cursor.etag`. */
+  notModified?: boolean;
+  /** The non-fatal problems that came up while reading the page. */
+  warnings?: ForgeWarning[];
+}
+/** Options for listings that can start from a point in time: events, comments, reactions. */
+interface ListOptions extends PageOptions {
+  /** Only items updated at or after this time. */
+  since?: Date;
+}
+/** Options for `notifications.list()`. */
+interface NotificationListOptions extends ListOptions {
+  /**
+   * Include notifications already marked read.
+   * @default false
+   */
+  all?: boolean;
+}
+/** Filters for `threads.list()`. */
+interface ThreadQuery extends PageOptions {
+  /** Omitted lists every listable kind; forges that list kinds separately emit them one after another. */
+  kind?: "issue" | "pull_request" | "discussion";
+  /**
+   * `'closed'` includes merged pull requests; `'merged'` lists pull requests only,
+   * and lists nothing for another `kind`.
+   * @default 'open'
+   */
+  state?: "open" | "closed" | "merged" | "all";
+  /** Threads carrying every one of these labels. */
+  labels?: string[];
+  /** Author login. */
+  author?: string;
+  /** Assignee login. */
+  assignee?: string;
+  /** Threads the login authored, is assigned, commented on or was mentioned in. */
+  involves?: string;
+  /** Threads the login was mentioned in. */
+  mentions?: string;
+  /** Milestone title, or `'none'` for threads with no milestone. */
+  milestone?: string;
+  /** Updated at or after. */
+  since?: Date;
+  /** Created at or after. */
+  createdAfter?: Date;
+  /**
+   * Unsupported orders produce a warning and the forge's own order.
+   * @default 'created'
+   */
+  sort?: "created" | "updated" | "comments";
+  /**
+   * @default 'desc'
+   */
+  direction?: "asc" | "desc";
+}
+/**
+ * A structured search. Providers translate it into their own syntax; a
+ * field the forge cannot filter on becomes a `filter_unsupported` warning
+ * on the page rather than a filter applied client-side.
+ */
+interface SearchQuery extends PageOptions {
+  /** Free text, matched against title and body. */
+  text?: string;
+  /**
+   * Forge-native query syntax, added to the query as is, for qualifiers the
+   * other fields don't cover. Forges whose search has no query syntax ignore
+   * it with a `filter_unsupported` warning.
+   */
+  queryRaw?: string;
+  /** Limit to one repository. */
+  repo?: RepoRef;
+  kind?: "issue" | "pull_request";
+  /** Defaults to every state. */
+  state?: "open" | "closed" | "all";
+  author?: string;
+  /** Threads the login authored, is assigned, commented on or was mentioned in. */
+  involves?: string;
+  assignee?: string;
+  /** Threads carrying every one of these labels. */
+  labels?: string[];
+  /** Updated at or after. */
+  since?: Date;
+  /** Defaults to the forge's relevance order. */
+  sort?: "created" | "updated" | "comments" | "relevance";
+  /**
+   * @default 'desc'
+   */
+  direction?: "asc" | "desc";
+}
+/** A search for commits. */
+interface CommitSearchQuery extends PageOptions {
+  /** Free text, matched against the commit message. */
+  text?: string;
+  /** Forge-native query syntax; see {@link SearchQuery.queryRaw}. */
+  queryRaw?: string;
+  /** Limit to one repository. */
+  repo?: RepoRef;
+  /** Commits whose author is this login. */
+  author?: string;
+  /** Commits whose committer is this login. */
+  committer?: string;
+  /** Authored or committed at or after. */
+  since?: Date;
+  /** Authored or committed at or before. */
+  until?: Date;
+  /** Defaults to the forge's relevance order. */
+  sort?: "author_date" | "committer_date";
+  /**
+   * @default 'desc'
+   */
+  direction?: "asc" | "desc";
+}
+/** A search for repositories. */
+interface RepoSearchQuery extends PageOptions {
+  text?: string;
+  /** Forge-native query syntax; see {@link SearchQuery.queryRaw}. */
+  queryRaw?: string;
+  /** Limit to one account or namespace. */
+  owner?: string;
+  /** The main language of the repository. */
+  language?: string;
+  /** Defaults to the forge's relevance order. */
+  sort?: "created" | "updated" | "stars" | "relevance";
+  /**
+   * @default desc
+   */
+  direction?: "asc" | "desc";
+}
+/** A search for code. */
+interface CodeSearchQuery extends PageOptions {
+  /** Free text, matched against the contents of files. */
+  text?: string;
+  /** Forge-native query syntax; see {@link SearchQuery.queryRaw}. */
+  queryRaw?: string;
+  /** Limit to one repository. */
+  repo?: RepoRef;
+  /** Limit to one account or namespace. */
+  owner?: string;
+}
+/** Options accepted by every operation that sends requests; the other options types extend it. */
+interface BaseOptions {
+  /**
+   * Aborts the operation's requests, and the operation rejects with the signal's reason.
+   * Writes the forge has already received are not undone.
+   */
+  signal?: AbortSignal;
+}
+/** Options for listings that take no filters: releases, installations, labels. */
+interface PageOptions extends BaseOptions {
+  /** How many items to ask for. The forge may return fewer. */
+  perPage?: number;
+  /** Resume after the page that returned this cursor. */
+  cursor?: Cursor;
+}
+/** How the account is attached to the repositories it lists. */
+type RepoAffiliation = "owner" | "collaborator" | "organisation_member";
+/** Filters for `repos.list()`. */
+interface RepoQuery extends PageOptions {
+  /** Defaults to every affiliation the forge lists. Unsupported values produce a `filter_unsupported` warning. */
+  affiliation?: RepoAffiliation[];
+  /** Only repositories with this visibility. */
+  visibility?: RepoVisibility | "all";
+  /** Defaults to the forge's own order. Unsupported orders produce a `sort_unsupported` warning. */
+  sort?: "created" | "updated" | "pushed" | "name";
+  /** Defaults to the forge's own direction. */
+  direction?: "asc" | "desc";
+}
+/** What `threads.upsertComment()` needs. */
+interface UpsertCommentInput {
+  /**
+   * Identifies the comment to replace across runs. It is written into the
+   * body as an HTML comment, so it is invisible when rendered but matchable
+   * on the next run.
+   */
+  key: string;
+  body: string;
+}
+/** What `threads.upsertComment()` did. */
+interface UpsertCommentResult {
+  /** The comment that was created or edited. */
+  comment: Comment;
+  /** `false` when an existing comment with the same key was edited. */
+  created: boolean;
+}
+/** What `threads.create()` needs. */
+interface ThreadCreateInput {
+  kind: "issue" | "pull_request" | "discussion";
+  title: string;
+  body?: string;
+  /** Names of the labels to add. */
+  labels?: string[];
+  /** Logins, or actors where the forge needs ids. */
+  assignees?: Array<string | Actor>;
+  /** Pull requests: source branch, optionally `owner:branch` for forks. */
+  head?: string;
+  /** Pull requests: target branch. */
+  base?: string;
+  /** Open the pull request as a draft. */
+  draft?: boolean;
+  /** Discussions: category name or id. */
+  category?: string;
+}
+/** The fields that `threads.update()` changes. Fields left out stay as they are. */
+interface ThreadUpdateInput {
+  title?: string;
+  body?: string;
+}
+/** One `threads.getMany()` entry, in input order; narrow on `ok`. */
+type GetManyResult = {
+  ok: true;
+  ref: ThreadRef;
+  thread: Thread;
+} | {
+  ok: false;
+  ref: ThreadRef;
+  warning: ForgeWarning;
+};
+/**
+ * The hidden marker `threads.upsertComment()` writes into a comment body to
+ * find it again. It renders as nothing on every forge that renders Markdown
+ * as HTML.
+ */
+declare function commentMarker(key: string): string;
+/** Whether `body` carries the marker for `key`. */
+declare function hasCommentMarker(body: string, key: string): boolean;
+/** A short-lived token that acts as one app installation. */
+interface InstallationToken {
+  token: string;
+  expiresAt: Date;
+  permissions: Record<string, string>;
+  /** Whether the token reaches all repositories or only selected ones. */
+  repositorySelection?: string;
+}
+/** Maximum lengths the forge accepts, in characters. */
+interface TextLimits {
+  bodyLength?: number;
+  commentLength?: number;
+  labelLength?: number;
+}
+/** Whether `forge` treats owner and repository names case-insensitively. Unknown forges are assumed not to. */
+declare function namesAreCaseInsensitive(forge: ForgeKind): boolean;
+/** `repo` with `owner` and `name` lowercased where the forge ignores case, so equal repositories compare equal. */
+declare function normaliseRepoName(repo: RepoRef): RepoRef;
+/** Whether `ref` addresses an organisation, group or workspace rather than a repository. */
+declare function isNamespaceRef(ref: RepoRef): boolean;
+/**
+ * Stable identity key for a repository: by `externalId` when known, so renames
+ * and transfers keep the key, otherwise by path, lowercased on forges that
+ * ignore case. A hand-built ref without `externalId` therefore keys
+ * differently from the same repo as a provider returns it.
+ */
+declare function repoKey(repo: RepoRef): string;
+/**
+ * Reads a {@link repoKey} back. Keys built from an `externalId` carry no path,
+ * so `owner` and `name` are empty on those.
+ */
+declare function parseRepoKey(key: string): RepoRef | undefined;
+/** The `owner/name` people read and type; the owner alone for a namespace. */
+declare function repoSlug(repo: RepoRef): string;
+/** A thread ref whose number is known, and which can therefore be keyed and fetched. */
+type ResolvedThreadRef = ThreadRef & {
+  number: string;
+};
+/** Whether a thread ref has a number, so that it is a `ResolvedThreadRef`. */
+declare function isResolvedThread(thread: ThreadRef): thread is ResolvedThreadRef;
+/**
+ * Stable identity key for a thread. `'other'` threads are keyed by their
+ * forge-native type so unrelated subjects with the same id never collide.
+ */
+declare function threadKey(thread: ResolvedThreadRef): string;
+/** A string that identifies a notification, for use as a key in a map or a store. */
+declare function notificationKey(ref: NotificationRef): string;
+/** Reads a {@link threadKey} back. */
+declare function parseThreadKey(key: string): ResolvedThreadRef | undefined;
+/** Reads a {@link notificationKey} back. */
+declare function parseNotificationKey(key: string): NotificationRef | undefined;
+/** `acme/widgets#42`, or `acme/widgets@abc1234` for a commit; uses the display number where the forge has one. */
+declare function threadSlug(ref: ThreadRef): string;
+/** The thread a notification concerns, or `undefined` for repo, actor and other subjects. */
+declare function notificationThread(notification: Notification): ThreadRef | undefined;
+/** How a pull request is merged. */
+type MergeMethod = "merge" | "squash" | "rebase" | "rebase_merge" | "fast_forward_only";
+/** Options for `threads.merge()`. */
+interface MergeOptions extends BaseOptions {
+  /** Defaults to the repository's only allowed method. */
+  method?: MergeMethod;
+  /** Expected head sha; the merge is refused if the branch has moved. */
+  sha?: string;
+  /** Merge commit title. Where the forge takes a single message, it goes above `message`, separated by a blank line. */
+  title?: string;
+  /** Merge commit body, where the forge takes one. Where the forge takes a single message and `title` is unset, this is the whole message. */
+  message?: string;
+  /** Queue the merge until required checks pass, where the forge supports it. */
+  whenChecksPass?: boolean;
+}
+/** Options for `threads.approveAndMerge()`. */
+interface ApproveAndMergeOptions extends MergeOptions {
+  /** Review body sent with the approval. Rejected where approvals carry no body (Azure DevOps, Bitbucket, GitLab). */
+  body?: string;
+}
+/** An app installation on an account, with its own credential scope. */
+interface Installation extends ForgeOrigin {
+  id: string;
+  account?: Actor;
+  /** Forge-native target type, for example `Organization` or `User`. */
+  targetTypeRaw?: string;
+  /** Forge-native repository selection, for example `all` or `selected`. */
+  repositorySelectionRaw?: string;
+  raw: unknown;
+}
+/** Every `Date` field in the model, by name. */
+declare const DATE_FIELDS: ReadonlySet<string>;
+/**
+ * Turns the ISO strings `JSON.stringify` left in a model value back into
+ * `Date`s, at any depth, for every field in {@link DATE_FIELDS}, skipping
+ * `raw` and `payload`. Returns a copy.
+ */
+declare function reviveDates<T>(value: T): T;
+//#endregion
+//#region src/errors.d.ts
+/** Where an error happened: the forge, the instance and the request. */
+interface ForgeErrorContext {
+  forge?: ForgeKind;
+  instance?: ForgeInstance;
+  url?: string;
+  method?: string;
+}
+/** Base class for every error that forges throws. */
+declare class ForgeError extends Error {
+  override name: string;
+  /** The forge that the request went to. */
+  readonly forge?: ForgeKind;
+  readonly instance?: ForgeInstance;
+  readonly url?: string;
+  readonly method?: string;
+  constructor(message: string, context?: ForgeErrorContext, options?: ErrorOptions);
+}
+/** The forge responded with an error. */
+declare class ForgeApiError extends ForgeError {
+  override name: string;
+  readonly status: number;
+  /** Truncated response body, for diagnostics. */
+  readonly body: string;
+  constructor(message: string, status: number, body: string, context?: ForgeErrorContext, options?: ErrorOptions);
+}
+/** A 404: the resource does not exist, or the credential cannot see it. Many forges respond the same way to both. */
+declare class NotFoundError extends ForgeApiError {
+  override name: string;
+}
+/**
+ * A 401, or a 403 with a request budget of zero (GitHub GraphQL), for a request
+ * sent without credentials. A rejected credential is {@link TokenRevokedError}.
+ */
+declare class AuthenticationRequiredError extends ForgeApiError {
+  override name: string;
+}
+/** A rate limit was hit and a retry didn't help. */
+declare class RateLimitedError extends ForgeApiError {
+  override name: string;
+  /** When the limit resets, when the forge says. */
+  readonly resetAt?: Date;
+  /** A secondary (abuse) limit, which has no remaining-request counter. */
+  readonly secondary: boolean;
+  constructor(message: string, status: number, body: string, options?: {
+    resetAt?: Date;
+    secondary?: boolean;
+  } & ForgeErrorContext, errorOptions?: ErrorOptions);
+}
+/** The credential was revoked or expired. */
+declare class TokenRevokedError extends ForgeApiError {
+  override name: string;
+}
+/** The credential is valid but lacks the scope or permission for this call. */
+declare class InsufficientScopeError extends ForgeApiError {
+  override name: string;
+}
+/**
+ * Why the forge refused a request the credential is otherwise valid for.
+ * `unknown` is a 403 whose body matched nothing recognised.
+ */
+type ForbiddenReason = "org_restriction" | "sso_required" | "rate_limit_abuse" | "immutable_release" | "resource_protected" | "unknown";
+/**
+ * The forge refused the request for a reason other than a missing scope: an
+ * organisation policy, an SSO requirement, an abuse limit, a protected
+ * resource, or a release the forge has marked immutable. A missing scope is
+ * {@link InsufficientScopeError}.
+ */
+declare class ForbiddenError extends ForgeApiError {
+  override name: string;
+  /** Why the forge refused the request. */
+  readonly reason: ForbiddenReason;
+  /** The forge's own wording, for diagnostics and for reasons that have no `ForbiddenReason`. */
+  readonly reasonRaw?: string;
+  constructor(message: string, status: number, body: string, reason: ForbiddenReason, context?: ForgeErrorContext & {
+    reasonRaw?: string;
+  }, options?: ErrorOptions);
+}
+/** The pull request cannot be merged yet, typically because of failing or pending checks or branch protection. */
+declare class MergeBlockedError extends ForgeApiError {
+  override name: string;
+}
+/** The merge conflicts with the base branch, or the head moved since `sha` was read. */
+declare class MergeConflictError extends ForgeApiError {
+  override name: string;
+}
+/** A request or a pending merge exceeded `timeout`. */
+declare class ForgeTimeoutError extends ForgeError {
+  override name: string;
+  /** The timeout that was exceeded, in milliseconds. */
+  readonly timeout: number;
+  constructor(message: string, timeout: number, context?: ForgeErrorContext, options?: ErrorOptions);
+}
+/** A subscription connection closed or failed. Resume from `cursor`. */
+declare class SubscriptionClosedError extends ForgeError {
+  override name: string;
+  /** The cursor of the last event received. Pass it to `subscribe()` to resume. */
+  readonly cursor?: string;
+  constructor(message: string, cursor: string | undefined, context?: ForgeErrorContext, options?: ErrorOptions);
+}
+/** The request never got a response: DNS, TLS, connection refused or a proxy refusal. */
+declare class ForgeNetworkError extends ForgeError {
+  override name: string;
+}
+/** A delivery's signature didn't match. */
+declare class WebhookVerificationError extends ForgeError {
+  override name: string;
+}
+/** The forge doesn't support the operation. */
+declare class UnsupportedOperationError extends ForgeError {
+  override name: string;
+}
+/** A write was called on a provider constructed with `readOnly: true`. */
+declare class ReadOnlyError extends UnsupportedOperationError {
+  override name: string;
+}
+/** `contents.file` was asked for text and the file's bytes are not valid UTF-8. */
+declare class ContentNotTextError extends ForgeError {
+  override name: string;
+}
+/** A ref names a forge instance no registered provider serves. */
+declare class UnknownForgeError extends ForgeError {
+  override name: string;
+}
+/** Maps a generic merge-endpoint failure onto {@link MergeBlockedError} or {@link MergeConflictError}. */
+declare function toMergeError(error: unknown): unknown;
+/** The thread ref has no number, or is a kind the provider cannot address. */
+declare class UnresolvedThreadError extends ForgeError {
+  override name: string;
+}
+/** No merge method was given, and the repository allows several or reports none. */
+declare class MergeMethodRequiredError extends ForgeError {
+  override name: string;
+  /** The merge methods that the repository allows. */
+  readonly allowed: MergeMethod[];
+  constructor(allowed: MergeMethod[], context?: ForgeErrorContext, options?: ErrorOptions);
+}
+/** Picks the only allowed merge method, or throws {@link MergeMethodRequiredError}. */
+declare function soleMergeMethod(allowed: Partial<Record<MergeMethod, boolean | undefined>>, context?: ForgeErrorContext): MergeMethod;
+//#endregion
+//#region src/fetch.d.ts
+/** The subset of `fetch` that forges needs, so a test or a runtime without a global `fetch` can supply its own. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Options for `createFetcher()`. */
+interface FetcherOptions {
+  baseUrl: string;
+  /** Injected for tests and for runtimes with a non-global fetch. */
+  fetch?: FetchLike;
+  /**
+   * Timeout in milliseconds (headers only for streams).
+   * @default 30000
+   */
+  timeout?: number;
+  /** Default headers, sent only to the API origin. */
+  headers?: Record<string, string>;
+  /** Credentials resolved before each API-origin request. */
+  authHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+  /** Requests carry credentials that `authHeaders` does not set, for example through a `fetch` that signs them. */
+  authenticated?: boolean;
+  /** API-origin query defaults; request parameters take precedence. */
+  query?: Record<string, string>;
+  /** Attached to every error the fetcher throws. */
+  context?: ForgeErrorContext;
+  /**
+   * Called before a request is retried. A secondary rate limit with a
+   * `retry-after` of at most a minute is retried once, after that wait.
+   */
+  onRetry?: (retry: {
+    url: string;
+    method: string;
+    wait: number;
+  }) => void;
+}
+/** Options for one request of a fetcher. */
+interface RequestOptions extends Omit<RequestInit, "signal"> {
+  /** Query parameters. Parameters that are `undefined` are left out. */
+  query?: Record<string, string | number | boolean | undefined>;
+  signal?: AbortSignal;
+  /** Send `If-None-Match`, and resolve with `notModified` instead of throwing. */
+  etag?: string;
+  /** Serialised as the JSON request body, with a matching `content-type`. */
+  json?: unknown;
+  /** Rewrites a failure from this request, for endpoints whose statuses mean something specific. */
+  mapError?: (error: unknown) => unknown;
+}
+/** Options for reading one page of a paginated endpoint. */
+interface PaginateOptions extends RequestOptions {
+  /**
+   * Reads items and the next page URL from a response body, for APIs that
+   * paginate in the body (Bitbucket's `values` / `next`). Without it, the
+   * body is the item array and the next page comes from the `Link` header.
+   * `linkNext` is the `Link` header's next URL, for APIs that wrap items in
+   * the body but still paginate with `Link`.
+   */
+  select?: (body: unknown, linkNext?: string) => {
+    items: unknown[];
+    next?: string;
+  };
+}
+/** A parsed response. */
+interface FetchResult<T> {
+  data: T;
+  response: Response;
+  /** The server answered `304 Not Modified` to the `etag` that the request sent. */
+  notModified: boolean;
+  /** Where the next page starts, when there is one. */
+  cursor?: Cursor;
+}
+/** A response whose body is read as it arrives rather than parsed. */
+interface RawResponse {
+  status: number;
+  headers: Headers;
+  /** The body, read as it arrives. */
+  body: ReadableStream<Uint8Array>;
+}
+/** A client for one forge API. It adds credentials, applies the timeout and retries, and maps failures to errors. */
+interface Fetcher {
+  /** Sends a request and returns the response unparsed. */
+  raw: (path: string, options?: RequestOptions) => Promise<Response>;
+  /**
+   * Bytes as they arrive, through the same timeout and error mapping as
+   * {@link Fetcher.json}. HTTP(S) download redirects to another origin omit
+   * all headers and credentials. HTTPS downloads cannot redirect to HTTP.
+   * Where `fetch` hides redirects (browsers), the runtime follows GET and HEAD
+   * under its own header rules.
+   */
+  stream: (path: string, options?: RequestOptions) => Promise<RawResponse>;
+  /** Sends a request and parses the JSON body. */
+  json: <T>(path: string, options?: RequestOptions) => Promise<FetchResult<T>>;
+  /** One page: `path` with its query, or `cursor.nextUrl` when given. */
+  page: <T>(path: string, options?: PaginateOptions & {
+    cursor?: Cursor;
+  }) => Promise<FetchResult<T[]>>;
+  /** Every item across every page, in order. */
+  items: <T>(path: string, options?: PaginateOptions) => AsyncGenerator<T>;
+  /** The absolute URL of a path and query, without sending a request. */
+  resolve: (path: string, query?: RequestOptions["query"]) => string;
+}
+/** Parses an RFC 5988 `Link` header into a map of rel to URL. */
+declare function parseLinkHeader(header: string | null | undefined): Record<string, string>;
+/**
+ * Creates a fetcher for one forge API.
+ * @param options The base URL and the credentials, timeout and error context of every request.
+ */
+declare function createFetcher(options: FetcherOptions): Fetcher;
+/** Options for `provider.request()`. */
+interface ForgeRequestOptions extends BaseOptions {
+  /** Query parameters. Parameters that are `undefined` are left out. */
+  query?: RequestOptions["query"];
+  /** Native fetch bodies and strings are sent as-is; other values are sent as JSON. */
+  body?: unknown;
+  /** Headers to send. They add to the provider's default headers. */
+  headers?: Record<string, string>;
+  /** Caller-declared mutation. Defaults to `false` for GET/HEAD/OPTIONS, otherwise `true`. */
+  mutates?: boolean;
+}
+/** The result of `provider.request()`. */
+interface ForgeResponse<T> {
+  status: number;
+  /** The parsed JSON body, or the text of a body that is not JSON. */
+  data: T;
+  headers: Headers;
+  /** The rate limit that the response headers report, when there is one. */
+  rateLimit?: RateLimit;
+}
+/** `request()` with `raw`, for endpoints that respond with bytes rather than JSON. */
+interface ForgeRawRequestOptions extends ForgeRequestOptions {
+  raw: true;
+}
+/**
+ * `provider.request()`: sends a request with the provider's credentials, for endpoints that the model does not cover.
+ */
+interface ForgeRequest {
+  (method: string, path: string, options: ForgeRawRequestOptions): Promise<RawResponse>;
+  <T = unknown>(method: string, path: string, options?: ForgeRequestOptions): Promise<ForgeResponse<T>>;
+}
+/** Options for `createRequest()`. */
+interface CreateRequestOptions {
+  /** Error for mutating requests. */
+  readOnly?: (method: string, path: string) => Error;
+}
+/**
+ * Builds a provider's `request()` escape hatch on top of its fetcher.
+ * @param fetcher The fetcher to send requests with.
+ * @param createOptions Where to reject writes, for a read-only provider.
+ */
+declare function createRequest(fetcher: Fetcher, createOptions?: CreateRequestOptions): ForgeRequest;
+//#endregion
+export { CiRunQuery as $, WebhookInput as $n, ReactionSummary as $t, RateLimitedError as A, SourceKind as An, GetManyResult as At, Actor as B, ThreadStack as Bn, Notification as Bt, ForgeNetworkError as C, Reviewer as Cn, ForgeEvent as Ct, MergeConflictError as D, SecurityAlertListOptions as Dn, ForgeOrigin as Dt, MergeBlockedError as E, SecurityAlertKind as En, ForgeKind as Et, UnresolvedThreadError as F, Thread as Fn, LabelInput as Ft, Check as G, TreeOptions as Gn, Page as Gt, BaseOptions as H, ThreadUpdateInput as Hn, NotificationReason as Ht, UnsupportedOperationError as I, ThreadCreateInput as In, ListOptions as It, CheckState as J, User as Jn, PushCommit as Jt, CheckRef as K, UpsertCommentInput as Kn, PageOptions as Kt, WebhookVerificationError as L, ThreadKind as Ln, MergeMethod as Lt, SubscriptionClosedError as M, Support as Mn, InstallationToken as Mt, TokenRevokedError as N, Tag as Nn, KnownForgeKind as Nt, MergeMethodRequiredError as O, SecurityAlertRef as On, ForgeWarning as Ot, UnknownForgeError as P, TextLimits as Pn, Label as Pt, CiRun as Q, WebhookEventType as Qn, ReactionContent as Qt, soleMergeMethod as R, ThreadQuery as Rn, MergeOptions as Rt, ForgeErrorContext as S, ReviewState as Sn, FileStatus as St, InsufficientScopeError as T, SecurityAlert as Tn, ForgeInstance as Tt, Branch as U, TreeEntry as Un, NotificationRef as Ut, ApproveAndMergeOptions as V, ThreadState as Vn, NotificationListOptions as Vt, ChangedFile as W, TreeEntryType as Wn, NotificationSubject as Wt, CiJob as X, WebhookDeliveryRecord as Xn, RateLimit as Xt, ChecksSummary as Y, Webhook as Yn, REACTION_CONTENTS as Yt, CiJobRef as Z, WebhookDeliveryRef as Zn, Reaction as Zt, ContentNotTextError as _, ReviewComment as _n, threadKey as _r, EventKind as _t, FetcherOptions as a, ReleaseUpdate as an, isResolvedThread as ar, Comment as at, ForgeApiError as b, ReviewInput as bn, FileMetadata as bt, ForgeRequestOptions as c, RepoFeatures as cn, notificationKey as cr, CommitQuery as ct, RawResponse as d, RepoRef as dn, parseRepoKey as dr, CommitSignature as dt, Release as en, WebhookRef as er, CiRunRef as et, RequestOptions as f, RepoRole as fn, parseThreadKey as fr, Comparison as ft, AuthenticationRequiredError as g, Review as gn, reviveDates as gr, EventDetail as gt, parseLinkHeader as h, ResolvedThreadRef as hn, repoSlug as hr, EventAction as ht, Fetcher as i, ReleaseRef as in, isNamespaceRef as ir, Collaborator as it, ReadOnlyError as j, SubscriptionState as jn, Installation as jt, NotFoundError as k, SecuritySeverity as kn, ForgeWarningCode as kt, ForgeResponse as l, RepoPermissions as ln, notificationThread as lr, CommitRef as lt, createRequest as m, RepoVisibility as mn, repoKey as mr, DATE_FIELDS as mt, FetchLike as n, ReleaseAssetRef as nn, commentMarker as nr, CodeMatch as nt, ForgeRawRequestOptions as o, Repo as on, namesAreCaseInsensitive as or, CommentRef as ot, createFetcher as p, RepoSearchQuery as pn, reactionContent as pr, Cursor as pt, CheckReportInput as q, UpsertCommentResult as qn, PullBranches as qt, FetchResult as r, ReleaseInput as rn, hasCommentMarker as rr, CodeSearchQuery as rt, ForgeRequest as s, RepoAffiliation as sn, normaliseRepoName as sr, Commit as st, CreateRequestOptions as t, ReleaseAsset as tn, WebhookUpdate as tr, CodeFragment as tt, PaginateOptions as u, RepoQuery as un, parseNotificationKey as ur, CommitSearchQuery as ut, ForbiddenError as v, ReviewCommentInput as vn, threadSlug as vr, FileContent as vt, ForgeTimeoutError as w, SearchQuery as wn, ForgeEventInput as wt, ForgeError as x, ReviewRef as xn, FileOptions as xt, ForbiddenReason as y, ReviewEvent as yn, FileEncoding as yt, toMergeError as z, ThreadRef as zn, Milestone as zt };