@ikatec/digisac-api-sdk 4.0.0 → 4.1.0

package/src/apis/contacts/ContactsApi.ts

@@ -35,7 +35,7 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
    * @permissions contacts.view
    */
   count(query?: CountContactsQuery, headers?: Record<string, string>): Promise<{ count: number }> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<{ count: number }>(`${this.basePath}/count${queryString}`, headers)
   }
 
@@ -62,7 +62,7 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
     query?: ListQuery<Contact>,
     headers?: Record<string, string>,
   ): Promise<Paginated<Contact>> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<Paginated<Contact>>(`${this.basePath}/forward${queryString}`, headers)
   }
 

package/src/apis/me/MeApi.ts

@@ -1,4 +1,4 @@
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { Account } from '../accounts/types'
 import type { User } from '../users/types'
 import type {
@@ -10,13 +10,7 @@ import type {
   UpdateMeStatusPayload,
 } from './types'
 
-export class MeApi {
-  protected readonly client: ApiClient
-
-  constructor(client: ApiClient) {
-    this.client = client
-  }
-
+export class MeApi extends BaseApi {
   /**
    * Returns the currently authenticated user, including their roles, departments, and timetable.
    * @permissions users.view

package/src/apis/messages/MessagesApi.test.ts

@@ -87,8 +87,8 @@ describe('MessagesApi', () => {
       await api.getMany({ page: 2, perPage: 5 })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
       expect(url).toContain('/messages?')
-      expect(url).toContain('page=2')
-      expect(url).toContain('perPage=5')
+      expect(decodeURIComponent(url)).toContain('"page":2')
+      expect(decodeURIComponent(url)).toContain('"perPage":5')
     })
 
     it('forwards custom headers', async () => {

package/src/apis/queryFormat.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import qs from 'qs'
+import type { ApiClient } from '../core/ApiClient'
+import { BaseApiClient } from '../core/BaseApiClient'
+import type { QueryFormat } from '../core/queryString'
+import { AuthHistoryApi } from './authHistory/AuthHistoryApi'
+import { ContactsApi } from './contacts/ContactsApi'
+import { ServiceAccessManagementApi } from './serviceAccessManagement/ServiceAccessManagementApi'
+import { StickerUsersApi } from './stickerUsers/StickerUsersApi'
+import { TermsApi } from './terms/TermsApi'
+
+/**
+ * Every method that sends a list/get query must serialize it in the client's `queryFormat` and
+ * honor `withQueryFormat`. A method listed here that ignored the format would fail below.
+ */
+
+function createMockClient(queryFormat?: QueryFormat): ApiClient {
+  return {
+    ...(queryFormat && { queryFormat }),
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn().mockResolvedValue([]),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+const listQuery = { where: { name: 'x' }, page: 2, perPage: 5 }
+const getQuery = { attributes: ['id'] }
+
+type Case = {
+  name: string
+  path: string
+  query: object
+  /** Calls the method on the API built from `client`, optionally through `withQueryFormat`. */
+  call: (client: ApiClient, override?: QueryFormat) => Promise<unknown>
+}
+
+const cases: Case[] = [
+  {
+    name: 'ContactsApi.getMany (BaseCrudApi)',
+    path: '/contacts',
+    query: listQuery,
+    call: (client, f) => {
+      const api = new ContactsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMany(listQuery)
+    },
+  },
+  {
+    name: 'ContactsApi.getById (BaseCrudApi)',
+    path: '/contacts/c1',
+    query: getQuery,
+    call: (client, f) => {
+      const api = new ContactsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getById('c1', { attributes: ['id'] })
+    },
+  },
+  {
+    name: 'ContactsApi.count',
+    path: '/contacts/count',
+    query: listQuery,
+    call: (client, f) => {
+      const api = new ContactsApi(client)
+      return (f ? api.withQueryFormat(f) : api).count(listQuery)
+    },
+  },
+  {
+    name: 'ContactsApi.forward',
+    path: '/contacts/forward',
+    query: listQuery,
+    call: (client, f) => {
+      const api = new ContactsApi(client)
+      return (f ? api.withQueryFormat(f) : api).forward(listQuery)
+    },
+  },
+  {
+    name: 'AuthHistoryApi.getMany',
+    path: '/auth-history',
+    query: { page: 2, perPage: 5 },
+    call: (client, f) => {
+      const api = new AuthHistoryApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMany({ page: 2, perPage: 5 })
+    },
+  },
+  {
+    name: 'ServiceAccessManagementApi.getMany',
+    path: '/service-access-management',
+    query: { page: 2, perPage: 5 },
+    call: (client, f) => {
+      const api = new ServiceAccessManagementApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMany({ page: 2, perPage: 5 })
+    },
+  },
+  {
+    name: 'StickerUsersApi.getMany',
+    path: '/sticker-users',
+    query: { page: 2, perPage: 5 },
+    call: (client, f) => {
+      const api = new StickerUsersApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMany({ page: 2, perPage: 5 })
+    },
+  },
+  {
+    name: 'TermsApi.getById',
+    path: '/terms/t1',
+    query: getQuery,
+    call: (client, f) => {
+      const api = new TermsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getById('t1', { attributes: ['id'] })
+    },
+  },
+]
+
+const jsonUrl = (path: string, query: object) =>
+  `${path}?query=${encodeURIComponent(JSON.stringify(query))}`
+const qsUrl = (path: string, query: object) => `${path}?${qs.stringify(query)}`
+const calledUrl = (client: ApiClient) => vi.mocked(client.get).mock.calls.at(0)?.at(0)
+
+describe.each(cases)('$name', ({ path, query, call }) => {
+  it("sends JSON with the default client format ('json')", async () => {
+    const client = createMockClient()
+    await call(client)
+    expect(calledUrl(client)).toBe(jsonUrl(path, query))
+  })
+
+  it("sends bracket notation with a 'qs' client", async () => {
+    const client = createMockClient('qs')
+    await call(client)
+    expect(calledUrl(client)).toBe(qsUrl(path, query))
+  })
+
+  it("withQueryFormat('qs') overrides a 'json' client", async () => {
+    const client = createMockClient()
+    await call(client, 'qs')
+    expect(calledUrl(client)).toBe(qsUrl(path, query))
+  })
+
+  it("withQueryFormat('json') overrides a 'qs' client", async () => {
+    const client = createMockClient('qs')
+    await call(client, 'json')
+    expect(calledUrl(client)).toBe(jsonUrl(path, query))
+  })
+})
+
+describe('query format through BaseApiClient', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  const mockFetch = () =>
+    vi
+      .spyOn(globalThis, 'fetch')
+      .mockImplementation(
+        async () =>
+          new Response('[]', { status: 200, headers: { 'Content-Type': 'application/json' } }),
+      )
+
+  it('builds the full ?query=<JSON> URL by default, keeping null typed', async () => {
+    const fetchSpy = mockFetch()
+    const contacts = new ContactsApi(new BaseApiClient('https://api.example.com/'))
+
+    await contacts.getMany({ where: { name: null }, paginate: false })
+
+    const query = '{"where":{"name":null},"paginate":false}'
+    expect(fetchSpy.mock.calls[0]?.[0]).toBe(
+      `https://api.example.com/contacts?query=${encodeURIComponent(query)}`,
+    )
+  })
+
+  it("builds the bracket URL with queryFormat 'qs'", async () => {
+    const fetchSpy = mockFetch()
+    const client = new BaseApiClient('https://api.example.com', undefined, { queryFormat: 'qs' })
+
+    await new ContactsApi(client).getMany({ where: { name: 'x' }, paginate: false })
+
+    expect(decodeURIComponent(fetchSpy.mock.calls[0]?.[0] as string)).toBe(
+      'https://api.example.com/contacts?where[name]=x&paginate=false',
+    )
+  })
+
+  it("setAccessToken on a copy's client only affects the copy", async () => {
+    const fetchSpy = mockFetch()
+    const client = new BaseApiClient('https://api.example.com', 'original')
+    const contacts = new ContactsApi(client)
+    const copy = contacts.withQueryFormat('qs')
+
+    copy.client.setAccessToken('copy-only')
+    await contacts.getMany({ paginate: false })
+    await copy.getMany({ paginate: false })
+
+    const authorization = (call: number) =>
+      (fetchSpy.mock.calls[call]?.[1]?.headers as Record<string, string>).Authorization
+    expect(authorization(0)).toBe('Bearer original')
+    expect(authorization(1)).toBe('Bearer copy-only')
+  })
+})

package/src/apis/serviceAccessManagement/ServiceAccessManagementApi.test.ts

@@ -63,7 +63,7 @@ describe('ServiceAccessManagementApi', () => {
       await api.getMany({ page: 2, perPage: 5 })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
       expect(url).toContain('/service-access-management?')
-      expect(url).toContain('page=2')
+      expect(decodeURIComponent(url)).toContain('"page":2')
     })
 
     it('forwards custom headers', async () => {
@@ -77,7 +77,7 @@ describe('ServiceAccessManagementApi', () => {
       vi.mocked(client.get).mockResolvedValue([record])
       const result = await api.getMany({ paginate: false })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
-      expect(url).toContain('paginate=false')
+      expect(decodeURIComponent(url)).toContain('"paginate":false')
       expect(result).toEqual([record])
     })
 

package/src/apis/serviceAccessManagement/ServiceAccessManagementApi.ts

@@ -1,15 +1,11 @@
-import qs from 'qs'
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { ListQuery, Paginated, HasGetMany } from '../../core/types'
 import type { ServiceAccessManagement } from './types'
 
-export class ServiceAccessManagementApi implements HasGetMany<ServiceAccessManagement> {
-  private readonly client: ApiClient
-
-  constructor(client: ApiClient) {
-    this.client = client
-  }
-
+export class ServiceAccessManagementApi
+  extends BaseApi
+  implements HasGetMany<ServiceAccessManagement>
+{
   /** Returns a paginated list of which users have access to which services. */
   getMany(
     query: ListQuery<ServiceAccessManagement> & { paginate: false },
@@ -19,11 +15,15 @@ export class ServiceAccessManagementApi implements HasGetMany<ServiceAccessManag
     query?: ListQuery<ServiceAccessManagement> & { paginate?: true },
     headers?: Record<string, string>,
   ): Promise<Paginated<ServiceAccessManagement>>
+  getMany(
+    query?: ListQuery<ServiceAccessManagement>,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<ServiceAccessManagement> | ServiceAccessManagement[]>
   getMany(
     query?: ListQuery<ServiceAccessManagement>,
     headers?: Record<string, string>,
   ): Promise<Paginated<ServiceAccessManagement> | ServiceAccessManagement[]> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<Paginated<ServiceAccessManagement> | ServiceAccessManagement[]>(
       `/service-access-management${queryString}`,
       headers,

package/src/apis/stickerUsers/StickerUsersApi.test.ts

@@ -66,7 +66,7 @@ describe('StickerUsersApi', () => {
       await api.getMany({ page: 2, perPage: 5 })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
       expect(url).toContain('/sticker-users?')
-      expect(url).toContain('page=2')
+      expect(decodeURIComponent(url)).toContain('"page":2')
     })
 
     it('forwards custom headers', async () => {

package/src/apis/stickerUsers/StickerUsersApi.ts

@@ -1,15 +1,8 @@
-import qs from 'qs'
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { ListQuery, Paginated, HasGetMany } from '../../core/types'
 import type { StickerUser } from './types'
 
-export class StickerUsersApi implements HasGetMany<StickerUser> {
-  private readonly client: ApiClient
-
-  constructor(client: ApiClient) {
-    this.client = client
-  }
-
+export class StickerUsersApi extends BaseApi implements HasGetMany<StickerUser> {
   /**
    * Returns a paginated list of sticker-user associations with their related file.
    * @permissions stickers.send
@@ -22,11 +15,15 @@ export class StickerUsersApi implements HasGetMany<StickerUser> {
     query?: ListQuery<StickerUser> & { paginate?: true },
     headers?: Record<string, string>,
   ): Promise<Paginated<StickerUser>>
+  getMany(
+    query?: ListQuery<StickerUser>,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<StickerUser> | StickerUser[]>
   getMany(
     query?: ListQuery<StickerUser>,
     headers?: Record<string, string>,
   ): Promise<Paginated<StickerUser> | StickerUser[]> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<Paginated<StickerUser> | StickerUser[]>(
       `/sticker-users${queryString}`,
       headers,

package/src/apis/terms/TermsApi.ts

@@ -1,5 +1,4 @@
-import qs from 'qs'
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { GetByIdQuery, HasGetById } from '../../core/types'
 import type { Term } from './types'
 
@@ -10,20 +9,12 @@ import type { Term } from './types'
  * `GET /terms/:id/export-pdf` is not exposed: it answers a binary PDF, and `ApiClient` only
  * handles JSON/text bodies.
  */
-export class TermsApi implements HasGetById<Term> {
-  protected readonly client: ApiClient
+export class TermsApi extends BaseApi implements HasGetById<Term> {
   public readonly basePath = '/terms'
 
-  constructor(client: ApiClient) {
-    this.client = client
-    this.getById = this.getById.bind(this)
-    this.getNotAgreed = this.getNotAgreed.bind(this)
-    this.agree = this.agree.bind(this)
-  }
-
   /** Returns a single term by its ID, scoped to the current account (`null` when not found). */
   getById(id: string, query?: GetByIdQuery<Term>, headers?: Record<string, string>): Promise<Term> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<Term>(`${this.basePath}/${id}${queryString}`, headers)
   }
 

package/src/apis/transcripts/TranscriptsApi.ts

@@ -1,15 +1,10 @@
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { HasGetById } from '../../core/types'
 import type { TranscriptResponse } from './types'
 
-export class TranscriptsApi implements HasGetById<TranscriptResponse> {
-  private readonly client: ApiClient
+export class TranscriptsApi extends BaseApi implements HasGetById<TranscriptResponse> {
   private readonly basePath = '/transcripts'
 
-  constructor(client: ApiClient) {
-    this.client = client
-  }
-
   /** Triggers audio transcription for a message by dispatching an async job, and marks it as transcribing. */
   getById(id: string, headers?: Record<string, string>): Promise<TranscriptResponse> {
     return this.client.get<TranscriptResponse>(`${this.basePath}/${id}`, headers)

package/src/core/ApiClient.ts

@@ -1,6 +1,10 @@
+import type { QueryFormat } from './queryString'
+
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
 
 export interface ApiClient {
+  /** How list/get queries are serialized in the URL (defaults to `'json'` when absent). */
+  readonly queryFormat?: QueryFormat
   setAccessToken(accessToken: string): this
   request<TResponse = unknown, TBody = unknown>(
     method: HttpMethod,

package/src/core/ArchivableCrudApi.ts

@@ -20,8 +20,6 @@ export class ArchivableCrudApi<
 > extends BaseCrudApi<TResponse, TCreate, TUpdate, TQuery> {
   constructor(client: ApiClient, basePath: string) {
     super(client, basePath)
-    this.archive = this.archive.bind(this)
-    this.unarchive = this.unarchive.bind(this)
   }
 
   /**

package/src/core/BaseApi.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ApiClient } from './ApiClient'
+import { BaseApi } from './BaseApi'
+import { BaseCrudApi } from './BaseCrudApi'
+import { ArchivableCrudApi } from './ArchivableCrudApi'
+import { bindMethods } from './bindMethods'
+import { AuthHistoryApi } from '../apis/authHistory/AuthHistoryApi'
+import { ClientFeedbackApi } from '../apis/clientFeedback/ClientFeedbackApi'
+import { MeApi } from '../apis/me/MeApi'
+import { ServiceAccessManagementApi } from '../apis/serviceAccessManagement/ServiceAccessManagementApi'
+import { StickerUsersApi } from '../apis/stickerUsers/StickerUsersApi'
+import { TermsApi } from '../apis/terms/TermsApi'
+import { TranscriptsApi } from '../apis/transcripts/TranscriptsApi'
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn().mockResolvedValue([]),
+    post: vi.fn().mockResolvedValue({}),
+    put: vi.fn().mockResolvedValue({}),
+    patch: vi.fn().mockResolvedValue({}),
+    delete: vi.fn().mockResolvedValue({}),
+  }
+}
+
+// ── bindMethods ──────────────────────────────────────────────────────
+
+describe('bindMethods', () => {
+  class Parent {
+    name = 'instance'
+    greet() {
+      return `parent:${this.name}`
+    }
+    shout() {
+      return this.greet().toUpperCase()
+    }
+  }
+
+  class Child extends Parent {
+    getterCalls = 0
+    override greet() {
+      return `child:${this.name}`
+    }
+    get computed() {
+      this.getterCalls += 1
+      return this.name
+    }
+  }
+
+  it('binds methods of the whole class chain so they survive destructuring', () => {
+    const child = new Child()
+    bindMethods(child)
+    const { greet, shout } = child
+    expect(greet()).toBe('child:instance')
+    expect(shout()).toBe('CHILD:INSTANCE')
+  })
+
+  it('binds the most derived implementation', () => {
+    const child = new Child()
+    bindMethods(child)
+    expect(Object.getOwnPropertyDescriptor(child, 'greet')?.value()).toBe('child:instance')
+  })
+
+  it('skips getters without calling them, and constructor', () => {
+    const child = new Child()
+    bindMethods(child)
+    expect(child.getterCalls).toBe(0)
+    expect(Object.hasOwn(child, 'computed')).toBe(false)
+    expect(Object.hasOwn(child, 'constructor')).toBe(false)
+    expect(child.computed).toBe('instance')
+  })
+
+  it('does not bind Object.prototype methods', () => {
+    const child = new Child()
+    bindMethods(child)
+    expect(Object.hasOwn(child, 'toString')).toBe(false)
+    expect(Object.hasOwn(child, 'hasOwnProperty')).toBe(false)
+  })
+})
+
+// ── BaseApi ──────────────────────────────────────────────────────────
+
+describe('BaseApi', () => {
+  class ItemsApi extends BaseApi {
+    list(query?: object) {
+      return this.client.get(`/items${this.toQueryString(query)}`)
+    }
+  }
+
+  it('exposes the client', () => {
+    const client = createMockClient()
+    expect(new ItemsApi(client).client).toBe(client)
+  })
+
+  it('binds subclass methods and its own', async () => {
+    const client = createMockClient()
+    const { list, withQueryFormat } = new ItemsApi(client)
+    await list({ page: 1 })
+    await withQueryFormat('qs').list({ page: 1 })
+    expect(vi.mocked(client.get).mock.calls.map(([url]) => decodeURIComponent(url))).toEqual([
+      '/items?query={"page":1}',
+      '/items?page=1',
+    ])
+  })
+
+  it("serializes queries in the client's queryFormat", async () => {
+    const client = Object.assign(createMockClient(), { queryFormat: 'qs' as const })
+    await new ItemsApi(client).list({ where: { name: 'x' } })
+    expect(decodeURIComponent(vi.mocked(client.get).mock.calls[0]?.[0] as string)).toBe(
+      '/items?where[name]=x',
+    )
+  })
+
+  it('is the base of BaseCrudApi and ArchivableCrudApi', () => {
+    const client = createMockClient()
+    expect(new BaseCrudApi(client, '/items')).toBeInstanceOf(BaseApi)
+    expect(new ArchivableCrudApi(client, '/items')).toBeInstanceOf(BaseApi)
+  })
+
+  it('binds ArchivableCrudApi methods without manual binding', async () => {
+    const client = createMockClient()
+    const { archive, unarchive } = new ArchivableCrudApi(client, '/items')
+    await archive('1')
+    await unarchive('1')
+    expect(client.put).toHaveBeenNthCalledWith(1, '/items/1', expect.anything(), undefined)
+    expect(client.put).toHaveBeenNthCalledWith(2, '/items/1', { archivedAt: null }, undefined)
+  })
+})
+
+// ── APIs that don't extend BaseCrudApi ───────────────────────────────
+
+describe.each([
+  ['AuthHistoryApi', (c: ApiClient) => new AuthHistoryApi(c).getMany],
+  ['ClientFeedbackApi', (c: ApiClient) => new ClientFeedbackApi(c).create],
+  ['MeApi', (c: ApiClient) => new MeApi(c).getMe],
+  ['ServiceAccessManagementApi', (c: ApiClient) => new ServiceAccessManagementApi(c).getMany],
+  ['StickerUsersApi', (c: ApiClient) => new StickerUsersApi(c).getMany],
+  ['TermsApi', (c: ApiClient) => new TermsApi(c).getNotAgreed],
+  ['TranscriptsApi', (c: ApiClient) => new TranscriptsApi(c).getById],
+])('%s', (_name, destructure) => {
+  it('extends BaseApi and keeps methods working when destructured', async () => {
+    const client = createMockClient()
+    const method = destructure(client) as (...args: unknown[]) => Promise<unknown>
+    await expect(method('id-1')).resolves.toBeDefined()
+  })
+})
+
+it('every API class that does not extend BaseCrudApi extends BaseApi', () => {
+  const client = createMockClient()
+  for (const api of [
+    new AuthHistoryApi(client),
+    new ClientFeedbackApi(client),
+    new MeApi(client),
+    new ServiceAccessManagementApi(client),
+    new StickerUsersApi(client),
+    new TermsApi(client),
+    new TranscriptsApi(client),
+  ]) {
+    expect(api).toBeInstanceOf(BaseApi)
+    expect(api.client).toBe(client)
+    expect(api.withQueryFormat('qs')).toBeInstanceOf(api.constructor)
+  }
+})

package/src/core/BaseApi.ts

@@ -0,0 +1,32 @@
+import type { ApiClient } from './ApiClient'
+import { bindMethods } from './bindMethods'
+import { toQueryString, type QueryFormat } from './queryString'
+import { cloneWithQueryFormat } from './withQueryFormat'
+
+/**
+ * Base of every API class: holds the client, binds the methods to the instance (so they can be
+ * destructured) and serializes queries in the client's `queryFormat`.
+ */
+export class BaseApi {
+  public readonly client: ApiClient
+
+  constructor(client: ApiClient) {
+    this.client = client
+    bindMethods(this)
+  }
+
+  /**
+   * Returns a copy of this API whose requests serialize queries in `format`, overriding the
+   * client's `queryFormat`. This instance is not changed.
+   *
+   * @example await contacts.withQueryFormat('qs').getMany({ where: { name: 'x' } })
+   */
+  withQueryFormat(format: QueryFormat): this {
+    return cloneWithQueryFormat(this, format)
+  }
+
+  /** Serializes a list/get query in the client's `queryFormat` (`''` when there is nothing to send). */
+  protected toQueryString(query?: object | null): string {
+    return toQueryString(query, this.client.queryFormat)
+  }
+}

package/src/core/BaseApiClient.test.ts

@@ -54,6 +54,16 @@ describe('BaseApiClient', () => {
     expect(spy).toHaveBeenCalledWith('https://api.example.com/test', expect.anything())
   })
 
+  it("defaults queryFormat to 'json'", () => {
+    expect(new BaseApiClient('https://api.example.com').queryFormat).toBe('json')
+  })
+
+  it('accepts a queryFormat option', () => {
+    expect(
+      new BaseApiClient('https://api.example.com', 'tok', { queryFormat: 'qs' }).queryFormat,
+    ).toBe('qs')
+  })
+
   // ── setAccessToken ───────────────────────────────────────────────
 
   it('returns this for chaining', () => {

package/src/core/BaseApiClient.ts

@@ -1,13 +1,21 @@
 import type { ApiClient, HttpMethod } from './ApiClient'
 import { ApiConnectionError, ApiError } from './errors'
+import { DEFAULT_QUERY_FORMAT, type QueryFormat } from './queryString'
+
+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 {