@ikatec/digisac-api-sdk 3.1.0 → 4.0.0

package/src/core/BaseApiClient.test.ts

@@ -1,5 +1,20 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { BaseApiClient, ApiError } from './BaseApiClient'
+import { BaseApiClient } from './BaseApiClient'
+import {
+  ApiConnectionError,
+  ApiError,
+  AuthenticationError,
+  BadRequestError,
+  ConflictError,
+  DigisacError,
+  InternalServerError,
+  NotFoundError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  RateLimitError,
+  UnprocessableEntityError,
+  ValidationError,
+} from './errors'
 
 function mockFetch(response: {
   ok: boolean
@@ -216,21 +231,7 @@ describe('BaseApiClient', () => {
     })
   })
 
-  it('includes validationErrors from JSON error response', async () => {
-    const validationErrors = [{ path: 'name', message: 'required', code: 'REQUIRED' }]
-    mockFetch({
-      ok: false,
-      status: 422,
-      statusText: 'Unprocessable Entity',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message: 'Bad input', validationErrors }),
-    })
-    await expect(client.get('/fail')).rejects.toMatchObject({
-      validationErrors,
-    })
-  })
-
-  it('maps the Digisac field errors (errors.<location>.<field>) into validationErrors', async () => {
+  it('maps the backend field errors (errors.<location>.<field>) into validationErrors', async () => {
     mockFetch({
       ok: false,
       status: 400,
@@ -252,23 +253,58 @@ describe('BaseApiClient', () => {
         },
       }),
     })
-    await expect(client.post('/fail', {})).rejects.toMatchObject({
+    const error = await client.post('/fail', {}).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ValidationError)
+    expect(error).toBeInstanceOf(BadRequestError)
+    expect(error).toMatchObject({
+      message: 'The given data was invalid.',
       errorClass: 'ValidationError',
       status: 400,
       validationErrors: [
-        { path: 'body.name', message: 'Required.', code: 'required' },
-        { path: 'body.title', message: 'Required.', code: 'required' },
         {
+          location: 'body',
+          field: 'name',
+          path: 'body.name',
+          message: 'Required.',
+          code: 'required',
+        },
+        {
+          location: 'body',
+          field: 'title',
+          path: 'body.title',
+          message: 'Required.',
+          code: 'required',
+        },
+        {
+          location: 'body',
+          field: 'title',
           path: 'body.title',
           message: 'Should contain lesser than or equals 255 characters.',
           code: 'hasLengthLesserThanOrEqual',
         },
-        { path: 'params.contactId', message: 'Should be an UUID v4 string.', code: 'uuid4' },
+        {
+          location: 'params',
+          field: 'contactId',
+          path: 'params.contactId',
+          message: 'Should be an UUID v4 string.',
+          code: 'uuid4',
+        },
       ],
     })
   })
 
   it('keeps validationErrors null when the error body has no field errors', async () => {
+    mockFetch({
+      ok: false,
+      status: 400,
+      statusText: 'Bad Request',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ error: 'BadRequestHttpError', message: 'Já existe', status: 400 }),
+    })
+    await expect(client.get('/fail')).rejects.toMatchObject({ validationErrors: null })
+  })
+
+  it('ignores malformed field errors', async () => {
     mockFetch({
       ok: false,
       status: 400,
@@ -276,13 +312,138 @@ describe('BaseApiClient', () => {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         error: 'BadRequestHttpError',
-        message: 'Já existe uma funil com esse nome',
-        status: 400,
+        errors: { body: { name: 'Required.', title: { messages: 'Required.' } }, query: [] },
       }),
     })
     await expect(client.get('/fail')).rejects.toMatchObject({ validationErrors: null })
   })
 
