@ikatec/digisac-api-sdk 4.14.0 → 4.16.0

package/src/apis/campaigns/types.ts

@@ -34,6 +34,8 @@ export type CampaignConfig = {
   nameField?: string
   /** Column name in the import file used as the phone number. */
   numberField?: string
+  /** Column name in the import file used as the username (contacts known only by it). */
+  usernameField?: string
   delimiter?: ',' | ';' | ':' | string
   error?: {
     message: string
@@ -65,7 +67,10 @@ export type Campaign = {
   marketingIntegration?: boolean
   /** Always `null`: the campaign has no such column (answered by the transformer). */
   userId?: null
-  /** Only in `getMany`: messages sent and viewed (ack 3). */
+  /**
+   * In the pages of `getMany` (not with `paginate: false`) and in `getOne`: messages sent and
+   * viewed (ack 3).
+   */
   stats?: { sent: number; viewed: number }
   accountId: string
   serviceId: string
@@ -116,9 +121,21 @@ export type CampaignRelationships =
   | 'messages'
   | 'importFile'
 
+/** The media of a header parameter of the template (send it as `{ link: '<url>' }`). */
+export type CampaignTemplateMedia = {
+  link?: string
+}
+
+/**
+ * A parameter of the template: `text`, or the media of its `type` (`image`, `video` or
+ * `document`).
+ */
 export type CampaignTemplateParameterItem = {
   type: string
   text?: string
+  image?: CampaignTemplateMedia
+  video?: CampaignTemplateMedia
+  document?: CampaignTemplateMedia
 }
 
 export type CampaignTemplateParameter = {
@@ -135,30 +152,111 @@ export type CampaignFileTemplate = {
   name?: string
 }
 
+/** A message of the campaign to create (without `hsm`, the campaign sends these). */
+export type CampaignMessageInput = {
+  text?: string
+  /** The attachment of the message, as a data URL (`data:<mimetype>;base64,<content>`). */
+  base64Url?: string
+  /** @deprecated Ignored by the backend: send the attachment as `base64Url`. */
+  fileId?: string
+}
+
 export type CreateCampaignPayload = {
   title: string
   serviceId: string
   config?: { minInterval: number | string; maxInterval: number | string }
   tagIds?: string[]
-  messages?: { text?: string; fileId?: string }[]
+  messages?: CampaignMessageInput[]
+  /** On create, replaces the `text` of every message (and is the text of the template message). */
+  text?: string
   isScheduled?: boolean
   sendsAt?: string | null
   mustOpenTicket?: boolean
   defaultDepartmentId?: string | null
   defaultUserId?: string | null
+  /** @deprecated Ignored by the backend: the contacts come from `tagIds` or the import `fileId`. */
   contacts?: Record<string, string>[]
+  /** @deprecated Ignored by the backend: the contacts come from `tagIds` or the import `fileId`. */
   useTags?: boolean
+  /**
+   * On create, the import file (CSV) of the contacts, uploaded with
+   * `attachedType: 'campaign.file'`. The columns are read by `nameField`, `numberField` and
+   * `usernameField`.
+   */
   fileId?: string
+  /** On create, stored in `config.nameField` (a `config.nameField` sent here is replaced). */
   nameField?: string
+  /** On create, stored in `config.numberField` (a `config.numberField` sent here is replaced). */
   numberField?: string
+  /** Stored in `config.usernameField` (a `config.usernameField` sent here is replaced). */
+  usernameField?: string
   // whatsapp-business specific
+  /**
+   * The template to send. On create, the campaign gets one message of it and `messages` is not
+   * read.
+   */
   hsm?: WhatsappBusinessTemplate
   parameters?: CampaignTemplateParameter[]
+  /**
+   * The header file of the template message (only with `hsm`), already uploaded. Takes precedence
+   * over `fileTemplate`.
+   */
+  hsmFileId?: string
+  /**
+   * The header media of the template message: `base64Url` as a data URL, with its `mimetype`
+   * (required on create) and `name`. On create, read only when `tagIds` is sent (an empty array is
+   * enough); with the import `fileId`, prefer `hsmFileId`. On update, it only replaces the header
+   * file the template message already has: send it only with a new data URL, and leave it out to
+   * keep the header.
+   */
   fileTemplate?: CampaignFileTemplate
   marketingIntegration?: boolean
 }
 
-export type UpdateCampaignPayload = Partial<CreateCampaignPayload>
+/**
+ * A message of `updateById`. With the `id` of an existing message, the message gets the `text`
+ * sent; without `id`, it is created (and `base64Url` is read as in the create).
+ */
+export type UpdateCampaignMessageInput = CampaignMessageInput & {
+  id?: string
+  /**
+   * On WhatsApp connections, keeps the attachment of an existing message (send the `file` of the
+   * message read); with `file`, `base64Url` is not read. Without `file` and `base64Url`, the
+   * attachment is removed.
+   */
+  file?: unknown
+  /**
+   * On WhatsApp connections, the name of the new attachment in `base64Url`: to replace the
+   * attachment of an existing message, send `base64Url` with a new name and without `file`.
+   */
+  fileName?: string
+}
+
+/**
+ * `updateById` (`PUT`). A non-empty `messages` replaces the messages: the ones with the `id` of an
+ * existing message update it, the ones without `id` are created and the existing ones left out are
+ * deleted (omitted, or `[]`, keeps them).
+ *
+ * Send `isScheduled` (with `sendsAt`) and `mustOpenTicket` (with `defaultDepartmentId` and
+ * `defaultUserId`) on every call: without `isScheduled: true`, `sendsAt` is stored as `null` and a
+ * scheduled campaign is no longer started at the date; without `mustOpenTicket: true`, the default
+ * department and user are cleared.
+ *
+ * On WhatsApp Business connections, send the existing message by its `id` (a message without `id`
+ * is created without the template), together with `hsm` and `parameters`: every update that sends
+ * `messages` or `hsm` rewrites both on the existing messages (a missing one is stored empty).
+ */
+export type UpdateCampaignPayload = Omit<
+  Partial<CreateCampaignPayload>,
+  'text' | 'usernameField' | 'hsmFileId' | 'messages' | 'config'
+> & {
+  /**
+   * Replaces the stored config as a whole. `minInterval` and `maxInterval` go as strings (a number
+   * answers 400).
+   */
+  config?: { minInterval: number | string; maxInterval: number | string }
+  messages?: UpdateCampaignMessageInput[]
+}
 
 /** The visible states the `status` filter of `getMany` takes (`'scheduled'` is derived from `isScheduled` + `sendsAt`). */
 export type CampaignListStatus = CampaignStatus | 'scheduled'

package/src/apis/cards/types.ts

@@ -182,8 +182,8 @@ export type BulkMoveCardsPayload = {
 export type BulkMoveCardsResult = { movedCount: number; ignoredCount: number }
 
 /**
- * Creates a product of a card, or updates the product of `id`. No validation on the backend:
- * a missing `name`/`ammount`/`value` fails with 500.
+ * Creates a product of a card, or updates the product of `id`. `name`, `ammount` and `value` are
+ * required (a missing one answers 500).
  */
 export type SaveCardProductPayload = {
   id?: string
@@ -218,9 +218,9 @@ export type CardOwner = {
 }
 
 /**
- * Body of `POST /cards/getCards`: Sequelize options sent as-is. The route does **not** scope the
- * query by account — without `where.accountId` it answers cards of other accounts. `order`
- * accepts card fields and `contact.name`.
+ * Body of `POST /cards/getCards`: a list query of the cards. Send `where.accountId` with the id of
+ * the current account (`accountId` of `MeApi.getMe`). `order` accepts card fields and
+ * `contact.name`.
  */
 export type GetCardsPayload = Omit<
   ListQuery<Card>,

package/src/apis/categories/CategoriesApi.ts

@@ -15,8 +15,7 @@ export class CategoriesApi extends BaseCrudApi<
   }
 
   /**
-   * Deletes a category. Resolves the text `'OK'`; an unknown id answers 500. The route checks no
-   * permission.
+   * Deletes a category. Resolves the text `'OK'`; an unknown id answers 500.
    */
   override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
     return super.deleteById(id, headers)

package/src/apis/clientFeedback/ClientFeedbackApi.ts

@@ -9,9 +9,8 @@ export class ClientFeedbackApi
   private readonly basePath = '/client-feedback'
 
   /**
-   * @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.
+   * @deprecated The route is not available (it answers 500). Send the rating of the AI summary
+   * when closing the ticket: `ContactsApi.closeTicket` with `aiSummaryRating`.
    */
   create(
     body: CreateClientFeedbackPayload,

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

@@ -138,6 +138,19 @@ describe('ContactsApi', () => {
       await api.getById('cnt-1', undefined, headers)
       expect(client.get).toHaveBeenCalledWith('/contacts/cnt-1', headers)
     })
+
+    it('sends formatCustomFields and the include of the custom fields in the query', async () => {
+      vi.mocked(client.get).mockResolvedValue(contact)
+      const query = {
+        include: [{ model: 'customFieldValues' as const, include: ['customField' as const] }],
+        formatCustomFields: true,
+      }
+      await api.getById('cnt-1', query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/contacts/cnt-1?query=${encodeURIComponent(JSON.stringify(query))}`,
+        undefined,
+      )
+    })
   })
 
   // ── create ───────────────────────────────────────────────────────
@@ -352,14 +365,26 @@ describe('ContactsApi', () => {
 
   describe('transferTicket', () => {
     it('calls client.post with /contacts/:id/ticket/transfer and payload', async () => {
-      vi.mocked(client.post).mockResolvedValue({ ok: true })
+      vi.mocked(client.post).mockResolvedValue(true)
       const result = await api.transferTicket('c1', { departmentId: 'd1' })
       expect(client.post).toHaveBeenCalledWith(
         '/contacts/c1/ticket/transfer',
         { departmentId: 'd1' },
         undefined,
       )
-      expect(result).toEqual({ ok: true })
+      expect(result).toBe(true)
+    })
+
+    it('sends includeKanbanCardId and resolves the id of the card', async () => {
+      vi.mocked(client.post).mockResolvedValue({ kanbanCardId: 'kc1' })
+      const payload = {
+        departmentId: 'd1',
+        kanbanCardColumnId: 'col1',
+        includeKanbanCardId: true,
+      } as const
+      const result = await api.transferTicket('c1', payload)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/transfer', payload, undefined)
+      expect(result.kanbanCardId).toBe('kc1')
     })
 
     it('includes optional userId and forwards custom headers', async () => {
@@ -374,6 +399,28 @@ describe('ContactsApi', () => {
     })
   })
 
+  // ── closeTicket ──────────────────────────────────────────────────
+
+  describe('closeTicket', () => {
+    it('calls client.post with /contacts/:id/ticket/close and an empty body by default', async () => {
+      vi.mocked(client.post).mockResolvedValue(true)
+      expect(await api.closeTicket('c1')).toBe(true)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/close', {}, undefined)
+    })
+
+    it('sends the subjects, the comment and the rating of the AI summary', async () => {
+      vi.mocked(client.post).mockResolvedValue(true)
+      const headers = { 'X-Custom': 'h' }
+      const payload = {
+        ticketTopicIds: ['tt1'],
+        comments: 'Resolvido',
+        aiSummaryRating: '5' as const,
+      }
+      await api.closeTicket('c1', payload, headers)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/close', payload, headers)
+    })
+  })
+
   // ── createMany ───────────────────────────────────────────────────
 
   describe('createMany', () => {

package/src/apis/contacts/ContactsApi.ts

@@ -6,7 +6,10 @@ import type {
   BlockContactPayload,
   BulkTransferTicketsPayload,
   BulkTransferTicketsResult,
+  CloseTicketPayload,
   Contact,
+  ContactGetByIdQuery,
+  ContactListQuery,
   ContactMediaPage,
   ContactMediaQuery,
   ContactsSelection,
@@ -19,16 +22,37 @@ import type {
   ExportTemplatePayload,
   ImportContactsPayload,
   SyncContactPayload,
+  TransferTicketKanbanCardResult,
   TransferTicketPayload,
   UpdateContactPayload,
   SummarizeTicketResult,
 } from './types'
 
-export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, UpdateContactPayload> {
+export class ContactsApi extends BaseCrudApi<
+  Contact,
+  CreateContactPayload,
+  UpdateContactPayload,
+  ContactListQuery
+> {
   constructor(client: ApiClient) {
     super(client, '/contacts')
   }
 
+  /**
+   * Returns a contact by ID. When it does not exist the route answers 200 with an empty body, which
+   * resolves to `undefined`. With `formatCustomFields: true` (and the include
+   * `{ model: 'customFieldValues', include: ['customField'] }`), the custom fields come keyed by name
+   * in `customFields`.
+   * @permissions contacts.view
+   */
+  override getById(
+    id: string,
+    query?: ContactGetByIdQuery,
+    headers?: Record<string, string>,
+  ): Promise<Contact> {
+    return super.getById(id, query, headers)
+  }
+
   /**
    * 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.
@@ -119,20 +143,56 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
   /**
    * Opens (or transfers) the contact's ticket to a department, and optionally a user.
    * This is the real ticket-open flow used by the UI — there is no `POST /tickets`.
+   * Resolves `true`, or `{ kanbanCardId }` with `includeKanbanCardId: true`. When the current
+   * ticket of the contact is already closed, the call only releases it and opens nothing: call it
+   * again to open a ticket.
    * @permissions tickets.transfer.all OR tickets.transfer.me
    */
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload & { includeKanbanCardId: true },
+    headers?: Record<string, string>,
+  ): Promise<TransferTicketKanbanCardResult>
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload & { includeKanbanCardId?: false },
+    headers?: Record<string, string>,
+  ): Promise<true>
   transferTicket(
     contactId: string,
     payload: TransferTicketPayload,
     headers?: Record<string, string>,
-  ): Promise<unknown> {
-    return this.client.post<unknown, TransferTicketPayload>(
+  ): Promise<true | TransferTicketKanbanCardResult>
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload,
+    headers?: Record<string, string>,
+  ): Promise<true | TransferTicketKanbanCardResult> {
+    return this.client.post<true | TransferTicketKanbanCardResult, TransferTicketPayload>(
       `${this.basePath}/${contactId}/ticket/transfer`,
       payload,
       headers,
     )
   }
 
+  /**
+   * Closes the open ticket of the contact and resolves `true`. A contact without an open ticket
+   * answers 500, or `true` (closing nothing) when its current ticket is already closed. An unknown
+   * subject in `ticketTopicIds`, or one of another department, answers 400.
+   * @permissions tickets.close.me OR tickets.close.all
+   */
+  closeTicket(
+    contactId: string,
+    payload: CloseTicketPayload = {},
+    headers?: Record<string, string>,
+  ): Promise<true> {
+    return this.client.post<true, CloseTicketPayload>(
+      `${this.basePath}/${contactId}/ticket/close`,
+      payload,
+      headers,
+    )
+  }
+
   /**
    * Creates or updates several contacts in one call. Existing contacts (same service and
    * number or e-mail) are updated; the others are created. Returns the resulting contacts.
@@ -204,7 +264,7 @@ 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 (`settings.isBlockListActive`; 400 otherwise).
-   * `byUserId` and `description` are stored as sent: the backend does not fill in the user.
+   * Send `byUserId` with the logged user (`id` of `MeApi.getMe`), as the web app does.
    * @permissions contacts.block
    */
   block(id: string, body: BlockContactPayload, headers?: Record<string, string>): Promise<Contact> {

package/src/apis/contacts/types.ts

@@ -1,10 +1,11 @@
+import type { CustomField, CustomFieldType } from '../customFields/types'
 import type { Department } from '../departments/types'
 import type { Person } from '../people/types'
 import type { Service } from '../services/types'
 import type { Tag } from '../tags/types'
 import type { Ticket } from '../tickets/types'
 import type { User } from '../users/types'
-import type { IncludeItem, ListQuery, WhereClause } from '../../core/types'
+import type { GetByIdQuery, IncludeItem, ListQuery, WhereClause } from '../../core/types'
 
 export type ContactStatus = 'online' | 'offline' | 'absent'
 export type ContactOrigin = 'api' | 'app' | 'campaign' | 'driver' | 'import' | 'web'
@@ -95,6 +96,56 @@ export type ContactDataBlock = {
   description: string
 }
 
+/**
+ * A value of a custom field of the contact, as `include: ['customFieldValues']` answers it (the
+ * stored row).
+ */
+export type CustomFieldValue = {
+  id: string
+  customFieldId: string
+  /** The contact. */
+  relatedId: string
+  relatedType: string | null
+  /**
+   * The value as stored: text, or JSON text for the composite types (`date-range`, `hour-range`,
+   * `numeric`, `monetary`, `phone`, `postal-code`).
+   */
+  value: string
+  createdAt: string
+  updatedAt: string
+  deletedAt: string | null
+  // relationships
+  customField?: CustomField
+}
+
+/**
+ * A custom field of the contact as `formatCustomFields: true` answers it, keyed by the name of the
+ * field in `Contact.customFields`.
+ */
+export type FormattedCustomField = {
+  name: string
+  /** The value, parsed from JSON for the composite types. */
+  value: unknown
+  /** Id of the value. */
+  id: string
+  type: CustomFieldType
+  /** Id of the field. */
+  fieldId: string
+  /** When the field was created. */
+  createdAt: string
+}
+
+/** A custom field value sent in the create or update of a contact. */
+export type ContactCustomFieldInput = {
+  /**
+   * Id of the custom field (`CustomField.id`, `FormattedCustomField.fieldId` or
+   * `CustomFieldValue.customFieldId`), not the id of the value.
+   */
+  id: string
+  /** Text, or an object for the composite types (stored as JSON). */
+  value: unknown
+}
+
 export type Contact = {
   id: string
   idFromService: string | null
@@ -139,6 +190,13 @@ export type Contact = {
   person?: Person | null
   tags?: Tag[]
   currentTicket?: Ticket | null
+  /** With `include: ['customFieldValues']`, unless `formatCustomFields` is set. */
+  customFieldValues?: CustomFieldValue[]
+  /**
+   * With `formatCustomFields: true` and the include
+   * `{ model: 'customFieldValues', include: ['customField'] }`: the values keyed by the field name.
+   */
+  customFields?: Record<string, FormattedCustomField>
 }
 
 export type ContactRelationships =
@@ -148,6 +206,23 @@ export type ContactRelationships =
   | 'person'
   | 'tags'
   | 'currentTicket'
+  | 'customFieldValues'
+  | 'customFields'
+
+type FormatCustomFieldsOption = {
+  /**
+   * Answers `customFields` keyed by the field name instead of the raw `customFieldValues` (with the
+   * include `{ model: 'customFieldValues', include: ['customField'] }`; without the nested
+   * `customField`, `customFields` comes empty).
+   */
+  formatCustomFields?: boolean
+}
+
+/** Query of `ContactsApi.getById`. */
+export type ContactGetByIdQuery = GetByIdQuery<Contact> & FormatCustomFieldsOption
+
+/** Query of `ContactsApi.getMany` and `getOne`. */
+export type ContactListQuery = ListQuery<Contact> & FormatCustomFieldsOption
 
 export type CreateContactPayload = {
   name?: string
@@ -160,6 +235,8 @@ export type CreateContactPayload = {
   data?: ContactData
   note?: string
   origin?: ContactOrigin
+  /** Values of the custom fields of the account. An id that is not a custom field answers 400. */
+  customFields?: ContactCustomFieldInput[]
 }
 
 export type UpdateContactPayload = {
@@ -174,6 +251,11 @@ export type UpdateContactPayload = {
   block?: boolean
   /** Tag IDs to associate with the contact. */
   tagIds?: string[]
+  /**
+   * Values of the custom fields of the account: a value of the same field is updated. An id that is
+   * not a custom field is skipped.
+   */
+  customFields?: ContactCustomFieldInput[]
 }
 
 /** Result of `ContactsApi.summarizeTicket`. */
@@ -209,6 +291,34 @@ export type TransferTicketPayload = {
   kanbanCardColumnId?: string
   kanbanCardSubject?: string
   initialMessage?: string
+  /** `true` (the boolean) resolves the id of the kanban card instead of `true`. */
+  includeKanbanCardId?: boolean
+}
+
+/** What `ContactsApi.transferTicket` resolves to with `includeKanbanCardId: true`. */
+export type TransferTicketKanbanCardResult = {
+  /**
+   * The kanban card of the ticket (created, or the contact's card moved, in `kanbanCardColumnId`);
+   * `null` without `kanbanCardColumnId` (even when the ticket gets a card in the initial column of
+   * the board: send `kanbanCardColumnId` to read its id), when the department has no board, or when
+   * the call only released a closed ticket.
+   */
+  kanbanCardId: string | null
+}
+
+/** The rating of the AI summary of the ticket. */
+export type AiSummaryRating = '1' | '2' | '3' | '4' | '5'
+
+export type CloseTicketPayload = {
+  /**
+   * Subjects of the ticket: of its department, or linked to no department. An unknown subject, or
+   * one of another department, answers 400.
+   */
+  ticketTopicIds?: string[]
+  /** The closing comment. */
+  comments?: string
+  /** Stored as the feedback of the AI summary of the ticket. */
+  aiSummaryRating?: AiSummaryRating
 }
 
 /**

package/src/apis/creditMovements/CreditMovementsApi.test.ts

@@ -83,6 +83,6 @@ describe('CreditMovementsApi', () => {
     const withoutRaw: ApiClient = { ...client, requestRaw: undefined }
     await expect(
       new CreditMovementsApi(withoutRaw).exportXlsx({ from: 'a', to: 'b', where: { $and: [] } }),
-    ).rejects.toThrow('requestRaw')
+    ).rejects.toThrow('exportXlsx needs a client with requestRaw')
   })
 })

package/src/apis/customFields/types.ts

@@ -22,10 +22,10 @@ export type CustomFieldOption = {
 }
 
 /**
- * Settings of a custom field — a free JSONB the backend does not validate, echoed back as sent.
- * The fields below are the ones the web app form sends (`front/src/pages/custom-fields/components/
- * form.tsx`): `options` for the `list` and `checkbox` types, `min`/`max` for `numeric` and `monetary`,
- * `currency` for `monetary`, `maxLength` for `text` and `long-text`, and `placeholder` for the inputs.
+ * Settings of a custom field (a free JSON object, answered as stored). The fields below are the
+ * ones the web app form sends: `options` for the `list` and `checkbox` types, `min`/`max` for
+ * `numeric` and `monetary`, `currency` for `monetary`, `maxLength` for `text` and `long-text`, and
+ * `placeholder` for the inputs.
  */
 export type CustomFieldSettings = {
   options?: CustomFieldOption[]

package/src/apis/dashboard/DashboardApi.test-d.ts

@@ -47,3 +47,12 @@ expectType<Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>
 expectError(dashboard.getByPeriod({ grouping: 'quarterly' }))
 expectError(dashboard.getByTopic({ withTotals: true }))
 expectError(dashboard.getByService({ withTotals: true }))
+
+// ── one connection, tag and subject (not a list) ────────────────────
+
+expectType<Promise<DashboardPeriodItem[]>>(
+  dashboard.getByPeriod({ serviceId: 's-1', tagId: 't-1', ticketTopicId: 'tt-1' }),
+)
+expectError(dashboard.getByPeriod({ serviceId: ['s-1', 's-2'] }))
+expectError(dashboard.getByPeriod({ tagId: ['t-1'] }))
+expectError(dashboard.getByPeriod({ ticketTopicId: ['tt-1'] }))

package/src/apis/dashboard/DashboardApi.ts

@@ -12,9 +12,9 @@ import type {
 } from './types'
 
 /**
- * Service statistics ("Estatísticas de atendimento"). The `/dashboard` routes only require an
- * authenticated user (no permission check). Every route takes the same {@link DashboardQuery}
- * filters; the grouped routes answer one item per day, user, department, topic or connection.
+ * Service statistics ("Estatísticas de atendimento"). Every route takes the same
+ * {@link DashboardQuery} filters; the grouped routes answer one item per day, user, department,
+ * topic or connection.
  */
 export class DashboardApi extends BaseApi {
   public readonly basePath = '/dashboard'

package/src/apis/dashboard/types.ts

@@ -14,7 +14,11 @@ export type DashboardQuery = {
   startPeriod?: string
   /** ISO date-time. Default: the end of the `startPeriod` day (or of today). */
   endPeriod?: string
-  /** Which ticket date the period filters: opening (default) or closing. */
+  /**
+   * Which ticket date the period filters: opening (`openDate`, the default) or closing. Sent
+   * without it, together with `status: 'all'`, the period is not applied. `getByPeriod` needs it:
+   * always send it there (the `openDate` default does not apply to that route).
+   */
   periodType?: 'openDate' | 'closeDate'
   /** Ticket status (`closed`, not `close`). */
   status?: 'all' | 'open' | 'closed'
@@ -39,9 +43,12 @@ export type DashboardQuery = {
    */
   userParticipation?: 'last' | 'middle'
   userStatus?: 'active' | 'archived' | 'all'
-  serviceId?: string | string[]
-  tagId?: string | string[]
-  ticketTopicId?: string | string[]
+  /** One connection id (unlike `departmentId` and `userId`, not a list). */
+  serviceId?: string
+  /** One tag id (not a list). */
+  tagId?: string
+  /** One ticket subject id (not a list). */
+  ticketTopicId?: string
   /**
    * Granularity of the `getByPeriod` items (the other routes ignore it). Default: `daily`. See
    * {@link DashboardGrouping} for the `name` of the items.

package/src/apis/departments/DepartmentsApi.ts

@@ -21,11 +21,11 @@ export class DepartmentsApi extends ArchivableCrudApi<
 
   /**
    * 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.
+   * by the UI: archiving refuses (403 `Cannot archive department.`) a department in use, or when it
+   * is the only active department of the account (the `extra` of the error is an
+   * `ArchiveDepartmentErrorExtra`). Archiving also 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(