@ycadence/sdk 0.1.0 → 0.2.0

package/src/client.ts

@@ -3,71 +3,111 @@
  *
  * Shared by the CLI, the MCP server and anyone integrating from TypeScript, so
  * there is one place that knows how to talk to the API — how errors are shaped,
- * how paging works, how a key is presented. Three separate implementations of
- * that would disagree, and the disagreement would surface as "the CLI works but
- * the MCP server does not".
+ * how paging works, how a key is presented, when a request is safe to retry.
+ * Three separate implementations of that would disagree, and the disagreement
+ * would surface as "the CLI works but the MCP server does not".
  */
 
+import { type ApiFailure, createError, RequestIntercepted, YCadenceError } from './errors'
+import { buildPath, isIdempotentMethod, OPERATIONS, type OperationId } from './operations'
+import { paginate } from './pagination'
+import type {
+  CreateViewInput,
+  CreateWorkItemInput,
+  Cycle,
+  CycleProgress,
+  Health,
+  ImportInput,
+  ImportPreview,
+  ImportRun,
+  IntakeItem,
+  Label,
+  ListWorkItemsOptions,
+  Me,
+  Page,
+  Project,
+  State,
+  SubmitIntakeInput,
+  SubmitIntakeResult,
+  TriageInput,
+  TriageResult,
+  UpdateWorkItemInput,
+  View,
+  WorkItem,
+  WorkItemDetail,
+} from './types'
+import { SDK_VERSION } from './version'
+
+export interface RetryOptions {
+  /** Attempts after the first. Default 2. `0` turns retrying off. */
+  retries?: number
+  /** First backoff, doubled each attempt, with jitter. Default 250ms. */
+  baseDelayMs?: number
+  /** Ceiling for one wait, including a server's `Retry-After`. Default 8s. */
+  maxDelayMs?: number
+}
+
+/** What happened to one HTTP exchange; for logging. Never carries credentials. */
+export interface ResponseInfo {
+  method: string
+  path: string
+  status: number
+  requestId: string | undefined
+  durationMs: number
+  attempt: number
+  replayed: boolean
+}
+
 export interface ClientOptions {
-  /** e.g. https://devpulse.yarlis.com. Trailing slashes are tolerated. */
+  /** e.g. https://ycadence.example.com. Trailing slashes are tolerated. */
   baseUrl: string
   apiKey: string
   /**
    * A Google identity token for an instance behind IAP or an authenticated
    * Cloud Run service, sent as `Authorization: Bearer`. The transport's
-   * credential and YCadence's are different things and travel in different
+   * credential and the product's are different things and travel in different
    * headers: the key always goes in `x-api-key`.
    *
    * A function is called before every request, because these tokens last
    * about an hour and a long-running caller — the MCP server — outlives one.
    */
-  identityToken?: string | (() => string | Promise<string>)
+  identityToken?: string | (() => string | undefined | Promise<string | undefined>)
   /** Defaults to 30s. A request that hangs forever is worse than one that fails. */
   timeoutMs?: number
   fetch?: typeof globalThis.fetch
+  /**
+   * Retries for 429, 5xx, timeouts and network errors. Only GET requests, and
+   * mutations sent with an idempotency key, are retried: repeating any other
+   * write could apply it twice.
+   */
+  retry?: RetryOptions
+  /** Prepended to the default `User-Agent`, e.g. `ycadence-cli/0.2.0`. */
+  userAgent?: string
+  /** Called after every response, including ones that are retried. */
+  onResponse?: (info: ResponseInfo) => void
+  /** Injected for tests; defaults to a timer. */
+  sleep?: (ms: number) => Promise<void>
 }
 
