Write a provider

A provider is one call to defineForgeProvider(). You declare each operation once, with verb(support, run), or with perKind(kinds, run) when support depends on the thread kind. Each declaration produces both the method and its capability entry.

In this excerpt from a provider's setup(), issue reads are experimental and getMany is unsupported:

const threads = {
  get: perKind({ issue: 'experimental' }, getIssue),
  listPage: perKind({ issue: 'experimental' }, listIssues),
  getMany: verb(false, async () => []),
}

forges adds the rest of the provider: capabilities, can(), the iterables (list from listPage, for example), readOnly, anonymous handling and a webhooks.ingest() that verifies each delivery before it translates it.

Declare operations

ProviderSpec in src/define.ts lists every operation and marks which ones are required. Declare a required operation that your forge lacks with verb(false, ...). Any other operation that you leave out, and any thread kind that you don't list, is false.

src/pushin/index.ts is a short provider to read as an example.

Handle webhooks

Webhook handlers go in the webhooks field of the definition. For a Lite variant, define a second factory from the same definition without webhooks.

Send requests

Use ctx.fetcher for requests. It applies the base URL, auth header, user agent, timeout and the caller's fetch, and it maps rate limits and revoked tokens to forges errors.

Run scripts without a build

Source files import each other with .ts extensions, so node scripts/<name>.ts runs without a build.

After you change a provider's capabilities, regenerate the capability matrix and the table on each provider page:

pnpm capability-matrix

Then record fixtures so that capabilities can be true.