@ikatec/digisac-api-sdk 4.2.0 → 4.4.0

package/src/apis/contacts/types.ts

@@ -4,7 +4,7 @@ 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 { ListQuery } from '../../core/types'
+import type { IncludeItem, ListQuery, WhereClause } from '../../core/types'
 
 export type ContactStatus = 'online' | 'offline' | 'absent'
 export type ContactOrigin = 'api' | 'app' | 'campaign' | 'driver' | 'import' | 'web'
@@ -204,3 +204,156 @@ export type TransferTicketPayload = {
   kanbanCardSubject?: string
   initialMessage?: string
 }
+
+/**
+ * One item of `POST /contacts/many`. The backend matches existing contacts by service and
+ * number (or e-mail) and updates them; the others are created. Items repeating a number of
+ * the same batch are dropped (the first one wins).
+ */
+export type CreateManyContactsItem = {
+  serviceId: string
+  name: string
+  /** Phone number with country code, or the e-mail address for e-mail connections. */
+  number: string
+  internalName?: string
+  personId?: string
+  defaultDepartmentId?: string
+  defaultUserId?: string
+  tagIds?: string[]
+  /** When `true`, the given `tagIds` are merged into the existing ones instead of replacing them. */
+  mergeRelations?: boolean
+  /**
+   * Only `data.number` is read, as a fallback when `number` is empty; the backend rebuilds
+   * `data` from the number.
+   */
+  data?: {
+    number: string
+  }
+}
+
+/**
+ * Selects a set of contacts by filter. Used by `DELETE /contacts/many` and by the tag
+ * attach/detach routes. The backend always scopes the filter to the current account.
+ *
+ * `where` is required on purpose: the backend applies the operation to every contact the
+ * filter matches, so an empty filter would reach every contact of the account.
+ */
+export type ContactsSelection = {
+  where: WhereClause<Contact>
+  include?: IncludeItem<Contact>[]
+  customFilter?: Record<string, unknown>
+}
+
+/**
+ * CSV layout of the contact export and import, as in `exportTemplate`:
+ * - `'colon'`: `;` as the column delimiter (any other value uses `,`);
+ * - `'google'`: phone columns as DDI + Phone ("Telefone") instead of DDI + Number.
+ *
+ * E-mail and webchat connections ignore it for the contact columns (Email / Email + Number).
+ */
+export type ContactsCsvType = 'colon' | 'google' | (string & {})
+
+/** Body for `POST /contacts/export/csv`. */
+export type ExportCsvPayload = Omit<ListQuery<Contact>, 'page' | 'perPage'> & {
+  serviceType: string
+  type: ContactsCsvType
+}
+
+/**
+ * Body for `POST /contacts/import-contacts`. The CSV must be uploaded first (see `FilesApi`);
+ * the header line is checked against the template of the service type and language.
+ */
+export type ImportContactsPayload = {
+  service: Pick<Service, 'id' | 'accountId' | 'type'>
+  file: {
+    id: string
+    name: string
+    mimetype: string
+    /** Sent by the web app; the backend reads only `id`. */
+    urlToUpload?: string
+  }
+  csvHeaderLine: string[]
+  type: ContactsCsvType
+  tagsIds?: string[]
+  defaultDepartmentId?: string
+  defaultUserId?: string
+}
+
+/** Body for `POST /contacts/:id/block`. Blocking a contact closes its open ticket. */
+export type BlockContactPayload = {
+  block: boolean
+  byUserId?: string
+  description?: string
+}
+
+/** Body for `POST /contacts/:id/sync`. */
+export type SyncContactPayload = {
+  forceSync?: boolean
+}
+
+export type ContactMediaType = 'media' | 'document' | 'link'
+
+/**
+ * Query for `GET /contacts/:id/media`. Cursor-based: pass the previous page's `nextCursor`
+ * as `where.cursor`.
+ */
+export type ContactMediaQuery = {
+  where?: {
+    /** `'media'` = images and videos. Omitted = images, videos and documents. */
+    type?: ContactMediaType
+    /** Case-insensitive filter by file name (ignored for links). */
+    name?: string
+    cursor?: string
+  }
+  perPage?: number
+  order?: [string, 'ASC' | 'DESC' | 'asc' | 'desc'][]
+}
+
+/**
+ * One item of `GET /contacts/:id/media`. When the user cannot see the message, the
+ * identifying fields come as `'UNAUTHORIZED_MESSAGE'` and `isAuthorized` is `false`.
+ */
+export type ContactMediaItem = {
+  id: string
+  /** ID of the message that carries the file or link. */
+  attachedId: string
+  /** File name; absent for links. */
+  name?: string | null
+  /** Only for files. */
+  mimetype?: string
+  createdAt: string
+  updatedAt: string
+  accountId: string
+  url: string | null
+  /** Only for files (filled for videos). */
+  previewUrl?: string | null
+  isAuthorized: boolean
+  /** Only for `type: 'link'`. */
+  links?: string[]
+}
+
+export type ContactMediaPage = {
+  data: ContactMediaItem[]
+  limit: number
+  hasNextPage: boolean
+  nextCursor: string | null
+}
+
+/** Body for `POST /contacts/ticket/bulk-transfer`. */
+export type BulkTransferTicketsPayload = {
+  departmentId?: string
+  /** `null` removes the assigned user. */
+  userId?: string | null
+  comments?: string
+  /** IDs of the tickets to transfer. Ignored when `allContactsSelected` is `true`. */
+  ticketsSelectedId?: string[]
+  allContactsSelected?: boolean
+  /** Contact filter used with `allContactsSelected`. */
+  query?: ListQuery<Contact>
+}
+
+export type BulkTransferTicketsResult = {
+  message: string
+  /** IDs of the tickets actually transferred (the ones the target user can access). */
+  ticketsSelectedId: string[]
+}

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

