@ikatec/digisac-api-sdk 4.6.0 → 4.8.0

package/src/apis/queryFormat.test.ts

@@ -4,6 +4,7 @@ import type { ApiClient } from '../core/ApiClient'
 import { BaseApiClient } from '../core/BaseApiClient'
 import type { QueryFormat } from '../core/queryString'
 import { AuthHistoryApi } from './authHistory/AuthHistoryApi'
+import { CampaignsApi } from './campaigns/CampaignsApi'
 import { ContactsApi } from './contacts/ContactsApi'
 import { DashboardApi } from './dashboard/DashboardApi'
 import { NowApi } from './now/NowApi'
@@ -11,6 +12,7 @@ import { PermissionsApi } from './permissions/PermissionsApi'
 import { ServiceAccessManagementApi } from './serviceAccessManagement/ServiceAccessManagementApi'
 import { StickerUsersApi } from './stickerUsers/StickerUsersApi'
 import { TermsApi } from './terms/TermsApi'
+import { TicketsApi } from './tickets/TicketsApi'
 
 /**
  * Every method that sends a list/get query must serialize it in the client's `queryFormat` and
@@ -34,6 +36,16 @@ const listQuery = { where: { name: 'x' }, page: 2, perPage: 5 }
 const getQuery = { attributes: ['id'] }
 /** `Permission.name` is a union of the catalog names, so the permissions case filters by a real one. */
 const permissionsQuery = { where: { name: 'chat' as const }, page: 2, perPage: 5 }
+const campaignsQuery = { status: 'scheduled' as const, q: 'Black Friday', page: 2, perPage: 5 }
+const campaignContactsQuery = {
+  contactStatus: ['not_sent' as const],
+  sortBy: 'sentAt' as const,
+  page: 2,
+}
+const ticketsQuery = {
+  where: { isOpen: true },
+  order: [['startedAt', 'DESC'] as ['startedAt', 'DESC']],
+}
 
 type Case = {
   name: string
@@ -44,6 +56,24 @@ type Case = {
 }
 
 const cases: Case[] = [
+  {
+    name: 'CampaignsApi.getMany (flat filters)',
+    path: '/campaigns',
+    query: campaignsQuery,
+    call: (client, f) => {
+      const api = new CampaignsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMany(campaignsQuery)
+    },
+  },
+  {
+    name: 'CampaignsApi.getContacts',
+    path: '/campaigns/c1/contacts',
+    query: campaignContactsQuery,
+    call: (client, f) => {
+      const api = new CampaignsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getContacts('c1', campaignContactsQuery)
+    },
+  },
   {
     name: 'ContactsApi.getMany (BaseCrudApi)',
     path: '/contacts',
@@ -273,6 +303,24 @@ const cases: Case[] = [
       return (f ? api.withQueryFormat(f) : api).getById('t1', { attributes: ['id'] })
     },
   },
+  {
+    name: 'TicketsApi.count',
+    path: '/tickets/count',
+    query: ticketsQuery,
+    call: (client, f) => {
+      const api = new TicketsApi(client)
+      return (f ? api.withQueryFormat(f) : api).count(ticketsQuery)
+    },
+  },
+  {
+    name: 'TicketsApi.exportHistory',
+    path: '/tickets/export-history',
+    query: ticketsQuery,
+    call: (client, f) => {
+      const api = new TicketsApi(client)
+      return (f ? api.withQueryFormat(f) : api).exportHistory(ticketsQuery)
+    },
+  },
 ]
 
 const jsonUrl = (path: string, query: object) =>

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,
+      )
+    })
+  })
 })

package/src/apis/tickets/TicketsApi.ts

@@ -5,26 +5,158 @@ import type {
   CreateTicketPayload,
   UpdateTicketPayload,
   CloseManyTicketsPayload,
+  TicketsCount,
+  TicketsCountManyQuery,
+  TicketsCountPostPayload,
+  TicketsCounts,
+  TicketsListQuery,
 } from './types'
 
