@ikatec/digisac-api-sdk 4.15.0 → 4.17.0

package/src/apis/tickets/TicketsApi.ts

@@ -1,5 +1,6 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
+import type { GetByIdQuery } from '../../core/types'
 import type {
   Ticket,
   CreateTicketPayload,
@@ -15,23 +16,42 @@ import type {
 /**
  * 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.
+ * `ContactsApi.transferTicket`, and the ticket of one contact is closed by
+ * `ContactsApi.closeTicket`. `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.
  */
 export class TicketsApi extends BaseCrudApi<Ticket, CreateTicketPayload, UpdateTicketPayload> {
   constructor(client: ApiClient) {
     super(client, '/tickets')
   }
 
+  /** Returns the first ticket matching the query, or `null` when none match. */
+  override getOne(
+    query?: TicketsListQuery,
+    headers?: Record<string, string>,
+  ): Promise<Ticket | null> {
+    return super.getOne(query, headers)
+  }
+
+  /** Returns a ticket by ID; an unknown id resolves `null`. */
+  override getById(
+    id: string,
+    query?: GetByIdQuery<Ticket>,
+    headers?: Record<string, string>,
+  ): Promise<Ticket> {
+    return super.getById(id, query, headers)
+  }
+
   /** @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`. */
+  /**
+   * @deprecated Not served: `PUT /tickets/{id}` answers 404 `Route not found.`. Transfer through
+   * `ContactsApi.transferTicket`, close through `ContactsApi.closeTicket` or `closeMany`.
+   */
   override updateById(
     id: string,
     body: UpdateTicketPayload,
@@ -46,8 +66,8 @@ export class TicketsApi extends BaseCrudApi<Ticket, CreateTicketPayload, UpdateT
   }
 
   /**
-   * 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.
+   * Closes multiple tickets in a single request. `ContactsApi.closeTicket` closes the ticket of one
+   * contact by the contact id, and also takes the rating of the AI summary.
    *
    * Pass `{ ids }` to close specific tickets, or `{ allContactsSelected: true, query }`
    * to close every OPEN ticket matching `query` (the backend forces `isOpen: true`): an empty

package/src/apis/tickets/types.ts

@@ -142,7 +142,10 @@ export type CreateTicketPayload = {
   origin?: TicketOrigin
 }
 
-/** @deprecated Not served: the backend has no `PUT /tickets/{id}`. Transfer through `ContactsApi.transferTicket`, close through `TicketsApi.closeMany`. */
+/**
+ * @deprecated Not served: the backend has no `PUT /tickets/{id}`. Transfer through
+ * `ContactsApi.transferTicket`, close through `ContactsApi.closeTicket` or `TicketsApi.closeMany`.
+ */
 export type UpdateTicketPayload = {
   departmentId?: string
   userId?: string | null

package/src/apis/timetable/TimetableApi.ts

@@ -3,6 +3,12 @@ import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Timetable, CreateTimetablePayload, UpdateTimetablePayload } from './types'
 
+/**
+ * Timetables (work hours) of the users. Out of the timetable of the user, most authenticated routes
+ * answer 403 `Is out of office hours`, with the `workPlan` of the timetable in the `extra` of the
+ * error body (see `OutOfOfficeHoursErrorExtra`). Logging in (`POST /oauth/token`) and setting
+ * the status to `offline` still work.
+ */
 export class TimetableApi extends BaseCrudApi<
   Timetable,
   CreateTimetablePayload,

package/src/apis/timetable/types.ts

@@ -32,3 +32,12 @@ export type CreateTimetablePayload = {
 
 /** The backend requires the three fields on every update (400 `required` otherwise). */
 export type UpdateTimetablePayload = CreateTimetablePayload
+
+/**
+ * The `extra` of the 403 `Is out of office hours` error body: the timetable of the user. The error
+ * is a `PermissionDeniedError` with that `message`; read it as
+ * `(error.body as { extra?: OutOfOfficeHoursErrorExtra }).extra?.workPlan`.
+ */
+export type OutOfOfficeHoursErrorExtra = {
+  workPlan: TimetableWorkSlot[]
+}

package/src/apis/users/UsersApi.test.ts

@@ -3,6 +3,7 @@ import { UsersApi } from './UsersApi'
 import type { ApiClient } from '../../core/ApiClient'
 import type {
   BulkUsersStatusPreview,
+  BulkUpdateUsersLinksResult,
   BulkUsersStatusResult,
   ImportUsersResult,
   User,
@@ -109,6 +110,22 @@ describe('UsersApi', () => {
     })
   })
 
+  describe('bulkUpdateLinks', () => {
+    it('calls client.put with /users/v2/bulk-update and body', async () => {
+      const response: BulkUpdateUsersLinksResult = {
+        changed: 1,
+        failed: 0,
+        changedIds: ['usr-1'],
+        missingIds: ['usr-2'],
+      }
+      vi.mocked(client.put).mockResolvedValue(response)
+      const body = { ids: ['usr-1', 'usr-2'], timetableId: null, departmentIds: ['dep-1'] }
+      const result = await api.bulkUpdateLinks(body, headers)
+      expect(client.put).toHaveBeenCalledWith('/users/v2/bulk-update', body, headers)
+      expect(result).toEqual(response)
+    })
+  })
+
   describe('bulkStatus', () => {
     it('calls client.post with /users/bulk-status and body', async () => {
       const response: BulkUsersStatusResult = {

package/src/apis/users/UsersApi.ts

@@ -7,6 +7,8 @@ import type {
   BulkUsersStatusPayload,
   BulkUsersStatusPreview,
   BulkUsersStatusResult,
+  BulkUpdateUsersLinksPayload,
+  BulkUpdateUsersLinksResult,
   CreateUserPayload,
   EnableUserAccessResult,
   ExportUsersPayload,
@@ -41,9 +43,8 @@ export class UsersApi extends ArchivableCrudApi<
   }
 
   /**
-   * Archives or restores a user through the dedicated route used by the UI, which also
-   * sets the user offline and ends its sessions. The route enforces the business rules that
-   * {@link archive}/{@link unarchive} (a plain `PUT { archivedAt }`) skip:
+   * Archives or restores a user through the route used by the UI, which also sets the user
+   * offline and ends its sessions:
    * - archiving refuses (403) a user referenced by a bot or with open tickets;
    * - restoring refuses (402) when the plan has no free user slot.
    * @permissions users.view OR users.archive
@@ -75,6 +76,23 @@ export class UsersApi extends ArchivableCrudApi<
     )
   }
 
+  /**
+   * Links up to 100 users at once to a timetable, departments or roles (see
+   * {@link BulkUpdateUsersLinksPayload}). The timetable is written for the whole batch at once; the
+   * departments and roles user by user, so the result may be partial (`failed`).
+   * @permissions users.update
+   */
+  bulkUpdateLinks(
+    body: BulkUpdateUsersLinksPayload,
+    headers?: Record<string, string>,
+  ): Promise<BulkUpdateUsersLinksResult> {
+    return this.client.put<BulkUpdateUsersLinksResult, BulkUpdateUsersLinksPayload>(
+      `${this.basePath}/v2/bulk-update`,
+      body,
+      headers,
+    )
+  }
+
   /**
    * Archives or unarchives up to 100 users at once.
    * @permissions users.archive

package/src/apis/users/types.ts

@@ -145,6 +145,34 @@ export type BulkUsersStatusResult = {
   missingIds: string[]
 }
 
+/**
+ * Body for `PUT /users/v2/bulk-update` (1 to 100 user IDs). Send at least one of `timetableId`,
+ * `departmentIds` and `roleIds` (400 otherwise). A link id of another account, or unknown, refuses
+ * the whole batch with 400 (`<field> contains ids that do not belong to the account.`).
+ */
+export type BulkUpdateUsersLinksPayload = {
+  ids: string[]
+  /** Sets the timetable of every user; `null` removes it. */
+  timetableId?: string | null
+  /** Adds the departments to every user (the current ones are kept). At least one id. */
+  departmentIds?: string[]
+  /** Adds the roles to every user (the current ones are kept). At least one id. */
+  roleIds?: string[]
+}
+
+export type BulkUpdateUsersLinksResult = {
+  /**
+   * Users of the batch written by at least one of the steps (with `timetableId`, `null` included,
+   * every user found; with `departmentIds`/`roleIds`, also those that already had them).
+   */
+  changed: number
+  /** Failures of the per-user writes (departments and roles), one per user and field. */
+  failed: number
+  changedIds: string[]
+  /** IDs of the batch that are not users of the account (they are skipped). */
+  missingIds: string[]
+}
+
 /** Body for `POST /users/export`. */
 export type ExportUsersPayload = {
   filter: 'all' | 'active' | 'archived'

package/src/apis/webhooks/types.ts

@@ -1,14 +1,46 @@
 import type { Service } from '../services/types'
 
+/**
+ * `by_service` and `whatsapp_low_level` only get the events of the connections in `services`.
+ * Events not tied to a connection (users, departments, tags...) reach `by_service` too. A webhook
+ * with `services`, whatever its type, only gets the events of those connections (events not tied
+ * to a connection reach it too); a `general` webhook is meant to have none.
+ */
+export type WebhookType = 'general' | 'by_service' | 'whatsapp_low_level'
+
+/**
+ * The categories of message the `message.created` event delivers. Only `false` leaves a category
+ * out (an absent key keeps it); `null`, or no filter, delivers every message. The other events are
+ * not filtered. A key outside these answers 400.
+ */
+export type WebhookMessageFilters = {
+  /** Messages of the contact (not their reactions). */
+  received?: boolean
+  /** Messages sent through the connection, except the bot's (and the reactions). */
+  sent?: boolean
+  /** Messages sent by the bot. */
+  bot?: boolean
+  /**
+   * Internal comments, ticket events, reactions, summaries, schedules, AI evaluations, the notices
+   * of the message block rule and the message types the platform does not know.
+   */
+  system?: boolean
+}
+
 export type Webhook = {
   id: string
   name: string
   url: string
-  type: string
+  /** A webhook created before the type was validated may hold another value. */
+  type: WebhookType
   active: boolean
   events: string[]
+  /** `null` when `events` has no `message.created` (the backend clears it on every write). */
+  messageFilters?: WebhookMessageFilters | null
   errorAt: string | null
   errorNotifiedAt: string | null
+  /** The average delivery latency, in ms (shown in the list of webhooks); `null` until measured. */
+  avgLatencyMs?: number | null
   userId: string
   accountId: string
   createdAt: string
@@ -23,15 +55,30 @@ export type WebhookRelationships = 'services'
 export type CreateWebhookPayload = {
   name: string
   url: string
-  type: string
+  type: WebhookType
   events: string[]
   active?: boolean
+  /** The connections of a `by_service` or `whatsapp_low_level` webhook (none for `general`). */
+  services?: string[]
+  /** Only kept with the `message.created` event. */
+  messageFilters?: WebhookMessageFilters | null
 }
 
+/**
+ * `updateById` sends a `PUT`: `name`, `url`, `type` and `events` are required (400 without them),
+ * as in the create.
+ */
 export type UpdateWebhookPayload = {
-  name?: string
-  url?: string
-  type?: string
-  events?: string[]
+  name: string
+  url: string
+  type: WebhookType
+  events: string[]
   active?: boolean
+  /**
+   * Replaces the connections of the webhook; omitted keeps them. Send `[]` when the type becomes
+   * `general`: the connections kept also filter a `general` webhook.
+   */
+  services?: string[]
+  /** Only kept with the `message.created` event. */
+  messageFilters?: WebhookMessageFilters | null
 }

package/src/core/errors.ts

@@ -181,7 +181,10 @@ export class PaymentRequiredError extends ApiError {
   override name = 'PaymentRequiredError'
 }
 
-/** 403 — the user lacks the permission for this action. */
+/**
+ * 403 — the user lacks the permission for this action, or the action is refused (e.g. out of
+ * office hours, see `OutOfOfficeHoursErrorExtra`).
+ */
 export class PermissionDeniedError extends ApiError {
   override name = 'PermissionDeniedError'
 }