@ikatec/digisac-api-sdk 3.1.0 → 4.1.0

package/src/core/BaseApiClient.ts

@@ -1,73 +1,21 @@
 import type { ApiClient, HttpMethod } from './ApiClient'
+import { ApiConnectionError, ApiError } from './errors'
+import { DEFAULT_QUERY_FORMAT, type QueryFormat } from './queryString'
 
-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
-  }
+export interface BaseApiClientOptions {
+  /** How list/get queries are serialized in the URL. Defaults to `'json'`. */
+  queryFormat?: QueryFormat
 }
 
 export class BaseApiClient implements ApiClient {
   protected readonly baseUrl: string
   protected accessToken: string | null = null
+  public readonly queryFormat: QueryFormat
 
-  constructor(baseUrl: string, accessToken?: string) {
+  constructor(baseUrl: string, accessToken?: string, options: BaseApiClientOptions = {}) {
     this.baseUrl = baseUrl.replace(/\/$/, '')
     this.accessToken = accessToken || null
+    this.queryFormat = options.queryFormat ?? DEFAULT_QUERY_FORMAT
   }
 
   setAccessToken(accessToken: string): this {
@@ -82,8 +30,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 +38,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 +92,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,57 @@
+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 }))
+
+declare const paginate: boolean
+expectType<Promise<Paginated<Item> | Item[]>>(api.getMany({ paginate }))
+
+// ── 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'] }))
+
+// ── withQueryFormat ─────────────────────────────────────────────────
+
+expectType<typeof api>(api.withQueryFormat('qs'))
+expectType<Promise<Item[]>>(api.withQueryFormat('json').getMany({ paginate: false }))
+expectError(api.withQueryFormat('xml'))

package/src/core/BaseCrudApi.test.ts

@@ -1,18 +1,24 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { BaseCrudApi } from './BaseCrudApi'
 import type { ApiClient } from './ApiClient'
+import type { QueryFormat } from './queryString'
 import type { Paginated } from './types'
 
 // ── Test types ───────────────────────────────────────────────────────
 
-type Item = { id: string; name: string }
+type Item = { id: string; name: string; deletedAt?: string | null }
 type CreateItem = { name: string }
 type UpdateItem = { name?: string }
+type ItemWithTags = Item & {
+  owner?: { id: string; name: string }
+  tags?: { id: string; label: string }[]
+}
 
 // ── Mock client factory ──────────────────────────────────────────────
 
