Capabilities

RepoCapabilities, capability gating, and how providers differ.

Providers are not identical. GitLab can date tags, GitHub can’t; Azure DevOps doesn’t support free-text repository search; only GitHub, GitLab, and Gitea emit release webhooks. Rather than hide these differences and silently drop options, repo-sdk advertises each provider’s capabilities and gates on them.

RepoCapabilities

Every provider exposes a capabilities object, also surfaced on client.capabilities:

const client = createClient({ provider: github({ auth: { token } }) });

client.capabilities.tagDates; // false for GitHub
client.capabilities.archiveFormats; // ['zip', 'tar.gz']
client.capabilities.webhookEvents; // ['push', 'tag_push', 'release']

Capability gating

When you pass an option a provider can’t honor, the client throws a RepoError with code unsupported before making a request — it never silently ignores it:

// Azure DevOps has no free-text repo search.
await client.repos.list({ query: 'checkout' });
// → RepoError { code: 'unsupported', provider: 'azure-devops' }

The same gating applies to:

• users.me() — requires userProfile
• repos.list({ query }) — requires repoSearch
• repos.list({ owned: true }) — requires ownedRepoFilter
• repos.downloadArchive({ format }) — the format must be in archiveFormats
• refs.search — requires refSearch
• webhooks.create / webhooks.update — every event must be in webhookEvents

Gate at runtime

Because capabilities are plain data, you can check them before offering a feature — for example, to hide a “search repositories” box when the active provider can’t search:

if (client.capabilities.repoSearch) {
  const { data } = await client.repos.list({ query: userInput });
}

if (client.capabilities.webhookEvents.includes('release')) {
  // offer release webhooks in the UI
}

Per-provider differences