@ikatec/digisac-api-sdk 4.2.0 → 4.4.0

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

@@ -85,7 +85,7 @@ describe('MessagesApi', () => {
     it('serializes query parameters', async () => {
       vi.mocked(client.get).mockResolvedValue(paginated)
       await api.getMany({ page: 2, perPage: 5 })
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
       expect(url).toContain('/messages?')
       expect(decodeURIComponent(url)).toContain('"page":2')
       expect(decodeURIComponent(url)).toContain('"perPage":5')
@@ -382,7 +382,7 @@ describe('MessagesApi', () => {
     it('appends limit query parameter when provided', async () => {
       vi.mocked(client.get).mockResolvedValue({ outOfRange: true })
       await api.outOfRange('msg-1', 50)
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
       expect(url).toContain('/messages/msg-1/out-of-range?')
       expect(url).toContain('limit=50')
     })
@@ -426,7 +426,7 @@ describe('MessagesApi', () => {
     it('appends limit query parameter when provided', async () => {
       vi.mocked(client.get).mockResolvedValue([])
       await api.around('msg-1', { limit: 10 })
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
       expect(url).toContain('/messages/msg-1/around?')
       expect(url).toContain('limit=10')
     })

package/src/apis/payloads.test-d.ts

@@ -1,8 +1,11 @@
 import { expectError } from 'tsd'
 import type { ApiClient } from '../core/ApiClient'
+import { ContactsApi } from './contacts/ContactsApi'
 import { PersonalAccessTokensApi } from './personalAccessTokens/PersonalAccessTokensApi'
 import { RolesApi } from './roles/RolesApi'
+import { TagsApi } from './tags/TagsApi'
 import { TimetableApi } from './timetable/TimetableApi'
+import { UsersApi } from './users/UsersApi'
 
 declare const client: ApiClient
 
@@ -37,3 +40,26 @@ tokens.create({ name: 'CI', expiresIn: '90d' })
 expectError(tokens.create({ name: 'CI', accessTokenExpiresAt: '2030-01-01T00:00:00Z' }))
 expectError(tokens.create({ name: 'CI', expiresIn: '7d' }))
 expectError(tokens.updateById('t-1', { scope: '*' }))
+
+// ── users: the dedicated archive route takes a boolean, not a date ──
+
+const users = new UsersApi(client)
+users.archiveWithValidation('u-1', { archive: true })
+expectError(users.archiveWithValidation('u-1', { archivedAt: '2030-01-01T00:00:00Z' }))
+expectError(users.exportCsv({ filter: 'deleted' }))
+
+// ── contacts: /many takes an array, the bulk delete a selection ─────
+
+const contacts = new ContactsApi(client)
+contacts.createMany([{ serviceId: 's-1', name: 'Alice', number: '5511999990001' }])
+expectError(contacts.createMany({ serviceId: 's-1', name: 'Alice', number: '5511999990001' }))
+expectError(contacts.getMedia('c-1', { where: { type: 'audio' } }))
+
+// ── contact selections: an empty filter would reach every contact of the account ─
+
+contacts.deleteMany({ where: { id: 'c-1' } })
+expectError(contacts.deleteMany({}))
+const tags = new TagsApi(client)
+tags.attachContacts('t-1', { where: { id: { $in: ['c-1', 'c-2'] } } })
+expectError(tags.attachContacts('t-1', {}))
+expectError(tags.detachContacts('t-1', { include: ['tags'] }))

package/src/apis/queryFormat.test.ts

@@ -32,6 +32,8 @@ function createMockClient(queryFormat?: QueryFormat): ApiClient {
 
 const listQuery = { where: { name: 'x' }, page: 2, perPage: 5 }
 const getQuery = { attributes: ['id'] }
+/** `Permission.name` is a union of the catalog names, so the permissions case filters by a real one. */
+const permissionsQuery = { where: { name: 'chat' as const }, page: 2, perPage: 5 }
 
 type Case = {
   name: string
@@ -69,6 +71,27 @@ const cases: Case[] = [
       return (f ? api.withQueryFormat(f) : api).count(listQuery)
     },
   },
+  {
+    name: 'ContactsApi.getMedia',
+    path: '/contacts/c1/media',
+    query: { where: { type: 'document' }, perPage: 10 },
+    call: (client, f) => {
+      const api = new ContactsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMedia('c1', {
+        where: { type: 'document' },
+        perPage: 10,
+      })
+    },
+  },
+  {
+    name: 'ContactsApi.createMany',
+    path: '/contacts/many',
+    query: { include: ['tags'] },
+    call: (client, f) => {
+      const api = new ContactsApi(client)
+      return (f ? api.withQueryFormat(f) : api).createMany([], { include: ['tags'] })
+    },
+  },
   {
     name: 'ContactsApi.forward',
     path: '/contacts/forward',
@@ -99,6 +122,70 @@ const cases: Case[] = [
       })
     },
   },
+  {
+    name: 'DashboardApi.getByPeriod',
+    path: '/dashboard/by-period',
+    query: { status: 'closed', departmentId: ['d1'], grouping: 'weekly', withTotals: true },
+    call: (client, f) => {
+      const api = new DashboardApi(client)
+      return (f ? api.withQueryFormat(f) : api).getByPeriod({
+        status: 'closed',
+        departmentId: ['d1'],
+        grouping: 'weekly',
+        withTotals: true,
+      })
+    },
+  },
+  {
+    name: 'DashboardApi.getByUser',
+    path: '/dashboard/by-user',
+    query: { status: 'closed', departmentId: ['d1'], withTotals: true },
+    call: (client, f) => {
+      const api = new DashboardApi(client)
+      return (f ? api.withQueryFormat(f) : api).getByUser({
+        status: 'closed',
+        departmentId: ['d1'],
+        withTotals: true,
+      })
+    },
+  },
+  {
+    name: 'DashboardApi.getByDepartment',
+    path: '/dashboard/by-department',
+    query: { status: 'closed', departmentId: ['d1'], withTotals: true },
+    call: (client, f) => {
+      const api = new DashboardApi(client)
+      return (f ? api.withQueryFormat(f) : api).getByDepartment({
+        status: 'closed',
+        departmentId: ['d1'],
+        withTotals: true,
+      })
+    },
+  },
+  {
+    name: 'DashboardApi.getByTopic',
+    path: '/dashboard/by-topic',
+    query: { status: 'closed', departmentId: ['d1'] },
+    call: (client, f) => {
+      const api = new DashboardApi(client)
+      return (f ? api.withQueryFormat(f) : api).getByTopic({
+        status: 'closed',
+        departmentId: ['d1'],
+      })
+    },
+  },
+  {
+    name: 'DashboardApi.getByService',
+    path: '/dashboard/by-service',
+    query: { status: 'closed', departmentId: ['d1'] },
+    call: (client, f) => {
+      const api = new DashboardApi(client)
+      return (f ? api.withQueryFormat(f) : api).getByService({
+        status: 'closed',
+        departmentId: ['d1'],
+      })
+    },
+  },
   {
     name: 'NowApi.getResume',
     path: '/now/resume',
@@ -135,10 +222,10 @@ const cases: Case[] = [
   {
     name: 'PermissionsApi.getMany',
     path: '/permissions',
-    query: listQuery,
+    query: permissionsQuery,
     call: (client, f) => {
       const api = new PermissionsApi(client)
-      return (f ? api.withQueryFormat(f) : api).getMany(listQuery)
+      return (f ? api.withQueryFormat(f) : api).getMany(permissionsQuery)
     },
   },
   {
@@ -191,7 +278,8 @@ const cases: Case[] = [
 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)
+const calledUrl = (client: ApiClient) =>
+  vi.mocked(client.get).mock.calls.at(0)?.at(0) ?? vi.mocked(client.post).mock.calls.at(0)?.at(0)
 
 describe.each(cases)('$name', ({ path, query, call }) => {
   it("sends JSON with the default client format ('json')", async () => {

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

@@ -61,7 +61,7 @@ describe('ServiceAccessManagementApi', () => {
     it('serializes query parameters', async () => {
       vi.mocked(client.get).mockResolvedValue(paginated)
       await api.getMany({ page: 2, perPage: 5 })
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
       expect(url).toContain('/service-access-management?')
       expect(decodeURIComponent(url)).toContain('"page":2')
     })
@@ -76,7 +76,7 @@ describe('ServiceAccessManagementApi', () => {
     it('returns unpaginated array when paginate: false', async () => {
       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
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
       expect(decodeURIComponent(url)).toContain('"paginate":false')
       expect(result).toEqual([record])
     })

package/src/apis/services/ServicesApi.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ServicesApi } from './ServicesApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type { ServiceLimits } from './types'
+
+// ── Mock client factory ──────────────────────────────────────────────
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('ServicesApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: ServicesApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new ServicesApi(client)
+  })
+
+  describe('getLimits', () => {
+    it('calls client.get with /services/limits', async () => {
+      const limits: ServiceLimits = {
+        whatsapp: { used: 1, total: 80, available: 79 },
+        telegram: { used: 0, total: 0, available: 0 },
+      }
+      vi.mocked(client.get).mockResolvedValue(limits)
+      const result = await api.getLimits()
+      expect(client.get).toHaveBeenCalledWith('/services/limits', undefined)
+      expect(result).toEqual(limits)
+    })
+
+    it('forwards custom headers', async () => {
+      const headers = { 'X-Custom': 'value' }
+      await api.getLimits(headers)
+      expect(client.get).toHaveBeenCalledWith('/services/limits', headers)
+    })
+  })
+})

package/src/apis/services/ServicesApi.ts

@@ -1,6 +1,6 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
-import type { Service, CreateServicePayload, UpdateServicePayload } from './types'
+import type { Service, CreateServicePayload, ServiceLimits, UpdateServicePayload } from './types'
 
 export class ServicesApi extends ArchivableCrudApi<
   Service,
@@ -10,4 +10,13 @@ export class ServicesApi extends ArchivableCrudApi<
   constructor(client: ApiClient) {
     super(client, '/services')
   }
+
+  /**
+   * Returns, for each connection type of the account plan, how many connections are used,
+   * allowed and still available.
+   * @permissions services.view
+   */
+  getLimits(headers?: Record<string, string>): Promise<ServiceLimits> {
+    return this.client.get<ServiceLimits>(`${this.basePath}/limits`, headers)
+  }
 }

package/src/apis/services/types.ts

@@ -221,3 +221,12 @@ export type UpdateServicePayload = {
   botId?: string | null
   archivedAt?: string | null
 }
+
+export type ServiceLimit = {
+  used: number
+  total: number
+  available: number
+}
+
+/** Connections used and allowed by the account plan, by connection type. */
+export type ServiceLimits = Partial<Record<ServiceType, ServiceLimit>>

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

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

package/src/apis/tags/TagsApi.test.ts

@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { TagsApi } from './TagsApi'
+import type { ApiClient } from '../../core/ApiClient'
+
+// ── Mock client factory ──────────────────────────────────────────────
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+const headers = { 'X-Custom': 'value' }
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('TagsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: TagsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new TagsApi(client)
+  })
+
+  describe('attachContacts', () => {
+    it('calls client.post with /tags/:id/contacts and the selection', async () => {
+      vi.mocked(client.post).mockResolvedValue('OK')
+      const body = { where: { id: { $in: ['c1', 'c2'] } } }
+      const result = await api.attachContacts('t1', body)
+      expect(client.post).toHaveBeenCalledWith('/tags/t1/contacts', body, undefined)
+      expect(result).toBe('OK')
+    })
+
+    it('forwards custom headers', async () => {
+      await api.attachContacts('t1', { where: { id: 'c1' } }, headers)
+      expect(client.post).toHaveBeenCalledWith(
+        '/tags/t1/contacts',
+        { where: { id: 'c1' } },
+        headers,
+      )
+    })
+  })
+
+  describe('detachContacts', () => {
+    it('calls client.request with DELETE /tags/:id/contacts and the selection', async () => {
+      vi.mocked(client.request).mockResolvedValue('OK')
+      const body = { where: { id: 'c1' } }
+      const result = await api.detachContacts('t1', body, headers)
+      expect(client.request).toHaveBeenCalledWith('DELETE', '/tags/t1/contacts', body, headers)
+      expect(result).toBe('OK')
+    })
+  })
+
+  describe('attachManyToDepartments', () => {
+    it('calls client.post with /tags/attach-many-departments and body', async () => {
+      vi.mocked(client.post).mockResolvedValue('OK')
+      const body = { ids: ['t1', 't2'], departmentIds: ['d1'] }
+      const result = await api.attachManyToDepartments(body)
+      expect(client.post).toHaveBeenCalledWith('/tags/attach-many-departments', body, undefined)
+      expect(result).toBe('OK')
+    })
+  })
+
+  describe('error propagation', () => {
+    it('propagates errors from attachManyToDepartments', async () => {
+      vi.mocked(client.post).mockRejectedValue(new Error('Invalid tag ids'))
+      await expect(api.attachManyToDepartments({ ids: [], departmentIds: [] })).rejects.toThrow(
+        'Invalid tag ids',
+      )
+    })
+  })
+})

package/src/apis/tags/TagsApi.ts

@@ -1,9 +1,65 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Tag, CreateTagPayload, UpdateTagPayload } from './types'
+import type { ContactsSelection } from '../contacts/types'
+import type {
+  AttachTagsToDepartmentsPayload,
+  CreateTagPayload,
+  Tag,
+  UpdateTagPayload,
+} from './types'
 
 export class TagsApi extends BaseCrudApi<Tag, CreateTagPayload, UpdateTagPayload> {
   constructor(client: ApiClient) {
     super(client, '/tags')
   }
+
+  /**
+   * Adds the tag to every contact of the account that matches the selection. Resolves to `'OK'`.
+   * @permissions tags.view
+   */
+  attachContacts(
+    id: string,
+    body: ContactsSelection,
+    headers?: Record<string, string>,
+  ): Promise<string> {
+    return this.client.post<string, ContactsSelection>(
+      `${this.basePath}/${id}/contacts`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Removes the tag from every contact of the account that matches the selection. Resolves to
+   * `'OK'`.
+   * @permissions tags.view OR tags.destroy
+   */
+  detachContacts(
+    id: string,
+    body: ContactsSelection,
+    headers?: Record<string, string>,
+  ): Promise<string> {
+    return this.client.request<string, ContactsSelection>(
+      'DELETE',
+      `${this.basePath}/${id}/contacts`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Links several tags to the given departments. Resolves to `'OK'`. A tag without departments
+   * is already available to all of them and is left unchanged.
+   * @permissions tags.view
+   */
+  attachManyToDepartments(
+    body: AttachTagsToDepartmentsPayload,
+    headers?: Record<string, string>,
+  ): Promise<string> {
+    return this.client.post<string, AttachTagsToDepartmentsPayload>(
+      `${this.basePath}/attach-many-departments`,
+      body,
+      headers,
+    )
+  }
 }

package/src/apis/tags/types.ts

@@ -27,3 +27,12 @@ export type UpdateTagPayload = {
   label?: string
   backgroundColor?: string | null
 }
+
+/**
+ * Body for `POST /tags/attach-many-departments`. An empty `departmentIds` makes the tags
+ * available to every department.
+ */
+export type AttachTagsToDepartmentsPayload = {
+  ids: string[]
+  departmentIds: string[]
+}

package/src/apis/terms/TermsApi.test.ts

@@ -66,7 +66,7 @@ describe('TermsApi', () => {
     it('serializes the query', async () => {
       vi.mocked(client.get).mockResolvedValue(term)
       await api.getById('term-1', { attributes: ['id', 'version'] })
-      const url = vi.mocked(client.get).mock.calls[0][0] as string
+      const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
       expect(url).toContain('/terms/term-1?')
       expect(url).toContain('attributes')
     })