JavaScript / TypeScript

@coa/adjudicate is a small TypeScript client over the Integration API. It’s dependency-free (uses the platform fetch, so it runs in Node 18+ and the browser), fully typed, and includes the auth exchange — so you go from credentials to typed appeal data in a few lines.

Install

The package is distributed to integration partners (it isn’t on the public registry). Once you have access:

npm install @coa/adjudicate
import {signIn, AdjudicateClient} from '@coa/adjudicate'

Authenticate

signIn exchanges a username + password for a bearer token via the API’s token endpoint — one HTTPS call, no extra config:

const {idToken, refreshToken} = await signIn({
  baseUrl: '<api-base-url>',
  username: '<you>',
  password: '<your-password>',
})

If you already hold a token (e.g. from a browser sign-in), skip signIn and pass it straight to the client.

Create a client

const adj = new AdjudicateClient({
  baseUrl: '<api-base-url>',   // https://….execute-api.us-east-1.amazonaws.com
  token: idToken,
})

Methods

appeals.list()

Every appeal in the environment, most-recently-uploaded first.

const appeals = await adj.appeals.list()
// Appeal[] — { id, docketNumber, veteran: {firstName, middleName?, lastName}, uploadedAt }

appeals.get(appealId)

const {appeal, documentCount} = await adj.appeals.get(appeals[0].id)

documents.list(appealId)

Documents in attorney-arranged order, each with its categories and tags.

const docs = await adj.documents.list(appealId)
// AdjudicateDocument[] — { id, name, startPage, endPage, position,
//                          receiptDate, description, categories, tags }

documents.get(appealId, docId)

const doc = await adj.documents.get(appealId, docId)

search(appealId, query)

Full-text search across every page of the appeal’s documents.

const {hits} = await adj.search(appealId, 'tinnitus')
// hits: { page: number, snippet: string }[]

Tags — tags.add / tags.remove

await adj.tags.add(appealId, docId, 'Issue: Tinnitus')
await adj.tags.remove(appealId, docId, 'Issue: Tinnitus')

Annotations — annotations.create / annotations.delete

const {annotation} = await adj.annotations.create(appealId, docId, {
  page: 3, x: 0.41, y: 0.18,
  comment: 'Tinnitus reported in 2018 STRs',
  relevantDate: '2018-04-12',
})
await adj.annotations.delete(appealId, docId, annotation.id)

Created tags and annotations appear on the document (tags, annotations) on the next read, each stamped with the authenticated caller as createdBy.

Errors

Non-2xx responses throw an AdjudicateError carrying the HTTP status:

import {AdjudicateError} from '@coa/adjudicate'

try {
  await adj.appeals.get('does-not-exist')
} catch (err) {
  if (err instanceof AdjudicateError && err.status === 404) {
    // appeal not found
  }
}

401 means the token is missing or expired — re-signIn (or refresh) and retry.

Types

The package ships its types; the key shapes are Appeal, Veteran, AdjudicateDocument, Annotation, NewAnnotation, SearchHit, and SearchResult. Each mirrors the API reference response shapes exactly — the SDK adds types and auth, not a different contract.