@ikatec/digisac-api-sdk 4.5.1 → 4.6.0

package/src/apis/bots/types.ts

@@ -1,4 +1,5 @@
 import type { BotVersion } from '../botVersions/types'
+import type { Contact } from '../contacts/types'
 import type { Service } from '../services/types'
 
 // ─── Settings ─────────────────────────────────────────────────────────────────
@@ -35,6 +36,10 @@ export type BotEvent =
   | 'CONTACT_RECONNECTED'
   | 'API_SIGNAL'
   | 'ANONYMOUS_USER_CREATED_WEBCHAT'
+  /** Fired by the worker in `@EVERY` when the contact stops answering the bot. */
+  | 'BOT_INACTIVE'
+  /** Fired by the worker when an asynchronous `HTTP_REQUEST` action gets its callback. */
+  | 'HTTP_REQUEST_CALLBACK'
 
 export type BotFlowTriggerNode = {
   id: string
@@ -69,8 +74,19 @@ export type BotFlowEdge = {
   sourceHandle: string
 }
 
-/** Visual flow graph used by the flow builder UI. Gets compiled into `contexts` on save. */
+/** Visual flow graph used by the flow builder UI, as the API answers it. */
 export type BotFlowJson = {
+  nodes: BotFlowNode[]
+  /** Absent in a bot saved without a flow (`{ nodes: [] }`). */
+  edges?: BotFlowEdge[]
+}
+
+/**
+ * The flow graph to save. `edges` is required: a bot saved without it (or without `flowJson`)
+ * never sends a message — the worker fails reading `flowJson.edges` (SD-2323). Send at least
+ * `{ nodes: [], edges: [] }`.
+ */
+export type BotFlowJsonInput = {
   nodes: BotFlowNode[]
   edges: BotFlowEdge[]
 }
@@ -108,7 +124,7 @@ export type BotActionDataMap = {
     actions?: { title: string; value: string }[]
   }
   SEND_TERM: {
-    /** Acceptance term UUID. */
+    /** Acceptance term UUID (as stored); see `BotActionInput` for how to send it. */
     acceptanceTerms?: string
   }
   CONFIRM_TERM: {
@@ -170,14 +186,21 @@ export type BotActionDataMap = {
     maxAttempts?: number
     /** Actions to take based on AI agent outcomes. */
     actions?: { context?: string; action: { id: string; type: string } }[]
+    /** Knowledge base subject UUIDs the agent answers from. */
+    knowledgeBase?: string[]
+    /** Waits `waitSeconds` to group the contact's messages before answering. */
+    messageGrouping?: { enabled?: boolean; waitSeconds?: number }
   }
   HTTP_REQUEST: {
     requestName?: string
     endpointUrl?: string
     httpMethod?: 'get' | 'post' | 'put' | 'patch' | 'delete'
     isAsyncRequest?: boolean
+    /** Sends the Digisac payload (contact, ticket, message) along with the request. */
+    sendDigisacPayload?: boolean
     bodyType?: 'json' | 'xml' | 'formData' | 'empty'
-    headers?: { key: string; value: string }[]
+    /** A `secret` header comes back from the API with `value: null`. */
+    headers?: { key: string; value: string | null; secret?: boolean }[]
     requestBodyFormData?: { key: string; value: string }[]
     requestBodyJson?: string
     requestBodyXml?: string
@@ -248,40 +271,269 @@ export type BotContexts = {
   [contextId: string]: BotContext
 }
 
+// ─── Contexts as the /bots routes take and return them ───────────────────────
+//
+// `BotContexts` above is the stored form (a map by context id), served as is by `/bot-versions`
+// and `currentBotVersion`. The `/bots` routes take the contexts as a LIST instead and answer the
+// list again, with each trigger, variable, operator and action described by its option object.
+
+/** A variable, operator or action option as the bot builder describes it. */
+export type BotOption<TValue extends string = string> = { value: TValue; name?: string }
+
+export type BotConditionTarget =
+  | string
+  | number
+  | string[]
+  | { id: string }
+  | { id: string }[]
+  | { value: string }
+  | { value: string }[]
+  | { variableName: string; variableValue: string }
+
+/** A condition is dropped in silence when `variable`, `operator` or a truthy `target` is missing. */
+export type BotConditionInput = {
+  variable: BotOption
+  operator: BotOption
+  target: BotConditionTarget
+}
+
+export type BotConditionGroupInput = {
+  conditionType: 'and' | 'or'
+  conditions: BotConditionInput[]
+}
+
+/** Actions the API saves. `SET_VAR` runs in the worker, but saving it answers 500. */
+export type BotSavableActionType = Exclude<BotActionType, 'SET_VAR'>
+
+export type BotActionInput = {
+  [K in BotSavableActionType]: {
+    type: BotOption<K>
+    /** Related records go as their id, except the ones below. */
+    data: K extends 'SEND_MESSAGE'
+      ? Omit<BotActionDataMap['SEND_MESSAGE'], 'file'> & {
+          /**
+           * The file goes as an object: a bare id is dropped. `{ fileName, mimetype, base64Url }`
+           * uploads a new one.
+           */
+          file?: { id: string } | { fileName: string; mimetype: string; base64Url: string }
+        }
+      : K extends 'SEND_TERM'
+        ? {
+            /**
+             * Send the term as `{ id }`: the bot keeps it as `data.currentDefaultTerm`, and both
+             * the "term in use" check of `DELETE /acceptance-terms/:id` and the reset of the
+             * contacts' acceptance read its `id`. A bare id is saved, but those checks miss it.
+             */
+            acceptanceTerms?: { id: string } | string
+          }
+        : BotActionDataMap[K]
+  }
+}[BotSavableActionType]
+
+/**
+ * A `SEND_MESSAGE` without text, interactive or file is dropped, and so is a rule left with no
+ * action (except a `BOT_INACTIVE` rule with `data`).
+ */
+export type BotRuleInput = {
+  title?: string
+  actions: BotActionInput[]
+  fallbackActions?: BotActionInput[]
+  /** Required: a missing `conditions` answers 500. */
+  conditions: BotConditionInput[] | BotConditionGroupInput
+  data?: Record<string, unknown>
+}
+
+export type BotTriggerInput = {
+  trigger: { type: BotEvent }
+  rules: BotRuleInput[]
+}
+
+/** `@INIT`, `@EVERY` and `@FALLBACK` are the built-in contexts; other ids are user-defined. */
+export type BotContextInput = {
+  id: string
+  name?: string
+  triggers: BotTriggerInput[]
+}
+
+export type BotParsedCondition =
+  | {
+      /** `undefined` for a variable the builder does not list. */
+      variable?: BotOption & { type?: string; subType?: string }
+      operator?: BotOption
+      /** Departments and tags come back as their records. */
+      target: unknown
+    }
+  | { $and: BotParsedCondition[] }
+  | { $or: BotParsedCondition[] }
+
+export type BotParsedAction = {
+  type: { value: BotSavableActionType; name: string }
+  /** The ids of questions, terms, tags, departments, users etc. come back as their records. */
+  data: Record<string, unknown>
+}
+
+export type BotParsedRule = {
+  title: string
+  actions: BotParsedAction[]
+  fallbackActions: BotParsedAction[]
+  conditions: BotParsedCondition[]
+}
+
+export type BotParsedTrigger = {
+  /** `undefined` for the worker events the builder does not list (`LEAVE_CONTEXT`, `BOT_INACTIVE`, `HTTP_REQUEST_CALLBACK`). */
+  trigger?: { type: BotEvent; name: string }
+  rules: BotParsedRule[]
+}
+
+export type BotParsedContext = {
+  id: string
+  name: string
+  triggers: BotParsedTrigger[]
+}
+
 // ─── Bot ──────────────────────────────────────────────────────────────────────
 
+/** Bots are hard-deleted (no `deletedAt`). */
 export type Bot = {
   id: string
   name: string
-  data: Record<string, unknown>
-  contexts: BotContexts
+  /** Rewritten on every save: the `SEND_TERM` acceptance term of the contexts, as it was sent. */
+  data: { currentDefaultTerm?: { id: string } | string | null } & Record<string, unknown>
+  /**
+   * The list form (see `BotParsedContext`), not the stored map. Saving it back as is loses the
+   * `data` of the rules and the `{{@variable}}` conditions (the list does not carry them).
+   */
+  contexts: BotParsedContext[]
   flowJson: BotFlowJson | null
   settings: BotSettings
   currentBotVersionId: string | null
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
+  /**
+   * The stored map of `contexts`: a JSON string in `getById`, an object in `updateById`; absent
+   * in `getMany` and `create`.
+   */
+  defaultContexts?: string | BotContexts
   // relationships
   currentBotVersion?: BotVersion | null
   services?: Service[]
+  /** In `getById`, the first version comes with its contexts in the list form. */
+  botVersions?: BotVersion[]
 }
 
+export type BotRelationships = 'currentBotVersion' | 'services' | 'botVersions'
+
+/** The bot as stored (contexts in the map form), as the `bot.*` webhooks deliver it. */
+export type BotRecord = Omit<
+  Bot,
+  'contexts' | 'defaultContexts' | 'flowJson' | BotRelationships
+> & {
+  contexts: BotContexts
+  /**
+   * Raw, unlike the API answers: `{}` for a bot saved without a flow, and the bare list of nodes
+   * for a bot created with `isDraft`.
+   */
+  flowJson: Partial<BotFlowJson> | BotFlowNode[] | null
+}
+
+/** What the `bot.api-signal` webhook delivers (the `triggerSignal` call), not the bot. */
+export type BotApiSignalData = {
+  botId: string
+  contactId: string
+  flag?: string
+}
+
+/** A duplicate name answers 409, unless the account allows duplicate names. */
 export type CreateBotPayload = {
   name: string
-  data?: Record<string, unknown>
-  contexts?: BotContexts
-  flowJson?: BotFlowJson
+  /** Required: a missing `contexts` answers 500. */
+  contexts: BotContextInput[]
+  /** Omitted, the bot never sends a message (SD-2323): send at least `{ nodes: [], edges: [] }`. */
+  flowJson?: BotFlowJsonInput
   settings?: BotSettings
+  /**
+   * Saves the version as a draft instead of publishing it. The bot itself still takes the draft
+   * contexts on create, and its `flowJson` is saved as the bare list of nodes.
+   */
+  isDraft?: boolean
+  /** The id of a bot of the account to duplicate: its secret HTTP headers are kept. */
+  id?: string
+  /** @deprecated Ignored: the backend rewrites `data` on every save. */
+  data?: Record<string, unknown>
 }
 
-export type BotRelationships = 'currentBotVersion' | 'services'
+/** Renames the bot without touching its contexts or versions. */
+export type RenameBotPayload = {
+  name: string
+  onlyUpdateBotName: true
+}
 
-export type UpdateBotPayload = {
-  name?: string
-  data?: Record<string, unknown>
-  contexts?: BotContexts
-  flowJson?: BotFlowJson
+export type SaveBotPayload = {
+  /** Required on update too. */
+  name: string
+  /**
+   * The whole flow: it replaces the published one (or the draft, with `isDraft`). An empty list
+   * publishes a bot with no contexts.
+   */
+  contexts: BotContextInput[]
+  /** Omitted or without `edges`, the bot never sends a message (SD-2323). */
+  flowJson?: BotFlowJsonInput
   settings?: BotSettings
+  /** Saves into the latest draft (or a new one) instead of publishing. */
+  isDraft?: boolean
+  /** @deprecated Ignored: the backend rewrites `data` on every save. */
+  data?: Record<string, unknown>
+  /** @deprecated Ignored: every publish points the bot to the version it saves. */
   currentBotVersionId?: string | null
 }
+
+export type UpdateBotPayload = RenameBotPayload | SaveBotPayload
+
+// ─── Bot errors and extra routes ─────────────────────────────────────────────
+
+export type BotHistoryStatus = 'PENDING' | 'SUCCESS' | 'FAILED'
+
+/** A step of a bot run, as `getErrors` lists it (always `status: 'FAILED'`). */
+export type BotHistory = {
+  id: string
+  action: string
+  context: string
+  payload: Record<string, unknown>
+  status: BotHistoryStatus
+  errorCode: string | null
+  errorMessage: string | null
+  createdAt: string
+  updatedAt: string
+  botId: string
+  botSessionId: string
+  accountId: string
+  contactId: string
+  contact?: Contact & { service?: Service }
+}
+
+export type BotErrorsQuery = {
+  page?: number
+  /** Defaults to 15, with no upper limit. */
+  perPage?: number
+  /** A column of the history, or `serviceName` for the connection of the contact. Defaults to `createdAt`. */
+  sort?: string
+  order?: 'ASC' | 'DESC'
+  errorCode?: string
+  serviceId?: string
+  /** Matches part of the action name. */
+  search?: string
+  /** ISO date. */
+  startDate?: string
+  /** ISO date. */
+  endDate?: string
+}
+
+export type SuggestAgentPromptPayload = {
+  voiceTone: 'formal' | 'neutral' | 'informal'
+  languageType: 'simple' | 'neutral' | 'technical'
+  function: 'triage' | 'sales' | 'answer-questions' | 'support'
+  companySegment: string
+  companySubject: string
+  companyServices: string
+}

package/src/apis/index.ts

@@ -4,6 +4,7 @@ export * from './accounts'
 export * from './activityLog'
 export * from './answers'
 export * from './authHistory'
+export * from './botSimulators'
 export * from './botVersions'
 export * from './bots'
 export * from './campaigns'

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

@@ -1,13 +1,24 @@
 import { expectAssignable, expectError, expectNotAssignable, expectType } from 'tsd'
 import type { ApiClient } from '../core/ApiClient'
+import type { Paginated } from '../core/types'
+import { AnswersApi } from './answers/AnswersApi'
+import type { AnswersOverview } from './answers/types'
+import { BotSimulatorsApi } from './botSimulators/BotSimulatorsApi'
+import { BotsApi } from './bots/BotsApi'
+import type { Bot, BotContextInput, BotParsedContext } from './bots/types'
 import { CardsApi } from './cards/CardsApi'
 import { ContactsApi } from './contacts/ContactsApi'
 import { KanbanColumnsApi } from './kanbanColumns/KanbanColumnsApi'
 import { PipelineApi } from './pipeline/PipelineApi'
 import type { PermissionName } from './permissions/types'
 import { PersonalAccessTokensApi } from './personalAccessTokens/PersonalAccessTokensApi'
+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 { TagsApi } from './tags/TagsApi'
+import { TicketTopicsApi } from './ticketTopics/TicketTopicsApi'
 import { TicketsApi } from './tickets/TicketsApi'
 import type { Ticket, TicketTransfer } from './tickets/types'
 import { TimetableApi } from './timetable/TimetableApi'
@@ -115,3 +126,140 @@ expectType<TicketTransfer[] | undefined>(ticket.ticketTransfers)
 declare const transfer: TicketTransfer
 expectType<string | null>(transfer.byUserId)
 expectType<'opened' | 'transferred' | 'closed' | null>(transfer.action)
+
+// ── bots: the /bots routes take and return the contexts as a list ───
+
+const bots = new BotsApi(client)
+const botContexts: BotContextInput[] = [
+  {
+    id: '@INIT',
+    triggers: [
+      {
+        trigger: { type: 'MESSAGE_RECEIVED' },
+        rules: [
+          { conditions: [], actions: [{ type: { value: 'SEND_MESSAGE' }, data: { text: 'Oi' } }] },
+        ],
+      },
+    ],
+  },
+]
+bots.create({ name: 'Bot', contexts: botContexts, flowJson: { nodes: [], edges: [] } })
+expectError(bots.create({ name: 'Bot', contexts: botContexts, flowJson: { nodes: [] } }))
+expectError(bots.create({ name: 'Bot' }))
+expectError(bots.create({ name: 'Bot', contexts: { '@INIT': { name: 'Início', triggers: {} } } }))
+expectError(
+  bots.create({
+    name: 'Bot',
+    contexts: [
+      {
+        id: '@INIT',
+        triggers: [
+          {
+            trigger: { type: 'MESSAGE_RECEIVED' },
+            rules: [
+              {
+                conditions: [],
+                actions: [{ type: { value: 'SET_VAR' }, data: { key: 'k', value: 'v' } }],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  }),
+)
+bots.updateById('b-1', { name: 'Bot', contexts: botContexts, isDraft: true })
+bots.updateById('b-1', { name: 'Bot', onlyUpdateBotName: true })
+bots.create({
+  name: 'Bot',
+  contexts: [
+    {
+      id: '@INIT',
+      triggers: [
+        {
+          trigger: { type: 'TICKET_OPENED' },
+          rules: [
+            {
+              conditions: [],
+              actions: [
+                { type: { value: 'SEND_TERM' }, data: { acceptanceTerms: { id: 'term-1' } } },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+})
+expectError(bots.updateById('b-1', { contexts: botContexts }))
+expectError(bots.updateById('b-1', { name: 'Bot' }))
+expectType<Promise<Paginated<Bot>>>(bots.getMany({ paginate: false }))
+expectType<Promise<'OK' | false>>(bots.deleteById('b-1'))
+declare const bot: Bot
+expectType<BotParsedContext[]>(bot.contexts)
+
+// ── bot simulator: the trigger pick needs the id of the selection message ──
+
+const simulator = new BotSimulatorsApi(client)
+simulator.sendEvent('b-1', { type: 'text_contact', text: 'oi' })
+simulator.sendEvent('b-1', { type: 'select_trigger', id: 'm-1', selectedValue: 'TICKET_OPENED' })
+expectError(simulator.sendEvent('b-1', { type: 'select_trigger', selectedValue: 'TICKET_OPENED' }))
+expectError(
+  simulator.sendEvent('b-1', { type: 'select_condition', id: 'm-1', selectedValue: 'yes' }),
+)
+
+// ── questions: duration goes as a string; update is not partial ─────
+
+const questions = new QuestionsApi(client)
+const question = {
+  name: 'NPS',
+  type: 'nps',
+  questionMessage: 'De 0 a 10?',
+  duration: '60',
+  tries: 3,
+  successMessage: 'Obrigado!',
+  invalidMessage: 'De 0 a 10, por favor',
+} as const
+questions.create(question)
+expectType<Promise<'OK'>>(questions.deleteById('q-1'))
+expectError(questions.create({ ...question, duration: 60 }))
+questions.updateById('q-1', { type: 'nps', questionMessage: 'x', duration: 60, tries: 3 })
+expectError(questions.updateById('q-1', { name: 'NPS' }))
+
+// ── answers: the overview NPS is positional ─────────────────────────
+
+const answers = new AnswersApi(client)
+expectType<Promise<AnswersOverview>>(answers.overview({ type: 'nps', periodType: 'closeDate' }))
+expectError(answers.overview({ type: 'custom' }))
+expectType<Promise<'OK'>>(answers.deleteById('a-1'))
+
+// ── schedule: create answers no body; update is not partial ─────────
+
+const schedule = new ScheduleApi(client)
+const scheduled = {
+  scheduledAt: '2026-10-02T12:00:00Z',
+  contactId: 'c-1',
+  departmentId: 'd-1',
+  notes: '',
+}
+expectType<Promise<void>>(schedule.create({ ...scheduled, message: 'Oi' }))
+expectType<Promise<ScheduleRecord>>(schedule.updateById('s-1', scheduled))
+expectError(schedule.updateById('s-1', { message: 'Oi' }))
+expectError(schedule.create({ ...scheduled, files: [{ name: 'a.png' }] }))
+expectError(schedule.create({ ...scheduled, files: [{ id: 'f-1' }] }))
+schedule.updateById('s-1', { ...scheduled, files: [{ id: 'f-1' }] })
+
+// ── ticket topics: create needs the departments ─────────────────────
+
+const topics = new TicketTopicsApi(client)
+topics.create({ name: 'Dúvida', departments: [] })
+expectError(topics.create({ name: 'Dúvida' }))
+expectError(topics.updateById('t-1', { departments: [] }))
+expectType<Promise<'OK'>>(topics.deleteById('t-1'))
+
+// ── quick replies: update fails without the files ───────────────────
+
+const quickReplies = new QuickRepliesApi(client)
+quickReplies.updateById('r-1', { title: 'Oi', text: 'Olá', files: [] })
+expectError(quickReplies.updateById('r-1', { title: 'Oi', text: 'Olá' }))
+expectType<Promise<'OK'>>(quickReplies.deleteById('r-1'))

package/src/apis/questions/QuestionsApi.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ApiClient } from '../../core/ApiClient'
+import { QuestionsApi } from './QuestionsApi'
+
+// ── Mock client factory ──────────────────────────────────────────────
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('QuestionsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: QuestionsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new QuestionsApi(client)
+  })
+
+  it('create sends duration as a string', async () => {
+    const body = {
+      name: 'NPS',
+      type: 'nps',
+      questionMessage: 'De 0 a 10?',
+      duration: '60',
+      tries: 3,
+      successMessage: 'Obrigado!',
+      invalidMessage: 'De 0 a 10',
+    } as const
+    await api.create(body)
+    expect(client.post).toHaveBeenCalledWith('/questions', body, undefined)
+  })
+
+  it('deleteById resolves to the OK of the route', async () => {
+    vi.mocked(client.delete).mockResolvedValue('OK')
+    expect(await api.deleteById('q1')).toBe('OK')
+    expect(client.delete).toHaveBeenCalledWith('/questions/q1', undefined)
+  })
+})

package/src/apis/questions/QuestionsApi.ts

@@ -1,13 +1,32 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
+import type { ListQuery } from '../../core/types'
 import type { Question, CreateQuestionPayload, UpdateQuestionPayload } from './types'
 
+/**
+ * Evaluation questions (NPS/CSAT), sent to the contact by the `SEND_QUESTION` bot action. The
+ * backend also serves the same routes under the singular `/question` (kept for compatibility).
+ *
+ * Permissions: `evaluation.view` to read; `evaluation.view` OR `evaluation.create`/`update`/
+ * `destroy` to write.
+ */
 export class QuestionsApi extends BaseCrudApi<
   Question,
   CreateQuestionPayload,
-  UpdateQuestionPayload
+  UpdateQuestionPayload,
+  ListQuery<Question>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/questions')
   }
+
+  /**
+   * Deletes a question (soft delete). Resolves to `'OK'`. A question used in a bot answers 403;
+   * the answers of a deleted question leave the overview and the exports.
+   * @permissions evaluation.view OR evaluation.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/questions/types.ts

@@ -1,5 +1,6 @@
 import type { Answer } from '../answers/types'
 
+/** `custom` exists in the database, but it never takes an answer (the UI hides it). */
 export type QuestionType = 'nps' | 'csat' | 'custom'
 
 export type Question = {
@@ -7,39 +8,57 @@ export type Question = {
   name: string
   type: QuestionType
   questionMessage: string
+  /** Minutes the contact has to answer. Comes back as a number, although it is sent as a string. */
   duration: number
   tries: number
   successMessage: string
   invalidMessage: string
   reasonMessage: string | null
+  /** Sends `closureMessage` after the evaluation ends. */
+  sendClosureMessage: boolean
+  closureMessage: string | null
   accountId: string
   createdAt: string
   updatedAt: string
   deletedAt: string | null
-  // relationships
+  /** @deprecated Never comes: the route drops every `include` (empty whitelist). */
   answers?: Answer[]
 }
 
+/** @deprecated The route drops every `include` (empty whitelist). */
 export type QuestionRelationships = 'answers'
 
 export type CreateQuestionPayload = {
+  /** Unique in the account (409, unless the account allows duplicate names). */
   name: string
+  /** An unknown type answers 500 (no validation before the database). */
   type: QuestionType
   questionMessage: string
-  duration: number
+  /** Minutes, AS A STRING: a number answers 400 (`Should be of type string.`). */
+  duration: string
+  /** Greater than 0. */
   tries: number
+  /** Not validated by the route: missing answers 500. */
   successMessage: string
+  /** Not validated by the route: missing answers 500. */
   invalidMessage: string
   reasonMessage?: string
+  sendClosureMessage?: boolean
+  /** Required when `sendClosureMessage` is true (400); up to 500 characters. */
+  closureMessage?: string
 }
 
+/** Not partial: `type`, `questionMessage`, `duration` and `tries` are required on update. */
 export type UpdateQuestionPayload = {
+  type: QuestionType
+  questionMessage: string
+  /** Minutes; on update a number is also taken. */
+  duration: string | number
+  tries: number
   name?: string
-  type?: QuestionType
-  questionMessage?: string
-  duration?: number
-  tries?: number
   successMessage?: string
   invalidMessage?: string
   reasonMessage?: string | null
+  sendClosureMessage?: boolean
+  closureMessage?: string | null
 }