--- title: "Provider kit" description: "The building blocks of a provider, from `forges/kit`." canonical_url: "https://forges.link/contributing/provider-kit" --- # Provider kit > The building blocks of a provider, from `forges/kit`. Import from `forges/kit`. Code that only uses providers imports from `forges` instead. See [Write a provider](https://forges.link/contributing/write-a-provider) for how they fit together. ## Define a provider ### `CapabilityEnv` What support can depend on once the provider exists.
Member Type Description
version? string Instance version from instanceVersion or refreshCapabilities() , when known.
### `SupportInput` A fixed support level, or one computed from the instance version. **one of:** - [`Support`](https://forges.link/reference/provider#support-1) - `((env: CapabilityEnv) => Support)` ### `VerbKind` The thread kinds that verbs can differ by. **type:** [`Exclude`](https://forges.link/reference/data-model#threadkind) ### `ThreadFilter` The `ThreadQuery` filters that a provider declares in `threads.listFilters` when its listing applies them. **one of:** - `'involves'` - `'mentions'` - `'milestone'` ### `AlertKind` The security alert kinds that support can differ by. **type:** [`Exclude`](https://forges.link/reference/data-model#securityalertkind) ### `Verb` A verb whose support does not depend on the thread kind. **type parameters:** `F`
Member Type Description
support SupportInput How well the verb is supported.
run F
### `KindVerb` A verb whose support depends on the thread kind it is called with. Kinds not listed are unsupported. **type parameters:** `F`
Member Type Description
kinds Partial> How well each thread kind is supported.
run F
### `verb()` Declares a verb whose support does not depend on the thread kind. ```ts function verb(support: SupportInput, run: F): Verb ```
Parameter Type Description
support SupportInput How well the verb is supported.
run F The function that implements the verb.
**Returns:** [`Verb`](https://forges.link/contributing/provider-kit#verb) ### `perKind()` Declares a verb whose support depends on the thread kind. **Example** ```ts const threads = { get: perKind({ issue: true, pull_request: true }, getThread), } ``` ```ts function perKind(kinds: Partial>, run: F): KindVerb ```
Parameter Type Description
kinds Partial> How well each thread kind is supported. Kinds that are left out are unsupported.
run F The function that implements the verb.
**Returns:** [`KindVerb`](https://forges.link/contributing/provider-kit#kindverb) ### `ProviderSpec` Everything a provider declares. Methods and capabilities are both derived from it. **type parameters:** `TExtensions extends object = Record`
Member Type Description
extensions? TExtensions Members that only this forge's providers have, such as graphql() on GitHub. They are added to the provider unchanged.
traits Capabilities that no single verb carries.
traits.eventKinds ForgeCapabilities['eventKinds'] Whether event kinds come from the forge or are inferred from text. See ForgeCapabilities.eventKinds .
traits.authKinds readonly AuthKind[] The auth types the provider accepts.
traits.limits? TextLimits Limits on the text the forge accepts.
repos Listings are declared as pages; core derives the iterables.
repos.get Verb
repos.listPage Verb
repos.byOwnerPage? Verb
repos.labelsPage? Verb
repos.createLabel? Verb
repos.milestonesPage? Verb
repos.collaboratorsPage? Verb
repos.contributorsPage? Verb
repos.contributorStats? Verb
repos.templates? Verb
repos.permissionFor? Verb
repos.addCollaborator? Verb
repos.assignableUsersPage? Verb
repos.reviewerCandidatesPage? Verb
repos.eventsPage? Verb<(repo: RepoRef, options?: EventFeedOptions) => Promise>> The implementation of provider.repos.events() and provider.repos.eventsPage() .
users? get is omitted when the forge cannot read an account by login.
orgs? An organisation's teams and their members. Listings are declared as pages; core derives the iterables.
threads.get ThreadVerb<'get'>
threads.listPage ThreadVerb<'listPage'>
threads.listFilters? readonly ThreadFilter[] The ThreadFilter s that listPage applies, or reports with its own warning. Core leaves the others out of the query and adds a filter_unsupported warning to the first page.
threads.getMany Verb
threads.eventsPage Verb<(ref: ThreadRef, options?: ListOptions) => Promise>>
threads.commentsPage ThreadVerb<'commentsPage'>
threads.getComment? ThreadVerb<'getComment'>
threads.comment? ThreadVerb<'comment'>
threads.editComment? ThreadVerb<'editComment'>
threads.deleteComment? ThreadVerb<'deleteComment'>
threads.close? ThreadVerb<'close'>
threads.reopen? ThreadVerb<'reopen'>
threads.create? ThreadVerb<'create'>
threads.update? ThreadVerb<'update'>
threads.setLabels? ThreadVerb<'setLabels'>
threads.addLabels? ThreadVerb<'addLabels'>
threads.removeLabels? ThreadVerb<'removeLabels'>
threads.setMilestone? ThreadVerb<'setMilestone'>
threads.reactions? KindVerb<{ [K in 'react' | 'unreact']: NonNullable }> One capability covers reacting and removing a reaction.
threads.reactionsPage? KindVerb Listing the reactions on a thread or one of its comments.
threads.transfer? Verb
threads.markDuplicate? Verb
threads.setAssignees? ThreadVerb<'setAssignees'>
threads.requestReview? ThreadVerb<'requestReview'>
threads.merge? Verb<(ref: ThreadRef, options?: MergeOptions, hooks?: MergeHooks) => Promise> beforeMerge runs once the merge is validated, just before it is sent.
threads.approveAndMerge? Optional support override; approval and merging must also be supported.
threads.subscriptions? KindVerb<{ [K in 'subscription' | 'subscribe' | 'unsubscribe']: NonNullable }> One capability covers reading and changing the subscription.
threads.checks? KindVerb<(ref: ThreadRef, options?: BaseOptions) => Promise>>
threads.reviewsPage? Verb
threads.getReview? Verb
threads.createReview? Verb
threads.submitReview? Verb
threads.replyToReviewComment? Verb
threads.approve? Verb Omit to derive approval from createReview .
threads.filesPage? Verb
threads.commitsPage? Verb
threads.reviewThreads? Verb> One capability covers resolving and unresolving.
emulated? Support for the single-item reads core emulates from their listings where the spec declares no endpoint. Each defaults to 'emulated' , capped by the listing's own support.
checks? Commit-level checks, beside the pull-level threads.checks .
ci? Read-only CI. Listings are declared as pages; core derives the iterables.
contents? Repository contents. Listings are declared as pages; core derives the iterables.
search? Cross-repository search. Listings are declared as pages; core derives the iterables.
securityAlerts? Support per alert kind; listPage is called with kind unset to list every supported kind.
notifications? { listPage: Verb<(options?: NotificationListOptions) => Promise>> } & { [K in Exclude]?: Verb> } Omit when the forge has no notifications. list is derived from page .
installations? Verb> The implementation of provider.installations , except for list() and repos() , which core derives.
webhooks Managing registered hooks. Listings are declared as pages; core derives the iterables.
webhooks.listPage? Verb
webhooks.create? Verb
webhooks.update? Verb
webhooks.delete? Verb
webhooks.rotateSecret? Verb
webhooks.deliveriesPage? Verb
webhooks.redeliver? Verb
scopes()? (verb: ForgeVerb) => VerbScopes Token scopes or app permissions per verb, for provider.scopesFor() .
normaliseMarkdown()? (body: string) => string The implementation of provider.normaliseMarkdown() . Without it, Markdown is returned unchanged.
web? WebLinks How the forge's web pages are laid out; omit when they have no stable pattern.
request? Fetcher Fetcher behind request() , when it differs from the context fetcher.
probeVersion()? () => Promise Reads the instance version for refreshCapabilities() . Omit when capabilities never depend on it.
rateLimits()? () => RateLimit[] The implementation of provider.rateLimits() , for a provider whose requests bypass its fetchers.
### `MergeHooks` Hooks that a provider runs around a merge.
Member Type Description
beforeMerge()? () => Promise Runs before the merge request is sent, for example to wait for a pending state.
### `ProviderBase` The options, the identity and the resolved URLs that provider hooks receive. **type parameters:** `TOptions, TState`
Member Type Description
options TOptions
forge ForgeKind
instance ForgeInstance
baseUrl string API base after defaults and the API path are applied.
headers Record Default headers: the definition's, plus user-agent outside browsers or when the caller sets one.
origin Error context for this provider.
origin.forge ForgeKind
origin.instance ForgeInstance
state TState State passed to derive() , or created by prepare() .
### `ProviderContext` The argument of `setup()`: the base, the fetchers and `derive()`. **type parameters:** `TOptions, TState` **extends:** [`ProviderBase`](https://forges.link/contributing/provider-kit#providerbase)
Member Type Description
fetcher Fetcher Authenticated with the definition's authHeaders .
createFetcher() (overrides: Partial & { baseUrl: string }) => Fetcher Another fetcher with the same timeout, fetch and error context. It sends no credentials unless it sets its own authHeaders . Its budgets count towards provider.rateLimits() only when neither it nor fetcher sends credentials.
derive() (options: TOptions, state?: TState) => ForgeProvider Another provider from the same definition, for example one per app installation.
options TOptions Inherited from ProviderBase .
forge ForgeKind Inherited from ProviderBase .
instance ForgeInstance Inherited from ProviderBase .
baseUrl string API base after defaults and the API path are applied. Inherited from ProviderBase .
headers Record Default headers: the definition's, plus user-agent outside browsers or when the caller sets one. Inherited from ProviderBase .
origin Error context for this provider. Inherited from ProviderBase .
origin.forge ForgeKind Inherited from ProviderBase .
origin.instance ForgeInstance Inherited from ProviderBase .
state TState State passed to derive() , or created by prepare() . Inherited from ProviderBase .
### `ProviderDefinition` The defaults, the authentication and the `setup()` of a forge. **type parameters:** `TOptions extends ForgeOptionsBase, TState = undefined, HasWeb extends boolean = boolean, TExtensions extends object = Record`
Member Type Description
forge ForgeKind
experimental? true The forge's API as a whole is unstable, so the provider can change with it.
anonymous? true | 'webhooks' 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.
baseUrl string Default baseUrl when the caller passes none.
apiPath? string Appended to baseUrl unless already present, for example /api/v4 .
instance()? (host: string) => string Maps the API host to the instance host, for example api.github.com to github.com .
headers? Record
prepare()? (base: ProviderBase) => TState Builds per-provider state once; receives the state given to derive() , if any.
authHeaders()? (base: ProviderBase) => FetcherOptions['authHeaders'] Resolves the credential headers of each request.
query? Record Query parameters for every request, such as an API version; see FetcherOptions.query .
hasWeb? HasWeb Whether the forge has a website: setup() must then return web , and the provider's webOrigin is typed string .
setup() (ctx: ProviderContext) => HasWeb extends true ? ProviderSpec & { web: WebLinks } : ProviderSpec Declares the verbs and the web links of one provider.
webhooks? WebhookHandlers Delivery verification and translation. Omit it and webhooks.ingest() is unsupported.
### `WebhookHandlers` Verifies and translates deliveries for one provider; built once per instance from its context. **type parameters:** `TOptions` **type:** `(ctx: Omit, 'state' | 'derive'>) => { events: WebhookEventType[] verify: (delivery: WebhookDelivery) => Promise translate: (delivery: WebhookDelivery) => ForgeEventInput[] | Promise }` ### `defineForgeProvider()` Defines a forge provider. Returns the factory end users call, for example `github({ auth })`. Nothing touches the network until `create()`. ```ts function defineForgeProvider>(definition: ProviderDefinition): ProviderFactoryFunction & TExtensions> ```
Parameter Type Description
definition ProviderDefinition The defaults, authentication and setup of the forge.
**Returns:** `ProviderFactoryFunction & TExtensions>` ## Capability table ### `CapabilityEntry` 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.
Member Type Description
capability string Where the support lands on ForgeCapabilities , dot-separated.
spec? string Where the verb is declared on ProviderSpec , dot-separated.
verbs? readonly string[] Verbs on ForgeProvider this capability covers.
perKind? boolean Support is declared per thread kind.
derived? 'experimental' | 'poll' | 'webhook' | 'threadEvents' | 'upsertComment' | 'getComment' | 'getReview' | 'ciJob' | 'subscriptionSet' | 'approve' | 'approveAndMerge' | 'alertKinds' | 'eventKinds' | 'authKinds' | 'limits' The capability is computed by core rather than read from a declared verb.
write? boolean The verbs change state, so readOnly and anonymous providers reject them.
account? boolean The verbs need an account, so anonymous providers reject them.
### `CAPABILITY_TABLE` Every capability with the verbs it covers and the flags that gate it, in the order the capability matrix lists them. **type:** [`readonly CapabilityEntry[]`](https://forges.link/contributing/provider-kit#capabilityentry) ## Requests ### `FetcherOptions` Options for `createFetcher()`.
Member Type Default Description
baseUrl string
fetch? FetchLike Injected for tests and for runtimes with a non-global fetch.
timeout? number 30000 Timeout in milliseconds (headers only for streams).
headers? Record Default headers, sent only to the API origin.
authHeaders()? () => Promise> | Record Credentials resolved before each API-origin request.
authenticated? boolean Requests carry credentials that authHeaders does not set, for example through a fetch that signs them.
query? Record API-origin query defaults; request parameters take precedence.
context? ForgeErrorContext Attached to every error the fetcher throws.
onRetry()? (retry: { url: string, method: string, wait: number }) => void Called before a request is retried. A rate limit with a retry-after of at most a minute is retried once, after that wait.
onRateLimit()? (event: { url: string, method: string, rateLimit: RateLimit }) => void Called with the rate limit that a response from the base URL's origin reports, including a response that fails or is 304 Not Modified . Responses without rate limit headers don't call it.
### `RequestOptions` Options for one request of a fetcher. **extends:** `Omit`
Member Type Description
query? Record Query parameters. Parameters that are undefined are left out.
signal? AbortSignal
etag? string Send If-None-Match , and resolve with notModified instead of throwing.
json? unknown Serialised as the JSON request body, with a matching content-type .
mapError()? (error: unknown) => unknown Rewrites a failure from this request, for endpoints whose statuses mean something specific.
### `PaginateOptions` Options for reading one page of a paginated endpoint. **extends:** [`RequestOptions`](https://forges.link/contributing/provider-kit#requestoptions)
Member Type Default Description
select()? (body: unknown, linkNext?: string) => { items: unknown[], next?: string, total?: number } 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 . total is the item total the body reports, such as a search's total_count .
conditional? boolean true Whether the first page sends cursor.etag as If-None-Match and reports its validator in etag . Turn it off for a page that is built from more than this one response.
query? Record Query parameters. Parameters that are undefined are left out. Inherited from RequestOptions .
signal? AbortSignal Inherited from RequestOptions .
etag? string Send If-None-Match , and resolve with notModified instead of throwing. Inherited from RequestOptions .
json? unknown Serialised as the JSON request body, with a matching content-type . Inherited from RequestOptions .
mapError()? (error: unknown) => unknown Rewrites a failure from this request, for endpoints whose statuses mean something specific. Inherited from RequestOptions .
### `FetchResult` A parsed response. **type parameters:** `T`
Member Type Description
data T
response Response
notModified boolean The server answered 304 Not Modified to the etag that the request sent.
cursor? Cursor Where the next page starts, when there is one.
total? number The total number of items the listing reports, where the response carries one.
etag? string The validator of a listing's first page, from Fetcher.page .
### `Fetcher` A client for one forge API. It adds credentials, applies the timeout and retries, and maps failures to errors.
Member Type Description
raw() (path: string, options?: RequestOptions) => Promise Sends a request and returns the response unparsed.
stream() (path: string, options?: RequestOptions) => Promise Bytes as they arrive, through the same timeout and error mapping as 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.
json() (path: string, options?: RequestOptions) => Promise> Sends a request and parses the JSON body.
page() (path: string, options?: PaginateOptions & { cursor?: Cursor }) => Promise> One page: path with its query, or cursor.nextUrl when given. A first page, whose cursor has neither nextUrl nor token , sends cursor.etag as If-None-Match and reports the response's validator in etag .
items() (path: string, options?: PaginateOptions) => AsyncGenerator Every item across every page, in order.
resolve() (path: string, query?: RequestOptions['query']) => string The absolute URL of a path and query, without sending a request.
### `parseLinkHeader()` Parses an RFC 5988 `Link` header into a map of rel to URL. ```ts function parseLinkHeader(header: string | null | undefined): Record ```
Parameter Type
header string | null | undefined
**Returns:** `Record` ### `createFetcher()` Creates a fetcher for one forge API. ```ts function createFetcher(options: FetcherOptions): Fetcher ```
Parameter Type Description
options FetcherOptions The base URL and the credentials, timeout and error context of every request.
**Returns:** [`Fetcher`](https://forges.link/contributing/provider-kit#fetcher) ### `CreateRequestOptions` Options for `createRequest()`.
Member Type Description
readOnly()? (method: string, path: string) => Error Error for mutating requests.
### `createRequest()` Builds a provider's `request()` escape hatch on top of its fetcher. ```ts function createRequest(fetcher: Fetcher, createOptions: CreateRequestOptions = {}): ForgeRequest ```
Parameter Type Description
fetcher Fetcher The fetcher to send requests with.
createOptions? CreateRequestOptions Where to reject writes, for a read-only provider. Defaults to {} .
**Returns:** [`ForgeRequest`](https://forges.link/reference/requests#forgerequest) ## Webhooks and events ### `eventAction()` Normalises a forge-native verb (`closed`, `close`, `synchronize`, ...) into an [`EventAction`](https://forges.link/reference/data-model#eventaction). ```ts function eventAction(raw: string | undefined): EventAction | undefined ```
Parameter Type
raw string | undefined
**Returns:** [`EventAction | undefined`](https://forges.link/reference/data-model#eventaction) ### `completeEvent()` Fills `action` from `actionRaw`, or from the last `.`/`:` segment of `kindRaw`, falling back to the kind's default verb, then `other`. ```ts function completeEvent(event: ForgeEventInput): ForgeEvent ```
Parameter Type
event ForgeEventInput
**Returns:** [`ForgeEvent`](https://forges.link/reference/data-model#forgeevent) ### `reviewState()` Normalises a forge-native review verdict (`APPROVED`, `changes_requested`, ...) into a [`ReviewState`](https://forges.link/reference/data-model#reviewstate). ```ts function reviewState(raw: string | undefined): ReviewState ```
Parameter Type
raw string | undefined
**Returns:** [`ReviewState`](https://forges.link/reference/data-model#reviewstate) ### `verifyHmacSignature()` Checks a hex HMAC-SHA256 of the raw body, sent in the first of `header` present, after an optional `prefix` such as `sha256=`. The delivery's own `secret` takes precedence over the provider's. ```ts function verifyHmacSignature(delivery: WebhookDelivery, secret: string | undefined, { header, prefix = '' }: { header: string | readonly string[], prefix?: string }): Promise ```
Parameter Type
delivery WebhookDelivery
secret string | undefined
{ header, prefix = '' } { header: string | readonly string[], prefix?: string }
**Returns:** `Promise` ### `verifySharedToken()` Checks a secret sent verbatim in `header`. ```ts function verifySharedToken(delivery: WebhookDelivery, secret: string | undefined, header: string): boolean ```
Parameter Type
delivery WebhookDelivery
secret string | undefined
header string
**Returns:** `boolean` ### `RefChange` One ref update in a push delivery.
Member Type Description
ref string A full ref such as refs/heads/main , or a bare name when refType is given.
refType? 'branch' | 'tag' Whether the ref is a branch or a tag.
before? string
after? string
created? boolean
deleted? boolean
forced? boolean
commits? PushCommit[]
commitCount? number Commits pushed, when the forge reports more than it sends.
### `refEvent()` The kind, detail and summary of one ref update in a push: a deletion, a creation, or new commits. Without `commits` or `commitCount`, the detail has no `commitCount`. ```ts function refEvent(who: string, change: RefChange): Pick ```
Parameter Type
who string
change RefChange
**Returns:** [`Pick`](https://forges.link/contributing/provider-kit#forgeeventinput) ### `NativeEventMap` Native event names per normalised kind, as a forge names them in a hook subscription. **type:** [`Partial>`](https://forges.link/reference/data-model#eventkind) ### `nativeEventsFor()` The forge's own event names for `events`, plus any `nativeEvents` passed through unchanged. ```ts function nativeEventsFor(map: NativeEventMap, events: EventKind[] | undefined, nativeEvents: string[] | undefined): string[] ```
Parameter Type
map NativeEventMap
events EventKind[] | undefined
nativeEvents string[] | undefined
**Returns:** `string[]` ## Cryptography ### `toBase64()` Base64 for arbitrary bytes, a byte at a time so a large buffer cannot overflow the call stack. ```ts function toBase64(bytes: Uint8Array): string ```
Parameter Type
bytes Uint8Array
**Returns:** `string` ### `hmacSha256Hex()` Lowercase hex HMAC-SHA256 of `body` under `secret`. ```ts function hmacSha256Hex(secret: string, body: string | Uint8Array): Promise ```
Parameter Type
secret string
body string | Uint8Array
**Returns:** `Promise` ### `timingSafeEqual()` Constant-time comparison of two strings. The time taken depends only on the length of `a`, so pass the untrusted value as `a`. ```ts function timingSafeEqual(a: string, b: string): boolean ```
Parameter Type
a string
b string
**Returns:** `boolean` ### `JwtClaims` The claims of a signed JWT. Other claims are passed through.
Member Type Description
iss string The issuer, such as the app ID.
iat number When the token was issued, in seconds since the epoch.
exp number When the token expires, in seconds since the epoch.
### `signRs256Jwt()` Signs an RS256 JWT with a PEM-encoded RSA private key. ```ts function signRs256Jwt(privateKeyPem: string, claims: JwtClaims): Promise ```
Parameter Type
privateKeyPem string
claims JwtClaims
**Returns:** `Promise` ### `headerValue()` The value of a header, whatever the casing of `name`, from a `Headers` object or a plain record. ```ts function headerValue(headers: Headers | Record, name: string): string | undefined ```
Parameter Type
headers Headers | Record
name string
**Returns:** `string | undefined` ### `bodyText()` A request body as text. ```ts function bodyText(body: string | Uint8Array): string ```
Parameter Type
body string | Uint8Array
**Returns:** `string` ### `sha256Hex()` Lowercase hex SHA-256 of `body`. ```ts function sha256Hex(body: string | Uint8Array): Promise ```
Parameter Type
body string | Uint8Array
**Returns:** `Promise` ### `signEdDsaJwt()` Signs an EdDSA (Ed25519) JWT with a PKCS#8 PEM private key. `kid` goes in the JOSE header. ```ts function signEdDsaJwt(privateKeyPem: string, claims: JwtClaims, kid?: string): Promise ```
Parameter Type
privateKeyPem string
claims JwtClaims
kid? string
**Returns:** `Promise` ### `Ed25519Jwk` An Ed25519 public key in JWK form, as served from a JWKS endpoint.
Member Type Description
kty 'OKP' The key type, always OKP .
crv 'Ed25519' The curve, always Ed25519 .
x string The public key, base64url encoded.
kid? string
### `verifyEd25519()` Verifies an Ed25519 signature (base64) over `data` with a JWK public key. ```ts function verifyEd25519(jwk: Ed25519Jwk, data: string | Uint8Array, signatureBase64: string): Promise ```
Parameter Type
jwk Ed25519Jwk
data string | Uint8Array
signatureBase64 string
**Returns:** `Promise` ### `hmacSha256Base64()` Base64 HMAC-SHA256 of `body` under `secret`. ```ts function hmacSha256Base64(secret: string, body: string | Uint8Array): Promise ```
Parameter Type
secret string
body string | Uint8Array
**Returns:** `Promise` ## Helpers ### `supportOnly()` Marks every declared verb unsupported except the capabilities in `keep` and anything under them, for a credential that reaches only part of the API. **Example** ```ts return appItself ? supportOnly(spec, ['installations']) : spec ``` ```ts function supportOnly(spec: T, keep: readonly string[]): T ```
Parameter Type Description
spec T The spec that setup() declares.
keep readonly string[] Capability paths, such as installations , that stay as declared.
**Returns:** `T` ### `fromBase64()` Decodes base64, tolerating the newlines GitHub and Gitea wrap it in. ```ts function fromBase64(value: string): Uint8Array ```
Parameter Type
value string
**Returns:** `Uint8Array` ### `toFileContent()` Shapes bytes as the caller asked: UTF-8 text for `as: 'text'`, bytes otherwise. Rejects with [`ContentNotTextError`](https://forges.link/reference/errors#contentnottexterror) when text was asked for and the bytes are not valid UTF-8. ```ts function toFileContent(bytes: Uint8Array, file: FileMetadata, options: FileOptions | undefined, context?: { forge?: string, instance?: string }): FileContent ```
Parameter Type
bytes Uint8Array
file FileMetadata
options FileOptions | undefined
context? { forge?: string, instance?: string }
**Returns:** [`FileContent`](https://forges.link/reference/data-model#filecontent) ### `toMergeError()` Maps a generic merge-endpoint failure onto [`MergeBlockedError`](https://forges.link/reference/data-model#mergeblockederror) or [`MergeConflictError`](https://forges.link/reference/data-model#mergeconflicterror). ```ts function toMergeError(error: unknown): unknown ```
Parameter Type
error unknown
**Returns:** `unknown` ### `soleMergeMethod()` Picks the only allowed merge method, or throws [`MergeMethodRequiredError`](https://forges.link/reference/data-model#mergemethodrequirederror). ```ts function soleMergeMethod(allowed: Partial>, context?: ForgeErrorContext): MergeMethod ```
Parameter Type
allowed Partial>
context? ForgeErrorContext
**Returns:** [`MergeMethod`](https://forges.link/reference/data-model#mergemethod) ### `reactionContent()` The normalised name for a forge-native reaction name, or `'other'` where there is none. ```ts function reactionContent(raw: string): ReactionContent | 'other' ```
Parameter Type
raw string
**Returns:** [`ReactionContent | 'other'`](https://forges.link/reference/data-model#reactioncontent) ### `ForgeEventInput` A [`ForgeEvent`](https://forges.link/reference/data-model#forgeevent) as a provider builds it; core derives `action` when it is absent. **type:** `Omit & { action?: EventAction }` ### `forgeIterable()` Wraps a generator so warnings it reports are collected on the returned iterable rather than interrupting iteration. ```ts function forgeIterable(run: (warn: (warning: ForgeWarning) => void) => AsyncIterable): ForgeIterable ```
Parameter Type
run (warn: (warning: ForgeWarning) => void) => AsyncIterable
**Returns:** `ForgeIterable` ### `iteratePages()` Drives a `page()` function until it reports no further cursor, collecting page warnings. ```ts function iteratePages(page: (options: O) => Promise>, options: O = {} as O): ForgeIterable ```
Parameter Type Description
page (options: O) => Promise>
options? O Defaults to {} as O .
**Returns:** `ForgeIterable` ### `toWarning()` Turns a caught error into a serialisable warning. ```ts function toWarning(code: string, error: unknown, subject?: string): ForgeWarning ```
Parameter Type
code string
error unknown
subject? string
**Returns:** [`ForgeWarning`](https://forges.link/reference/requests#forgewarning) ### `mapConcurrent()` Maps with at most `limit` calls in flight, preserving order. Once a call rejects, no further calls start. ```ts function mapConcurrent(items: readonly T[], limit: number, fn: (item: T) => Promise): Promise ```
Parameter Type
items readonly T[]
limit number
fn (item: T) => Promise
**Returns:** `Promise` ### `getManyConcurrently()` `threads.getMany` for forges without a batch endpoint. A rate limit or a rejected credential rejects the call; other failures become per-item warnings. ```ts function getManyConcurrently(refs: ThreadRef[], get: (ref: ThreadRef, options?: BaseOptions) => Promise, options: BaseOptions = {}): Promise ```
Parameter Type Description
refs ThreadRef[]
get (ref: ThreadRef, options?: BaseOptions) => Promise
options? BaseOptions Defaults to {} .
**Returns:** [`Promise`](https://forges.link/reference/data-model#getmanyresult) ### `versionAtLeast()` Compares dotted numeric versions, ignoring any suffix after the numbers. ```ts function versionAtLeast(version: string | undefined, minimum: string): boolean ```
Parameter Type
version string | undefined
minimum string
**Returns:** `boolean` ### `toDate()` Reads a timestamp from a forge response, or `undefined` when it is empty or not a date. ```ts function toDate(value: string | number | null | undefined): Date | undefined ```
Parameter Type
value string | number | null | undefined
**Returns:** `Date | undefined` ### `hostOf()` The host of `baseUrl`, including the port when there is one. ```ts function hostOf(baseUrl: string): string ```
Parameter Type
baseUrl string
**Returns:** `string` ### `requireThread()` Narrows a ref to one a provider can address, or throws [`UnresolvedThreadError`](https://forges.link/reference/errors#unresolvedthreaderror). ```ts function requireThread(ref: ThreadRef, context?: ForgeErrorContext): ResolvedThreadRef ```
Parameter Type
ref ThreadRef
context? ForgeErrorContext
**Returns:** [`ResolvedThreadRef`](https://forges.link/reference/data-model#resolvedthreadref) ### `requireIssueOrPull()` Narrows a ref to an issue or pull request, or throws [`UnsupportedOperationError`](https://forges.link/reference/errors#unsupportedoperationerror) naming the verb that needs one. ```ts function requireIssueOrPull(ref: ThreadRef, context: ForgeErrorContext, verb: string): ResolvedThreadRef & { kind: 'issue' | 'pull_request' } ```
Parameter Type
ref ThreadRef
context ForgeErrorContext
verb string
**Returns:** [`ResolvedThreadRef & { kind: 'issue' | 'pull_request' }`](https://forges.link/reference/data-model#resolvedthreadref) ### `resolveToken()` The token in `auth`, read again on every call when it is a function. ```ts function resolveToken(auth: TokenAuth): Promise ```
Parameter Type
auth TokenAuth
**Returns:** `Promise` ### `actorLogin()` A login from either a login string or an actor. ```ts function actorLogin(actor: string | Actor): string ```
Parameter Type
actor string | Actor
**Returns:** `string` ### `toPage()` Maps one fetched page into a [`Page`](https://forges.link/reference/requests#page). The cursor is kept only when there is a next page. ```ts function toPage(result: FetchResult, map: (raw: R) => T | undefined, warnings?: ForgeWarning[]): Page ```
Parameter Type
result FetchResult
map (raw: R) => T | undefined
warnings? ForgeWarning[]
**Returns:** `Page` ### `ListingExtras` Extra options for a listing: the query, how to select the items and map errors, and where to collect warnings. **extends:** [`Pick`](https://forges.link/contributing/provider-kit#paginateoptions)
Member Type Description
warnings? ForgeWarning[] Collects the non-fatal warnings of the listing.
query? Record Query parameters. Parameters that are undefined are left out. Inherited from RequestOptions .
select()? (body: unknown, linkNext?: string) => { items: unknown[], next?: string, total?: number } 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 . total is the item total the body reports, such as a search's total_count . Inherited from PaginateOptions .
mapError()? (error: unknown) => unknown Rewrites a failure from this request, for endpoints whose statuses mean something specific. Inherited from RequestOptions .
### `Listing` One page of `path` as the model, with `options` mapped onto the forge's page-size parameter. **type:** `(path: string, options: PageOptions, map: (raw: R) => T | undefined, extras?: ListingExtras) => Promise>` ### `createListing()` Builds a [`Listing`](https://forges.link/contributing/provider-kit#listing) for a forge that names its page-size parameter `pageParam`. ```ts function createListing(fetcher: Fetcher, pageParam: string, defaultPerPage?: number): Listing ```
Parameter Type
fetcher Fetcher
pageParam string
defaultPerPage? number
**Returns:** [`Listing`](https://forges.link/contributing/provider-kit#listing) ### `phased()` Chains listings that a forge serves from separate endpoints. The cursor `token` records which phase is next, ahead of the phase's own token. With one phase, the first page is conditional as that phase's is; with more, one validator cannot cover every endpoint, so no page has an `etag`. ```ts function phased(phases: Array<(cursor?: Cursor) => Promise>>, cursor?: Cursor): Promise> ```
Parameter Type
phases Array<(cursor?: Cursor) => Promise>>
cursor? Cursor
**Returns:** `Promise>` ### `hasEveryLabel()` Whether `labels` include every name in `wanted`; true when nothing is wanted. ```ts function hasEveryLabel(labels: ReadonlyArray<{ name: string }> | undefined, wanted: readonly string[] | undefined): boolean ```
Parameter Type
labels ReadonlyArray<{ name: string }> | undefined
wanted readonly string[] | undefined
**Returns:** `boolean` ### `summariseChecks()` Any failure fails, else any pending is pending, else any unknown (or none at all) is unknown, else success. ```ts function summariseChecks(states: CheckState[], url?: string): ChecksSummary ```
Parameter Type
states CheckState[]
url? string
**Returns:** [`ChecksSummary`](https://forges.link/reference/data-model#checkssummary) ### `memo()` Caches the result of `load` after its first call. A rejected load is forgotten so the next call retries; with `ttl` (milliseconds) a resolved value is reloaded once it is older than that. ```ts function memo(load: () => Promise, ttl?: number): () => Promise ```
Parameter Type
load () => Promise
ttl? number
**Returns:** `() => Promise` ### `memoBy()` [`memo`](https://forges.link/contributing/provider-kit#memo) per key. ```ts function memoBy(load: (key: K) => Promise): (key: K) => Promise ```
Parameter Type
load (key: K) => Promise
**Returns:** `(key: K) => Promise` ### `syntheticReview()` A review standing in for an approval, vote or participant state on a forge that has no review objects. `comments` is `false` because there is nothing to hang inline comments on. ```ts function syntheticReview(thread: ResolvedThreadRef, id: string, state: ReviewState, extras: { author?: Actor, stateRaw?: string, submittedAt?: Date, raw: unknown }): Review ```
Parameter Type
thread ResolvedThreadRef
id string
state ReviewState
extras { author?: Actor, stateRaw?: string, submittedAt?: Date, raw: unknown }
**Returns:** [`Review`](https://forges.link/reference/data-model#review) ### `hexColour()` A label colour as six hex digits, with the `#` prefix the forge expects. `ededed` when none is given. ```ts function hexColour(colour: string | undefined, prefix: '#' | '' = ''): string ```
Parameter Type Description
colour string | undefined
prefix? '#' | '' Defaults to '' .
**Returns:** `string` ### `WebLinks` How a provider builds and reads its web URLs. Builders return a path relative to `baseUrl` or an absolute URL, and may return `undefined` when the forge has no such page.
Member Type Description
baseUrl string The base URL of the forge website, such as https://github.com or https://example.com/gitlab .
repo() (repo: RepoRef) => string The page of a repository.
section()? (repo: RepoRef, section: RepoSection) => string | undefined The page of one of a repository's sections, such as its issues, pull requests, stargazers or forks.
thread() (ref: ResolvedThreadRef) => string | undefined The page of an issue or pull request.
comment()? (ref: ResolvedCommentRef) => string | undefined The page of a comment, anchored on its thread.
release()? (ref: ReleaseRef) => string | undefined The page of a release.
file()? (repo: RepoRef, path: string, at: string, line?: number) => string | undefined The page of a file at a revision, optionally at a line.
raw()? (repo: RepoRef, path: string, at: string) => string | undefined The raw bytes of a file at a revision.
compare()? (repo: RepoRef, base: string, head: string) => string | undefined The page that compares two revisions.
parse() (segments: string[], url: URL, origin: ForgeOrigin) => ParsedForgeUrl | undefined Reads a URL already known to be under baseUrl , split into the path segments after it.
reference()? (ref: ResolvedThreadRef, sameRepo: boolean, expand: boolean) => string | undefined The forge's cross-reference syntax; undefined falls back to the thread URL.
### `GitHubShape` How a forge that lays out its website like GitHub differs from GitHub.
Member Type Description
pull string The path segment of pull requests, such as pull or pulls .
discussions? boolean The forge has discussions, which are addressed like issues.
commentFragment string Fragment for a comment id, for example issuecomment- or note_ .
file() (at: string) => string The path segment that leads to a file at a revision.
parseFile()? (segments: string[]) => { at: string, path: string } | undefined Reads a file page back from the segments after the repository name; defaults to blob/{at}/{path} .
commit? string The path segment of commits; defaults to commit .
raw? boolean Whether the forge serves raw files at /raw/{at}/{path} ; defaults to true .
rawOrigin? string The origin that serves raw files at /{owner}/{name}/{at}/{path} ; when unset, raw files are linked at /raw/{at}/{path} on the forge.
lineFragment() (line: number) => string The URL fragment that selects a line of a file.
pullPrefix? string Reference prefix for pulls when it differs from issues.
sections? Partial> Path segments for sections whose path is not the section's own name, such as a forge that lists stargazers at stars ; null marks a section the forge has no page for, so section() returns undefined for it.
reserved? readonly string[] Reserved owner segments.
### `githubShapedWeb()` Web links for forges laid out like GitHub: `/{owner}/{name}/issues/{n}` and friends. ```ts function githubShapedWeb(baseUrl: string, shape: GitHubShape): WebLinks ```
Parameter Type
baseUrl string
shape GitHubShape
**Returns:** [`WebLinks`](https://forges.link/contributing/provider-kit#weblinks) These exports are documented elsewhere: [`ProviderFactoryFunction`](https://forges.link/reference/providers#providerfactoryfunction). ## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.