@ikatec/digisac-api-sdk 4.9.0 → 4.10.0

package/src/apis/absence/AbsenceApi.ts

@@ -1,9 +1,28 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
+import type { GetByIdQuery } from '../../core/types'
 import type { Absence, CreateAbsencePayload, UpdateAbsencePayload } from './types'
 
+/**
+ * Absences of the users. The backend serves the report (`GET /absence`), `POST /absence` and
+ * `PUT /absence/:id`; there is no read by id nor delete.
+ */
 export class AbsenceApi extends BaseCrudApi<Absence, CreateAbsencePayload, UpdateAbsencePayload> {
   constructor(client: ApiClient) {
     super(client, '/absence')
   }
+
+  /** @deprecated Not served: the backend has no GET /absence/:id, so this route answers 404. */
+  override getById(
+    id: string,
+    query?: GetByIdQuery<Absence>,
+    headers?: Record<string, string>,
+  ): Promise<Absence> {
+    return super.getById(id, query, headers)
+  }
+
+  /** @deprecated Not served: the backend has no DELETE /absence/:id, so this route answers 404. */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<Absence> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/acceptanceTerms/AcceptanceTermsApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type {
   AcceptanceTerm,
@@ -9,9 +10,20 @@ import type {
 export class AcceptanceTermsApi extends BaseCrudApi<
   AcceptanceTerm,
   CreateAcceptanceTermPayload,
-  UpdateAcceptanceTermPayload
+  UpdateAcceptanceTermPayload,
+  ListQuery<AcceptanceTerm>,
+  void
 > {
   constructor(client: ApiClient) {
     super(client, '/acceptance-terms')
   }
+
+  /**
+   * Deletes an acceptance term. Resolves with no body; a term in use answers 404 `{ message: 'Term
+   * in use' }`.
+   * @permissions acceptanceTerms.view OR acceptanceTerms.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<void> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/accounts/AccountsApi.ts

@@ -2,6 +2,11 @@ import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Account, CreateAccountPayload, UpdateAccountPayload } from './types'
 
+/**
+ * @deprecated Not served: the backend mounts no `/accounts` route, so every method answers 404
+ * `Route not found.`. Read and update the account of the user with `MeApi.getAccount` and
+ * `MeApi.updateAccount`; `/admin/accounts` is a super admin route, kept out of the SDK.
+ */
 export class AccountsApi extends BaseCrudApi<Account, CreateAccountPayload, UpdateAccountPayload> {
   constructor(client: ApiClient) {
     super(client, '/accounts')

package/src/apis/accounts/types.ts

@@ -121,6 +121,8 @@ export type AccountSettingsCampaign = {
 }
 
 export type AccountSettings = {
+  /** Enables the block list (required by `ContactsApi.block`). */
+  isBlockListActive?: boolean
   /** Feature flags that toggle specific platform capabilities. */
   flags?: AccountSettingsFlags
   /** Enables/disables specific communication channels (whatsapp, telegram, webchat, etc.). */

package/src/apis/activityLog/ActivityLogApi.ts

@@ -2,6 +2,10 @@ import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { ActivityLog, CreateActivityLogPayload, UpdateActivityLogPayload } from './types'
 
+/**
+ * Activity log of the account (stored in MongoDB: the routes answer 503 when it is unavailable).
+ * The backend serves `GET /log`, `GET /log/:id` and `POST /log`; there is no update or delete.
+ */
 export class ActivityLogApi extends BaseCrudApi<
   ActivityLog,
   CreateActivityLogPayload,
@@ -10,4 +14,18 @@ export class ActivityLogApi extends BaseCrudApi<
   constructor(client: ApiClient) {
     super(client, '/log')
   }
+
+  /** @deprecated Not served: the backend has no PUT /log/:id, so this route answers 404. */
+  override updateById(
+    id: string,
+    body: UpdateActivityLogPayload,
+    headers?: Record<string, string>,
+  ): Promise<ActivityLog> {
+    return super.updateById(id, body, headers)
+  }
+
+  /** @deprecated Not served: the backend has no DELETE /log/:id, so this route answers 404. */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<ActivityLog> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/categories/CategoriesApi.ts

@@ -1,13 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Category, CreateCategoryPayload, UpdateCategoryPayload } from './types'
 
 export class CategoriesApi extends BaseCrudApi<
   Category,
   CreateCategoryPayload,
-  UpdateCategoryPayload
+  UpdateCategoryPayload,
+  ListQuery<Category>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/categories')
   }
+
+  /**
+   * Deletes a category. Resolves the text `'OK'`; an unknown id answers 500. The route checks no
+   * permission.
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/clientFeedback/ClientFeedbackApi.ts

@@ -8,7 +8,11 @@ export class ClientFeedbackApi
 {
   private readonly basePath = '/client-feedback'
 
-  /** Creates a client feedback record for a ticket (accountId, ticketId, and feedback text are required). */
+  /**
+   * @deprecated The route is broken in the backend: it is mounted with no authentication (the
+   * account context throws, 500) and calls a `createFeedback` the resource does not have. The
+   * feedback on the AI summary is stored when the ticket is closed.
+   */
   create(
     body: CreateClientFeedbackPayload,
     headers?: Record<string, string>,

package/src/apis/contactBlockLists/ContactBlockListsApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type {
   ContactBlockList,
@@ -9,9 +10,20 @@ import type {
 export class ContactBlockListsApi extends BaseCrudApi<
   ContactBlockList,
   CreateContactBlockListPayload,
-  UpdateContactBlockListPayload
+  UpdateContactBlockListPayload,
+  ListQuery<ContactBlockList>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/contact-block-lists')
   }
+
+  /**
+   * Deletes a block list and its numbers. Resolves the text `'OK'`; a list being processed (or with
+   * a block/unblock in progress) answers 500.
+   * @permissions contacts.view OR contacts.destroy OR contacts.block
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/contactBlockListsControls/ContactBlockListsControlsApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type {
   ContactBlockListsControl,
@@ -9,9 +10,19 @@ import type {
 export class ContactBlockListsControlsApi extends BaseCrudApi<
   ContactBlockListsControl,
   CreateContactBlockListsControlPayload,
-  UpdateContactBlockListsControlPayload
+  UpdateContactBlockListsControlPayload,
+  ListQuery<ContactBlockListsControl>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/contact-block-lists-controls')
   }
+
+  /**
+   * Deletes a block/unblock run. Resolves the text `'OK'`.
+   * @permissions contacts.view OR contacts.destroy OR contacts.block
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/contacts/ContactsApi.test.ts

@@ -202,12 +202,13 @@ describe('ContactsApi', () => {
   // ── exportTemplate ───────────────────────────────────────────────
 
   describe('exportTemplate', () => {
-    it('calls client.post with /contacts/export-template and body', async () => {
-      vi.mocked(client.post).mockResolvedValue({ ok: true })
-      const body: ExportTemplatePayload = { serviceType: 'whatsapp', type: 'csv' }
+    it('calls client.post with /contacts/export-template and resolves the CSV text', async () => {
+      const csv = 'Nome;DDI;Número;Atendente Padrão;Departamento Padrão;Tags;Criado em\n'
+      vi.mocked(client.post).mockResolvedValue(csv)
+      const body: ExportTemplatePayload = { serviceType: 'whatsapp' }
       const result = await api.exportTemplate(body)
       expect(client.post).toHaveBeenCalledWith('/contacts/export-template', body, undefined)
-      expect(result).toEqual({ ok: true })
+      expect(result).toBe(csv)
     })
 
     it('forwards custom headers', async () => {
@@ -476,6 +477,21 @@ describe('ContactsApi', () => {
 
   // ── block ────────────────────────────────────────────────────────
 
+  describe('summarizeTicket', () => {
+    it('calls client.post with /contacts/:id/ticket/summary and no body', async () => {
+      vi.mocked(client.post).mockResolvedValue({ success: true })
+      const result = await api.summarizeTicket('c1')
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/summary', undefined, undefined)
+      expect(result).toEqual({ success: true })
+    })
+
+    it('forwards custom headers', async () => {
+      const headers = { 'X-Custom': 'value' }
+      await api.summarizeTicket('c1', headers)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/summary', undefined, headers)
+    })
+  })
+
   describe('block', () => {
     it('calls client.post with /contacts/:id/block and body', async () => {
       vi.mocked(client.post).mockResolvedValue({ ...contact, block: true })

package/src/apis/contacts/ContactsApi.ts

@@ -21,6 +21,7 @@ import type {
   SyncContactPayload,
   TransferTicketPayload,
   UpdateContactPayload,
+  SummarizeTicketResult,
 } from './types'
 
 export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, UpdateContactPayload> {
@@ -29,11 +30,12 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
   }
 
   /**
-   * Downloads a CSV template for importing contacts, with columns based on the service type.
+   * Downloads the CSV template (`;`-separated header line, in the language of the user) for
+   * importing contacts, with columns based on the service type. Answered with no Content-Type.
    * @permissions contacts.view AND contacts.export
    */
-  exportTemplate(body: ExportTemplatePayload, headers?: Record<string, string>): Promise<unknown> {
-    return this.client.post<unknown, ExportTemplatePayload>(
+  exportTemplate(body: ExportTemplatePayload, headers?: Record<string, string>): Promise<string> {
+    return this.client.post<string, ExportTemplatePayload>(
       `${this.basePath}/export-template`,
       body,
       headers,
@@ -172,7 +174,9 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
 
   /**
    * Starts the import of a CSV file previously uploaded through `FilesApi`. The import runs
-   * in the background; the header line is validated against the service type template.
+   * in the background; `csvHeaderLine` is validated against the service type template, with
+   * every column of `exportTemplate` (including "Criado em"/"Created at"): a different header
+   * answers 403 `Csv File - Invalid Header`. The file itself is only read by the job.
    * Resolves to `'OK'`.
    * @permissions contacts.view OR contacts.update OR contacts.create
    */
@@ -199,7 +203,8 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
 
   /**
    * Blocks or unblocks a contact. Blocking closes the contact's open ticket. Requires the
-   * block list to be active on the account.
+   * block list to be active on the account (`settings.isBlockListActive`; 400 otherwise).
+   * `byUserId` and `description` are stored as sent: the backend does not fill in the user.
    * @permissions contacts.block
    */
   block(id: string, body: BlockContactPayload, headers?: Record<string, string>): Promise<Contact> {
@@ -210,6 +215,20 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
     )
   }
 
+  /**
+   * Generates an AI summary of the open ticket of the contact. Consumes AI credits; resolves
+   * `{ success, limitReached? }`. A contact with no open ticket (or an unknown contact) answers
+   * 400.
+   * @permissions tickets.update
+   */
+  summarizeTicket(id: string, headers?: Record<string, string>): Promise<SummarizeTicketResult> {
+    return this.client.post<SummarizeTicketResult>(
+      `${this.basePath}/${id}/ticket/summary`,
+      undefined,
+      headers,
+    )
+  }
+
   /**
    * Resets the contact's unread counter. Resolves to `'OK'`.
    * @permissions contacts.view OR contacts.update

package/src/apis/contacts/types.ts

@@ -176,9 +176,15 @@ export type UpdateContactPayload = {
   tagIds?: string[]
 }
 
+/** Result of `ContactsApi.summarizeTicket`. */
+export type SummarizeTicketResult = {
+  success: boolean
+  limitReached?: boolean
+}
+
 export type ExportTemplatePayload = {
   serviceType: string
-  type: string
+  type?: string
 }
 
 export type CountContactsQuery = ListQuery<Contact> & {

package/src/apis/creditMovements/CreditMovementsApi.ts

@@ -6,6 +6,11 @@ import type {
   UpdateCreditMovementPayload,
 } from './types'
 
+/**
+ * Credit movements of the account (SMS and AI credits), only for reading: the writes are super
+ * admin routes (`/admin/credit-movements`). The backend serves only `GET /credit-movements` and
+ * `GET /credit-movements/:id`.
+ */
 export class CreditMovementsApi extends BaseCrudApi<
   CreditMovement,
   CreateCreditMovementPayload,
@@ -14,4 +19,26 @@ export class CreditMovementsApi extends BaseCrudApi<
   constructor(client: ApiClient) {
     super(client, '/credit-movements')
   }
+
+  /** @deprecated Not served: the backend has no POST /credit-movements, so this route answers 404. */
+  override create(
+    body: CreateCreditMovementPayload,
+    headers?: Record<string, string>,
+  ): Promise<CreditMovement> {
+    return super.create(body, headers)
+  }
+
+  /** @deprecated Not served: the backend has no PUT /credit-movements/:id, so this route answers 404. */
+  override updateById(
+    id: string,
+    body: UpdateCreditMovementPayload,
+    headers?: Record<string, string>,
+  ): Promise<CreditMovement> {
+    return super.updateById(id, body, headers)
+  }
+
+  /** @deprecated Not served: the backend has no DELETE /credit-movements/:id, so this route answers 404. */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<CreditMovement> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/customFields/CustomFieldsApi.ts

@@ -1,13 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { CustomField, CreateCustomFieldPayload, UpdateCustomFieldPayload } from './types'
 
 export class CustomFieldsApi extends BaseCrudApi<
   CustomField,
   CreateCustomFieldPayload,
-  UpdateCustomFieldPayload
+  UpdateCustomFieldPayload,
+  ListQuery<CustomField>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/custom-fields')
   }
+
+  /**
+   * Deletes a custom field. Resolves the text `'OK'`.
+   * @permissions customFields.view OR customFields.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/departments/DepartmentsApi.test.ts

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DepartmentsApi } from './DepartmentsApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type { Department } 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(),
+  }
+}
+
+const department: Department = {
+  id: 'dep-1',
+  name: 'Support',
+  accountId: 'acc-1',
+  distributionId: null,
+  archivedAt: '2026-01-01T00:00:00Z',
+  createdAt: '2026-01-01T00:00:00Z',
+  updatedAt: '2026-01-01T00:00:00Z',
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('DepartmentsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: DepartmentsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new DepartmentsApi(client)
+  })
+
+  describe('archiveWithValidation', () => {
+    it('calls client.post with /departments/:id/archive and { archive: true }', async () => {
+      vi.mocked(client.post).mockResolvedValue(department)
+      const result = await api.archiveWithValidation('dep-1', { archive: true })
+      expect(client.post).toHaveBeenCalledWith(
+        '/departments/dep-1/archive',
+        { archive: true },
+        undefined,
+      )
+      expect(result).toEqual(department)
+    })
+
+    it('restores with { archive: false } and forwards custom headers', async () => {
+      const headers = { 'X-Custom': 'value' }
+      await api.archiveWithValidation('dep-1', { archive: false }, headers)
+      expect(client.post).toHaveBeenCalledWith(
+        '/departments/dep-1/archive',
+        { archive: false },
+        headers,
+      )
+    })
+  })
+
+  describe('archive / unarchive (PUT { archivedAt })', () => {
+    it('archive sends the current time in archivedAt', async () => {
+      await api.archive('dep-1')
+      expect(client.put).toHaveBeenCalledWith(
+        '/departments/dep-1',
+        { archivedAt: expect.any(String) },
+        undefined,
+      )
+    })
+
+    it('unarchive sends archivedAt null', async () => {
+      await api.unarchive('dep-1')
+      expect(client.put).toHaveBeenCalledWith('/departments/dep-1', { archivedAt: null }, undefined)
+    })
+  })
+
+  describe('deleteById', () => {
+    it("calls client.delete with /departments/:id and resolves 'OK'", async () => {
+      vi.mocked(client.delete).mockResolvedValue('OK')
+      const result = await api.deleteById('dep-1')
+      expect(client.delete).toHaveBeenCalledWith('/departments/dep-1', undefined)
+      expect(result).toBe('OK')
+    })
+  })
+})

package/src/apis/departments/DepartmentsApi.ts

@@ -1,13 +1,52 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
-import type { Department, CreateDepartmentPayload, UpdateDepartmentPayload } from './types'
+import type {
+  Department,
+  CreateDepartmentPayload,
+  UpdateDepartmentPayload,
+  ArchiveDepartmentPayload,
+} from './types'
 
 export class DepartmentsApi extends ArchivableCrudApi<
   Department,
   CreateDepartmentPayload,
-  UpdateDepartmentPayload
+  UpdateDepartmentPayload,
+  ListQuery<Department>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/departments')
   }
+
+  /**
+   * Archives (`archive: true`) or restores (`archive: false`) a department through the route used
+   * by the UI, which enforces what {@link archive}/{@link unarchive} (a plain `PUT { archivedAt }`)
+   * skip: archiving refuses (403 `Cannot archive department.`, with the reasons and the open
+   * tickets count) a department in use, and clears it as the default department of contacts and
+   * connections, marks its schedules as done and unlinks its users and quick replies. Resolves the
+   * stored department (not transformed); an unknown id answers 500.
+   * @permissions departments.view OR departments.archive
+   */
+  archiveWithValidation(
+    id: string,
+    body: ArchiveDepartmentPayload,
+    headers?: Record<string, string>,
+  ): Promise<Department> {
+    return this.client.post<Department, ArchiveDepartmentPayload>(
+      `${this.basePath}/${id}/archive`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Deletes a department. Resolves the text `'OK'`; a department that is the default of the account
+   * or that is referenced in the attendant name visibility settings is refused, and an unknown id
+   * answers 500.
+   * @permissions departments.view OR departments.archive
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/departments/types.ts

@@ -26,3 +26,9 @@ export type UpdateDepartmentPayload = {
   distributionId?: string | null
   archivedAt?: string | null
 }
+
+/** Body of `DepartmentsApi.archiveWithValidation`. */
+export type ArchiveDepartmentPayload = {
+  /** `true` archives, `false` restores. */
+  archive: boolean
+}

package/src/apis/distribution/DistributionApi.ts

@@ -1,13 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Distribution, CreateDistributionPayload, UpdateDistributionPayload } from './types'
 
 export class DistributionApi extends BaseCrudApi<
   Distribution,
   CreateDistributionPayload,
-  UpdateDistributionPayload
+  UpdateDistributionPayload,
+  ListQuery<Distribution>,
+  void
 > {
   constructor(client: ApiClient) {
     super(client, '/distribution')
   }
+
+  /**
+   * Deletes a distribution. Resolves with no body, also for an unknown id (200).
+   * @permissions distribution.view OR distribution.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<void> {
+    return super.deleteById(id, headers)
+  }
 }