@ikatec/digisac-api-sdk 4.15.0 → 4.17.0

package/src/apis/kanbanColumns/KanbanColumnsApi.ts

@@ -3,6 +3,7 @@ import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type {
   KanbanColumn,
   CreateKanbanColumnPayload,
+  DeleteKanbanColumnPayload,
   ReorderKanbanColumnPayload,
   UpdateKanbanColumnPayload,
 } from './types'
@@ -16,6 +17,36 @@ export class KanbanColumnsApi extends BaseCrudApi<
     super(client, '/kanban-columns')
   }
 
+  /**
+   * Deletes a column and its cards (their tickets are kept as they are). The `'initial'` and
+   * `'final'` columns cannot be deleted (500). Resolves to the deleted column. To keep the cards,
+   * use {@link deleteMovingCards}.
+   * @permissions kanban.columns.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<KanbanColumn> {
+    return super.deleteById(id, headers)
+  }
+
+  /**
+   * Deletes a column after moving its cards to the top of another column of the board, in their
+   * order. The cards move as `KanbanCardsApi.reorder` moves them: to the `'final'` column,
+   * their open tickets are closed. The `'initial'` and `'final'` columns cannot be deleted (500).
+   * Resolves to the deleted column.
+   * @permissions kanban.columns.destroy
+   */
+  deleteMovingCards(
+    id: string,
+    body: DeleteKanbanColumnPayload,
+    headers?: Record<string, string>,
+  ): Promise<KanbanColumn> {
+    return this.client.request<KanbanColumn, DeleteKanbanColumnPayload>(
+      'DELETE',
+      `${this.basePath}/${id}`,
+      body,
+      headers,
+    )
+  }
+
   /**
    * Moves a column between two neighbours of the same board. Both the column and a neighbour
    * must be draggable; swapped neighbours (`before` after `after`) fail with 500. Resolves to the

package/src/apis/kanbanColumns/types.ts

@@ -50,3 +50,8 @@ export type ReorderKanbanColumnPayload = {
   /** The column that ends up on the right. */
   afterColumnId?: string
 }
+
+export type DeleteKanbanColumnPayload = {
+  /** The column of the same board that receives the cards of the deleted one. */
+  cardsDestinationColumnId: string
+}

package/src/apis/messages/MessagesApi.ts

