@ikatec/digisac-api-sdk 4.15.0 → 4.17.0

package/src/apis/campaigns/types.ts

@@ -34,6 +34,8 @@ export type CampaignConfig = {
   nameField?: string
   /** Column name in the import file used as the phone number. */
   numberField?: string
+  /** Column name in the import file used as the username (contacts known only by it). */
+  usernameField?: string
   delimiter?: ',' | ';' | ':' | string
   error?: {
     message: string
@@ -65,7 +67,10 @@ export type Campaign = {
   marketingIntegration?: boolean
   /** Always `null`: the campaign has no such column (answered by the transformer). */
   userId?: null
-  /** Only in `getMany`: messages sent and viewed (ack 3). */
+  /**
+   * In the pages of `getMany` (not with `paginate: false`) and in `getOne`: messages sent and
+   * viewed (ack 3).
+   */
   stats?: { sent: number; viewed: number }
   accountId: string
   serviceId: string
@@ -116,9 +121,21 @@ export type CampaignRelationships =
   | 'messages'
   | 'importFile'
 
+/** The media of a header parameter of the template (send it as `{ link: '<url>' }`). */
+export type CampaignTemplateMedia = {
+  link?: string
+}
+
+/**
+ * A parameter of the template: `text`, or the media of its `type` (`image`, `video` or
+ * `document`).
+ */
 export type CampaignTemplateParameterItem = {
   type: string
   text?: string
+  image?: CampaignTemplateMedia
+  video?: CampaignTemplateMedia
+  document?: CampaignTemplateMedia
 }
 
 export type CampaignTemplateParameter = {
@@ -135,30 +152,111 @@ export type CampaignFileTemplate = {
   name?: string
 }
 
+/** A message of the campaign to create (without `hsm`, the campaign sends these). */
+export type CampaignMessageInput = {
+  text?: string
+  /** The attachment of the message, as a data URL (`data:<mimetype>;base64,<content>`). */
+  base64Url?: string
+  /** @deprecated Ignored by the backend: send the attachment as `base64Url`. */
+  fileId?: string
+}
+
 export type CreateCampaignPayload = {
   title: string
   serviceId: string
   config?: { minInterval: number | string; maxInterval: number | string }
   tagIds?: string[]
-  messages?: { text?: string; fileId?: string }[]
+  messages?: CampaignMessageInput[]
+  /** On create, replaces the `text` of every message (and is the text of the template message). */
+  text?: string
   isScheduled?: boolean
   sendsAt?: string | null
   mustOpenTicket?: boolean
   defaultDepartmentId?: string | null
   defaultUserId?: string | null
+  /** @deprecated Ignored by the backend: the contacts come from `tagIds` or the import `fileId`. */
   contacts?: Record<string, string>[]
+  /** @deprecated Ignored by the backend: the contacts come from `tagIds` or the import `fileId`. */
   useTags?: boolean
+  /**
+   * On create, the import file (CSV) of the contacts, uploaded with
+   * `attachedType: 'campaign.file'`. The columns are read by `nameField`, `numberField` and
+   * `usernameField`.
+   */
   fileId?: string
+  /** On create, stored in `config.nameField` (a `config.nameField` sent here is replaced). */
   nameField?: string
+  /** On create, stored in `config.numberField` (a `config.numberField` sent here is replaced). */
   numberField?: string
+  /** Stored in `config.usernameField` (a `config.usernameField` sent here is replaced). */
+  usernameField?: string
   // whatsapp-business specific
+  /**
+   * The template to send. On create, the campaign gets one message of it and `messages` is not
+   * read.
+   */
   hsm?: WhatsappBusinessTemplate
   parameters?: CampaignTemplateParameter[]
+  /**
+   * The header file of the template message (only with `hsm`), already uploaded. Takes precedence
+   * over `fileTemplate`.
+   */
+  hsmFileId?: string
+  /**
+   * The header media of the template message: `base64Url` as a data URL, with its `mimetype`
+   * (required on create) and `name`. On create, read only when `tagIds` is sent (an empty array is
+   * enough); with the import `fileId`, prefer `hsmFileId`. On update, it only replaces the header
+   * file the template message already has: send it only with a new data URL, and leave it out to
+   * keep the header.
+   */
   fileTemplate?: CampaignFileTemplate
   marketingIntegration?: boolean
 }
 
-export type UpdateCampaignPayload = Partial<CreateCampaignPayload>
+/**
+ * A message of `updateById`. With the `id` of an existing message, the message gets the `text`
+ * sent; without `id`, it is created (and `base64Url` is read as in the create).
+ */
+export type UpdateCampaignMessageInput = CampaignMessageInput & {
+  id?: string
+  /**
+   * On WhatsApp connections, keeps the attachment of an existing message (send the `file` of the
+   * message read); with `file`, `base64Url` is not read. Without `file` and `base64Url`, the
+   * attachment is removed.
+   */
+  file?: unknown
+  /**
+   * On WhatsApp connections, the name of the new attachment in `base64Url`: to replace the
+   * attachment of an existing message, send `base64Url` with a new name and without `file`.
+   */
+  fileName?: string
+}
+
+/**
+ * `updateById` (`PUT`). A non-empty `messages` replaces the messages: the ones with the `id` of an
+ * existing message update it, the ones without `id` are created and the existing ones left out are
+ * deleted (omitted, or `[]`, keeps them).
+ *
+ * Send `isScheduled` (with `sendsAt`) and `mustOpenTicket` (with `defaultDepartmentId` and
+ * `defaultUserId`) on every call: without `isScheduled: true`, `sendsAt` is stored as `null` and a
+ * scheduled campaign is no longer started at the date; without `mustOpenTicket: true`, the default
+ * department and user are cleared.
+ *
+ * On WhatsApp Business connections, send the existing message by its `id` (a message without `id`
+ * is created without the template), together with `hsm` and `parameters`: every update that sends
+ * `messages` or `hsm` rewrites both on the existing messages (a missing one is stored empty).
+ */
+export type UpdateCampaignPayload = Omit<
+  Partial<CreateCampaignPayload>,
+  'text' | 'usernameField' | 'hsmFileId' | 'messages' | 'config'
+> & {
+  /**
+   * Replaces the stored config as a whole. `minInterval` and `maxInterval` go as strings (a number
+   * answers 400).
+   */
+  config?: { minInterval: number | string; maxInterval: number | string }
+  messages?: UpdateCampaignMessageInput[]
+}
 
 /** The visible states the `status` filter of `getMany` takes (`'scheduled'` is derived from `isScheduled` + `sendsAt`). */
 export type CampaignListStatus = CampaignStatus | 'scheduled'

package/src/apis/cards/types.ts

@@ -182,8 +182,8 @@ export type BulkMoveCardsPayload = {
 export type BulkMoveCardsResult = { movedCount: number; ignoredCount: number }
 
 /**
- * Creates a product of a card, or updates the product of `id`. No validation on the backend:
- * a missing `name`/`ammount`/`value` fails with 500.
+ * Creates a product of a card, or updates the product of `id`. `name`, `ammount` and `value` are
+ * required (a missing one answers 500).
  */
 export type SaveCardProductPayload = {
   id?: string
@@ -218,9 +218,9 @@ export type CardOwner = {
 }
 
 /**
- * Body of `POST /cards/getCards`: Sequelize options sent as-is. The route does **not** scope the
- * query by account — without `where.accountId` it answers cards of other accounts. `order`
- * accepts card fields and `contact.name`.
+ * Body of `POST /cards/getCards`: a list query of the cards. Send `where.accountId` with the id of
+ * the current account (`accountId` of `MeApi.getMe`). `order` accepts card fields and
+ * `contact.name`.
  */
 export type GetCardsPayload = Omit<
   ListQuery<Card>,

package/src/apis/categories/CategoriesApi.ts

@@ -15,8 +15,7 @@ export class CategoriesApi extends BaseCrudApi<
   }
 
   /**
-   * Deletes a category. Resolves the text `'OK'`; an unknown id answers 500. The route checks no
-   * permission.
+   * Deletes a category. Resolves the text `'OK'`; an unknown id answers 500.
    */
   override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
     return super.deleteById(id, headers)

package/src/apis/clientFeedback/ClientFeedbackApi.ts

@@ -9,9 +9,8 @@ export class ClientFeedbackApi
   private readonly basePath = '/client-feedback'
 
   /**
-   * @deprecated The route is broken in the backend: it is mounted with no authentication (the
-   * account context throws, 500) and calls a `createFeedback` the resource does not have. The
-   * feedback on the AI summary is stored when the ticket is closed.
+   * @deprecated The route is not available (it answers 500). Send the rating of the AI summary
+   * when closing the ticket: `ContactsApi.closeTicket` with `aiSummaryRating`.
    */
   create(
     body: CreateClientFeedbackPayload,

package/src/apis/contacts/ContactsApi.test.ts

@@ -365,14 +365,26 @@ describe('ContactsApi', () => {
 
   describe('transferTicket', () => {
     it('calls client.post with /contacts/:id/ticket/transfer and payload', async () => {
-      vi.mocked(client.post).mockResolvedValue({ ok: true })
+      vi.mocked(client.post).mockResolvedValue(true)
       const result = await api.transferTicket('c1', { departmentId: 'd1' })
       expect(client.post).toHaveBeenCalledWith(
         '/contacts/c1/ticket/transfer',
         { departmentId: 'd1' },
         undefined,
       )
-      expect(result).toEqual({ ok: true })
+      expect(result).toBe(true)
+    })
+
+    it('sends includeKanbanCardId and resolves the id of the card', async () => {
+      vi.mocked(client.post).mockResolvedValue({ kanbanCardId: 'kc1' })
+      const payload = {
+        departmentId: 'd1',
+        kanbanCardColumnId: 'col1',
+        includeKanbanCardId: true,
+      } as const
+      const result = await api.transferTicket('c1', payload)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/transfer', payload, undefined)
+      expect(result.kanbanCardId).toBe('kc1')
     })
 
     it('includes optional userId and forwards custom headers', async () => {
@@ -387,6 +399,28 @@ describe('ContactsApi', () => {
     })
   })
 
+  // ── closeTicket ──────────────────────────────────────────────────
+
+  describe('closeTicket', () => {
+    it('calls client.post with /contacts/:id/ticket/close and an empty body by default', async () => {
+      vi.mocked(client.post).mockResolvedValue(true)
+      expect(await api.closeTicket('c1')).toBe(true)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/close', {}, undefined)
+    })
+
+    it('sends the subjects, the comment and the rating of the AI summary', async () => {
+      vi.mocked(client.post).mockResolvedValue(true)
+      const headers = { 'X-Custom': 'h' }
+      const payload = {
+        ticketTopicIds: ['tt1'],
+        comments: 'Resolvido',
+        aiSummaryRating: '5' as const,
+      }
+      await api.closeTicket('c1', payload, headers)
+      expect(client.post).toHaveBeenCalledWith('/contacts/c1/ticket/close', payload, headers)
+    })
+  })
+
   // ── createMany ───────────────────────────────────────────────────
 
   describe('createMany', () => {

package/src/apis/contacts/ContactsApi.ts

@@ -6,6 +6,7 @@ import type {
   BlockContactPayload,
   BulkTransferTicketsPayload,
   BulkTransferTicketsResult,
+  CloseTicketPayload,
   Contact,
   ContactGetByIdQuery,
   ContactListQuery,
@@ -21,6 +22,7 @@ import type {
   ExportTemplatePayload,
   ImportContactsPayload,
   SyncContactPayload,
+  TransferTicketKanbanCardResult,
   TransferTicketPayload,
   UpdateContactPayload,
   SummarizeTicketResult,
@@ -141,20 +143,56 @@ export class ContactsApi extends BaseCrudApi<
   /**
    * Opens (or transfers) the contact's ticket to a department, and optionally a user.
    * This is the real ticket-open flow used by the UI — there is no `POST /tickets`.
+   * Resolves `true`, or `{ kanbanCardId }` with `includeKanbanCardId: true`. When the current
+   * ticket of the contact is already closed, the call only releases it and opens nothing: call it
+   * again to open a ticket.
    * @permissions tickets.transfer.all OR tickets.transfer.me
    */
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload & { includeKanbanCardId: true },
+    headers?: Record<string, string>,
+  ): Promise<TransferTicketKanbanCardResult>
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload & { includeKanbanCardId?: false },
+    headers?: Record<string, string>,
+  ): Promise<true>
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload,
+    headers?: Record<string, string>,
+  ): Promise<true | TransferTicketKanbanCardResult>
   transferTicket(
     contactId: string,
     payload: TransferTicketPayload,
     headers?: Record<string, string>,
-  ): Promise<unknown> {
-    return this.client.post<unknown, TransferTicketPayload>(
+  ): Promise<true | TransferTicketKanbanCardResult> {
+    return this.client.post<true | TransferTicketKanbanCardResult, TransferTicketPayload>(
       `${this.basePath}/${contactId}/ticket/transfer`,
       payload,
       headers,
     )
   }
 
+  /**
+   * Closes the open ticket of the contact and resolves `true`. A contact without an open ticket
+   * answers 500, or `true` (closing nothing) when its current ticket is already closed. An unknown
+   * subject in `ticketTopicIds`, or one of another department, answers 400.
+   * @permissions tickets.close.me OR tickets.close.all
+   */
+  closeTicket(
+    contactId: string,
+    payload: CloseTicketPayload = {},
+    headers?: Record<string, string>,
+  ): Promise<true> {
+    return this.client.post<true, CloseTicketPayload>(
+      `${this.basePath}/${contactId}/ticket/close`,
+      payload,
+      headers,
+    )
+  }
+
   /**
    * Creates or updates several contacts in one call. Existing contacts (same service and
    * number or e-mail) are updated; the others are created. Returns the resulting contacts.
@@ -226,7 +264,7 @@ export class ContactsApi extends BaseCrudApi<
   /**
    * Blocks or unblocks a contact. Blocking closes the contact's open ticket. Requires the
    * block list to be active on the account (`settings.isBlockListActive`; 400 otherwise).
-   * `byUserId` and `description` are stored as sent: the backend does not fill in the user.
+   * Send `byUserId` with the logged user (`id` of `MeApi.getMe`), as the web app does.
    * @permissions contacts.block
    */
   block(id: string, body: BlockContactPayload, headers?: Record<string, string>): Promise<Contact> {

package/src/apis/contacts/types.ts

@@ -291,6 +291,34 @@ export type TransferTicketPayload = {
   kanbanCardColumnId?: string
   kanbanCardSubject?: string
   initialMessage?: string
+  /** `true` (the boolean) resolves the id of the kanban card instead of `true`. */
+  includeKanbanCardId?: boolean
+}
+
+/** What `ContactsApi.transferTicket` resolves to with `includeKanbanCardId: true`. */
+export type TransferTicketKanbanCardResult = {
+  /**
+   * The kanban card of the ticket (created, or the contact's card moved, in `kanbanCardColumnId`);
+   * `null` without `kanbanCardColumnId` (even when the ticket gets a card in the initial column of
+   * the board: send `kanbanCardColumnId` to read its id), when the department has no board, or when
+   * the call only released a closed ticket.
+   */
+  kanbanCardId: string | null
+}
+
+/** The rating of the AI summary of the ticket. */
+export type AiSummaryRating = '1' | '2' | '3' | '4' | '5'
+
+export type CloseTicketPayload = {
+  /**
+   * Subjects of the ticket: of its department, or linked to no department. An unknown subject, or
+   * one of another department, answers 400.
+   */
+  ticketTopicIds?: string[]
+  /** The closing comment. */
+  comments?: string
+  /** Stored as the feedback of the AI summary of the ticket. */
+  aiSummaryRating?: AiSummaryRating
 }
 
 /**

package/src/apis/creditMovements/CreditMovementsApi.test.ts

@@ -83,6 +83,6 @@ describe('CreditMovementsApi', () => {
     const withoutRaw: ApiClient = { ...client, requestRaw: undefined }
     await expect(
       new CreditMovementsApi(withoutRaw).exportXlsx({ from: 'a', to: 'b', where: { $and: [] } }),
-    ).rejects.toThrow('requestRaw')
+    ).rejects.toThrow('exportXlsx needs a client with requestRaw')
   })
 })

package/src/apis/customFields/types.ts

@@ -22,10 +22,10 @@ export type CustomFieldOption = {
 }
 
 /**
- * Settings of a custom field — a free JSONB the backend does not validate, echoed back as sent.
- * The fields below are the ones the web app form sends (`front/src/pages/custom-fields/components/
- * form.tsx`): `options` for the `list` and `checkbox` types, `min`/`max` for `numeric` and `monetary`,
- * `currency` for `monetary`, `maxLength` for `text` and `long-text`, and `placeholder` for the inputs.
+ * Settings of a custom field (a free JSON object, answered as stored). The fields below are the
+ * ones the web app form sends: `options` for the `list` and `checkbox` types, `min`/`max` for
+ * `numeric` and `monetary`, `currency` for `monetary`, `maxLength` for `text` and `long-text`, and
+ * `placeholder` for the inputs.
  */
 export type CustomFieldSettings = {
   options?: CustomFieldOption[]

package/src/apis/dashboard/DashboardApi.test-d.ts

@@ -47,3 +47,12 @@ expectType<Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>
 expectError(dashboard.getByPeriod({ grouping: 'quarterly' }))
 expectError(dashboard.getByTopic({ withTotals: true }))
 expectError(dashboard.getByService({ withTotals: true }))
+
+// ── one connection, tag and subject (not a list) ────────────────────
+
+expectType<Promise<DashboardPeriodItem[]>>(
+  dashboard.getByPeriod({ serviceId: 's-1', tagId: 't-1', ticketTopicId: 'tt-1' }),
+)
+expectError(dashboard.getByPeriod({ serviceId: ['s-1', 's-2'] }))
+expectError(dashboard.getByPeriod({ tagId: ['t-1'] }))
+expectError(dashboard.getByPeriod({ ticketTopicId: ['tt-1'] }))

package/src/apis/dashboard/DashboardApi.ts

@@ -12,9 +12,9 @@ import type {
 } from './types'
 
 /**
- * Service statistics ("Estatísticas de atendimento"). The `/dashboard` routes only require an
- * authenticated user (no permission check). Every route takes the same {@link DashboardQuery}
- * filters; the grouped routes answer one item per day, user, department, topic or connection.
+ * Service statistics ("Estatísticas de atendimento"). Every route takes the same
+ * {@link DashboardQuery} filters; the grouped routes answer one item per day, user, department,
+ * topic or connection.
  */
 export class DashboardApi extends BaseApi {
   public readonly basePath = '/dashboard'

package/src/apis/dashboard/types.ts

@@ -14,7 +14,11 @@ export type DashboardQuery = {
   startPeriod?: string
   /** ISO date-time. Default: the end of the `startPeriod` day (or of today). */
   endPeriod?: string
-  /** Which ticket date the period filters: opening (default) or closing. */
+  /**
+   * Which ticket date the period filters: opening (`openDate`, the default) or closing. Sent
+   * without it, together with `status: 'all'`, the period is not applied. `getByPeriod` needs it:
+   * always send it there (the `openDate` default does not apply to that route).
+   */
   periodType?: 'openDate' | 'closeDate'
   /** Ticket status (`closed`, not `close`). */
   status?: 'all' | 'open' | 'closed'
@@ -39,9 +43,12 @@ export type DashboardQuery = {
    */
   userParticipation?: 'last' | 'middle'
   userStatus?: 'active' | 'archived' | 'all'
-  serviceId?: string | string[]
-  tagId?: string | string[]
-  ticketTopicId?: string | string[]
+  /** One connection id (unlike `departmentId` and `userId`, not a list). */
+  serviceId?: string
+  /** One tag id (not a list). */
+  tagId?: string
+  /** One ticket subject id (not a list). */
+  ticketTopicId?: string
   /**
    * Granularity of the `getByPeriod` items (the other routes ignore it). Default: `daily`. See
    * {@link DashboardGrouping} for the `name` of the items.

package/src/apis/departments/DepartmentsApi.ts

@@ -21,11 +21,11 @@ export class DepartmentsApi extends ArchivableCrudApi<
 
   /**
    * Archives (`archive: true`) or restores (`archive: false`) a department through the route used
-   * by the UI, which enforces what {@link archive}/{@link unarchive} (a plain `PUT { archivedAt }`)
-   * skip: archiving refuses (403 `Cannot archive department.`, with the reasons and the open
-   * tickets count) a department in use, and clears it as the default department of contacts and
-   * connections, marks its schedules as done and unlinks its users and quick replies. Resolves the
-   * stored department (not transformed); an unknown id answers 500.
+   * by the UI: archiving refuses (403 `Cannot archive department.`) a department in use, or when it
+   * is the only active department of the account (the `extra` of the error is an
+   * `ArchiveDepartmentErrorExtra`). Archiving also clears it as the default department of contacts
+   * and connections, marks its schedules as done and unlinks its users and quick replies. Resolves
+   * the stored department (not transformed); an unknown id answers 500.
    * @permissions departments.view OR departments.archive
    */
   archiveWithValidation(

package/src/apis/departments/types.ts

@@ -32,3 +32,16 @@ export type ArchiveDepartmentPayload = {
   /** `true` archives, `false` restores. */
   archive: boolean
 }
+
+/** The `extra` of the 403 `Cannot archive department.` error of `archiveWithValidation`. */
+export type ArchiveDepartmentErrorExtra = {
+  reasons: (
+    | 'ONLY_ONE'
+    | 'USED_BOT'
+    | 'DEFAULT_DEPARTMENT'
+    | 'VISIBILITY_SETTINGS'
+    | 'OPEN_TICKETS'
+  )[]
+  /** Only with open tickets. */
+  openTicketsCount?: number
+}

package/src/apis/distribution/DistributionApi.ts

@@ -34,10 +34,9 @@ export class DistributionApi extends BaseCrudApi<
   }
 
   /**
-   * Updates a distribution. The backend reads the id from the body, so it is sent there too. It replaces
-   * the links: omitting `roles` or `departments` clears them. Resolves the stored distribution (with
-   * `deletedAt`, without the links) or, when `departments` is sent, the updated departments. An unknown id
-   * answers 500.
+   * Updates a distribution. It replaces the links: omitting `roles` or `departments` clears them.
+   * Resolves the stored distribution (with `deletedAt`, without the links) or, when `departments`
+   * is sent, the updated departments. An unknown id answers 500.
    * @permissions distribution.view OR distribution.update
    */
   override updateById(

package/src/apis/kanbanCards/KanbanCardsApi.test.ts

@@ -43,4 +43,25 @@ describe('KanbanCardsApi', () => {
       await expect(api.reorder('kc1', {})).rejects.toThrow('Invalid reorder operation.')
     })
   })
+
+  describe('getById / create / updateById', () => {
+    it('keep the generic routes of /kanban-cards', async () => {
+      vi.mocked(client.get).mockResolvedValue({ id: 'kc1' })
+      vi.mocked(client.post).mockResolvedValue({ id: 'kc1' })
+      vi.mocked(client.put).mockResolvedValue({ id: 'kc1' })
+      await api.getById('kc1', { attributes: ['id'] }, headers)
+      await api.create({ columnId: 'col1', ticketId: 't1' }, headers)
+      await api.updateById('kc1', { columnId: 'col2' }, headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/kanban-cards/kc1?query=${encodeURIComponent(JSON.stringify({ attributes: ['id'] }))}`,
+        headers,
+      )
+      expect(client.post).toHaveBeenCalledWith(
+        '/kanban-cards',
+        { columnId: 'col1', ticketId: 't1' },
+        headers,
+      )
+      expect(client.put).toHaveBeenCalledWith('/kanban-cards/kc1', { columnId: 'col2' }, headers)
+    })
+  })
 })

package/src/apis/kanbanCards/KanbanCardsApi.ts

@@ -1,5 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
-import type { ListQuery } from '../../core/types'
+import type { GetByIdQuery, ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type {
   KanbanCard,
@@ -8,6 +8,13 @@ import type {
   UpdateKanbanCardPayload,
 } from './types'
 
+/**
+ * Cards of the kanban boards: one per ticket in each board. The reads need `kanban.boards.view`
+ * and the writes `kanban.cards.move`. `getMany` takes the column in `where.columnId`. The errors of
+ * the writes (unknown column or ticket, ticket of a department not linked to the board, a second
+ * card of the ticket in the board, an update by a user outside the department of the ticket)
+ * answer 500.
+ */
 export class KanbanCardsApi extends BaseCrudApi<
   KanbanCard,
   CreateKanbanCardPayload,
@@ -19,6 +26,45 @@ export class KanbanCardsApi extends BaseCrudApi<
     super(client, '/kanban-cards')
   }
 
+  /**
+   * Returns a card by ID. An unknown id answers 404 `Kanban card not found.`.
+   * @permissions kanban.boards.view
+   */
+  override getById(
+    id: string,
+    query?: GetByIdQuery<KanbanCard>,
+    headers?: Record<string, string>,
+  ): Promise<KanbanCard> {
+    return super.getById(id, query, headers)
+  }
+
+  /**
+   * Creates the card of a ticket in a column. The ticket must be of a department linked to the
+   * board and have no card in it yet.
+   * @permissions kanban.cards.move
+   */
+  override create(
+    body: CreateKanbanCardPayload,
+    headers?: Record<string, string>,
+  ): Promise<KanbanCard> {
+    return super.create(body, headers)
+  }
+
+  /**
+   * Updates a card. To move it, use {@link reorder}: `updateById` does not recalculate the
+   * `position` and does not close or reopen the ticket. The user must belong to the
+   * department of the card's ticket (of the new `ticketId` when sent), or have
+   * `tickets.transfer.all`, or be admin; otherwise 500.
+   * @permissions kanban.cards.move
+   */
+  override updateById(
+    id: string,
+    body: UpdateKanbanCardPayload,
+    headers?: Record<string, string>,
+  ): Promise<KanbanCard> {
+    return super.updateById(id, body, headers)
+  }
+
   /**
    * Deletes a card. Resolves the text `'OK'`.
    * @permissions kanban.cards.move

package/src/apis/kanbanCards/types.ts

@@ -27,7 +27,7 @@ export type CreateKanbanCardPayload = {
 export type UpdateKanbanCardPayload = {
   columnId?: string
   position?: string
-  /** The caller must share a department with the ticket (or transfer to all / be admin). */
+  /** Moves the card to another ticket (see `KanbanCardsApi.updateById` for who can update it). */
   ticketId?: string
 }
 

package/src/apis/kanbanColumns/KanbanColumnsApi.test.ts

@@ -43,4 +43,30 @@ describe('KanbanColumnsApi', () => {
       await expect(api.reorder('col1', {})).rejects.toThrow('Invalid reorder operation.')
     })
   })
+
+  describe('deleteById', () => {
+    it('calls client.delete with /kanban-columns/:id and resolves the deleted column', async () => {
+      vi.mocked(client.delete).mockResolvedValue({ id: 'col1' })
+      expect(await api.deleteById('col1', headers)).toEqual({ id: 'col1' })
+      expect(client.delete).toHaveBeenCalledWith('/kanban-columns/col1', headers)
+    })
+  })
+
+  describe('deleteMovingCards', () => {
+    it('sends DELETE /kanban-columns/:id with the destination column in the body', async () => {
+      vi.mocked(client.request).mockResolvedValue({ id: 'col1' })
+      const body = { cardsDestinationColumnId: 'col2' }
+      expect(await api.deleteMovingCards('col1', body, headers)).toEqual({ id: 'col1' })
+      expect(client.request).toHaveBeenCalledWith('DELETE', '/kanban-columns/col1', body, headers)
+    })
+
+    it('propagates errors', async () => {
+      vi.mocked(client.request).mockRejectedValue(
+        new Error('Initial and final columns cannot be deleted.'),
+      )
+      await expect(
+        api.deleteMovingCards('col1', { cardsDestinationColumnId: 'col2' }),
+      ).rejects.toThrow('Initial and final columns cannot be deleted.')
+    })
+  })
 })