@ikatec/digisac-api-sdk 4.0.0 → 4.2.0

package/src/apis/roles/types.ts

@@ -1,5 +1,9 @@
+import type { ListQuery } from '../../core/types'
 import type { Permission } from '../permissions/types'
 
+/**
+ * A role (cargo). Roles are not soft-deleted, so there is no `deletedAt`.
+ */
 export type Role = {
   id: string
   displayName: string
@@ -7,21 +11,40 @@ export type Role = {
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
+  /** Only when listed with `customInclude: ['usersCount']`. */
+  usersCount?: number
   // relationships
   permissions?: Permission[]
 }
 
 export type RoleRelationships = 'permissions'
 
+/**
+ * The permissions of a role, by id or `{ id }`. The backend reads the `permissions` key (also
+ * `permissionsId`/`permissionsIds`) — any other key is silently ignored and the role ends up with
+ * no permissions.
+ */
+export type RolePermissionRef = string | { id: string }
+
 export type CreateRolePayload = {
+  /** Up to 255 characters; must be unique in the account. */
   displayName: string
   isAdmin?: boolean
-  permissionIds?: string[]
+  permissions?: RolePermissionRef[]
 }
 
 export type UpdateRolePayload = {
-  displayName?: string
+  /** Required by the backend on every update (400 `required` otherwise). */
+  displayName: string
   isAdmin?: boolean | null
-  permissionIds?: string[]
+  /** Replaces the role permissions. An empty array leaves them unchanged. */
+  permissions?: RolePermissionRef[]
+}
+
+/** List query of `/roles`, with the backend extras to count the users of each role. */
+export type RolesListQuery = ListQuery<Role> & {
+  /** `['usersCount']` adds `usersCount` to each role. */
+  customInclude?: 'usersCount'[]
+  /** Which users `usersCount` counts (default `all`). */
+  usersCountFilter?: 'all' | 'active' | 'archived'
 }

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,15 @@ 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). */
+  /**
+   * Returns a single term by its ID, scoped to the current account. When it does not exist the
+   * backend answers 200 with an empty body, which resolves to `undefined`.
+   */
   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/timetable/types.ts

@@ -1,8 +1,15 @@
+export type TimetableWeekDay = 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
+
+/**
+ * A working period of the timetable. `start`/`end` are `HH:MM` and `end` must be later than
+ * `start`; the period applies to every day in `weekDays`.
+ */
 export type TimetableWorkSlot = {
-  day: number
+  /** `HH:MM` */
   start: string
+  /** `HH:MM`, later than `start`. */
   end: string
-  active: boolean
+  weekDays: TimetableWeekDay[]
 }
 
 export type Timetable = {
@@ -16,13 +23,12 @@ export type Timetable = {
 }
 
 export type CreateTimetablePayload = {
+  /** Must be unique in the account (409 otherwise, unless the account allows duplicate names). */
   name: string
+  /** Minutes before the end of the period to notify. Must be truthy: `0` answers 400 `required`. */
   previousTimeToNotification: number
   workPlan: TimetableWorkSlot[]
 }
 
-export type UpdateTimetablePayload = {
-  name?: string
-  previousTimeToNotification?: number
-  workPlan?: TimetableWorkSlot[]
-}
+/** The backend requires the three fields on every update (400 `required` otherwise). */
+export type UpdateTimetablePayload = CreateTimetablePayload

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 {

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

@@ -20,6 +20,9 @@ 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())
@@ -46,3 +49,9 @@ expectError(api.updateById('1', { name: 1 }))
 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'))