@@ -0,0 +1,49 @@
+import { expectError, expectType } from 'tsd'
+import type { ApiClient } from '../../core/ApiClient'
+import { DashboardApi } from './DashboardApi'
+import type {
+  DashboardDepartmentItem,
+  DashboardGrouped,
+  DashboardPeriodItem,
+  DashboardQuery,
+  DashboardUserItem,
+} from './types'
+
+declare const client: ApiClient
+declare const filters: DashboardQuery
+declare const flag: boolean
+const dashboard = new DashboardApi(client)
+
+// ── without `withTotals` (or `false`): the plain array ──────────────
+
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod())
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod({ grouping: 'weekly' }))
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod({ withTotals: false }))
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod(filters))
+expectType<Promise<DashboardUserItem[]>>(dashboard.getByUser(filters))
+expectType<Promise<DashboardDepartmentItem[]>>(dashboard.getByDepartment(filters))
+
+// ── `withTotals: true`: `{ totals, items }` ─────────────────────────
+
+expectType<Promise<DashboardGrouped<DashboardPeriodItem>>>(
+  dashboard.getByPeriod({ withTotals: true }),
+)
+expectType<Promise<DashboardGrouped<DashboardPeriodItem>>>(
+  dashboard.getByPeriod({ ...filters, withTotals: true }),
+)
+expectType<Promise<DashboardGrouped<DashboardUserItem>>>(dashboard.getByUser({ withTotals: true }))
+expectType<Promise<DashboardGrouped<DashboardDepartmentItem>>>(
+  dashboard.getByDepartment({ withTotals: true }),
+)
+
+// ── `withTotals` only known at runtime: the union ───────────────────
+
+expectType<Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>>>(
+  dashboard.getByPeriod({ ...filters, withTotals: flag }),
+)
+
+// ── what the backend does not take ──────────────────────────────────
+
+expectError(dashboard.getByPeriod({ grouping: 'quarterly' }))
+expectError(dashboard.getByTopic({ withTotals: true }))
+expectError(dashboard.getByService({ withTotals: true }))

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

