Check what a forge supports

provider.capabilities describes what a provider supports. The provider computes it without a network request. Capabilities explains the four values.

Call can() before an operation

A verb is the path of the method on the provider, such as threads.addLabels or webhooks.create. Pass the thread kind as well when support differs by kind:

if (gh.can('threads.addLabels', thread.ref.kind)) {
  await gh.threads.addLabels(thread.ref, ['triage'])
}

can() returns true for true, 'experimental', and 'emulated'. To treat experimental or emulated support differently, read the value from capabilities. Its keys follow the capability matrix, so threads.addLabels is capabilities.writes.addLabels:

const support = provider.capabilities.writes.addLabels.issue

Provide a fallback

Every method exists on every provider. A method for an unsupported operation rejects with UnsupportedOperationError. Check first, and choose what to do instead:

if (provider.can('threads.upsertComment', thread.ref.kind)) {
  await provider.threads.upsertComment(thread.ref, {
    key: 'ci-report',
    body,
  })
}
else {
  await provider.threads.comment(thread.ref, body)
}

Check a stored capabilities object

supports(capabilities, verb, kind?) gives the same answer from a plain capabilities object. Use it with capabilities that you stored or received from another process:

import { supports } from 'forges'

const canMerge = supports(saved, 'threads.merge')

Handle version-dependent capabilities

Some capabilities depend on the version of the instance. GitHub Enterprise Server supports marking notifications done from version 3.13, for example. Pass instanceVersion if you know it. Otherwise, call refreshCapabilities(), which reads the version once per provider and updates capabilities:

const capabilities = await forge.refreshCapabilities()

Find the scopes a verb needs

When can() is true but a call fails with InsufficientScopeError, use scopesFor().