@ikatec/digisac-api-sdk 4.5.1 → 4.7.0

package/src/apis/schedule/ScheduleApi.ts

@@ -1,13 +1,66 @@
 import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Schedule, CreateSchedulePayload, UpdateSchedulePayload } from './types'
-
-export class ScheduleApi extends BaseCrudApi<
+import { BaseReadApi } from '../../core/BaseReadApi'
+import type {
   Schedule,
+  ScheduleRecord,
   CreateSchedulePayload,
-  UpdateSchedulePayload
-> {
+  UpdateSchedulePayload,
+} from './types'
+
+/**
+ * Scheduled messages. Create answers no body and update answers the stored record, so this
+ * class extends `BaseReadApi` and writes its own create/update/delete.
+ */
+export class ScheduleApi extends BaseReadApi<Schedule> {
   constructor(client: ApiClient) {
     super(client, '/schedule')
   }
+
+  /**
+   * Creates a schedule. Resolves with NO CONTENT: find it back with `getOne` (e.g. by
+   * `contactId` and `scheduledAt`).
+   * @permissions schedule.create
+   */
+  create(body: CreateSchedulePayload, headers?: Record<string, string>): Promise<void> {
+    return this.client.post<void, CreateSchedulePayload>(this.basePath, body, headers)
+  }
+
+  /**
+   * Updates a schedule. Resolves to the stored record, without relationships. An unknown id
+   * answers 500.
+   * @permissions schedule.view OR schedule.update
+   */
+  updateById(
+    id: string,
+    body: UpdateSchedulePayload,
+    headers?: Record<string, string>,
+  ): Promise<ScheduleRecord> {
+    return this.client.put<ScheduleRecord, UpdateSchedulePayload>(
+      `${this.basePath}/${id}`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Deletes a schedule (soft delete). Resolves to `'OK'`; an unknown id answers 500.
+   * @permissions schedule.view OR schedule.destroy
+   */
+  deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.delete<'OK'>(`${this.basePath}/${id}`, headers)
+  }
+
+  /**
+   * Deletes several schedules of the account. Ids that are not UUIDs, or of another account, are
+   * skipped in silence; always resolves to `'OK'`.
+   * @permissions schedule.destroy
+   */
+  deleteMany(ids: string[], headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.request<'OK', { where: { id: string[] } }>(
+      'DELETE',
+      `${this.basePath}/many`,
+      { where: { id: ids } },
+      headers,
+    )
+  }
 }

package/src/apis/schedule/types.ts

@@ -1,15 +1,28 @@
 import type { Contact } from '../contacts/types'
 import type { Department } from '../departments/types'
+import type { File } from '../files/types'
 import type { User } from '../users/types'
 
+/** `scheduled` until the worker runs it; `error` and `not_sent` come with the `reason`. */
+export type ScheduleStatus = 'scheduled' | 'done' | 'error' | 'not_sent'
+
 export type Schedule = {
   id: string
-  status: string
+  status: ScheduleStatus
+  /**
+   * Why it was not sent: `ALREADY_TICKET_OPENED`, `DDD_BLOCKED`, `SERVICE_IS_NOT_ENABLED`,
+   * `CONTACT_IS_BLOCKED`, `CONTACT_NOT_EXISTS`, `HSM_LIMIT_EXCEEDED`, `HSM_IS_BLOCKED`,
+   * `SERVICE_IS_BLOCKED`, `INVALID_PAYLOAD`, a WhatsApp Business error code or
+   * `SCHEDULE_UNKNOWN_REASON`.
+   */
   reason: string | null
-  message: string
+  /** For a WhatsApp Business template (`hsmId`), the message the server built from it. */
+  message: string | null
   notes: string
-  openTicket: boolean
-  notificateUser: boolean
+  openTicket: boolean | null
+  notificateUser: boolean | null
+  /** Sends the message even when the contact already has an open ticket. */
+  sendWithOpenTicket: boolean | null
   extraOptions: Record<string, unknown> | null
   hsmId: string | null
   hsmFileId: string | null
@@ -20,39 +33,81 @@ export type Schedule = {
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
   // relationships
   contact?: Contact
   department?: Department
   user?: User | null
+  files?: File[]
+  /** The header media of the WhatsApp Business template. */
+  hsmFile?: File
+}
+
+/** The schedule as stored, without relationships: what `updateById` resolves to. */
+export type ScheduleRecord = Omit<
+  Schedule,
+  'contact' | 'department' | 'user' | 'files' | 'hsmFile'
+> & {
+  deletedAt: string | null
 }
 
-export type ScheduleRelationships = 'contact' | 'department' | 'user'
+export type ScheduleRelationships =
+  | 'contact'
+  | 'department'
+  | 'user'
+  | 'files'
+  | 'hsmFile'
+  | 'contact.service'
+  | 'contact.person'
+
+/** A new attachment. */
+export type ScheduleNewFilePayload = { base64: string; name: string; mimetype: string }
 
+/** On update: a new attachment, or one to keep (`id`). */
+export type ScheduleFilePayload = ScheduleNewFilePayload | { id: string }
+
+/**
+ * Another schedule of the connection less than 5 minutes apart answers 402
+ * (`Schedule time is already exist.`). A contact of another account answers 500.
+ */
 export type CreateSchedulePayload = {
   scheduledAt: string
   contactId: string
   departmentId: string
-  message: string
+  /** Up to 1024 characters. Optional for a WhatsApp Business template, built from `hsmId`. */
+  message?: string
+  /**
+   * Up to 1024 characters. Required by the route only with `openTicket: true`, but the column is
+   * NOT NULL: send it always (an empty string is fine).
+   */
   notes: string
-  openTicket: boolean
+  openTicket?: boolean
   notificateUser?: boolean
+  sendWithOpenTicket?: boolean
   userId?: string
   hsmId?: string
   hsmFileId?: string
   extraOptions?: Record<string, unknown>
+  /** New attachments only: the create drops `{ id }` items. */
+  files?: ScheduleNewFilePayload[]
 }
 
+/**
+ * Not partial: `scheduledAt`, `contactId` and `departmentId` are required on update too. The
+ * 5-minute conflict (402) is checked against the whole account.
+ */
 export type UpdateSchedulePayload = {
-  scheduledAt?: string
-  contactId?: string
-  departmentId?: string
+  scheduledAt: string
+  contactId: string
+  departmentId: string
   userId?: string | null
   message?: string
   notes?: string
   openTicket?: boolean
   notificateUser?: boolean
+  sendWithOpenTicket?: boolean
   hsmId?: string | null
   hsmFileId?: string | null
   extraOptions?: Record<string, unknown> | null
+  /** Replaces the attachments: `{ id }` keeps one, `{ base64, ... }` adds one; omitted or `[]` removes all. */
+  files?: ScheduleFilePayload[]
 }

package/src/apis/ticketTopics/TicketTopicsApi.test.ts

@@ -55,4 +55,44 @@ describe('TicketTopicsApi', () => {
     await unarchive('t1')
     expect(client.post).toHaveBeenCalledTimes(2)
   })
+
+  it('create sends the department ids', async () => {
+    await api.create({ name: 'Dúvida', departments: ['d1'] })
+    expect(client.post).toHaveBeenCalledWith(
+      '/ticket-topics',
+      { name: 'Dúvida', departments: ['d1'] },
+      undefined,
+    )
+  })
+
+  it('getMany sends the department filters at the top of the query', async () => {
+    const query = { departmentIds: ['d1'], includeNoDepartment: true }
+    await api.getMany(query)
+    expect(client.get).toHaveBeenCalledWith(
+      `/ticket-topics?query=${encodeURIComponent(JSON.stringify(query))}`,
+      undefined,
+    )
+  })
+
+  it('deleteById resolves to the OK of the route', async () => {
+    vi.mocked(client.delete).mockResolvedValue('OK')
+    expect(await api.deleteById('t1')).toBe('OK')
+    expect(client.delete).toHaveBeenCalledWith('/ticket-topics/t1', undefined)
+  })
+
+  it('getOne reads one item of the paginated list, where the department filters apply', async () => {
+    vi.mocked(client.get).mockResolvedValue({ data: [{ id: 't1' }], total: 1 })
+    expect(await api.getOne({ departmentIds: ['d1'] })).toEqual({ id: 't1' })
+    expect(client.get).toHaveBeenCalledWith(
+      `/ticket-topics?query=${encodeURIComponent(
+        JSON.stringify({ departmentIds: ['d1'], paginate: true, perPage: 1, page: 1 }),
+      )}`,
+      undefined,
+    )
+  })
+
+  it('getOne resolves null on an empty page', async () => {
+    vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+    expect(await api.getOne()).toBeNull()
+  })
 })

package/src/apis/ticketTopics/TicketTopicsApi.ts

@@ -1,11 +1,18 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { TicketTopic, CreateTicketTopicPayload, UpdateTicketTopicPayload } from './types'
+import type {
+  TicketTopic,
+  TicketTopicListQuery,
+  CreateTicketTopicPayload,
+  UpdateTicketTopicPayload,
+} from './types'
 
 export class TicketTopicsApi extends BaseCrudApi<
   TicketTopic,
   CreateTicketTopicPayload,
-  UpdateTicketTopicPayload
+  UpdateTicketTopicPayload,
+  TicketTopicListQuery,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/ticket-topics')
@@ -13,10 +20,34 @@ export class TicketTopicsApi extends BaseCrudApi<
     this.unarchive = this.unarchive.bind(this)
   }
 