-function createMockClient(): ApiClient {
+function createMockClient(queryFormat?: QueryFormat): ApiClient {
   return {
+    ...(queryFormat && { queryFormat }),
     setAccessToken: vi.fn().mockReturnThis(),
     request: vi.fn(),
     get: vi.fn(),
@@ -23,6 +29,23 @@ 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)
+}
+
+/** The path of the nth `client.get` call, without the query string. */
+function calledPath(client: ApiClient, call = 0): string {
+  return (vi.mocked(client.get).mock.calls.at(call)?.at(0) as string).split('?')[0] as string
+}
+
+/** The query sent by the nth `client.get` call, decoded from `?query=<JSON>`. */
+function calledQuery(client: ApiClient, call = 0): unknown {
+  const url = vi.mocked(client.get).mock.calls.at(call)?.at(0) as string
+  const json = new URLSearchParams(url.split('?')[1] ?? '').get('query')
+  return json === null ? undefined : JSON.parse(json)
+}
+
 // ── Tests ────────────────────────────────────────────────────────────
 
 describe('BaseCrudApi', () => {
@@ -73,6 +96,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(calledQuery(client, 0)).toEqual({ paginate: false })
+      expect(calledQuery(client, 1)).toEqual({ 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', () => {
@@ -98,20 +145,15 @@ describe('BaseCrudApi', () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 
       await api.getMany({ page: 2, perPage: 25 })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('/items?')
-      expect(calledUrl).toContain('page=2')
-      expect(calledUrl).toContain('perPage=25')
+      expect(calledPath(client)).toBe('/items')
+      expect(calledQuery(client)).toEqual({ page: 2, perPage: 25 })
     })
 
     it('serializes where clause into query string', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 
       await api.getMany({ where: { name: 'test' } })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('where')
-      expect(calledUrl).toContain('name')
-      expect(calledUrl).toContain('test')
+      expect(calledQuery(client)).toEqual({ where: { name: 'test' } })
     })
 
     it('forwards custom headers', async () => {
@@ -122,6 +164,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(calledQuery(client)).toEqual({ 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(calledQuery(client)).toEqual({ page: 2, where: {} })
+    })
+
     it('forwards headers with query', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
       const headers = { Authorization: 'Bearer token' }
@@ -139,13 +202,43 @@ describe('BaseCrudApi', () => {
       vi.mocked(client.get).mockResolvedValue([item])
 
       const result = await api.getOne()
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('/items?')
-      expect(calledUrl).toContain('limit=1')
-      expect(calledUrl).toContain('paginate=false')
+      expect(calledPath(client)).toBe('/items')
+      expect(calledQuery(client)).toEqual({ limit: 1, paginate: false })
       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(calledQuery(client)).toEqual({
+        where: { name: 'x' },
+        order: [['name', '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 the API returns an empty body', async () => {
+      vi.mocked(client.get).mockResolvedValue(undefined)
+
+      expect(await api.getOne()).toBeNull()
+    })
+
     it('returns null when no records match', async () => {
       vi.mocked(client.get).mockResolvedValue([])
 
@@ -174,6 +267,25 @@ 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(calledPath(client)).toBe('/items/abc')
+      expect(calledQuery(client)).toEqual({ attributes: ['id', '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?query=${encodeURIComponent('{"attributes":["id"]}')}`,
+        headers,
+      )
+    })
+
     it('forwards custom headers', async () => {
       vi.mocked(client.get).mockResolvedValue({ id: '1', name: 'x' })
       const headers = { 'X-Tenant': '123' }
@@ -269,41 +381,150 @@ 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')
     })
   })
 
-  // ── Query serialization edge cases ───────────────────────────────
+  // ── Query serialization: 'json' (default) ───────────────────────
+
+  describe("query serialization (queryFormat: 'json', the default)", () => {
+    it('sends the query as ?query=<JSON>', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { name: 'x' }, page: 2 })
+      expect(client.get).toHaveBeenCalledWith(
+        `/items?query=${encodeURIComponent('{"where":{"name":"x"},"page":2}')}`,
+        undefined,
+      )
+    })
 
-  describe('query serialization', () => {
-    it('handles complex where with operators', async () => {
+    it('keeps null, booleans and numbers typed', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const query = {
+        where: { deletedAt: null, id: { $ne: 'x' }, name: { $ne: 'y' } },
+        paranoid: false,
+        distinct: true,
+        limit: 10,
+      }
 
-      await api.getMany({ where: { name: { $like: '%test%' } } })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toMatch(/^\/items\?/)
-      expect(calledUrl).toContain('%25test%25')
+      await api.getMany(query)
+      expect(calledQuery(client)).toEqual(query)
     })
 
-    it('handles order parameter', async () => {
+    it('keeps deeply nested includes intact', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const tagsApi = new BaseCrudApi<ItemWithTags, CreateItem>(client, '/items')
+      const query = {
+        include: [
+          'owner' as const,
+          { model: 'tags' as const, where: { label: { $in: ['a', 'b'] } }, required: true },
+        ],
+      }
 
-      await api.getMany({ order: [['name', 'ASC']] })
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      expect(calledUrl).toContain('order')
-      expect(calledUrl).toContain('name')
-      expect(calledUrl).toContain('ASC')
+      await tagsApi.getMany(query)
+      expect(calledQuery(client)).toEqual(query)
     })
 
-    it('handles empty query object', async () => {
+    it('encodes special characters', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { name: { $like: '%a&b=c?#%' } } })
+      expect(calledQuery(client)).toEqual({ where: { name: { $like: '%a&b=c?#%' } } })
+    })
+
+    it('sends no query string for an empty query object', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 
       await api.getMany({})
-      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
-      // qs.stringify({}) produces '', so we get '/items?'
-      expect(calledUrl).toBe('/items?')
+      expect(client.get).toHaveBeenCalledWith('/items', undefined)
+    })
+  })
+
+  // ── Query serialization: 'qs' ────────────────────────────────────
+
+  describe("query serialization (queryFormat: 'qs')", () => {
+    let qsClient: ApiClient
+    let qsApi: BaseCrudApi<ItemWithTags, CreateItem, UpdateItem>
+
+    beforeEach(() => {
+      qsClient = createMockClient('qs')
+      qsApi = new BaseCrudApi<ItemWithTags, CreateItem, UpdateItem>(qsClient, '/items')
+      vi.mocked(qsClient.get).mockResolvedValue({ data: [], total: 0 })
+    })
+
+    it('serializes where with operators', async () => {
+      await qsApi.getMany({ where: { name: { $like: '%test%' } } })
+      expect(vi.mocked(qsClient.get).mock.calls.at(0)?.at(0)).toBe(
+        '/items?where%5Bname%5D%5B%24like%5D=%25test%25',
+      )
+    })
+
+    it('serializes nested include with where and include', async () => {
+      await qsApi.getMany({
+        include: ['owner', { model: 'tags', where: { label: 'vip' }, required: true }],
+      })
+      expect(calledUrl(qsClient)).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 () => {
+      await qsApi.getMany({ where: { id: { $in: ['a', 'b'] } } })
+      expect(calledUrl(qsClient)).toBe('/items?where[id][$in][0]=a&where[id][$in][1]=b')
+    })
+
+    it('serializes $or/$and combinators', async () => {
+      await qsApi.getMany({ where: { $or: [{ name: 'a' }, { name: 'b' }] } })
+      expect(calledUrl(qsClient)).toBe('/items?where[$or][0][name]=a&where[$or][1][name]=b')
+    })
+
+    it('serializes order exactly', async () => {
+      await qsApi.getMany({
+        order: [
+          ['name', 'ASC'],
+          ['id', 'desc'],
+        ],
+      })
+      expect(calledUrl(qsClient)).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 () => {
+      await qsApi.getMany({ paranoid: false, distinct: true, limit: 10, offset: 20 })
+      expect(calledUrl(qsClient)).toBe('/items?paranoid=false&distinct=true&limit=10&offset=20')
+    })
+
+    it('serializes null as an empty value (the backend reads it as an empty string)', async () => {
+      await qsApi.getMany({ where: { deletedAt: null } })
+      expect(calledUrl(qsClient)).toBe('/items?where[deletedAt]=')
+    })
+
+    it('serializes getOne and getById queries', async () => {
+      vi.mocked(qsClient.get).mockResolvedValueOnce([]).mockResolvedValueOnce({ id: '1' })
+
+      await qsApi.getOne({ where: { name: 'x' } })
+      await qsApi.getById('1', { attributes: ['id'] })
+      expect(calledUrl(qsClient, 0)).toBe('/items?where[name]=x&limit=1&paginate=false')
+      expect(calledUrl(qsClient, 1)).toBe('/items/1?attributes[0]=id')
+    })
+
+    it('sends no query string for an empty query object', async () => {
+      await qsApi.getMany({})
+      expect(qsClient.get).toHaveBeenCalledWith('/items', undefined)
     })
   })
 })

package/src/core/BaseCrudApi.ts

@@ -1,5 +1,5 @@
-import qs from 'qs'
 import type { ApiClient } from './ApiClient'
+import { BaseApi } from './BaseApi'
 import type { CrudApi, GetByIdQuery, ListQuery, Paginated } from './types'
 export type {
   WhereClause,
@@ -20,19 +20,15 @@ export class BaseCrudApi<
   TCreate,
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
-> implements CrudApi<TResponse, TCreate, TUpdate, TQuery> {
-  public readonly client: ApiClient
+>
+  extends BaseApi
+  implements CrudApi<TResponse, TCreate, TUpdate, TQuery>
+{
   public readonly basePath: string
 
   constructor(client: ApiClient, basePath: string) {
-    this.client = client
+    super(client)
     this.basePath = basePath.replace(/\/$/, '')
-    this.getMany = this.getMany.bind(this)
-    this.getOne = this.getOne.bind(this)
-    this.getById = this.getById.bind(this)
-    this.create = this.create.bind(this)
-    this.updateById = this.updateById.bind(this)
-    this.deleteById = this.deleteById.bind(this)
   }
 
   getMany(
@@ -43,11 +39,15 @@ export class BaseCrudApi<
     query?: TQuery & { paginate?: true },
     headers?: Record<string, string>,
   ): Promise<Paginated<TResponse>>
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]>
   getMany(
     query?: TQuery,
     headers?: Record<string, string>,
   ): Promise<Paginated<TResponse> | TResponse[]> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<Paginated<TResponse> | TResponse[]>(
       `${this.basePath}${queryString}`,
       headers,
@@ -64,7 +64,8 @@ export class BaseCrudApi<
       { ...query, limit: 1, paginate: false } as TQuery & { paginate: false },
       headers,
     )
-    return results[0] ?? null
+    // An empty response body resolves to `undefined`.
+    return results?.[0] ?? null
   }
 
   /**
@@ -76,8 +77,7 @@ export class BaseCrudApi<
     query?: GetByIdQuery<TResponse>,
     headers?: Record<string, string>,
   ): Promise<TResponse> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
-    return this.client.get<TResponse>(`${this.basePath}/${id}${queryString}`, headers)
+    return this.client.get<TResponse>(`${this.basePath}/${id}${this.toQueryString(query)}`, headers)
   }
 
   /**