@@ -1,7 +1,16 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { DashboardApi } from './DashboardApi'
 import type { ApiClient } from '../../core/ApiClient'
-import type { DashboardGeneral } from './types'
+import type {
+  DashboardDepartmentItem,
+  DashboardGeneral,
+  DashboardPeriodItem,
+  DashboardQuery,
+  DashboardServiceItem,
+  DashboardTopicItem,
+  DashboardUserItem,
+  DashboardWithTotals,
+} from './types'
 
 // ── Mock client factory ──────────────────────────────────────────────
 
@@ -33,6 +42,37 @@ const general: DashboardGeneral = {
   contactsCount: 4,
 }
 
+const periodItems: DashboardPeriodItem[] = [
+  { name: '01/09/2026', sentMessagesCount: 4, receivedMessagesCount: 2, totalMessagesCount: 6 },
+  { name: '02/09/2026', openedTicketsCount: 1, closedTicketsCount: 1, totalTicketsCount: 2 },
+]
+
+const userItems: DashboardUserItem[] = [
+  { name: 'Alice', sentMessagesCount: 7, closedTicketsCount: 3, ticketTopicsCount: 1 },
+]
+
+const departmentItems: DashboardDepartmentItem[] = [
+  { name: 'Suporte', openedTicketsCount: 2, waitingTime: 60, ticketTime: 600 },
+]
+
+const topicItems: DashboardTopicItem[] = [
+  { name: 'Financeiro', openedTicketsCount: 1, waitingTimeAfterBot: 30, waitingTimeAvg: 45 },
+]
+
+const serviceItems: DashboardServiceItem[] = [
+  { name: 'WhatsApp', receivedMessagesCount: 5, contactsCount: 4, ticketTopicsCount: 2 },
+]
+
+const filters: DashboardQuery = {
+  startPeriod: '2026-09-01T00:00:00.000Z',
+  endPeriod: '2026-09-07T23:59:59.999Z',
+  status: 'closed',
+  departmentId: ['d1'],
+}
+
+const queryString = (query: DashboardQuery & DashboardWithTotals) =>
+  `?query=${encodeURIComponent(JSON.stringify(query))}`
+
 // ── Tests ────────────────────────────────────────────────────────────
 
 describe('DashboardApi', () => {
@@ -59,15 +99,9 @@ describe('DashboardApi', () => {
 
     it('sends the filters in the query string', async () => {
       vi.mocked(client.get).mockResolvedValue(general)
-      const query = {
-        startPeriod: '2026-09-01T00:00:00.000Z',
-        endPeriod: '2026-09-07T23:59:59.999Z',
-        status: 'closed' as const,
-        departmentId: ['d1'],
-      }
-      await api.getGeneral(query)
+      await api.getGeneral(filters)
       expect(client.get).toHaveBeenCalledWith(
-        `/dashboard/general?query=${encodeURIComponent(JSON.stringify(query))}`,
+        `/dashboard/general${queryString(filters)}`,
         undefined,
       )
     })
@@ -79,4 +113,158 @@ describe('DashboardApi', () => {
       expect(client.get).toHaveBeenCalledWith('/dashboard/general', headers)
     })
   })
+
+  describe('getByPeriod', () => {
+    it('calls client.get with /dashboard/by-period and no query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      const result = await api.getByPeriod()
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-period', undefined)
+      expect(result).toEqual(periodItems)
+    })
+
+    it('sends the filters and the grouping in the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      const query: DashboardQuery = { ...filters, grouping: 'weekly' }
+      await api.getByPeriod(query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-period${queryString(query)}`,
+        undefined,
+      )
+    })
+
+    it('answers { totals, items } with withTotals: true', async () => {
+      const grouped = { totals: general, items: periodItems }
+      vi.mocked(client.get).mockResolvedValue(grouped)
+      const query = { ...filters, withTotals: true as const }
+      const result = await api.getByPeriod(query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-period${queryString(query)}`,
+        undefined,
+      )
+      expect(result).toEqual(grouped)
+      expect(result.totals.totalTicketsCount).toBe(5)
+      expect(result.items).toHaveLength(2)
+    })
+
+    it('does not send withTotals: false (the backend reads it as truthy in the qs format)', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      await api.getByPeriod({ ...filters, withTotals: false })
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-period${queryString(filters)}`,
+        undefined,
+      )
+      await api.withQueryFormat('qs').getByPeriod({ withTotals: false, grouping: 'weekly' })
+      expect(client.get).toHaveBeenLastCalledWith('/dashboard/by-period?grouping=weekly', undefined)
+      await api.getByPeriod({ withTotals: false })
+      expect(client.get).toHaveBeenLastCalledWith('/dashboard/by-period', undefined)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByPeriod(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-period', headers)
+    })
+  })
+
+  describe('getByUser', () => {
+    it('calls client.get with /dashboard/by-user and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(userItems)
+      const result = await api.getByUser(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-user${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(userItems)
+    })
+
+    it('answers { totals, items } with withTotals: true', async () => {
+      const grouped = { totals: general, items: userItems }
+      vi.mocked(client.get).mockResolvedValue(grouped)
+      const result = await api.getByUser({ withTotals: true })
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-user${queryString({ withTotals: true })}`,
+        undefined,
+      )
+      expect(result.items[0]?.name).toBe('Alice')
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(userItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByUser(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-user', headers)
+    })
+  })
+
+  describe('getByDepartment', () => {
+    it('calls client.get with /dashboard/by-department and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(departmentItems)
+      const result = await api.getByDepartment(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-department${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(departmentItems)
+    })
+
+    it('answers { totals, items } with withTotals: true', async () => {
+      const grouped = { totals: general, items: departmentItems }
+      vi.mocked(client.get).mockResolvedValue(grouped)
+      const result = await api.getByDepartment({ withTotals: true })
+      expect(result).toEqual(grouped)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(departmentItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByDepartment(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-department', headers)
+    })
+  })
+
+  describe('getByTopic', () => {
+    it('calls client.get with /dashboard/by-topic and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(topicItems)
+      const result = await api.getByTopic(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-topic${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(topicItems)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(topicItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByTopic(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-topic', headers)
+    })
+  })
+
+  describe('getByService', () => {
+    it('calls client.get with /dashboard/by-service and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(serviceItems)
+      const result = await api.getByService(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-service${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(serviceItems)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(serviceItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByService(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-service', headers)
+    })
+  })
+
+  describe('error propagation', () => {
+    it('propagates errors from the grouped routes', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Unauthorized'))
+      await expect(api.getByPeriod()).rejects.toThrow('Unauthorized')
+    })
+  })
 })

package/src/apis/dashboard/DashboardApi.ts

@@ -1,9 +1,20 @@
 import { BaseApi } from '../../core/BaseApi'
-import type { DashboardGeneral, DashboardQuery } from './types'
+import type {
+  DashboardDepartmentItem,
+  DashboardGeneral,
+  DashboardGrouped,
+  DashboardPeriodItem,
+  DashboardQuery,
+  DashboardServiceItem,
+  DashboardTopicItem,
+  DashboardUserItem,
+  DashboardWithTotals,
+} from './types'
 
 /**
  * Service statistics ("Estatísticas de atendimento"). The `/dashboard` routes only require an
- * authenticated user (no permission check).
+ * 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.
  */
 export class DashboardApi extends BaseApi {
   public readonly basePath = '/dashboard'
@@ -15,4 +26,121 @@ export class DashboardApi extends BaseApi {
       headers,
     )
   }
+
+  /**
+   * The counts of each bucket of the period (`GET /dashboard/by-period`): one item per day by default,
+   * or per `grouping` (hour, week, month, year). With `withTotals: true` the answer is
+   * `{ totals, items }`.
+   */
+  getByPeriod(
+    query: DashboardQuery & { withTotals: true },
+    headers?: Record<string, string>,
+  ): Promise<DashboardGrouped<DashboardPeriodItem>>
+  getByPeriod(
+    query?: DashboardQuery & { withTotals?: false },
+    headers?: Record<string, string>,
+  ): Promise<DashboardPeriodItem[]>
+  /** When `withTotals` is only known at runtime (e.g. a `boolean` variable). */
+  getByPeriod(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>>
+  getByPeriod(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>> {
+    return this.getGrouped<DashboardPeriodItem>('by-period', query, headers)
+  }
+
+  /**
+   * The counts of each user of the period (`GET /dashboard/by-user`). With `withTotals: true` the
+   * answer is `{ totals, items }`.
+   */
+  getByUser(
+    query: DashboardQuery & { withTotals: true },
+    headers?: Record<string, string>,
+  ): Promise<DashboardGrouped<DashboardUserItem>>
+  getByUser(
+    query?: DashboardQuery & { withTotals?: false },
+    headers?: Record<string, string>,
+  ): Promise<DashboardUserItem[]>
+  /** When `withTotals` is only known at runtime (e.g. a `boolean` variable). */
+  getByUser(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardUserItem[] | DashboardGrouped<DashboardUserItem>>
+  getByUser(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardUserItem[] | DashboardGrouped<DashboardUserItem>> {
+    return this.getGrouped<DashboardUserItem>('by-user', query, headers)
+  }
+
+  /**
+   * The counts of each department of the period (`GET /dashboard/by-department`). With
+   * `withTotals: true` the answer is `{ totals, items }`.
+   */
+  getByDepartment(
+    query: DashboardQuery & { withTotals: true },
+    headers?: Record<string, string>,
+  ): Promise<DashboardGrouped<DashboardDepartmentItem>>
+  getByDepartment(
+    query?: DashboardQuery & { withTotals?: false },
+    headers?: Record<string, string>,
+  ): Promise<DashboardDepartmentItem[]>
+  /** When `withTotals` is only known at runtime (e.g. a `boolean` variable). */
+  getByDepartment(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardDepartmentItem[] | DashboardGrouped<DashboardDepartmentItem>>
+  getByDepartment(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardDepartmentItem[] | DashboardGrouped<DashboardDepartmentItem>> {
+    return this.getGrouped<DashboardDepartmentItem>('by-department', query, headers)
+  }
+
+  /**
+   * The counts of each ticket topic of the period (`GET /dashboard/by-topic`). Does not take
+   * `withTotals` (the backend ignores it).
+   */
+  getByTopic(
+    query?: DashboardQuery,
+    headers?: Record<string, string>,
+  ): Promise<DashboardTopicItem[]> {
+    return this.client.get<DashboardTopicItem[]>(
+      `${this.basePath}/by-topic${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * The counts of each connection of the period (`GET /dashboard/by-service`). Does not take
+   * `withTotals` (the backend ignores it).
+   */
+  getByService(
+    query?: DashboardQuery,
+    headers?: Record<string, string>,
+  ): Promise<DashboardServiceItem[]> {
+    return this.client.get<DashboardServiceItem[]>(
+      `${this.basePath}/by-service${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * `withTotals` is only sent when `true`: the backend reads it with a truthiness check, so in the
+   * `qs` format a serialized `withTotals=false` (the string `'false'`) would wrap the answer anyway.
+   */
+  private getGrouped<TItem>(
+    route: string,
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<TItem[] | DashboardGrouped<TItem>> {
+    const { withTotals, ...filters } = query ?? {}
+    return this.client.get<TItem[] | DashboardGrouped<TItem>>(
+      `${this.basePath}/${route}${this.toQueryString(withTotals ? { ...filters, withTotals: true } : filters)}`,
+      headers,
+    )
+  }
 }

package/src/apis/dashboard/types.ts

@@ -1,3 +1,10 @@
+/**
+ * Granularity of the by-period items (`grouping`). Default: `daily`. Whatever the granularity, the
+ * `name` of each item is its day (`dd/MM/yyyy`), so with `hourly` the items of one day share the same
+ * `name` (they come in chronological order).
+ */
+export type DashboardGrouping = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly'
+
 /**
  * Filters of the service statistics (`/dashboard`). Every field is optional; the period defaults to
  * the last 7 days.
@@ -35,8 +42,21 @@ export type DashboardQuery = {
   serviceId?: string | string[]
   tagId?: string | string[]
   ticketTopicId?: string | string[]
+  /**
+   * Granularity of the `getByPeriod` items (the other routes ignore it). Default: `daily`. See
+   * {@link DashboardGrouping} for the `name` of the items.
+   */
+  grouping?: DashboardGrouping
 }
 
+/**
+ * `withTotals: true` makes `getByPeriod`, `getByUser` and `getByDepartment` answer `{ totals, items }`,
+ * where `totals` are the `getGeneral` counts of the same filters (`getByTopic` and `getByService` do
+ * not take it). Kept out of `DashboardQuery` so a query without it keeps the plain array overload.
+ * Only sent to the backend when `true`.
+ */
+export type DashboardWithTotals = { withTotals?: boolean }
+
 /** `GET /dashboard/general` — counts of the period. Times are in seconds. */
 export type DashboardGeneral = {
   sentMessagesCount: number
@@ -51,3 +71,61 @@ export type DashboardGeneral = {
   ticketTime: number
   contactsCount: number
 }
+
+/**
+ * Counts shared by the grouped routes (`by-period`, `by-user`, `by-department`, `by-topic`,
+ * `by-service`). The backend builds each item from the rows it found, so a count is ABSENT (not 0)
+ * when the group has no row for it: read them with a default. Times are in seconds.
+ */
+export type DashboardGroupCounts = {
+  sentMessagesCount?: number
+  receivedMessagesCount?: number
+  openedTicketsCount?: number
+  closedTicketsCount?: number
+  waitingTime?: number
+  ticketTime?: number
+  contactsCount?: number
+}
+
+/** `GET /dashboard/by-period` — the counts of one day of the period (`name` as `dd/MM/yyyy`). */
+export type DashboardPeriodItem = DashboardGroupCounts & {
+  name: string
+  totalMessagesCount?: number
+  totalTicketsCount?: number
+  waitingTimeAfterBot?: number
+  waitingTimeAvg?: number
+}
+
+/** `GET /dashboard/by-user` — the counts of one user (`name` is the user's name). */
+export type DashboardUserItem = DashboardGroupCounts & {
+  name: string
+  ticketTopicsCount?: number
+}
+
+/** `GET /dashboard/by-department` — the counts of one department (`name` is its name). */
+export type DashboardDepartmentItem = DashboardGroupCounts & {
+  name: string
+  ticketTopicsCount?: number
+}
+
+/** `GET /dashboard/by-topic` — the counts of one ticket topic (`name` is the topic's name). */
+export type DashboardTopicItem = DashboardGroupCounts & {
+  name: string
+  waitingTimeAfterBot?: number
+  waitingTimeAvg?: number
+}
+
+/** `GET /dashboard/by-service` — the counts of one connection (`name` is the connection's name). */
+export type DashboardServiceItem = DashboardGroupCounts & {
+  name: string
+  waitingTimeAfterBot?: number
+  waitingTimeAvg?: number
+  ticketTopicsCount?: number
+}
+
+/** Answer of `getByPeriod`, `getByUser` and `getByDepartment` with `withTotals: true`. */
+export type DashboardGrouped<TItem> = {
+  /** The `getGeneral` counts of the same filters. */
+  totals: DashboardGeneral
+  items: TItem[]
+}