+  it.each([
+    [400, BadRequestError],
+    [401, AuthenticationError],
+    [402, PaymentRequiredError],
+    [403, PermissionDeniedError],
+    [404, NotFoundError],
+    [409, ConflictError],
+    [422, UnprocessableEntityError],
+    [429, RateLimitError],
+    [500, InternalServerError],
+    [503, InternalServerError],
+  ])('throws the matching subclass for status %i', async (status, ErrorClass) => {
+    mockFetch({ ok: false, status, statusText: 'Error' })
+    const error = await client.get('/fail').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ErrorClass)
+    expect(error).toBeInstanceOf(ApiError)
+    expect(error).toBeInstanceOf(DigisacError)
+    expect(error).toMatchObject({ name: ErrorClass.name, status })
+  })
+
+  it('throws a plain ApiError for unmapped statuses', async () => {
+    mockFetch({ ok: false, status: 418, statusText: "I'm a teapot" })
+    const error = await client.get('/fail').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ApiError)
+    expect(Object.getPrototypeOf(error)).toBe(ApiError.prototype)
+    expect(error).toMatchObject({ name: 'ApiError', status: 418 })
+  })
+
+  it('exposes the response headers and the parsed body', async () => {
+    const body = { error: 'PaymentRequired', message: 'Limit', status: 402, extra: { limit: 10 } }
+    mockFetch({
+      ok: false,
+      status: 402,
+      statusText: 'Payment Required',
+      headers: { 'Content-Type': 'application/json', 'X-Request-Id': 'req-1' },
+      body: JSON.stringify(body),
+    })
+    const error = (await client.get('/fail').catch((e: unknown) => e)) as ApiError
+    expect(error.body).toEqual(body)
+    expect(error.headers?.get('X-Request-Id')).toBe('req-1')
+  })
+
+  it('exposes a non-JSON error body as text', async () => {
+    mockFetch({
+      ok: false,
+      status: 502,
+      statusText: 'Bad Gateway',
+      body: '<html>bad gateway</html>',
+    })
+    await expect(client.get('/fail')).rejects.toMatchObject({
+      message: 'HTTP Error 502: Bad Gateway',
+      body: '<html>bad gateway</html>',
+    })
+  })
+
+  it('reads Retry-After (seconds) on RateLimitError', async () => {
+    mockFetch({
+      ok: false,
+      status: 429,
+      statusText: 'Too Many Requests',
+      headers: { 'Retry-After': '30' },
+    })
+    const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+    expect(error.retryAfter).toBe(30)
+  })
+
+  it('reads Retry-After (HTTP date) on RateLimitError', async () => {
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') })
+    try {
+      mockFetch({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        headers: { 'Retry-After': 'Thu, 01 Jan 2026 00:01:00 GMT' },
+      })
+      const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+      expect(error.retryAfter).toBe(60)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('reads X-RateLimit-Reset (Unix seconds) on RateLimitError', async () => {
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') })
+    try {
+      mockFetch({
+        ok: false,
+        status: 429,
+        statusText: 'Too Many Requests',
+        headers: { 'X-RateLimit-Reset': String(Date.parse('2026-01-01T01:00:00Z') / 1000) },
+      })
+      const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+      expect(error.retryAfter).toBe(3600)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('returns null retryAfter when the header is absent', async () => {
+    mockFetch({ ok: false, status: 429, statusText: 'Too Many Requests' })
+    const error = (await client.get('/fail').catch((e: unknown) => e)) as RateLimitError
+    expect(error.retryAfter).toBeNull()
+  })
+
+  it('wraps network failures in ApiConnectionError', async () => {
+    const cause = new TypeError('fetch failed')
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(cause)
+    const error = await client.get('/fail').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ApiConnectionError)
+    expect(error).toBeInstanceOf(DigisacError)
+    expect(error).not.toBeInstanceOf(ApiError)
+    expect(error).toMatchObject({
+      message: 'Request to GET https://api.example.com/fail failed: fetch failed',
+      cause,
+    })
+  })
+
+  it('does not report a body serialization failure as a connection error', async () => {
+    const spy = vi.spyOn(globalThis, 'fetch')
+    const circular: Record<string, unknown> = {}
+    circular.self = circular
+    const error = await client.post('/fail', circular).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(TypeError)
+    expect(spy).not.toHaveBeenCalled()
+  })
+
   it('falls back to default message when JSON parsing fails', async () => {
     mockFetch({
       ok: false,

package/src/core/BaseApiClient.ts

@@ -1,65 +1,5 @@
 import type { ApiClient, HttpMethod } from './ApiClient'
-
-export interface ValidationError {
-  path: string
-  message: string
-  code: string
-}
-
-/**
- * Digisac field errors: `{ errors: { <location>: { <field>: { messages: string[], types: string[] } } } }`,
- * where location is `body`, `params`, `query`, `headers` or `cookies` (backend `validate` middleware).
- */
-type DigisacFieldErrors = Record<string, Record<string, { messages?: unknown; types?: unknown }>>
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-/**
- * Flattens the Digisac `errors` object into `ValidationError[]` — one entry per message, with
- * `path` = `<location>.<field>` (e.g. `body.name`) and `code` = the rule type (e.g. `required`).
- * Returns `null` when the body carries no field errors.
- */
-function parseValidationErrors(errors: unknown): ValidationError[] | null {
-  if (!isRecord(errors)) {
-    return null
-  }
-
-  const parsed: ValidationError[] = []
-  for (const [location, fields] of Object.entries(errors as DigisacFieldErrors)) {
-    if (!isRecord(fields)) {
-      continue
-    }
-    for (const [field, detail] of Object.entries(fields)) {
-      const messages = Array.isArray(detail?.messages) ? detail.messages.map(String) : []
-      const types = Array.isArray(detail?.types) ? detail.types.map(String) : []
-      messages.forEach((message, index) => {
-        parsed.push({ path: `${location}.${field}`, message, code: types[index] ?? types[0] ?? '' })
-      })
-    }
-  }
-
-  return parsed.length ? parsed : null
-}
-
-export class ApiError extends Error {
-  public readonly errorClass?: string | undefined
-  public readonly status?: number | undefined
-  public readonly validationErrors: ValidationError[] | null
-
-  constructor(
-    message: string,
-    errorClass?: string,
-    status?: number,
-    validationErrors: ValidationError[] | null = null,
-  ) {
-    super(message)
-    this.name = 'ApiError'
-    this.errorClass = errorClass
-    this.status = status
-    this.validationErrors = validationErrors
-  }
-}
+import { ApiConnectionError, ApiError } from './errors'
 
 export class BaseApiClient implements ApiClient {
   protected readonly baseUrl: string
@@ -82,8 +22,7 @@ export class BaseApiClient implements ApiClient {
     headers?: Record<string, string>,
   ): Promise<TResponse> {
     const url = `${this.baseUrl}/${endpoint.replace(/^\//, '')}`
-
-    const response = await fetch(url, {
+    const init: RequestInit = {
       method,
       headers: {
         'Content-Type': 'application/json',
@@ -91,35 +30,29 @@ export class BaseApiClient implements ApiClient {
         ...headers,
       },
       ...(body !== undefined && { body: JSON.stringify(body) }),
-    })
+    }
+
+    let response: Response
+    try {
+      response = await fetch(url, init)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      throw new ApiConnectionError(`Request to ${method} ${url} failed: ${reason}`, {
+        cause: error,
+      })
+    }
 
     return this.handleResponse<TResponse>(response)
   }
 
   protected async handleResponse<TResponse>(response: Response): Promise<TResponse> {
     if (!response.ok) {
-      const contentType = response.headers.get('Content-Type')
-      const isJson = contentType?.includes('application/json') ?? false
-
-      let errorMessage = `HTTP Error ${response.status}: ${response.statusText}`
-      let errorClass: string | undefined
-      let validationErrors: ValidationError[] | null = null
-
-      if (isJson) {
-        try {
-          const errorText = await response.text()
-          if (errorText) {
-            const errorData = JSON.parse(errorText)
-            errorMessage = errorData.message || errorData.error || errorMessage
-            errorClass = errorData.error
-            validationErrors = errorData.validationErrors ?? parseValidationErrors(errorData.errors)
-          }
-        } catch {
-          // If JSON parsing fails, use the default error message
-        }
-      }
-
-      throw new ApiError(errorMessage, errorClass, response.status, validationErrors)
+      throw ApiError.fromResponse(
+        response.status,
+        response.statusText,
+        response.headers,
+        await this.readErrorBody(response),
+      )
     }
 
     // 204 No Content never has a body; short-circuit before reading the stream.
@@ -151,6 +84,24 @@ export class BaseApiClient implements ApiClient {
     }
   }
 
+  /** Reads an error body: parsed JSON when possible, the raw text otherwise, `undefined` when empty. */
+  protected async readErrorBody(response: Response): Promise<unknown> {
+    let text: string
+    try {
+      text = await response.text()
+    } catch {
+      return undefined
+    }
+    if (!text) {
+      return undefined
+    }
+    try {
+      return JSON.parse(text)
+    } catch {
+      return text
+    }
+  }
+
   get<TResponse = unknown>(endpoint: string, headers?: Record<string, string>): Promise<TResponse> {
     return this.request<TResponse>('GET', endpoint, undefined, headers)
   }

package/src/core/BaseCrudApi.test-d.ts

@@ -0,0 +1,48 @@
+import { expectError, expectType } from 'tsd'
+import type { ApiClient } from './ApiClient'
+import { BaseCrudApi } from './BaseCrudApi'
+import type { Paginated } from './types'
+
+// ── Test model ──────────────────────────────────────────────────────
+
+type Item = { id: string; name: string; tags?: { id: string; label: string }[] }
+type CreateItem = { name: string }
+type UpdateItem = { name?: string }
+
+declare const client: ApiClient
+const api = new BaseCrudApi<Item, CreateItem, UpdateItem>(client, '/items')
+
+// ── getMany overloads ───────────────────────────────────────────────
+
+expectType<Promise<Paginated<Item>>>(api.getMany())
+expectType<Promise<Paginated<Item>>>(api.getMany({ page: 1 }))
+expectType<Promise<Paginated<Item>>>(api.getMany({ paginate: true }))
+expectType<Promise<Item[]>>(api.getMany({ paginate: false }))
+expectType<Promise<Item[]>>(api.getMany({ where: { name: 'x' }, paginate: false }))
+
+// ── getOne / getById ────────────────────────────────────────────────
+
+expectType<Promise<Item | null>>(api.getOne())
+expectType<Promise<Item | null>>(api.getOne({ where: { name: 'x' } }))
+expectType<Promise<Item>>(api.getById('1'))
+expectType<Promise<Item>>(api.getById('1', { include: ['tags'], attributes: ['id'] }))
+
+// getById only accepts include/attributes
+expectError(api.getById('1', { where: { name: 'x' } }))
+expectError(api.getById('1', { attributes: ['missing'] }))
+
+// ── create / updateById / deleteById ────────────────────────────────
+
+expectType<Promise<Item>>(api.create({ name: 'x' }))
+expectType<Promise<Item>>(api.updateById('1', {}))
+expectType<Promise<Item>>(api.deleteById('1'))
+
+expectError(api.create({}))
+expectError(api.create({ name: 1 }))
+expectError(api.updateById('1', { name: 1 }))
+
+// ── Query typing ────────────────────────────────────────────────────
+
+expectError(api.getMany({ where: { missing: 'x' } }))
+expectError(api.getMany({ order: [['missing', 'ASC']] }))
+expectError(api.getMany({ include: ['name'] }))

package/src/core/BaseCrudApi.test.ts

@@ -8,6 +8,10 @@ import type { Paginated } from './types'
 type Item = { id: string; name: string }
 type CreateItem = { name: string }
 type UpdateItem = { name?: string }
+type ItemWithTags = Item & {
+  owner?: { id: string; name: string }
+  tags?: { id: string; label: string }[]
+}
 
 // ── Mock client factory ──────────────────────────────────────────────
 
@@ -23,6 +27,11 @@ function createMockClient(): ApiClient {
   }
 }
 
+/** The URL passed to the nth `client.get` call, with the query string percent-decoded. */
+function calledUrl(client: ApiClient, call = 0): string {
+  return decodeURIComponent(vi.mocked(client.get).mock.calls.at(call)?.at(0) as string)
+}
+
 // ── Tests ────────────────────────────────────────────────────────────
 
 describe('BaseCrudApi', () => {
@@ -73,6 +82,30 @@ describe('BaseCrudApi', () => {
     })
   })
 
+  describe('method binding', () => {
+    it('keeps `this` when methods are destructured', async () => {
+      vi.mocked(client.get).mockResolvedValue([{ id: '1', name: 'x' }])
+      vi.mocked(client.post).mockResolvedValue({ id: '1', name: 'x' })
+      vi.mocked(client.put).mockResolvedValue({ id: '1', name: 'x' })
+      vi.mocked(client.delete).mockResolvedValue({ id: '1', name: 'x' })
+      const { getMany, getOne, getById, create, updateById, deleteById } = api
+
+      await getMany({ paginate: false })
+      await getOne()
+      await getById('1')
+      await create({ name: 'x' })
+      await updateById('1', { name: 'x' })
+      await deleteById('1')
+
+      expect(calledUrl(client, 0)).toBe('/items?paginate=false')
+      expect(calledUrl(client, 1)).toBe('/items?limit=1&paginate=false')
+      expect(calledUrl(client, 2)).toBe('/items/1')
+      expect(client.post).toHaveBeenCalledWith('/items', { name: 'x' }, undefined)
+      expect(client.put).toHaveBeenCalledWith('/items/1', { name: 'x' }, undefined)
+      expect(client.delete).toHaveBeenCalledWith('/items/1', undefined)
+    })
+  })
+
   // ── getMany ──────────────────────────────────────────────────────
 
   describe('getMany', () => {
@@ -122,6 +155,27 @@ describe('BaseCrudApi', () => {
       expect(client.get).toHaveBeenCalledWith('/items', headers)
     })
 
+    it('returns the plain array when paginate is false', async () => {
+      const items: Item[] = [{ id: '1', name: 'a' }]
+      vi.mocked(client.get).mockResolvedValue(items)
+
+      const result = await api.getMany({ paginate: false })
+      expect(calledUrl(client)).toBe('/items?paginate=false')
+      expect(result).toEqual(items)
+    })
+
+    it('omits undefined query values', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      // Explicit undefined is rejected by exactOptionalPropertyTypes but reaches the SDK from JS
+      // callers or from consumers compiled without that flag.
+      const query = { page: 2, perPage: undefined, where: { name: undefined } } as unknown as {
+        page: number
+      }
+      await api.getMany(query)
+      expect(calledUrl(client)).toBe('/items?page=2')
+    })
+
     it('forwards headers with query', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
       const headers = { Authorization: 'Bearer token' }
@@ -146,6 +200,29 @@ describe('BaseCrudApi', () => {
       expect(result).toEqual(item)
     })
 
+    it('keeps the caller query and forces limit 1 and paginate false', async () => {
+      vi.mocked(client.get).mockResolvedValue([])
+
+      await api.getOne({
+        where: { name: 'x' },
+        order: [['name', 'DESC']],
+        limit: 50,
+        paginate: true,
+      })
+      expect(calledUrl(client)).toBe(
+        '/items?where[name]=x&order[0][0]=name&order[0][1]=DESC&limit=1&paginate=false',
+      )
+    })
+
+    it('returns only the first item when the API returns more than one', async () => {
+      vi.mocked(client.get).mockResolvedValue([
+        { id: '1', name: 'a' },
+        { id: '2', name: 'b' },
+      ])
+
+      expect(await api.getOne()).toEqual({ id: '1', name: 'a' })
+    })
+
     it('returns null when no records match', async () => {
       vi.mocked(client.get).mockResolvedValue([])
 
@@ -174,6 +251,21 @@ describe('BaseCrudApi', () => {
       expect(result).toEqual(item)
     })
 
+    it('serializes include and attributes into the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue({ id: 'abc', name: 'Test' })
+
+      await api.getById('abc', { attributes: ['id', 'name'] })
+      expect(calledUrl(client)).toBe('/items/abc?attributes[0]=id&attributes[1]=name')
+    })
+
+    it('forwards query and headers together', async () => {
+      vi.mocked(client.get).mockResolvedValue({ id: '1', name: 'x' })
+      const headers = { 'X-Tenant': '123' }
+
+      await api.getById('1', { attributes: ['id'] }, headers)
+      expect(client.get).toHaveBeenCalledWith('/items/1?attributes%5B0%5D=id', headers)
+    })
+
     it('forwards custom headers', async () => {
       vi.mocked(client.get).mockResolvedValue({ id: '1', name: 'x' })
       const headers = { 'X-Tenant': '123' }
@@ -269,6 +361,17 @@ describe('BaseCrudApi', () => {
       await expect(api.updateById('1', { name: 'x' })).rejects.toThrow('Conflict')
     })
 
+    it('propagates errors from client.get in getOne', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Unauthorized'))
+      await expect(api.getOne()).rejects.toThrow('Unauthorized')
+    })
+
+    it('rethrows the client error instance unchanged', async () => {
+      const error = Object.assign(new Error('Bad request'), { status: 400 })
+      vi.mocked(client.post).mockRejectedValue(error)
+      await expect(api.create({ name: 'bad' })).rejects.toBe(error)
+    })
+
     it('propagates errors from client.delete in deleteById', async () => {
       vi.mocked(client.delete).mockRejectedValue(new Error('Forbidden'))
       await expect(api.deleteById('1')).rejects.toThrow('Forbidden')
@@ -297,6 +400,53 @@ describe('BaseCrudApi', () => {
       expect(calledUrl).toContain('ASC')
     })
 
+    it('serializes nested include with where and include', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const tagsApi = new BaseCrudApi<ItemWithTags, CreateItem>(client, '/items')
+
+      await tagsApi.getMany({
+        include: ['owner', { model: 'tags', where: { label: 'vip' }, required: true }],
+      })
+      expect(calledUrl(client)).toBe(
+        '/items?include[0]=owner&include[1][model]=tags&include[1][where][label]=vip&include[1][required]=true',
+      )
+    })
+
+    it('serializes $in arrays with indices', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { id: { $in: ['a', 'b'] } } })
+      expect(calledUrl(client)).toBe('/items?where[id][$in][0]=a&where[id][$in][1]=b')
+    })
+
+    it('serializes $or/$and combinators', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { $or: [{ name: 'a' }, { name: 'b' }] } })
+      expect(calledUrl(client)).toBe('/items?where[$or][0][name]=a&where[$or][1][name]=b')
+    })
+
+    it('serializes order exactly', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({
+        order: [
+          ['name', 'ASC'],
+          ['id', 'desc'],
+        ],
+      })
+      expect(calledUrl(client)).toBe(
+        '/items?order[0][0]=name&order[0][1]=ASC&order[1][0]=id&order[1][1]=desc',
+      )
+    })
+
+    it('serializes booleans and numbers as strings', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ paranoid: false, distinct: true, limit: 10, offset: 20 })
+      expect(calledUrl(client)).toBe('/items?paranoid=false&distinct=true&limit=10&offset=20')
+    })
+
     it('handles empty query object', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 

package/src/core/errors.test-d.ts

@@ -0,0 +1,14 @@
+import { expectAssignable, expectType } from 'tsd'
+import type { ApiError, ErrorClassName, FieldError, ValidationError } from './errors'
+
+declare const apiError: ApiError
+declare const validationError: ValidationError
+
+// ValidationError always carries an array; ApiError may not
+expectType<FieldError[]>(validationError.validationErrors)
+expectType<FieldError[] | null>(apiError.validationErrors)
+
+// errorClass accepts the known backend names and any other string
+expectAssignable<ErrorClassName>('PaymentRequired')
+expectAssignable<ErrorClassName>('SomeFutureError')
+expectType<ErrorClassName | undefined>(apiError.errorClass)