forges 0.0.0 → 0.1.0

package/dist/define-B2_4ob2i.d.mts

@@ -0,0 +1,307 @@
+import { Bt as Notification, En as SecurityAlertKind, Et as ForgeKind, G as Check, Gt as Page, H as BaseOptions, It as ListOptions, Ln as ThreadKind, Mn as Support, Pn as TextLimits, Qn as WebhookEventType, Rt as MergeOptions, Tt as ForgeInstance, Vt as NotificationListOptions, a as FetcherOptions, i as Fetcher, wt as ForgeEventInput, zn as ThreadRef } from "./fetch-D4pSRvvA.mjs";
+import { C as ReleasesApi, D as SecurityAlertsApi, E as SearchApi, F as WebhookDelivery, H as WebLinks, I as WebhooksApi, N as UsersApi, P as VerbScopes, T as ReposApi, c as CiApi, d as ContentsApi, f as ForgeCapabilities, g as ForgeProviderFactory, h as ForgeProvider, i as AuthKind, j as ThreadsApi, k as SubscribeOptions, m as ForgeOptionsBase, q as ForgeVerb, s as ChecksApi, v as InstallationsApi, x as NotificationsApi } from "./provider-CoZ7cCxp.mjs";
+//#region src/define.d.ts
+/** What support can depend on once the provider exists. */
+interface CapabilityEnv {
+  /** Instance version from `instanceVersion` or `refreshCapabilities()`, when known. */
+  version?: string;
+}
+/** A fixed support level, or one computed from the instance version. */
+type SupportInput = Support | ((env: CapabilityEnv) => Support);
+/** The thread kinds that verbs can differ by. */
+type VerbKind = Exclude<ThreadKind, "other">;
+/** The security alert kinds that support can differ by. */
+type AlertKind = Exclude<SecurityAlertKind, "other">;
+/** A verb whose support does not depend on the thread kind. */
+interface Verb<F> {
+  /** How well the verb is supported. */
+  support: SupportInput;
+  run: F;
+}
+/** A verb whose support depends on the thread kind it is called with. Kinds not listed are unsupported. */
+interface KindVerb<F> {
+  /** How well each thread kind is supported. */
+  kinds: Partial<Record<VerbKind, SupportInput>>;
+  run: F;
+}
+/**
+ * Declares a verb whose support does not depend on the thread kind.
+ * @param support How well the verb is supported.
+ * @param run The function that implements the verb.
+ */
+declare function verb<F>(support: SupportInput, run: F): Verb<F>;
+/**
+ * Declares a verb whose support depends on the thread kind.
+ * @param kinds How well each thread kind is supported. Kinds that are left out are unsupported.
+ * @param run The function that implements the verb.
+ * @example
+ * ```ts
+ * const threads = {
+ *   get: perKind({ issue: true, pull_request: true }, getThread),
+ * }
+ * ```
+ */
+declare function perKind<F>(kinds: Partial<Record<VerbKind, SupportInput>>, run: F): KindVerb<F>;
+type ThreadVerb<K extends keyof ThreadsApi> = KindVerb<NonNullable<ThreadsApi[K]>>;
+/** Everything a provider declares. Methods and capabilities are both derived from it. */
+interface ProviderSpec {
+  /** Capabilities that no single verb carries. */
+  traits: {
+    /** Whether event kinds come from the forge or are inferred from text. See `ForgeCapabilities.eventKinds`. */
+    eventKinds: ForgeCapabilities["eventKinds"];
+    /** The auth types the provider accepts. */
+    authKinds: readonly AuthKind[];
+    /** Limits on the text the forge accepts. */
+    limits?: TextLimits;
+  };
+  /** Listings are declared as pages; core derives the iterables. */
+  repos: {
+    get: Verb<ReposApi["get"]>;
+    listPage: Verb<ReposApi["listPage"]>;
+    labelsPage?: Verb<ReposApi["labelsPage"]>;
+    createLabel?: Verb<ReposApi["createLabel"]>;
+    milestonesPage?: Verb<ReposApi["milestonesPage"]>;
+    collaboratorsPage?: Verb<ReposApi["collaboratorsPage"]>;
+    permissionFor?: Verb<ReposApi["permissionFor"]>;
+    addCollaborator?: Verb<ReposApi["addCollaborator"]>;
+    assignableUsersPage?: Verb<ReposApi["assignableUsersPage"]>;
+    reviewerCandidatesPage?: Verb<ReposApi["reviewerCandidatesPage"]>;
+  };
+  /** `get` is omitted when the forge cannot read an account by login. */
+  users?: {
+    get?: Verb<UsersApi["get"]>;
+    me?: Verb<UsersApi["me"]>;
+  };
+  threads: {
+    get: ThreadVerb<"get">;
+    listPage: ThreadVerb<"listPage">;
+    getMany: Verb<ThreadsApi["getMany"]>;
+    eventsPage: Verb<(ref: ThreadRef, options?: ListOptions) => Promise<Page<ForgeEventInput>>>;
+    commentsPage: ThreadVerb<"commentsPage">;
+    comment?: ThreadVerb<"comment">;
+    editComment?: ThreadVerb<"editComment">;
+    deleteComment?: ThreadVerb<"deleteComment">;
+    close?: ThreadVerb<"close">;
+    reopen?: ThreadVerb<"reopen">;
+    create?: ThreadVerb<"create">;
+    update?: ThreadVerb<"update">;
+    setLabels?: ThreadVerb<"setLabels">;
+    addLabels?: ThreadVerb<"addLabels">;
+    removeLabels?: ThreadVerb<"removeLabels">;
+    setMilestone?: ThreadVerb<"setMilestone">;
+    /** One capability covers reacting and removing a reaction. */
+    reactions?: KindVerb<{ [K in "react" | "unreact"]: NonNullable<ThreadsApi[K]>; }>;
+    /** Listing the reactions on a thread or one of its comments. */
+    reactionsPage?: KindVerb<ThreadsApi["reactionsPage"]>;
+    transfer?: Verb<ThreadsApi["transfer"]>;
+    markDuplicate?: Verb<ThreadsApi["markDuplicate"]>;
+    setAssignees?: ThreadVerb<"setAssignees">;
+    requestReview?: ThreadVerb<"requestReview">;
+    /** `beforeMerge` runs once the merge is validated, just before it is sent. */
+    merge?: Verb<(ref: ThreadRef, options?: MergeOptions, hooks?: MergeHooks) => Promise<void>>;
+    /** Optional support override; approval and merging must also be supported. */
+    approveAndMerge?: {
+      support: SupportInput;
+    };
+    /** One capability covers reading and changing the subscription. */
+    subscriptions?: KindVerb<{ [K in "subscription" | "subscribe" | "unsubscribe"]: NonNullable<ThreadsApi[K]>; }>;
+    checks?: KindVerb<(ref: ThreadRef, options?: BaseOptions) => Promise<Page<Check>>>;
+    reviewsPage?: Verb<ThreadsApi["reviewsPage"]>;
+    createReview?: Verb<ThreadsApi["createReview"]>;
+    submitReview?: Verb<ThreadsApi["submitReview"]>;
+    /** Omit to derive approval from `createReview`. */
+    approve?: Verb<ThreadsApi["approve"]>;
+    filesPage?: Verb<ThreadsApi["filesPage"]>;
+    commitsPage?: Verb<ThreadsApi["commitsPage"]>;
+    /** One capability covers resolving and unresolving. */
+    reviewThreads?: Verb<Pick<ThreadsApi, "resolveReviewThread" | "unresolveReviewThread">>;
+  };
+  /** Commit-level checks, beside the pull-level `threads.checks`. */
+  checks?: {
+    /** The implementation of `provider.checks.list()`. */
+    list?: Verb<ChecksApi["list"]>;
+    /** The implementation of `provider.checks.report()`. */
+    report?: Verb<ChecksApi["report"]>;
+    /** The implementation of `provider.checks.rerun()`. */
+    rerun?: Verb<ChecksApi["rerun"]>;
+  };
+  /** Read-only CI. Listings are declared as pages; core derives the iterables. */
+  ci?: {
+    /** The implementation of `provider.ci.runs()` and `provider.ci.runsPage()`. */
+    runsPage?: Verb<CiApi["runsPage"]>;
+    /** The implementation of `provider.ci.run()`. */
+    run?: Verb<CiApi["run"]>;
+    /** The implementation of `provider.ci.jobs()` and `provider.ci.jobsPage()`. */
+    jobsPage?: Verb<CiApi["jobsPage"]>;
+    /** The implementation of `provider.ci.log()`. */
+    log?: Verb<CiApi["log"]>;
+  };
+  /** Repository contents. Listings are declared as pages; core derives the iterables. */
+  contents?: {
+    /** The implementation of `provider.contents.file()`. */
+    file?: Verb<ContentsApi["file"]>;
+    /** The implementation of `provider.contents.tree()` and `provider.contents.treePage()`. */
+    treePage?: Verb<ContentsApi["treePage"]>;
+    /** The implementation of `provider.contents.branches()` and `provider.contents.branchesPage()`. */
+    branchesPage?: Verb<ContentsApi["branchesPage"]>;
+    /** The implementation of `provider.contents.tags()` and `provider.contents.tagsPage()`. */
+    tagsPage?: Verb<ContentsApi["tagsPage"]>;
+    /** Omit where a sha lookup is impossible; core still short-circuits a 40-hex ref. */
+    resolveRef?: Verb<ContentsApi["resolveRef"]>;
+    /** The implementation of `provider.contents.commits()` and `provider.contents.commitsPage()`. */
+    commitsPage?: Verb<ContentsApi["commitsPage"]>;
+    /** The implementation of `provider.contents.commit()`. */
+    commit?: Verb<ContentsApi["commit"]>;
+    /** The implementation of `provider.contents.compare()`. */
+    compare?: Verb<ContentsApi["compare"]>;
+  };
+  /** Cross-repository search. Listings are declared as pages; core derives the iterables. */
+  search?: {
+    /** The implementation of `provider.search.threads()` and `provider.search.threadsPage()`. */
+    threadsPage?: Verb<SearchApi["threadsPage"]>;
+    /** The implementation of `provider.search.repos()` and `provider.search.reposPage()`. */
+    reposPage?: Verb<SearchApi["reposPage"]>;
+    /** The implementation of `provider.search.commits()` and `provider.search.commitsPage()`. */
+    commitsPage?: Verb<SearchApi["commitsPage"]>;
+    /** The implementation of `provider.search.code()` and `provider.search.codePage()`. */
+    codePage?: Verb<SearchApi["codePage"]>;
+    /** The searches pass `queryRaw` on; without this, core drops it with a warning. */
+    queryRaw?: boolean;
+  };
+  releases?: {
+    /** The implementation of `provider.releases.list()` and `provider.releases.listPage()`. */
+    listPage: Verb<ReleasesApi["listPage"]>;
+    /** The implementation of `provider.releases.get()`. */
+    get: Verb<ReleasesApi["get"]>;
+    /** The implementation of `provider.releases.latest()`. */
+    latest: Verb<ReleasesApi["latest"]>;
+    /** The implementation of `provider.releases.getByTag()`. */
+    getByTag?: Verb<ReleasesApi["getByTag"]>;
+    /** The implementation of `provider.releases.downloadAsset()`. */
+    downloadAsset?: Verb<ReleasesApi["downloadAsset"]>;
+    /** The implementation of `provider.releases.create()`. */
+    create?: Verb<ReleasesApi["create"]>;
+    /** The implementation of `provider.releases.update()`. */
+    update?: Verb<ReleasesApi["update"]>;
+  };
+  /** Support per alert kind; `listPage` is called with `kind` unset to list every supported kind. */
+  securityAlerts?: {
+    /** The implementation of `provider.securityAlerts.kinds()`. */
+    kinds: Partial<Record<AlertKind, SupportInput>>;
+    /** The implementation of `provider.securityAlerts.list()` and `provider.securityAlerts.listPage()`. */
+    listPage: SecurityAlertsApi["listPage"];
+  };
+  /** Omit when the forge has no notifications. `list` is derived from `page`. */
+  notifications?: {
+    listPage: Verb<(options?: NotificationListOptions) => Promise<Page<Notification>>>;
+  } & { [K in Exclude<keyof NotificationsApi, "list" | "listPage">]?: Verb<NonNullable<NotificationsApi[K]>>; };
+  /** The implementation of `provider.installations`, except for `list()` and `repos()`, which core derives. */
+  installations?: Verb<Omit<InstallationsApi, "list" | "repos">>;
+  sources?: {
+    subscribe: Verb<(options?: SubscribeOptions) => AsyncIterable<{
+      event: ForgeEventInput;
+      cursor: string;
+    }>>;
+  };
+  /** Managing registered hooks. Listings are declared as pages; core derives the iterables. */
+  webhooks: {
+    listPage?: Verb<WebhooksApi["listPage"]>;
+    create?: Verb<WebhooksApi["create"]>;
+    update?: Verb<WebhooksApi["update"]>;
+    delete?: Verb<WebhooksApi["delete"]>;
+    rotateSecret?: Verb<WebhooksApi["rotateSecret"]>;
+    deliveriesPage?: Verb<WebhooksApi["deliveriesPage"]>;
+    redeliver?: Verb<WebhooksApi["redeliver"]>;
+  };
+  /** Token scopes or app permissions per verb, for `provider.scopesFor()`. */
+  scopes?: (verb: ForgeVerb) => VerbScopes;
+  /** The implementation of `provider.normaliseMarkdown()`. Without it, Markdown is returned unchanged. */
+  normaliseMarkdown?: (body: string) => string;
+  /** How the forge's web pages are laid out; omit when they have no stable pattern. */
+  web?: WebLinks;
+  /** Fetcher behind `request()`, when it differs from the context fetcher. */
+  request?: Fetcher;
+  /** Reads the instance version for `refreshCapabilities()`. Omit when capabilities never depend on it. */
+  probeVersion?: () => Promise<string | undefined>;
+}
+/** Hooks that a provider runs around a merge. */
+interface MergeHooks {
+  /** Runs before the merge request is sent, for example to wait for a pending state. */
+  beforeMerge?: () => Promise<void>;
+}
+/** The options, the identity and the resolved URLs that provider hooks receive. */
+interface ProviderBase<TOptions, TState> {
+  options: TOptions;
+  forge: ForgeKind;
+  instance: ForgeInstance;
+  /** API base after defaults and the API path are applied. */
+  baseUrl: string;
+  /** Default headers: the definition's, plus `user-agent` outside browsers or when the caller sets one. */
+  headers: Record<string, string>;
+  /** Error context for this provider. */
+  origin: {
+    forge: ForgeKind;
+    instance: ForgeInstance;
+  };
+  /** State passed to `derive()`, or created by `prepare()`. */
+  state: TState;
+}
+/** The argument of `setup()`: the base, the fetchers and `derive()`. */
+interface ProviderContext<TOptions, TState> extends ProviderBase<TOptions, TState> {
+  /** Authenticated with the definition's `authHeaders`. */
+  fetcher: Fetcher;
+  /** Another fetcher with the same timeout, `fetch` and error context. */
+  createFetcher: (overrides: Partial<FetcherOptions> & {
+    baseUrl: string;
+  }) => Fetcher;
+  /** Another provider from the same definition, for example one per app installation. */
+  derive: (options: TOptions, state?: TState) => ForgeProvider;
+}
+/** The defaults, the authentication and the `setup()` of a forge. */
+interface ProviderDefinition<TOptions extends ForgeOptionsBase, TState = undefined> {
+  forge: ForgeKind;
+  /** The forge's API as a whole is unstable, so the provider can change with it. */
+  experimental?: true;
+  /**
+   * Accepts a missing `auth` as `{ type: 'anonymous' }`: core then sends no
+   * credentials and marks writes, notifications, subscriptions, installations
+   * and the account's repository list unsupported. `'webhooks'` marks every
+   * verb unsupported, for a forge whose API needs credentials but whose
+   * webhook deliveries can be verified without them.
+   */
+  anonymous?: true | "webhooks";
+  /** Default `baseUrl` when the caller passes none. */
+  baseUrl: string;
+  /** Appended to `baseUrl` unless already present, for example `/api/v4`. */
+  apiPath?: string;
+  /** Maps the API host to the instance host, for example `api.github.com` to `github.com`. */
+  instance?: (host: string) => string;
+  headers?: Record<string, string>;
+  /** Builds per-provider state once; receives the state given to `derive()`, if any. */
+  prepare?: (base: ProviderBase<TOptions, TState | undefined>) => TState;
+  /** Resolves the credential headers of each request. */
+  authHeaders?: (base: ProviderBase<TOptions, TState>) => FetcherOptions["authHeaders"];
+  /** Query parameters for every request, such as an API version; see `FetcherOptions.query`. */
+  query?: Record<string, string>;
+  /** Declares the verbs and the web links of one provider. */
+  setup: (ctx: ProviderContext<TOptions, TState>) => ProviderSpec;
+  /** Delivery verification and translation. Omit it and `webhooks.ingest()` is unsupported. */
+  webhooks?: WebhookHandlers<TOptions>;
+}
+/** Verifies and translates deliveries for one provider; built once per instance from its context. */
+type WebhookHandlers<TOptions> = (ctx: Omit<ProviderContext<TOptions, unknown>, "state" | "derive">) => {
+  /** Normalised kinds and actions the handlers translate. */
+  events: WebhookEventType[];
+  verify: (delivery: WebhookDelivery) => Promise<boolean>;
+  translate: (delivery: WebhookDelivery) => ForgeEventInput[] | Promise<ForgeEventInput[]>;
+};
+/**
+ * Defines a forge provider. Returns the factory end users call, for example
+ * `github({ auth })`. Nothing touches the network until `create()`.
+ * @param definition The defaults, authentication and setup of the forge.
+ */
+declare function defineForgeProvider<TOptions extends ForgeOptionsBase, TState = undefined>(definition: ProviderDefinition<TOptions, TState>): ProviderFactoryFunction<TOptions>;
+/** The function `defineForgeProvider()` returns. Options are optional when every option is. */
+type ProviderFactoryFunction<TOptions> = Record<never, never> extends TOptions ? (options?: TOptions) => ForgeProviderFactory<ForgeProvider> : (options: TOptions) => ForgeProviderFactory<ForgeProvider>;
+//#endregion
+export { ProviderBase as a, ProviderFactoryFunction as c, Verb as d, VerbKind as f, verb as g, perKind as h, MergeHooks as i, ProviderSpec as l, defineForgeProvider as m, CapabilityEnv as n, ProviderContext as o, WebhookHandlers as p, KindVerb as r, ProviderDefinition as s, AlertKind as t, SupportInput as u };