+/**
+ * Tickets. The backend only serves them for reading (`getMany`, `getOne`, `getById`, the counts,
+ * the first waiting time and the exports) plus `closeMany`: a ticket is opened and transferred by
+ * `ContactsApi.transferTicket`. The reads check no permission (any authenticated user): the
+ * `@permissions` of the inherited `getMany`, `getOne` and `getById` do not apply here. `getById`
+ * of an unknown id resolves `null`. For a user who is not an admin, `getMany` leaves out the
+ * tickets of the contacts of the connections restricted to that user; the counts and `getById`
+ * do not.
+ */
 export class TicketsApi extends BaseCrudApi<Ticket, CreateTicketPayload, UpdateTicketPayload> {
   constructor(client: ApiClient) {
     super(client, '/tickets')
   }
 
+  /** @deprecated Not served: `POST /tickets` answers 404 `Route not found.`. Open a ticket through `ContactsApi.transferTicket`. */
+  override create(body: CreateTicketPayload, headers?: Record<string, string>): Promise<Ticket> {
+    return super.create(body, headers)
+  }
+
+  /** @deprecated Not served: `PUT /tickets/{id}` answers 404 `Route not found.`. Transfer through `ContactsApi.transferTicket`, close through `closeMany`. */
+  override updateById(
+    id: string,
+    body: UpdateTicketPayload,
+    headers?: Record<string, string>,
+  ): Promise<Ticket> {
+    return super.updateById(id, body, headers)
+  }
+
+  /** @deprecated Not served: `DELETE /tickets/{id}` answers 404 `Route not found.`. */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<Ticket> {
+    return super.deleteById(id, headers)
+  }
+
   /**
    * Closes multiple tickets in a single request. This is the only ticket-close
    * endpoint exposed by the API — there is no per-ticket close/update route.
    *
    * Pass `{ ids }` to close specific tickets, or `{ allContactsSelected: true, query }`
-   * to close every OPEN ticket matching `query` (the backend forces `isOpen: true`).
+   * to close every OPEN ticket matching `query` (the backend forces `isOpen: true`): an empty
+   * `where` closes every open ticket of the account. The answer has no body. Ids of closed,
+   * unknown or other accounts' tickets are skipped in silence; no id and no
+   * `allContactsSelected` answers 400 `ids not found`.
    * @permissions tickets.close.all OR tickets.close.me
    */
-  closeMany(payload: CloseManyTicketsPayload, headers?: Record<string, string>): Promise<unknown> {
-    return this.client.put<unknown, CloseManyTicketsPayload>(
+  closeMany(payload: CloseManyTicketsPayload, headers?: Record<string, string>): Promise<void> {
+    return this.client.put<void, CloseManyTicketsPayload>(
       `${this.basePath}/close-many`,
       payload,
       headers,
     )
   }
+
+  /**
+   * Counts the tickets matching the query. With `queries`, answers one count per query, in the
+   * same order (the root filters are then ignored).
+   */
+  count(query: TicketsCountManyQuery, headers?: Record<string, string>): Promise<TicketsCounts>
+  count(query?: TicketsListQuery, headers?: Record<string, string>): Promise<TicketsCount>
+  count(
+    query?: TicketsListQuery | TicketsCountManyQuery,
+    headers?: Record<string, string>,
+  ): Promise<TicketsCount | TicketsCounts> {
+    return this.client.get<TicketsCount | TicketsCounts>(
+      `${this.basePath}/count${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * POST variant of `count`, for queries too long for the URL. See {@link TicketsCountPostPayload}:
+   * `query` is required.
+   */
+  countPost(
+    body: TicketsCountPostPayload & { query: { queries: TicketsListQuery[] } },
+    headers?: Record<string, string>,
+  ): Promise<TicketsCounts>
+  countPost(body: TicketsCountPostPayload, headers?: Record<string, string>): Promise<TicketsCount>
+  countPost(
+    body: TicketsCountPostPayload,
+    headers?: Record<string, string>,
+  ): Promise<TicketsCount | TicketsCounts> {
+    return this.client.post<TicketsCount | TicketsCounts, TicketsCountPostPayload>(
+      `${this.basePath}/count`,
+      body,
+      headers,
+    )
+  }
+
+  /** Counts the open tickets of the contacts of a connection. An unknown id counts 0. */
+  countOpenByService(serviceId: string, headers?: Record<string, string>): Promise<number> {
+    return this.client.get<number>(`${this.basePath}/count-open/${serviceId}`, headers)
+  }
+
+  /** Counts the open tickets of a department. An unknown id counts 0. */
+  countOpenByDepartment(departmentId: string, headers?: Record<string, string>): Promise<number> {
+    return this.client.get<number>(
+      `${this.basePath}/count-open-by-department/${departmentId}`,
+      headers,
+    )
+  }
+
+  /** Counts the open tickets assigned to a user. An unknown id counts 0. */
+  countOpenByUser(userId: string, headers?: Record<string, string>): Promise<number> {
+    return this.client.get<number>(`${this.basePath}/count-open-by-user/${userId}`, headers)
+  }
+
+  /**
+   * The first waiting time of the ticket (`metrics.waitingTime`) as `HH:mm:ss`; `'00:00:00'` while
+   * it was not measured. The hours wrap every 24 h (a wait of 25 h answers `'01:00:00'`): read
+   * `metrics.waitingTime` (seconds) for the full value. An unknown id answers 500.
+   */
+  getFirstWaitingTime(id: string, headers?: Record<string, string>): Promise<string> {
+    return this.client.get<string>(`${this.basePath}/${id}/first-waiting-time`, headers)
+  }
+
+  /**
+   * Exports the conversation of a ticket as text, by its protocol (contact, attendants, subjects,
+   * summary, dates and the messages without the internal comments), sent as the attachment
+   * `<protocol>.txt` (Content-Type `plain/text`). Without a protocol the body is empty
+   * (`undefined`); an unknown protocol never answers.
+   */
+  exportTxt(protocol: string, headers?: Record<string, string>): Promise<string> {
+    return this.client.post<string, { protocol: string }>(
+      `${this.basePath}/export`,
+      { protocol },
+      headers,
+    )
+  }
+
+  /**
+   * Exports the tickets matching the query as CSV (`;`, a header of 20 columns in the language of
+   * the user, dates in the timezone of the account), streamed without a Content-Type.
+   *
+   * The query must include `contact` with its `service` (the History screen also includes
+   * `contact.tags`, `contact.person`, `user`, `department`, `ticketTopics` and `firstMessage`),
+   * and `order` must name unambiguous columns (e.g. `startedAt`): when a row fails after the header
+   * is sent, the answer never ends. Leave `page` out: the route pages through every match itself
+   * (`perPage` only sets the size of each batch), and a `page` in the query is read on every
+   * batch, so its rows are repeated or the CSV comes with the header only.
+   */
+  exportHistory(query: TicketsListQuery, headers?: Record<string, string>): Promise<string> {
+    return this.client.post<string>(
+      `${this.basePath}/export-history${this.toQueryString(query)}`,
+      undefined,
+      headers,
+    )
+  }
 }

package/src/apis/tickets/types.ts

@@ -1,7 +1,10 @@
+import type { ListQuery } from '../../core/types'
+import type { Account } from '../accounts/types'
 import type { Contact } from '../contacts/types'
 import type { Department } from '../departments/types'
 import type { Message } from '../messages/types'
 import type { Service } from '../services/types'
+import type { TicketTopic } from '../ticketTopics/types'
 import type { User } from '../users/types'
 
 export type TicketOrigin = 'automatic' | 'manual' | 'widget'
@@ -22,6 +25,14 @@ export type TicketMetrics = {
   /** Average waiting time per transfer. */
   waitingTimeTransfersAvg?: number
   isActiveTicket?: boolean
+  /** Longest waiting time in seconds, among the opening and the transfers. */
+  maxWaitingTime?: number
+  /** Department where the longest wait happened. */
+  maxWaitingTimeDepartmentId?: string
+  /** Name of that department when the wait was measured (the history export prefers the current name). */
+  maxWaitingTimeDepartmentName?: string
+  maxWaitingTimeStartedAt?: string
+  maxWaitingTimeEndedAt?: string
 }
 
 export type TicketTransferAction = 'opened' | 'transferred' | 'closed'
@@ -61,6 +72,16 @@ export type TicketTransfer = {
   lastMessage?: Message | null
 }
 
+/**
+ * A ticket as `GET /tickets` and `GET /tickets/{id}` answer it. The relationships come only when
+ * asked in `include`, except `firstMessage` and `lastMessage`, which always come: `null` when not
+ * included (or when the ticket has no message).
+ *
+ * The `include` whitelist of the route takes `contact` (and `contact.avatar`, `.thumbAvatar`,
+ * `.lastMessage`, `.tags`, `.service`, `.person`), `department`, `user`, `account`, `ticketTopics`,
+ * `firstMessage` and `ticketTransfers` (with `fromUser`, `toUser`, `fromDepartment`,
+ * `toDepartment`, `byUser`); anything else is dropped in silence.
+ */
 export type Ticket = {
   id: string
   isOpen: boolean
@@ -70,13 +91,18 @@ export type Ticket = {
   metrics: TicketMetrics
   startedAt: string | null
   endedAt: string | null
-  isDistributing: boolean
-  count: number | null
+  /** Only in the `ticket.*` webhooks (the stored ticket): the routes of `/tickets` never send it. */
+  isDistributing?: boolean
+  /** Only in the `ticket.*` webhooks (the stored ticket): the routes of `/tickets` never send it. */
+  distributingAt?: string | null
+  /** Only in the `ticket.*` webhooks (the stored ticket): the routes of `/tickets` never send it. */
+  count?: number | null
   accountId: string
   departmentId: string
   contactId: string
   userId: string | null
-  serviceId: string | null
+  /** @deprecated Never comes: a ticket has no connection of its own. Read `contact.serviceId`. */
+  serviceId?: string | null
   firstMessageId: string | null
   lastMessageId: string | null
   currentTicketTransferId: string | null
@@ -86,12 +112,28 @@ export type Ticket = {
   contact?: Contact
   department?: Department
   user?: User | null
+  account?: Account
+  ticketTopics?: TicketTopic[]
+  firstMessage?: Message | null
+  /** @deprecated Always `null`: `lastMessage` is out of the include whitelist. Include `contact.lastMessage`. */
+  lastMessage?: Message | null
+  /** @deprecated Never comes: `service` is out of the include whitelist. Include `contact.service`. */
   service?: Service | null
   ticketTransfers?: TicketTransfer[]
 }
 
-export type TicketRelationships = 'contact' | 'department' | 'user' | 'service' | 'ticketTransfers'
+export type TicketRelationships =
+  | 'contact'
+  | 'department'
+  | 'user'
+  | 'account'
+  | 'ticketTopics'
+  | 'firstMessage'
+  | 'lastMessage'
+  | 'service'
+  | 'ticketTransfers'
 
+/** @deprecated Not served: the backend has no `POST /tickets`. A ticket is opened by `ContactsApi.transferTicket`. */
 export type CreateTicketPayload = {
   contactId: string
   departmentId: string
@@ -100,6 +142,7 @@ export type CreateTicketPayload = {
   origin?: TicketOrigin
 }
 
+/** @deprecated Not served: the backend has no `PUT /tickets/{id}`. Transfer through `ContactsApi.transferTicket`, close through `TicketsApi.closeMany`. */
 export type UpdateTicketPayload = {
   departmentId?: string
   userId?: string | null
@@ -107,6 +150,14 @@ export type UpdateTicketPayload = {
   isOpen?: boolean
 }
 
+/** What `closeMany` records on every ticket it closes. */
+export type CloseTicketsData = {
+  /** Subjects of the closing (one id or a list). */
+  ticketTopicIds?: string[] | string
+  /** Summary of the closing, stored in `comments`. */
+  comments?: string
+}
+
 /**
  * Body for `PUT /tickets/close-many`.
  *
@@ -116,5 +167,24 @@ export type UpdateTicketPayload = {
  * the backend always forces `where.isOpen = true`.
  */
 export type CloseManyTicketsPayload =
-  | { ids: string[]; ticketTopicIds?: string[] | string; comments?: string }
-  | { allContactsSelected: true; query: { query: string } }
+  | ({ ids: string[] } & CloseTicketsData)
+  | ({ allContactsSelected: true; query: { query: string } } & CloseTicketsData)
+
+/** A list query of tickets, as `count` and `exportHistory` take it. */
+export type TicketsListQuery = ListQuery<Ticket>
+
+/** `count` with `queries`: one count per query, in the same order. */
+export type TicketsCountManyQuery = TicketsListQuery & { queries: TicketsListQuery[] }
+
+/**
+ * Body of `POST /tickets/count`. The filters go at the root, as in a list query, and `query` is
+ * required: without it the route answers 500. `query: {}` counts the root filters into
+ * `{ count }`; `query: { queries }` ignores them and answers `{ counts }`, one per query.
+ */
+export type TicketsCountPostPayload = TicketsListQuery & {
+  query: { queries?: TicketsListQuery[] }
+}
+
+export type TicketsCount = { count: number }
+
+export type TicketsCounts = { counts: number[] }

package/src/incommingWebhooks/index.test-d.ts

@@ -1,5 +1,12 @@
 import { expectAssignable, expectNotAssignable, expectType } from 'tsd'
-import type { WebhookPayload, WebhookEvent, WebhookEventPayloadMap, BotCommandData } from './index'
+import type {
+  WebhookPayload,
+  WebhookEvent,
+  WebhookEventPayloadMap,
+  BotCommandData,
+  TicketWebhookData,
+} from './index'
+import type { Contact, ContactRelationships } from '../apis/contacts'
 import type { Message, MessageRelationships } from '../apis/messages'
 import type { Ticket, TicketRelationships } from '../apis/tickets'
 import type { BotApiSignalData, BotContexts } from '../apis/bots'
@@ -27,6 +34,12 @@ expectNotAssignable<WebhookPayload<'ticket.updated'>['data']>(
   {} as Pick<Ticket, TicketRelationships>,
 )
 
+// ...except the contact, which the sender always attaches (stored contact, no relationships)
+declare const ticketUpdated: WebhookPayload<'ticket.updated'>
+expectType<TicketWebhookData>(ticketUpdated.data)
+expectType<Omit<Contact, ContactRelationships>>(ticketUpdated.data.contact)
+expectType<string>(ticketUpdated.data.contact.serviceId)
+
 // ── event narrowing tightens data type ───────────────────────────────────────
 
 declare const ticketPayload: WebhookPayload<'ticket.created'>

package/src/incommingWebhooks/index.ts

@@ -66,6 +66,15 @@ export type WebhookEvent =
 
 // ─── Event → Payload map ─────────────────────────────────────────────────────
 
+/**
+ * `data` of `ticket.created` and `ticket.updated`: the stored ticket (so `isDistributing`,
+ * `distributingAt` and `count` come, and `serviceId` does not) plus its stored contact, which the
+ * sender always attaches. Read the connection of the ticket in `contact.serviceId`.
+ */
+export type TicketWebhookData = Omit<Ticket, TicketRelationships> & {
+  contact: Omit<Contact, ContactRelationships>
+}
+
 export type BotCommandData = {
   id: string
   contactId: string
@@ -77,8 +86,8 @@ export type BotCommandData = {
 export interface WebhookEventPayloadMap {
   'message.created': Omit<Message, MessageRelationships>
   'message.updated': Omit<Message, MessageRelationships>
-  'ticket.created': Omit<Ticket, TicketRelationships>
-  'ticket.updated': Omit<Ticket, TicketRelationships>
+  'ticket.created': TicketWebhookData
+  'ticket.updated': TicketWebhookData
   'service.created': Omit<Service, ServiceRelationships>
   'service.updated': Omit<Service, ServiceRelationships>
   'service.destroyed': Omit<Service, ServiceRelationships>