@@ -24,10 +24,19 @@ export class MessagesApi extends BaseCrudApi<Message, CreateMessagePayload, Upda
   }
 
   /**
-   * Edits the text (or the file) of a message sent by the account, up to 15 minutes after it was
-   * sent (403 `Cannot edit message` after that). `contactId` is required (without it the route
-   * answers 500), and `text` or `file` (400 without both). Sent as `PATCH /messages/:id`.
-   * @permissions messages.update
+   * Edits the text of a message sent by the account, up to 15 minutes after it was sent. Sent as
+   * `PATCH /messages/:id`. `contactId` is required: without it the route answers 500, and an
+   * unknown or blocked contact answers 400 `The given data was invalid.` (the error comes in
+   * `contactId`). So is `text`: `text: ''` alone answers 400 (`At least one field (text or file)
+   * must be provided`), and a `text` with only spaces answers 400 `Text cannot be empty`. Only the
+   * text is edited: `file` is not sent to the connection. A message received, or sent more than
+   * 15 minutes ago, answers 403 `Cannot edit message`; an unknown message answers 404
+   * `Message not found`. The message passes to the user who edited it.
+   *
+   * The message is answered once the edit is sent to the connection, before the connection
+   * confirms it: read it again until `text` changes (`data.edited` is set to `true` when the
+   * connection reports the edit). On WhatsApp Business and Telegram connections the route answers
+   * the result of the edit job, not the message: read it again with `getById`.
    */
   override updateById(
     id: string,

package/src/apis/messages/types.ts

@@ -62,6 +62,11 @@ export type MessageData = {
   subject?: unknown
   resourceId?: string
   hasReaction?: boolean
+  /**
+   * `true` once the connection reports that the text was edited (see `MessagesApi.updateById`; on
+   * WhatsApp, an edit made by the contact included).
+   */
+  edited?: boolean
   whatsappMessageId?: string
   startBlockedAt?: string
   endBlockedAt?: string
@@ -173,15 +178,27 @@ export type MessageRelationships =
   | 'mentionedList'
   | 'interpolatedHsmMessage'
 
+/** A file sent inline in a message. `base64` may also be a `data:` URL, which carries the mimetype. */
+export type MessageFileInput = {
+  base64: string
+  mimetype: string
+  name: string
+}
+
 export type CreateMessagePayload = {
   text?: string
   contactId?: string
   number?: string
+  /** Name of the contact created when the message is sent by `number`. */
+  name?: string
   serviceId?: string
   userId?: string
+  /** The file sent with the message, usually a {@link MessageFileInput}; `text` goes as its caption. */
   file?: unknown
   fileId?: string
   filesIds?: string[]
+  /** Files attached to an e-mail. The other connections send a single `file`. */
+  attachments?: MessageFileInput[]
   quotedMessageId?: string
   hsmId?: string
   hsm?: unknown
@@ -194,7 +211,21 @@ export type CreateMessagePayload = {
   mentionedList?: string[]
   interactiveMessage?: unknown
   stickerId?: string
+  /**
+   * Sends an audio as a voice note. When omitted the audio is converted as a voice note (the
+   * backend defaults it to `true` on the conversion).
+   */
   isPtt?: boolean
+  /** Sends the file as a document, keeping its original format (audio is not converted). */
+  sendAsDocument?: boolean
+  /** Template parameters of a WhatsApp Business HSM. */
+  parameters?: unknown
+  /** Header media of a WhatsApp Business HSM. */
+  fileTemplate?: MessageFileInput
+  /** Contact card sent by a WhatsApp Business connection. Other connections use `sendVcards`. */
+  vcard?: unknown
+  /** Actions shown by the webchat widget. */
+  actions?: unknown
   subject?: string
   ccs?: unknown[]
 }

package/src/apis/payloads.test-d.ts

@@ -13,6 +13,7 @@ import type {
   CampaignContactsPage,
   CampaignMessage,
   CampaignStats,
+  CampaignTemplateParameter,
   CampaignTimelineEvent,
 } from './campaigns/types'
 import { CardsApi } from './cards/CardsApi'
@@ -36,7 +37,7 @@ import { QuestionsApi } from './questions/QuestionsApi'
 import { QuickRepliesApi } from './quickReplies/QuickRepliesApi'
 import { RolesApi } from './roles/RolesApi'
 import { ScheduleApi } from './schedule/ScheduleApi'
-import type { ScheduleRecord } from './schedule/types'
+import type { Schedule, ScheduleRecord } from './schedule/types'
 import type {
   CreateServicePayload,
   Service,
@@ -48,6 +49,7 @@ import { TicketTopicsApi } from './ticketTopics/TicketTopicsApi'
 import { TicketsApi } from './tickets/TicketsApi'
 import type { Ticket, TicketTransfer, TicketsCount, TicketsCounts } from './tickets/types'
 import { TimetableApi } from './timetable/TimetableApi'
+import type { OutOfOfficeHoursErrorExtra, TimetableWorkSlot } from './timetable/types'
 import { UsersApi } from './users/UsersApi'
 
 import { AcceptanceTermsApi } from './acceptanceTerms/AcceptanceTermsApi'
@@ -59,12 +61,14 @@ import type {
   CustomFieldValue,
   FormattedCustomField,
   SummarizeTicketResult,
+  TransferTicketKanbanCardResult,
+  TransferTicketPayload,
 } from './contacts/types'
 import { AuthHistoryApi } from './authHistory/AuthHistoryApi'
 import type { AuthHistoryEvent } from './authHistory/types'
 import { CustomFieldsApi } from './customFields/CustomFieldsApi'
 import { DepartmentsApi } from './departments/DepartmentsApi'
-import type { Department } from './departments/types'
+import type { ArchiveDepartmentErrorExtra, Department } from './departments/types'
 import type { Distribution } from './distribution/types'
 import type { ContactBlockList } from './contactBlockLists/types'
 import { DistributionApi } from './distribution/DistributionApi'
@@ -93,8 +97,11 @@ import type { Sticker } from './stickers/types'
 import { OrganizationsApi } from './organizations/OrganizationsApi'
 import { PeopleApi } from './people/PeopleApi'
 import { ServicesApi } from './services/ServicesApi'
-import type { UpdateUserPayload, User } from './users/types'
+import type { BulkUpdateUsersLinksResult, UpdateUserPayload, User } from './users/types'
 import { WebhooksApi } from './webhooks/WebhooksApi'
+import type { KanbanColumn } from './kanbanColumns/types'
+import type { CreateMessagePayload, Message } from './messages/types'
+import type { Webhook, WebhookMessageFilters, WebhookType } from './webhooks/types'
 
 declare const client: ApiClient
 
@@ -313,7 +320,7 @@ expectError(pipelines.deleteStatus('st-1', { action: 'move-to-another' }))
 expectError(pipelines.createAutomation({ pipelineId: 'p-1', type: 'email' }))
 expectError(pipelines.deleteStage('s-1', { typeAction: 'archive' }))
 
-// ── cards: getCards is not scoped by the backend and only answers the attributes asked ─
+// ── cards: getCards takes where.accountId and only answers the attributes asked ─
 
 const cards = new CardsApi(client)
 cards.getCards({
@@ -684,6 +691,17 @@ expectType<Promise<Department>>(
 )
 expectError(new DepartmentsApi(client).archiveWithValidation('d-1', {}))
 new MessagesApi(client).updateById('m-1', { text: 'x', contactId: 'c-1', mentionedList: ['5511'] })
+expectAssignable<CreateMessagePayload>({
+  contactId: 'c-1',
+  file: { base64: 'AAAA', mimetype: 'audio/mpeg', name: 'a.mp3' },
+  isPtt: false,
+  sendAsDocument: true,
+})
+expectAssignable<CreateMessagePayload>({
+  contactId: 'c-1',
+  attachments: [{ base64: 'AAAA', mimetype: 'application/pdf', name: 'a.pdf' }],
+})
+expectNotAssignable<CreateMessagePayload>({ attachments: [{ base64: 'AAAA' }] })
 expectAssignable<UpdateUserPayload>({ restrictedServices: [{ value: 's-1' }], password: 'x' })
 expectNotAssignable<UpdateUserPayload>({ restrictedServices: ['s-1'] })
 
@@ -807,3 +825,198 @@ expectType<Promise<string>>(new FilesApi(client).duplicateFile({ fileId: 'file-1
 expectError(new FilesApi(client).duplicateFile({ urlToUpload: 'https://storage' }))
 expectType<Promise<void>>(new AuthHistoryApi(client).registerLogout())
 expectAssignable<AuthHistoryEvent>('2fa_disabled')
+
+// ── QARC-948 (4.16.0): the open subtasks ─────────────────────────────
+
+// campaigns: one page of one campaign, and the fields the create reads
+expectType<Promise<Campaign | null>>(new CampaignsApi(client).getOne({ status: 'ready' }))
+expectAssignable<Parameters<CampaignsApi['create']>[0]>({
+  title: 'Campanha',
+  serviceId: 's-1',
+  text: 'Olá',
+  messages: [{ text: 'Olá', base64Url: 'data:image/png;base64,AAAA' }],
+  fileId: 'f-1',
+  nameField: 'Nome',
+  numberField: 'Número',
+  usernameField: 'Usuário',
+  hsmFileId: 'f-2',
+})
+
+// campaigns: the update reads its own fields and updates the messages by id
+expectAssignable<Parameters<CampaignsApi['updateById']>[1]>({
+  title: 'Campanha',
+  messages: [{ id: 'm-1', text: 'Olá' }, { text: 'Nova' }],
+})
+expectAssignable<Parameters<CampaignsApi['updateById']>[1]>({
+  config: { minInterval: '1', maxInterval: '5' },
+  messages: [
+    { id: 'm-1', text: 'Olá', file: { id: 'f-1' } },
+    {
+      id: 'm-2',
+      base64Url: 'data:image/png;base64,AAAA',
+      fileName: 'b.png',
+    },
+  ],
+})
+expectError(new CampaignsApi(client).updateById('cmp-1', { text: 'Olá' }))
+expectError(new CampaignsApi(client).updateById('cmp-1', { usernameField: 'Usuário' }))
+expectError(new CampaignsApi(client).updateById('cmp-1', { hsmFileId: 'f-2' }))
+expectAssignable<CampaignTemplateParameter>({
+  type: 'header',
+  parameters: [{ type: 'image', image: { link: 'https://example.invalid/a.png' } }],
+})
+
+// messages: the edit flag of the connection
+declare const editedMessage: Message
+expectType<boolean | undefined>(editedMessage.data.edited)
+
+// schedule: the template parameters
+expectAssignable<Parameters<ScheduleApi['create']>[0]>({
+  scheduledAt: '2026-10-20T12:00:00.000Z',
+  contactId: 'c-1',
+  departmentId: 'd-1',
+  notes: '',
+  hsmId: 'h-1',
+  extraOptions: { parameters: [{ type: 'body', parameters: [{ type: 'text', text: 'Ana' }] }] },
+})
+expectError(
+  new ScheduleApi(client).create({
+    scheduledAt: '2026-10-20T12:00:00.000Z',
+    contactId: 'c-1',
+    departmentId: 'd-1',
+    notes: '',
+    extraOptions: { parameters: 'Ana' },
+  }),
+)
+
+declare const storedSchedule: Schedule
+expectType<CampaignTemplateParameter[] | undefined>(storedSchedule.extraOptions?.parameters)
+
+// kanban: deleting a column moving its cards
+expectType<Promise<KanbanColumn>>(
+  new KanbanColumnsApi(client).deleteMovingCards('col-1', { cardsDestinationColumnId: 'col-2' }),
+)
+expectError(new KanbanColumnsApi(client).deleteMovingCards('col-1', {}))
+expectType<Promise<KanbanColumn>>(new KanbanColumnsApi(client).deleteById('col-1'))
+
+// contacts: the result of the transfer and the close of the ticket
+const ticketContacts = new ContactsApi(client)
+expectType<Promise<TransferTicketKanbanCardResult>>(
+  ticketContacts.transferTicket('c-1', { departmentId: 'd-1', includeKanbanCardId: true }),
+)
+expectType<Promise<true>>(ticketContacts.transferTicket('c-1', { departmentId: 'd-1' }))
+declare const transferPayload: TransferTicketPayload
+expectType<Promise<true | TransferTicketKanbanCardResult>>(
+  ticketContacts.transferTicket('c-1', transferPayload),
+)
+declare const transferResult: TransferTicketKanbanCardResult
+expectType<string | null>(transferResult.kanbanCardId)
+expectType<Promise<true>>(ticketContacts.closeTicket('c-1'))
+expectType<Promise<true>>(
+  ticketContacts.closeTicket('c-1', { ticketTopicIds: ['tt-1'], aiSummaryRating: '5' }),
+)
+expectError(ticketContacts.closeTicket('c-1', { aiSummaryRating: '6' }))
+
+// webhooks: the type, the connections and the message filters
+declare const webhook: Webhook
+expectType<WebhookType>(webhook.type)
+expectType<WebhookMessageFilters | null | undefined>(webhook.messageFilters)
+expectType<number | null | undefined>(webhook.avgLatencyMs)
+expectAssignable<Parameters<WebhooksApi['create']>[0]>({
+  name: 'Webhook',
+  url: 'https://example.invalid/hook',
+  type: 'by_service',
+  events: ['message.created'],
+  services: ['s-1'],
+  messageFilters: { bot: false, system: false },
+})
+expectAssignable<Parameters<WebhooksApi['create']>[0]>({
+  name: 'Webhook',
+  url: 'https://example.invalid/hook',
+  type: 'general',
+  events: ['message.created'],
+  messageFilters: null,
+})
+expectError(
+  new WebhooksApi(client).create({
+    name: 'Webhook',
+    url: 'https://example.invalid/hook',
+    type: 'other',
+    events: [],
+  }),
+)
+expectError(
+  new WebhooksApi(client).create({
+    name: 'Webhook',
+    url: 'https://example.invalid/hook',
+    type: 'general',
+    events: [],
+    messageFilters: { comments: false },
+  }),
+)
+expectError(new WebhooksApi(client).updateById('w-1', { active: false }))
+const hookUrl = 'https://example.invalid/hook'
+const hooks = new WebhooksApi(client)
+expectError(hooks.updateById('w-1', { url: hookUrl, type: 'general', events: [] }))
+expectError(hooks.updateById('w-1', { name: 'Webhook', type: 'general', events: [] }))
+expectError(hooks.updateById('w-1', { name: 'Webhook', url: hookUrl, events: [] }))
+expectError(hooks.updateById('w-1', { name: 'Webhook', url: hookUrl, type: 'general' }))
+expectError(hooks.updateById('w-1', { name: 'Webhook', url: hookUrl, type: 'other', events: [] }))
+expectAssignable<WebhookType>('whatsapp_low_level')
+expectAssignable<WebhookMessageFilters>({ received: true, sent: false, bot: true, system: false })
+expectAssignable<Parameters<WebhooksApi['updateById']>[1]>({
+  name: 'Webhook',
+  url: 'https://example.invalid/hook',
+  type: 'by_service',
+  events: ['message.created'],
+  services: ['s-1'],
+  messageFilters: { received: false },
+})
+expectAssignable<Parameters<WebhooksApi['updateById']>[1]>({
+  name: 'Webhook',
+  url: 'https://example.invalid/hook',
+  type: 'general',
+  events: ['message.created'],
+  messageFilters: null,
+})
+
+// users, bots and answers
+expectType<Promise<BulkUpdateUsersLinksResult>>(
+  new UsersApi(client).bulkUpdateLinks({ ids: ['u-1'], timetableId: null }),
+)
+expectError(new UsersApi(client).bulkUpdateLinks({ timetableId: 't-1' }))
+expectType<Promise<ArrayBuffer>>(new BotsApi(client).exportErrors('b-1'))
+expectType<Promise<Response>>(new AnswersApi(client).exportTxtRaw())
+expectType<Promise<Response>>(new AnswersApi(client).exportCsvRaw())
+
+// QARC-948, second review: the remaining fields of the new types
+expectAssignable<CampaignTemplateParameter>({
+  type: 'header',
+  parameters: [
+    { type: 'video', video: { link: 'https://example.invalid/a.mp4' } },
+    { type: 'document', document: { link: 'https://example.invalid/a.pdf' } },
+  ],
+})
+expectAssignable<Parameters<ContactsApi['closeTicket']>[1]>({ comments: 'Resolvido' })
+expectAssignable<TransferTicketPayload>({ departmentId: 'd-1', includeKanbanCardId: true })
+expectError(
+  new ScheduleApi(client).updateById('sch-1', {
+    scheduledAt: '2026-10-20T12:00:00.000Z',
+    contactId: 'c-1',
+    departmentId: 'd-1',
+    extraOptions: { parameters: 'Ana' },
+  }),
+)
+expectAssignable<Parameters<UsersApi['bulkUpdateLinks']>[0]>({
+  ids: ['u-1'],
+  departmentIds: ['d-1'],
+  roleIds: ['r-1'],
+})
+declare const linksResult: BulkUpdateUsersLinksResult
+expectType<number>(linksResult.failed)
+expectType<string[]>(linksResult.missingIds)
+declare const outOfOffice: OutOfOfficeHoursErrorExtra
+expectType<TimetableWorkSlot[]>(outOfOffice.workPlan)
+declare const archiveRefusal: ArchiveDepartmentErrorExtra
+expectAssignable<ArchiveDepartmentErrorExtra['reasons'][number]>('ONLY_ONE')
+expectType<number | undefined>(archiveRefusal.openTicketsCount)

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'