@ikatec/digisac-api-sdk 4.15.0 → 4.16.0

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'
 }