-export interface ApiFailure {
-  error: string
-  code: string
-  issues?: { path: string; message: string }[]
-}
-
-export class YCadenceError extends Error {
-  constructor(
-    readonly status: number,
-    readonly code: string,
-    message: string,
-    readonly issues?: ApiFailure['issues']
-  ) {
-    super(message)
-    this.name = 'YCadenceError'
-  }
-
-  /** Whether retrying unchanged could plausibly succeed. */
-  get retryable(): boolean {
-    return this.status === 429 || this.status >= 500
-  }
-}
-
-export interface WorkItem {
-  id: string
-  key: string
-  sequenceId: number
-  name: string
-  priority: 'urgent' | 'high' | 'medium' | 'low' | 'none'
-  stateId: string | null
-  assigneeIds: string[]
-  labelIds: string[]
-  parentId: string | null
-  sortOrder: string
-  createdAt: string
+/** Per-call options for any request. */
+export interface RequestOptions {
+  /**
+   * Sent as `Idempotency-Key` on a mutation, which also makes the mutation
+   * safe to retry. Servers that do not support the header ignore it.
+   */
+  idempotencyKey?: string
+  /**
+   * The version the caller last saw, sent as `If-Match: "<version>"`. A server
+   * that versions the resource answers 409 `version_conflict` or 412 when it
+   * has moved on; one that does not ignores the header.
+   */
+  expectedVersion?: number | string
+  signal?: AbortSignal
+  /** Overrides the client's retry count for this call. */
+  retries?: number
 }
 
-export interface Page<T> {
-  items: T[]
-  nextCursor: string | null
-}
+const DEFAULT_RETRY: Required<RetryOptions> = { retries: 2, baseDelayMs: 250, maxDelayMs: 8_000 }
 
 export class YCadenceClient {
   private readonly baseUrl: string
@@ -75,29 +115,71 @@ export class YCadenceClient {
   private readonly identityToken: ClientOptions['identityToken']
   private readonly timeoutMs: number
   private readonly doFetch: typeof globalThis.fetch
+  private readonly retry: Required<RetryOptions>
+  private readonly userAgent: string
+  private readonly onResponse: ClientOptions['onResponse']
+  private readonly sleep: (ms: number) => Promise<void>
 
-  constructor(options: ClientOptions) {
+  constructor(private readonly options: ClientOptions) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, '')
     this.apiKey = options.apiKey
     this.identityToken = options.identityToken
     this.timeoutMs = options.timeoutMs ?? 30_000
-    this.doFetch = options.fetch ?? globalThis.fetch
+    this.doFetch =
+      options.fetch ?? (((input, init) => globalThis.fetch(input, init)) as typeof globalThis.fetch)
+    this.retry = { ...DEFAULT_RETRY, ...options.retry }
+    this.userAgent = [options.userAgent, `ycadence-sdk/${SDK_VERSION}`]
+      .filter((part) => part !== undefined && part !== '')
+      .join(' ')
+    this.onResponse = options.onResponse
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  }
+
+  /** A copy of this client with some options replaced. */
+  withOptions(overrides: Partial<ClientOptions>): YCadenceClient {
+    return new YCadenceClient({ ...this.options, ...overrides })
+  }
+
+  /** The fetch this client sends with; for wrapping in `withOptions`. */
+  get fetchImplementation(): typeof globalThis.fetch {
+    return this.doFetch
+  }
+
+  async health(): Promise<Health> {
+    return this.call('health')
   }
 
-  async health(): Promise<{ status: string; checks: Record<string, string> }> {
-    return this.request('GET', '/api/health')
+  /** Who the credential is. A 404 means the server predates Slice 2A. */
+  async me(options?: RequestOptions): Promise<Me> {
+    return this.call('me', {}, undefined, undefined, options)
+  }
+
+  /** Projects the credential can read; `q` matches a name or identifier prefix. */
+  async listProjects(
+    query: { q?: string; archived?: boolean; limit?: number; cursor?: string } = {},
+    options?: RequestOptions
+  ): Promise<Page<Project>> {
+    return this.call('listProjects', {}, query, undefined, options)
   }
 
   async listWorkItems(
     projectId: string,
-    options: { filter?: unknown; limit?: number; cursor?: string } = {}
+    query: ListWorkItemsOptions = {},
+    options?: RequestOptions
   ): Promise<Page<WorkItem>> {
-    const query = new URLSearchParams()
-    if (options.filter !== undefined) query.set('filter', JSON.stringify(options.filter))
-    if (options.limit !== undefined) query.set('limit', String(options.limit))
-    if (options.cursor !== undefined) query.set('cursor', options.cursor)
-
-    return this.request('GET', `/api/v1/projects/${projectId}/work-items?${query}`)
+    return this.call(
+      'listWorkItems',
+      { projectId },
+      {
+        filter: query.filter === undefined ? undefined : JSON.stringify(query.filter),
+        limit: query.limit,
+        cursor: query.cursor,
+        state: query.state,
+        priority: query.priority,
+      },
+      undefined,
+      options
+    )
   }
 
   /**
@@ -107,131 +189,303 @@ export class YCadenceClient {
    * thousands of items, and a caller that wanted the first twenty should not
    * pay for all of them — nor should the process hold them all in memory.
    */
-  async *iterateWorkItems(
+  iterateWorkItems(
     projectId: string,
     options: { filter?: unknown; pageSize?: number } = {}
   ): AsyncGenerator<WorkItem> {
-    let cursor: string | undefined
-
-    do {
-      const page = await this.listWorkItems(projectId, {
+    return paginate((cursor) =>
+      this.listWorkItems(projectId, {
         filter: options.filter,
         limit: options.pageSize ?? 100,
         cursor,
       })
-      for (const item of page.items) yield item
-      cursor = page.nextCursor ?? undefined
-    } while (cursor !== undefined)
+    )
+  }
+
+  async createWorkItem(
+    projectId: string,
+    body: CreateWorkItemInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<WorkItem> {
+    return this.call('createWorkItem', { projectId }, undefined, body, options)
+  }
+
+  async getWorkItem(workItemId: string, options?: RequestOptions): Promise<WorkItemDetail> {
+    return this.call('getWorkItem', { workItemId }, undefined, undefined, options)
+  }
+
+  async updateWorkItem(
+    workItemId: string,
+    body: UpdateWorkItemInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<WorkItem> {
+    return this.call('updateWorkItem', { workItemId }, undefined, body, options)
+  }
+
+  async deleteWorkItem(workItemId: string, options?: RequestOptions): Promise<void> {
+    await this.call('deleteWorkItem', { workItemId }, undefined, undefined, options)
+  }
+
+  async listStates(projectId: string, options?: RequestOptions): Promise<{ states: State[] }> {
+    return this.call('listStates', { projectId }, undefined, undefined, options)
+  }
+
+  async listLabels(projectId: string, options?: RequestOptions): Promise<{ labels: Label[] }> {
+    return this.call('listLabels', { projectId }, undefined, undefined, options)
+  }
+
+  async createLabel(
+    projectId: string,
+    body: { name: string; color: string; description?: string },
+    options?: RequestOptions
+  ): Promise<Label> {
+    return this.call('createLabel', { projectId }, undefined, body, options)
   }
 
-  async createWorkItem(projectId: string, body: Record<string, unknown>): Promise<WorkItem> {
-    return this.request('POST', `/api/v1/projects/${projectId}/work-items`, body)
+  async listTypes(projectId: string, options?: RequestOptions): Promise<{ types: unknown[] }> {
+    return this.call('listTypes', { projectId }, undefined, undefined, options)
   }
 
-  async getWorkItem(workItemId: string): Promise<WorkItem & { description: string | null }> {
-    return this.request('GET', `/api/v1/work-items/${workItemId}`)
+  async listCycles(projectId: string, options?: RequestOptions): Promise<{ cycles: Cycle[] }> {
+    return this.call('listCycles', { projectId }, undefined, undefined, options)
   }
 
-  async updateWorkItem(workItemId: string, body: Record<string, unknown>): Promise<WorkItem> {
-    return this.request('PATCH', `/api/v1/work-items/${workItemId}`, body)
+  async createCycle(
+    projectId: string,
+    body: { name: string; description?: string; startDate?: string; endDate?: string },
+    options?: RequestOptions
+  ): Promise<Cycle> {
+    return this.call('createCycle', { projectId }, undefined, body, options)
+  }
+
+  async getCycleProgress(cycleId: string, options?: RequestOptions): Promise<CycleProgress> {
+    return this.call('getCycleProgress', { cycleId }, undefined, undefined, options)
+  }
+
+  async addWorkItemsToCycle(
+    cycleId: string,
+    workItemIds: string[],
+    options?: RequestOptions
+  ): Promise<{ added: number }> {
+    return this.call('addWorkItemsToCycle', { cycleId }, undefined, { workItemIds }, options)
+  }
+
+  async listViews(projectId: string, options?: RequestOptions): Promise<{ views: View[] }> {
+    return this.call('listViews', { projectId }, undefined, undefined, options)
+  }
+
+  async createView(
+    projectId: string,
+    body: CreateViewInput,
+    options?: RequestOptions
+  ): Promise<View> {
+    return this.call('createView', { projectId }, undefined, body, options)
+  }
+
+  async listIntake(
+    projectId: string,
+    query: { includeDecided?: boolean } = {},
+    options?: RequestOptions
+  ): Promise<{ items: IntakeItem[] }> {
+    return this.call('listIntake', { projectId }, query, undefined, options)
   }
 
-  async deleteWorkItem(workItemId: string): Promise<void> {
-    await this.request('DELETE', `/api/v1/work-items/${workItemId}`)
+  async submitIntake(
+    projectId: string,
+    body: SubmitIntakeInput,
+    options?: RequestOptions
+  ): Promise<SubmitIntakeResult> {
+    return this.call('submitIntake', { projectId }, undefined, body, options)
   }
 
-  async listStates(
-    projectId: string
-  ): Promise<{ states: { id: string; name: string; group: string }[] }> {
-    return this.request('GET', `/api/v1/projects/${projectId}/states`)
+  async triageIntake(
+    intakeItemId: string,
+    body: TriageInput,
+    options?: RequestOptions
+  ): Promise<TriageResult> {
+    return this.call('triageIntake', { intakeItemId }, undefined, body, options)
   }
 
-  async listLabels(projectId: string): Promise<{ labels: { id: string; name: string }[] }> {
-    return this.request('GET', `/api/v1/projects/${projectId}/labels`)
+  async previewImport(
+    projectId: string,
+    body: ImportInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<ImportPreview> {
+    return this.call('previewImport', { projectId }, undefined, body, options)
   }
 
-  async listCycles(
-    projectId: string
-  ): Promise<{ cycles: { id: string; name: string; status: string }[] }> {
-    return this.request('GET', `/api/v1/projects/${projectId}/cycles`)
+  async startImport(
+    projectId: string,
+    body: ImportInput | Record<string, unknown>,
+    options?: RequestOptions
+  ): Promise<{ runId: string }> {
+    return this.call('startImport', { projectId }, undefined, body, options)
   }
 
-  async previewImport(projectId: string, body: Record<string, unknown>): Promise<ImportPreview> {
-    return this.request('POST', `/api/v1/projects/${projectId}/imports/preview`, body)
+  async getImport(runId: string, options?: RequestOptions): Promise<ImportRun> {
+    return this.call('getImport', { runId }, undefined, undefined, options)
   }
 
-  async startImport(projectId: string, body: Record<string, unknown>): Promise<{ runId: string }> {
-    return this.request('POST', `/api/v1/projects/${projectId}/imports`, body)
+  async listImports(projectId: string, options?: RequestOptions): Promise<{ runs: ImportRun[] }> {
+    return this.call('listImports', { projectId }, undefined, undefined, options)
   }
 
-  async getImport(runId: string): Promise<ImportRun> {
-    return this.request('GET', `/api/v1/imports/${runId}`)
+  /** Call any operation in the table by id. */
+  async call<T>(
+    operation: OperationId,
+    params: Record<string, string> = {},
+    query?: Record<string, string | number | boolean | undefined>,
+    body?: unknown,
+    options: RequestOptions = {}
+  ): Promise<T> {
+    const { method, path } = OPERATIONS[operation]
+    let url = buildPath(path, params)
+    if (query !== undefined) {
+      const search = new URLSearchParams()
+      for (const [name, value] of Object.entries(query)) {
+        if (value !== undefined) search.set(name, String(value))
+      }
+      const encoded = search.toString()
+      if (encoded.length > 0) url += `?${encoded}`
+    }
+    return this.request<T>(method, url, body, options)
   }
 
-  async listImports(projectId: string): Promise<{ runs: ImportRun[] }> {
-    return this.request('GET', `/api/v1/projects/${projectId}/imports`)
+  private async request<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options: RequestOptions
+  ): Promise<T> {
+    const retryable = isIdempotentMethod(method) || options.idempotencyKey !== undefined
+    const retries = retryable ? (options.retries ?? this.retry.retries) : 0
+
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await this.send<T>(method, path, body, options, attempt)
+      } catch (error) {
+        const failure = error as YCadenceError
+        const again =
+          attempt < retries &&
+          typeof failure.retryable === 'boolean' &&
+          // 409 request_in_progress: the first request with this key is still
+          // running, so asking again later is exactly right.
+          (failure.retryable || failure.code === 'request_in_progress')
+        if (!again) throw error
+        await this.sleep(this.backoff(attempt, failure.retryAfter))
+      }
+    }
   }
 
-  async listViews(projectId: string): Promise<{ views: { id: string; name: string }[] }> {
-    return this.request('GET', `/api/v1/projects/${projectId}/views`)
+  private backoff(attempt: number, retryAfter: number | undefined): number {
+    if (retryAfter !== undefined) return Math.min(retryAfter * 1000, this.retry.maxDelayMs)
+    const exponential = this.retry.baseDelayMs * 2 ** attempt
+    // Full jitter on the upper half, so a fleet of clients does not retry in step.
+    const jittered = exponential / 2 + Math.random() * (exponential / 2)
+    return Math.min(jittered, this.retry.maxDelayMs)
   }
 
-  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  private async send<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options: RequestOptions,
+    attempt: number
+  ): Promise<T> {
     // An explicit timeout, because the default is none: a hung request holds a
     // CLI open until the user gives up, and blocks an agent indefinitely.
     const controller = new AbortController()
     const timer = setTimeout(() => controller.abort(), this.timeoutMs)
+    const abort = () => controller.abort()
+    options.signal?.addEventListener('abort', abort)
+    const started = Date.now()
 
     let response: Response
     try {
       const identityToken =
         typeof this.identityToken === 'function' ? await this.identityToken() : this.identityToken
 
+      const headers: Record<string, string> = {
+        // Never Authorization for the key: in front of IAP that header must
+        // carry the Google token, and a key there is rejected before the app runs.
+        'x-api-key': this.apiKey,
+        ...(identityToken === undefined || identityToken.length === 0
+          ? {}
+          : { Authorization: `Bearer ${identityToken}` }),
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        Accept: 'application/json',
+        'User-Agent': this.userAgent,
+      }
+      if (options.idempotencyKey !== undefined && !isIdempotentMethod(method)) {
+        headers['Idempotency-Key'] = options.idempotencyKey
+      }
+      if (options.expectedVersion !== undefined && !isIdempotentMethod(method)) {
+        headers['If-Match'] = `"${String(options.expectedVersion).replace(/"/g, '')}"`
+      }
+
       response = await this.doFetch(`${this.baseUrl}${path}`, {
         method,
-        headers: {
-          // Never Authorization: in front of IAP that header must carry the
-          // Google token, and a key there is rejected before the app runs.
-          'x-api-key': this.apiKey,
-          ...(identityToken === undefined || identityToken.length === 0
-            ? {}
-            : { Authorization: `Bearer ${identityToken}` }),
-          ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
-        },
+        headers,
         body: body === undefined ? undefined : JSON.stringify(body),
         signal: controller.signal,
       })
     } catch (error) {
+      if (error instanceof RequestIntercepted) throw error
       if (error instanceof Error && error.name === 'AbortError') {
-        throw new YCadenceError(
+        throw createError(
           408,
           'timeout',
-          `${method} ${path} timed out after ${this.timeoutMs}ms.`
+          `${method} ${path} timed out after ${this.timeoutMs}ms.`,
+          undefined,
+          { method, path }
         )
       }
-      throw new YCadenceError(
+      throw createError(
         0,
         'network_error',
-        `Could not reach ${this.baseUrl}: ${error instanceof Error ? error.message : 'unknown error'}`
+        `Could not reach ${this.baseUrl}: ${error instanceof Error ? error.message : 'unknown error'}`,
+        undefined,
+        { method, path }
       )
     } finally {
       clearTimeout(timer)
+      options.signal?.removeEventListener('abort', abort)
     }
 
+    const headerRequestId = response.headers?.get?.('x-request-id') ?? undefined
+    this.onResponse?.({
+      method,
+      path,
+      status: response.status,
+      requestId: headerRequestId,
+      durationMs: Date.now() - started,
+      attempt,
+      replayed: response.headers?.get?.('idempotent-replayed') === 'true',
+    })
+
     if (response.status === 204) return undefined as T
 
     const text = await response.text()
     const parsed = text.length === 0 ? undefined : safeJson(text)
 
     if (!response.ok) {
-      const failure = (parsed ?? {}) as ApiFailure
-      throw new YCadenceError(
+      const failure = (isRecord(parsed) ? parsed : {}) as Partial<ApiFailure>
+      throw createError(
         response.status,
-        failure.code ?? 'unknown',
+        typeof failure.code === 'string' ? failure.code : codeForStatus(response.status),
         // The server's message when there is one; the status only as a fallback,
         // so an unexpected error shape still produces something actionable.
-        failure.error ?? `${method} ${path} failed with ${response.status}.`,
-        failure.issues
+        typeof failure.error === 'string'
+          ? failure.error
+          : `${method} ${path} failed with ${response.status}.`,
+        failure.issues,
+        {
+          requestId: failure.requestId ?? headerRequestId,
+          details: failure.details,
+          retryAfter: parseRetryAfter(response.headers?.get?.('retry-after') ?? null),
+          method,
+          path,
+        }
       )
     }
 
@@ -247,34 +501,36 @@ function safeJson(text: string): unknown {
   }
 }
 
-export interface ImportPreview {
-  source: string
-  total: number
-  states: { name: string; suggestedStateId: string | null }[]
-  labels: { name: string; exists: boolean }[]
-  assignees: { value: string; matched: boolean }[]
-  skipped: { row: number; reason: string }[]
-  unmappedPriorities: string[]
-  /**
-   * False when re-importing would create duplicates rather than update — a CSV
-   * with no id column. Worth showing before the import, not after.
-   */
-  idempotent: boolean
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-export interface ImportRun {
-  id: string
-  source: string
-  status: string
-  totalItems: number
-  createdCount: number
-  updatedCount: number
-  cursor: number
-  skipped: { row: number; reason: string }[]
-  unmatched: { kind: string; value: string; item: string }[]
-  error: string | null
+function codeForStatus(status: number): string {
+  const codes: Record<number, string> = {
+    400: 'bad_request',
+    401: 'unauthorized',
+    403: 'forbidden',
+    404: 'not_found',
+    409: 'conflict',
+    412: 'precondition_failed',
+    422: 'validation_failed',
+    429: 'rate_limited',
+  }
+  return codes[status] ?? (status >= 500 ? 'server_error' : 'unknown')
 }
 
+/** Seconds, from either form `Retry-After` takes: a number or an HTTP date. */
+export function parseRetryAfter(value: string | null, now = Date.now()): number | undefined {
+  if (value === null || value.trim() === '') return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) return Math.max(0, seconds)
+  const date = Date.parse(value)
+  if (Number.isNaN(date)) return undefined
+  return Math.max(0, Math.ceil((date - now) / 1000))
+}
+
+export type { ImportPreview, ImportRun, Page, WorkItem } from './types'
+
 /**
  * @deprecated Renamed to {@link YCadenceClient}. This alias stays for one
  * release so existing integrations keep compiling.
@@ -283,6 +539,8 @@ export const DevPulseClient = YCadenceClient
 /** @deprecated Renamed to {@link YCadenceClient}. */
 export type DevPulseClient = YCadenceClient
 
+export { type ApiFailure, YCadenceError } from './errors'
+
 /**
  * @deprecated Renamed to {@link YCadenceError}. The alias is the same class,
  * so `error instanceof DevPulseError` still matches errors the client throws.