@ikatec/digisac-api-sdk 4.5.1 → 4.7.0

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/core/BaseCrudApi.ts

@@ -14,15 +14,19 @@ export type {
   CrudApi,
 } from './types'
 
-/** Generic CRUD resource: the reads of `BaseReadApi` plus `create`, `updateById` and `deleteById`. */
+/**
+ * Generic CRUD resource: the reads of `BaseReadApi` plus `create`, `updateById` and `deleteById`.
+ * `TDeleteResponse` is what `deleteById` resolves to (most routes answer the text `'OK'`).
+ */
 export class BaseCrudApi<
   TResponse,
   TCreate,
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
+  TDeleteResponse = TResponse,
 >
   extends BaseReadApi<TResponse, TQuery>
-  implements CrudApi<TResponse, TCreate, TUpdate, TQuery>
+  implements CrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse>
 {
   /**
    * Creates a new resource.
@@ -42,9 +46,9 @@ export class BaseCrudApi<
 
   /**
    * Deletes a resource by ID.
-   * @permissions $resourceName.delete
+   * @permissions $resourceName.destroy
    */
-  deleteById(id: string, headers?: Record<string, string>): Promise<TResponse> {
-    return this.client.delete<TResponse>(`${this.basePath}/${id}`, headers)
+  deleteById(id: string, headers?: Record<string, string>): Promise<TDeleteResponse> {
+    return this.client.delete<TDeleteResponse>(`${this.basePath}/${id}`, headers)
   }
 }

package/src/core/types.ts

@@ -159,8 +159,9 @@ export type CrudApi<
   TCreate,
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
+  TDeleteResponse = TResponse,
 > = HasGetMany<TResponse, TQuery> &
   HasGetById<TResponse> &
   HasCreate<TResponse, TCreate> &
   HasUpdateById<TResponse, TUpdate> &
-  HasDeleteById<TResponse>
+  HasDeleteById<TDeleteResponse>

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

@@ -1,7 +1,15 @@
 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'
 
 // ── WebhookPayload (generic) ─────────────────────────────────────────────────
 
@@ -26,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'>
@@ -37,6 +51,14 @@ declare const botPayload: WebhookPayload<'bot.command'>
 expectType<BotCommandData>(botPayload.data)
 expectAssignable<{ id: string; command: string }>(botPayload.data)
 
+// ── bot.* deliver the stored bot, with the contexts in the map form ──────────
+
+declare const botCreated: WebhookPayload<'bot.created'>
+expectType<BotContexts>(botCreated.data.contexts)
+
+declare const apiSignal: WebhookPayload<'bot.api-signal'>
+expectType<BotApiSignalData>(apiSignal.data)
+
 // ── invalid events are rejected ──────────────────────────────────────────────
 
 expectNotAssignable<WebhookEvent>('message.deleted')

package/src/incommingWebhooks/index.ts

@@ -1,4 +1,4 @@
-import type { Bot, BotRelationships } from '../apis/bots'
+import type { BotApiSignalData, BotRecord } from '../apis/bots'
 import type { Campaign, CampaignRelationships } from '../apis/campaigns'
 import type { Contact, ContactRelationships } from '../apis/contacts'
 import type { Department, DepartmentRelationships } from '../apis/departments'
@@ -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>
@@ -103,13 +112,13 @@ export interface WebhookEventPayloadMap {
   'role.created': Omit<Role, RoleRelationships>
   'role.updated': Omit<Role, RoleRelationships>
   'role.destroyed': Omit<Role, RoleRelationships>
-  'bot.created': Omit<Bot, BotRelationships>
-  'bot.updated': Omit<Bot, BotRelationships>
-  'bot.destroyed': Omit<Bot, BotRelationships>
+  'bot.created': BotRecord
+  'bot.updated': BotRecord
+  'bot.destroyed': BotRecord
   'bot.command': BotCommandData
-  'bot.enter-context': Omit<Bot, BotRelationships>
-  'bot.leave-context': Omit<Bot, BotRelationships>
-  'bot.api-signal': Omit<Bot, BotRelationships>
+  'bot.enter-context': BotRecord
+  'bot.leave-context': BotRecord
+  'bot.api-signal': BotApiSignalData
   'quickReplies.created': Omit<QuickReply, QuickReplyRelationships>
   'quickReplies.updated': Omit<QuickReply, QuickReplyRelationships>
   'quickReplies.destroyed': Omit<QuickReply, QuickReplyRelationships>