---
title: Programmatic API
description: Run a provider-neutral Bugbot review through the request-only package API.
---

# Programmatic API

Import the API from `@vypdev/copilot/bugbot`. Construct
`BugbotReviewService` with provider-neutral findings and SCM ports, then pass a
single `BugbotReviewRequest` to `review`.

```ts
import {
  ApplicationError,
  BugbotReviewService,
  type BugbotReviewRequest,
  type BugbotScmGateway,
  type FindingsQueryPort,
  type MessageCatalogResolutionPort,
} from '@vypdev/copilot/bugbot';

const service = new BugbotReviewService(findingsPort, scmGateway);

const request: BugbotReviewRequest = {
  target: {
    kind: 'pull-request',
    number: 42,
    head: 'feature/42-checkout',
    base: 'develop',
  },
  agent: {
    provider: 'codex',
    modelProvider: 'openai',
    model: 'gpt-6-luna',
    executable: 'codex',
  },
  configuration: { publicationMode: 'dry-run', effort: 'high' },
};

try {
  const results = await service.review(request);
  for (const result of results) {
    for (const error of result.errors) console.error(error.toJSON());
  }
} catch (error) {
  if (error instanceof ApplicationError) console.error(error.toJSON());
  else throw error;
}
```

`target` is a discriminated union: use `kind: 'pull-request'` with a positive
PR number and head branch, or `kind: 'branch'` with a branch name. Runtime input
is validated and bounded even when JavaScript bypasses TypeScript.

The returned error array is readonly and contains only semantic
`ApplicationError` values. `toJSON()` exposes the safe message, code, category,
retry decision, impact, action, retained state, and correlation ID. It never
includes a token, provider payload, raw cause, stack, prompt, command arguments,
or local path.

`locale.issue` and `locale.pullRequest` accept canonicalizable BCP-47 tags and
default independently to `en-US`. Branch or issue-only publication uses the
issue locale; publication attached to a verified pull request uses the pull
request locale. Invalid tags and unknown locale keys fail before analysis or
publication.

The optional third constructor argument is a `MessageCatalogResolutionPort`.
English and Spanish are bundled. For any other valid locale, the service asks
that resolver for one complete catalog per review, including every cardinal
plural category required by the locale, and reuses it across the
status card, review snapshot, inline findings, overflow, and resolution notes.
An absent resolver, failed request, or incomplete response falls back atomically
to English; a review never mixes partially translated catalog entries. Dry-run,
skipped, superseded, and issue-only no-mutation paths do not resolve a
presentation catalog.

The API intentionally has no overload accepting the internal runtime aggregate
and does not export `Execution` or `Ai`. It also never accepts a token in the
request. Callers expose the bound `{ owner, name }` repository identity on the
`BugbotScmGateway` and keep its credentials closed inside the adapter before
constructing the service; review workflows
receive only capability methods. Internal orchestration and authority remain
package-owned.

Construction validates, copies, and freezes the gateway's `{ owner, name }`
identity. Mutating the caller-owned gateway object later cannot redirect a
review or desynchronize its operation context from the already-bound SCM
methods. An incomplete identity fails immediately with a semantic validation
error.

See [Application error reference](/security-operations/operations/error-reference)
for the stable code meanings and operator actions.