Kontrakty i klient Trackera

Kontrakty to schematy Zod 4 wszystkiego, co API Trackera v1 wysyła i przyjmuje. Schematy nazywają się <Thing>Schema i mają odpowiadający im typ. Każda nazwa pola jest taka, jaką wysyła API, także w snake_case.

Eksportowane są też listy wartości, na których opierają się enumy:

Wartości domyślne: priorytet medium, czynność we wpisie czasu development, sortowanie -updated, 25 elementów na stronę.

import { CreateIssueInputSchema, normalizeInput } from '@skribly/core'
import { validate } from '@skribly/core/problem'

const input = validate(CreateIssueInputSchema, normalizeInput(await request.json()))

normalizeInput przycina ciągi znaków i zamienia puste ciągi na null, tak jak wydany Tracker. validate rzuca ProblemError ze statusem 422, a jego komunikaty brzmią jak komunikaty samego Trackera. Przekaż { translate }, aby linia taka jak tracker.errors.bad_date została przetłumaczona. toIso8601 formatuje znaczniki czasu z offsetem, tak jak wysyła je API.

import { createTrackerClient, ProblemError } from '@skribly/core'

const tracker = createTrackerClient({ baseUrl: 'http://localhost:8100', token })

const me = await tracker.whoami()
const page = await tracker.mine()
await tracker.setStatus('WEB-3', 'Done')

Nazwy metod pochodzą od wartości operationId z opisu OpenAPI Trackera, a dodatkowo dostępna jest metoda mine(). Są to operacje wymienione w dokumentacji API, na przykład getIssue, createIssue, updateIssue, comment, assign, logTime i search. Zwracają zawartość data, z wyjątkiem:

• listIssues i mine, które zwracają całą stronę wraz z links i meta;
• downloadAttachment, która zwraca surowy obiekt Response.

Każda odpowiedź jest sprawdzana względem schematów, więc klient nigdy nie pracuje z danymi spoza kontraktu.

try {
  await tracker.getIssue('WEB-404')
} catch (error) {
  if (error instanceof ProblemError && error.status === 404) console.log('No such issue')
  else throw error
}

@skribly/core przechowuje kopię opisu OpenAPI Trackera i plików językowych w swoich testach. Testy sprawdzają klienta i schematy względem pliku OpenAPI, a parser plików językowych i podpisy webhooków względem wyników wydanego Trackera. Ta witryna buduje dokumentację API z tego samego pliku, a jej build kończy się błędem, gdy kopia się rozjedzie.