@ikatec/digisac-api-sdk 4.14.0 → 4.16.0

package/src/apis/pipeline/types.ts

@@ -129,8 +129,7 @@ export type CreatePipelineStagePayload = {
 
 export type UpdatePipelineStagePayload = CreatePipelineStagePayload & {
   /**
-   * The stage id. Send it: the duplicate-name check compares against the `id` of the body,
-   * so without it keeping the current name answers `'STAGE_ALREADY_EXIST'`.
+   * The stage id. Send it: without it, keeping the current name answers `'STAGE_ALREADY_EXIST'`.
    */
   id?: string
 }
@@ -145,10 +144,10 @@ export type DeletePipelineStagePayload = {
   typeAction?: 'move'
   idNewStage?: string
   /**
-   * Author of the card movements written by `'move'` — the backend reads it from the body, not
-   * from the token (the UI sends the logged user). Without it, moving a stage that has cards
-   * fails with 500 (`CardMovement.userId cannot be null`) after the cards were already moved,
-   * and the stage is kept.
+   * The user that moves the cards with `'move'`: send the logged user (`{ id }` of
+   * `MeApi.getMe`). Without it, moving a stage that has cards fails with 500
+   * (`CardMovement.userId cannot be null`) after the cards were already moved, and the stage is
+   * kept.
    */
   user?: { id: string }
 }
@@ -163,7 +162,7 @@ export type PipelineStageStatusWithCount = PipelineStageStatus & { cardsCount: n
 
 /**
  * What happens to the cards of a deleted status: `'keep-without-status'` clears their status,
- * `'move-to-another'` sets `newStatusId` (not validated by the backend).
+ * `'move-to-another'` moves them to the status `newStatusId`.
  */
 export type DeletePipelineStatusPayload =
   | { action: 'keep-without-status' }
@@ -192,7 +191,7 @@ export type PipelineAutomation = {
 
 export type CreatePipelineAutomationPayload = {
   pipelineId: string
-  /** The backend does not validate it (any string is stored); `'notification'` is the only one used. */
+  /** `'notification'` is the only one used. */
   type: PipelineAutomationType
   config?: PipelineAutomationConfig
   isArchived?: boolean

package/src/apis/queryFormat.test.ts

@@ -65,6 +65,19 @@ const cases: Case[] = [
       return (f ? api.withQueryFormat(f) : api).getMany(campaignsQuery)
     },
   },
+  {
+    name: 'CampaignsApi.getOne (one page of one campaign)',
+    path: '/campaigns',
+    query: { ...campaignsQuery, page: 1, perPage: 1 },
+    call: (client, f) => {
+      const api = new CampaignsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getOne({
+        ...campaignsQuery,
+        paginate: false,
+        limit: 5,
+      })
+    },
+  },
   {
     name: 'CampaignsApi.getContacts',
     path: '/campaigns/c1/contacts',

package/src/apis/quickReplies/types.ts

@@ -49,7 +49,10 @@ export type UpdateQuickReplyPayload = {
   files: QuickReplyFilePayload[]
 }
 
-/** The query of `loadOnDemand`, passed to the database as is. */
+/**
+ * The query of `loadOnDemand`: the `where`, `include`, `order`, `attributes`, `limit` and `offset`
+ * of a list query.
+ */
 export type QuickRepliesLoadOnDemandQuery = Pick<
   ListQuery<QuickReply>,
   'where' | 'include' | 'order' | 'attributes' | 'limit' | 'offset'

package/src/apis/schedule/types.ts

@@ -1,29 +1,52 @@
+import type { CampaignTemplateParameter } from '../campaigns/types'
 import type { Contact } from '../contacts/types'
 import type { Department } from '../departments/types'
 import type { File } from '../files/types'
 import type { User } from '../users/types'
 
-/** `scheduled` until the worker runs it; `error` and `not_sent` come with the `reason`. */
+/**
+ * - `scheduled`: waiting for the worker.
+ * - `done`: sent, or skipped with `reason: null` (contact blocked, connection off, open ticket
+ *   without `sendWithOpenTicket`, user without access to the connection). It is stored
+ *   before the message is sent, so a template schedule can still turn `error` afterwards.
+ *   Archiving the connection also sets its `scheduled` schedules as `done`, and archiving the
+ *   department every schedule of it (keeping the `reason` of the ones that had failed).
+ * - `not_sent`: only for a template schedule (`hsmId`), with `HSM_IS_BLOCKED` or
+ *   `SERVICE_IS_BLOCKED`.
+ * - `error`: `DDD_BLOCKED` for any schedule; the other reasons only for a template schedule sent
+ *   with `extraOptions` (a plain schedule is `done` instead).
+ */
 export type ScheduleStatus = 'scheduled' | 'done' | 'error' | 'not_sent'
 
+/** The template parameters of a WhatsApp Business schedule (`hsmId`), sent with the message. */
+export type ScheduleExtraOptions = {
+  /** The parameters of the header, body and buttons of the template, as a campaign takes them. */
+  parameters?: CampaignTemplateParameter[]
+  [key: string]: unknown
+}
+
 export type Schedule = {
   id: string
   status: ScheduleStatus
   /**
-   * Why it was not sent: `ALREADY_TICKET_OPENED`, `DDD_BLOCKED`, `SERVICE_IS_NOT_ENABLED`,
-   * `CONTACT_IS_BLOCKED`, `CONTACT_NOT_EXISTS`, `HSM_LIMIT_EXCEEDED`, `HSM_IS_BLOCKED`,
-   * `SERVICE_IS_BLOCKED`, `INVALID_PAYLOAD`, a WhatsApp Business error code or
-   * `SCHEDULE_UNKNOWN_REASON`.
+   * Why an `error` or `not_sent` schedule was not sent (see {@link ScheduleStatus}):
+   * `ALREADY_TICKET_OPENED`, `DDD_BLOCKED`, `SERVICE_IS_NOT_ENABLED`, `CONTACT_IS_BLOCKED`,
+   * `CONTACT_NOT_EXISTS`, `HSM_LIMIT_EXCEEDED`, `HSM_IS_BLOCKED`, `SERVICE_IS_BLOCKED`,
+   * `INVALID_PAYLOAD`, a WhatsApp Business error code or `SCHEDULE_UNKNOWN_REASON`. Usually `null`
+   * for a `done` schedule (see the archiving of the department in {@link ScheduleStatus}).
    */
   reason: string | null
-  /** For a WhatsApp Business template (`hsmId`), the message the server built from it. */
+  /**
+   * For a WhatsApp Business template (`hsmId`) sent with `extraOptions`, the message the server
+   * built from it; otherwise the `message` sent.
+   */
   message: string | null
   notes: string
   openTicket: boolean | null
   notificateUser: boolean | null
   /** Sends the message even when the contact already has an open ticket. */
   sendWithOpenTicket: boolean | null
-  extraOptions: Record<string, unknown> | null
+  extraOptions: ScheduleExtraOptions | null
   hsmId: string | null
   hsmFileId: string | null
   scheduledAt: string
@@ -73,7 +96,11 @@ export type CreateSchedulePayload = {
   scheduledAt: string
   contactId: string
   departmentId: string
-  /** Up to 1024 characters. Optional for a WhatsApp Business template, built from `hsmId`. */
+  /**
+   * Up to 1024 characters. Optional for a WhatsApp Business template sent with `extraOptions` (the
+   * server builds it from the template); without both, the schedule turns `done` and no message is
+   * sent.
+   */
   message?: string
   /**
    * Up to 1024 characters. Required by the route only with `openTicket: true`, but the column is
@@ -85,8 +112,13 @@ export type CreateSchedulePayload = {
   sendWithOpenTicket?: boolean
   userId?: string
   hsmId?: string
+  /** The header file of the template (`hsmId`), uploaded with `attachedType: 'hsm.file'`. */
   hsmFileId?: string
-  extraOptions?: Record<string, unknown>
+  /**
+   * Send it with `hsmId` (`{}` is enough for a template without parameters): without it the
+   * schedule sends `message` as plain text, not the template.
+   */
+  extraOptions?: ScheduleExtraOptions
   /** New attachments only: the create drops `{ id }` items. */
   files?: ScheduleNewFilePayload[]
 }
@@ -107,7 +139,7 @@ export type UpdateSchedulePayload = {
   sendWithOpenTicket?: boolean
   hsmId?: string | null
   hsmFileId?: string | null
-  extraOptions?: Record<string, unknown> | null
+  extraOptions?: ScheduleExtraOptions | null
   /** Replaces the attachments: `{ id }` keeps one, `{ base64, ... }` adds one; omitted or `[]` removes all. */
   files?: ScheduleFilePayload[]
 }

package/src/apis/terms/TermsApi.ts

@@ -6,8 +6,8 @@ import type { Term } from './types'
  * Platform terms of use. Terms are published by Agnus (billing) and accepted by the account users,
  * so the `/terms` route has no create/list/update/delete — only the routes below.
  *
- * `GET /terms/:id/export-pdf` is not exposed: it answers a binary PDF, and `ApiClient` only
- * handles JSON/text bodies.
+ * `GET /terms/:id/export-pdf` (a binary PDF) has no method: read it with `client.requestRaw` (see
+ * "Raw responses" in the README).
  */
 export class TermsApi extends BaseApi implements HasGetById<Term> {
   public readonly basePath = '/terms'

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/BaseReadApi.ts

@@ -4,8 +4,8 @@ import type { GetByIdQuery, HasGetById, HasGetMany, ListQuery, Paginated } from
 
 /**
  * Generic read-only resource: `getMany`, `getOne` and `getById` under `basePath`. Base of
- * `BaseCrudApi`, and of the resources the backend only serves for reading (e.g. permissions,
- * auth history).
+ * `BaseCrudApi`, and of the resources the backend serves for reading, plus their own actions (e.g.
+ * permissions, auth history).
  */
 export class BaseReadApi<TResponse, TQuery extends ListQuery<TResponse> = ListQuery<TResponse>>
   extends BaseApi

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