@ikatec/digisac-api-sdk 3.1.0 → 4.1.0

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

@@ -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
@@ -39,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', () => {
@@ -216,21 +241,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 +263,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 +322,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,