+  /**
+   * Returns the first topic matching the query, or `null` when none match. Reads one item of the
+   * paginated list (instead of `paginate: false`), the only path where `departmentIds` and
+   * `includeNoDepartment` apply.
+   * @permissions ticketTopics.view
+   */
+  override async getOne(
+    query?: TicketTopicListQuery,
+    headers?: Record<string, string>,
+  ): Promise<TicketTopic | null> {
+    const page = await this.getMany({ ...query, paginate: true, perPage: 1, page: 1 }, headers)
+    return page?.data?.[0] ?? null
+  }
+
+  /**
+   * Deletes a ticket topic (soft delete). Resolves to `'OK'`; an unknown id answers 500.
+   * @permissions ticketTopics.view OR ticketTopics.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
+
   /**
    * Archives a ticket topic. Unlike most resources, ticket-topics archive through a
    * dedicated endpoint (POST `${basePath}/${id}/archive`) rather than `updateById`.
-   * @permissions ticketTopic.update
+   * Resolves to the stored topic, without `departments`. A topic used in a bot answers 403;
+   * an unknown id answers 500.
+   * @permissions ticketTopics.archive
    */
   archive(id: string, headers?: Record<string, string>): Promise<TicketTopic> {
     return this.client.post<TicketTopic>(
@@ -28,7 +59,7 @@ export class TicketTopicsApi extends BaseCrudApi<
 
   /**
    * Restores a previously archived ticket topic via the same dedicated endpoint.
-   * @permissions ticketTopic.update
+   * @permissions ticketTopics.archive
    */
   unarchive(id: string, headers?: Record<string, string>): Promise<TicketTopic> {
     return this.client.post<TicketTopic>(

package/src/apis/ticketTopics/types.ts

@@ -1,3 +1,6 @@
+import type { ListQuery } from '../../core/types'
+import type { Department } from '../departments/types'
+
 export type TicketTopic = {
   id: string
   name: string
@@ -6,12 +9,34 @@ export type TicketTopic = {
   createdAt: string
   updatedAt: string
   deletedAt: string | null
+  // relationships
+  /** Always comes in the paginated `getMany`; elsewhere only with `include`. Empty = all departments. */
+  departments?: Department[]
+}
+
+export type TicketTopicRelationships = 'departments'
+
+/**
+ * Department filters of the paginated `getMany` and of `getOne`. `getMany({ paginate: false })`
+ * ignores them in silence (the route reads them only on the paginated path).
+ */
+export type TicketTopicListQuery = ListQuery<TicketTopic> & {
+  /** Topics linked to any of these departments. */
+  departmentIds?: string | string[]
+  /** Also (or only) the topics linked to no department. Only with the default `'json'` query format. */
+  includeNoDepartment?: boolean
 }
 
 export type CreateTicketTopicPayload = {
+  /** Unique in the account (409, unless the account allows duplicate names); trimmed. */
   name: string
+  /** Department ids; `[]` = all departments. Required: a missing list answers 500 after creating the topic. */
+  departments: string[]
 }
 
 export type UpdateTicketTopicPayload = {
-  name?: string
+  /** Required on update too. */
+  name: string
+  /** Department ids, replacing the current ones; omitted keeps them. */
+  departments?: string[]
 }

package/src/apis/tickets/TicketsApi.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { TicketsApi } from './TicketsApi'
 import type { ApiClient } from '../../core/ApiClient'
+import type { TicketsListQuery } from './types'
 
 // ── Mock client factory ──────────────────────────────────────────────
 
@@ -18,6 +19,8 @@ function createMockClient(): ApiClient {
 
 // ── Tests ────────────────────────────────────────────────────────────
 
+const headers = { 'X-Custom': 'value' }
+
 describe('TicketsApi', () => {
   let client: ReturnType<typeof createMockClient>
   let api: TicketsApi
@@ -29,18 +32,28 @@ describe('TicketsApi', () => {
 
   describe('closeMany', () => {
     it('PUTs /tickets/close-many with explicit ids', async () => {
-      vi.mocked(client.put).mockResolvedValue({ ok: true })
+      vi.mocked(client.put).mockResolvedValue(undefined)
       const result = await api.closeMany({ ids: ['t1', 't2'] })
       expect(client.put).toHaveBeenCalledWith(
         '/tickets/close-many',
         { ids: ['t1', 't2'] },
         undefined,
       )
-      expect(result).toEqual({ ok: true })
+      expect(result).toBeUndefined()
+    })
+
+    it('sends the subjects and the summary of the closing', async () => {
+      vi.mocked(client.put).mockResolvedValue(undefined)
+      await api.closeMany({ ids: ['t1'], ticketTopicIds: ['tt1'], comments: 'Resolved' })
+      expect(client.put).toHaveBeenCalledWith(
+        '/tickets/close-many',
+        { ids: ['t1'], ticketTopicIds: ['tt1'], comments: 'Resolved' },
+        undefined,
+      )
     })
 
     it('PUTs /tickets/close-many with a JSON-stringified query for the select-all variant', async () => {
-      vi.mocked(client.put).mockResolvedValue({ ok: true })
+      vi.mocked(client.put).mockResolvedValue(undefined)
       await api.closeMany({ allContactsSelected: true, query: { query: '{"where":{}}' } })
       expect(client.put).toHaveBeenCalledWith(
         '/tickets/close-many',
@@ -50,8 +63,7 @@ describe('TicketsApi', () => {
     })
 
     it('forwards custom headers', async () => {
-      vi.mocked(client.put).mockResolvedValue({ ok: true })
-      const headers = { 'X-Custom': 'value' }
+      vi.mocked(client.put).mockResolvedValue(undefined)
       await api.closeMany({ ids: ['t1'] }, headers)
       expect(client.put).toHaveBeenCalledWith('/tickets/close-many', { ids: ['t1'] }, headers)
     })
@@ -61,4 +73,129 @@ describe('TicketsApi', () => {
       await expect(api.closeMany({ ids: ['t1'] })).rejects.toThrow('Forbidden')
     })
   })
+
+  describe('deprecated CRUD', () => {
+    it('keeps create, updateById and deleteById on the generic routes', async () => {
+      vi.mocked(client.post).mockResolvedValue({})
+      vi.mocked(client.put).mockResolvedValue({})
+      vi.mocked(client.delete).mockResolvedValue({})
+      await api.create({ contactId: 'c1', departmentId: 'd1' })
+      await api.updateById('t1', { comments: 'x' })
+      await api.deleteById('t1')
+      expect(client.post).toHaveBeenCalledWith(
+        '/tickets',
+        { contactId: 'c1', departmentId: 'd1' },
+        undefined,
+      )
+      expect(client.put).toHaveBeenCalledWith('/tickets/t1', { comments: 'x' }, undefined)
+      expect(client.delete).toHaveBeenCalledWith('/tickets/t1', undefined)
+    })
+  })
+
+  describe('count', () => {
+    it('GETs /tickets/count with the query', async () => {
+      vi.mocked(client.get).mockResolvedValue({ count: 3 })
+      const query = { where: { isOpen: true } }
+      const result = await api.count(query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/tickets/count?query=${encodeURIComponent(JSON.stringify(query))}`,
+        undefined,
+      )
+      expect(result).toEqual({ count: 3 })
+    })
+
+    it('GETs /tickets/count without a query', async () => {
+      vi.mocked(client.get).mockResolvedValue({ count: 10 })
+      await api.count()
+      expect(client.get).toHaveBeenCalledWith('/tickets/count', undefined)
+    })
+
+    it('sends the queries for one count per query', async () => {
+      vi.mocked(client.get).mockResolvedValue({ counts: [1, 2] })
+      const query = { queries: [{ where: { isOpen: true } }, { where: { isOpen: false } }] }
+      const result = await api.count(query, headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/tickets/count?query=${encodeURIComponent(JSON.stringify(query))}`,
+        headers,
+      )
+      expect(result).toEqual({ counts: [1, 2] })
+    })
+  })
+
+  describe('countPost', () => {
+    it('POSTs /tickets/count with the filters and the query', async () => {
+      vi.mocked(client.post).mockResolvedValue({ count: 3 })
+      const body = { where: { isOpen: true }, query: {} }
+      const result = await api.countPost(body, headers)
+      expect(client.post).toHaveBeenCalledWith('/tickets/count', body, headers)
+      expect(result).toEqual({ count: 3 })
+    })
+
+    it('POSTs the queries for one count per query', async () => {
+      vi.mocked(client.post).mockResolvedValue({ counts: [3, 0] })
+      const body = {
+        query: { queries: [{ where: { isOpen: true } }, { where: { isOpen: false } }] },
+      }
+      const result = await api.countPost(body)
+      expect(client.post).toHaveBeenCalledWith('/tickets/count', body, undefined)
+      expect(result).toEqual({ counts: [3, 0] })
+    })
+  })
+
+  describe('open ticket counts', () => {
+    it('GETs /tickets/count-open/{serviceId}', async () => {
+      vi.mocked(client.get).mockResolvedValue(3)
+      expect(await api.countOpenByService('s1', headers)).toBe(3)
+      expect(client.get).toHaveBeenCalledWith('/tickets/count-open/s1', headers)
+    })
+
+    it('GETs /tickets/count-open-by-department/{departmentId}', async () => {
+      vi.mocked(client.get).mockResolvedValue(2)
+      expect(await api.countOpenByDepartment('d1')).toBe(2)
+      expect(client.get).toHaveBeenCalledWith('/tickets/count-open-by-department/d1', undefined)
+    })
+
+    it('GETs /tickets/count-open-by-user/{userId}', async () => {
+      vi.mocked(client.get).mockResolvedValue(0)
+      expect(await api.countOpenByUser('u1')).toBe(0)
+      expect(client.get).toHaveBeenCalledWith('/tickets/count-open-by-user/u1', undefined)
+    })
+  })
+
+  describe('getFirstWaitingTime', () => {
+    it('GETs /tickets/{id}/first-waiting-time', async () => {
+      vi.mocked(client.get).mockResolvedValue('00:01:30')
+      expect(await api.getFirstWaitingTime('t1', headers)).toBe('00:01:30')
+      expect(client.get).toHaveBeenCalledWith('/tickets/t1/first-waiting-time', headers)
+    })
+  })
+
+  describe('exportTxt', () => {
+    it('POSTs /tickets/export with the protocol', async () => {
+      vi.mocked(client.post).mockResolvedValue('Nome do contato: A')
+      expect(await api.exportTxt('202610061675', headers)).toBe('Nome do contato: A')
+      expect(client.post).toHaveBeenCalledWith(
+        '/tickets/export',
+        { protocol: '202610061675' },
+        headers,
+      )
+    })
+  })
+
+  describe('exportHistory', () => {
+    it('POSTs /tickets/export-history with the query in the URL and no body', async () => {
+      vi.mocked(client.post).mockResolvedValue('Protocolo;Nome\n')
+      const query: TicketsListQuery = {
+        where: { isOpen: true },
+        include: [{ model: 'contact', include: ['service'] }],
+        order: [['startedAt', 'DESC']],
+      }
+      expect(await api.exportHistory(query)).toBe('Protocolo;Nome\n')
+      expect(client.post).toHaveBeenCalledWith(
+        `/tickets/export-history?query=${encodeURIComponent(JSON.stringify(query))}`,
+        undefined,
+        undefined,
+      )
+    })
+  })
 })