@ikatec/digisac-api-sdk 4.5.1 → 4.7.0

package/src/apis/bots/BotsApi.test.ts

@@ -0,0 +1,177 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ApiClient } from '../../core/ApiClient'
+import { BotsApi } from './BotsApi'
+import type { BotContextInput } from './types'
+
+// ── 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(),
+  }
+}
+
+const headers = { 'X-Custom': 'value' }
+
+const contexts: BotContextInput[] = [
+  {
+    id: '@INIT',
+    name: 'Contexto inicial',
+    triggers: [
+      {
+        trigger: { type: 'TICKET_OPENED' },
+        rules: [
+          {
+            title: 'abertura',
+            conditions: [],
+            actions: [{ type: { value: 'SEND_MESSAGE' }, data: { text: 'Olá' } }],
+          },
+        ],
+      },
+    ],
+  },
+]
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('BotsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: BotsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new BotsApi(client)
+  })
+
+  describe('getMany', () => {
+    it('calls client.get with /bots and the query', async () => {
+      await api.getMany({ where: { name: 'x' } }, headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/bots?query=${encodeURIComponent(JSON.stringify({ where: { name: 'x' } }))}`,
+        headers,
+      )
+    })
+  })
+
+  describe('getOne', () => {
+    it('reads the first item of a one-item page', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [{ id: 'b1' }], total: 1 })
+      const result = await api.getOne({ where: { name: 'x' } })
+      expect(client.get).toHaveBeenCalledWith(
+        `/bots?query=${encodeURIComponent(
+          JSON.stringify({ where: { name: 'x' }, perPage: 1, page: 1 }),
+        )}`,
+        undefined,
+      )
+      expect(result).toEqual({ id: 'b1' })
+    })
+
+    it('resolves null on an empty page', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      expect(await api.getOne()).toBeNull()
+    })
+  })
+
+  describe('CRUD', () => {
+    it('getById calls client.get with /bots/:id', async () => {
+      await api.getById('b1', { include: ['currentBotVersion'] }, headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/bots/b1?query=${encodeURIComponent(JSON.stringify({ include: ['currentBotVersion'] }))}`,
+        headers,
+      )
+    })
+
+    it('create calls client.post with /bots and the contexts list', async () => {
+      const body = { name: 'Robô', contexts, isDraft: true }
+      await api.create(body, headers)
+      expect(client.post).toHaveBeenCalledWith('/bots', body, headers)
+    })
+
+    it('updateById saves the flow or only renames', async () => {
+      await api.updateById('b1', { name: 'Robô', contexts })
+      expect(client.put).toHaveBeenCalledWith('/bots/b1', { name: 'Robô', contexts }, undefined)
+      await api.updateById('b1', { name: 'Novo', onlyUpdateBotName: true })
+      expect(client.put).toHaveBeenCalledWith(
+        '/bots/b1',
+        { name: 'Novo', onlyUpdateBotName: true },
+        undefined,
+      )
+    })
+
+    it('deleteById calls client.delete with /bots/:id', async () => {
+      vi.mocked(client.delete).mockResolvedValue(false)
+      expect(await api.deleteById('b1', headers)).toBe(false)
+      expect(client.delete).toHaveBeenCalledWith('/bots/b1', headers)
+    })
+
+    it("deleteById passes the 'OK' of a fixed backend through", async () => {
+      vi.mocked(client.delete).mockResolvedValue('OK')
+      expect(await api.deleteById('b1')).toBe('OK')
+    })
+  })
+
+  describe('getErrors', () => {
+    it('calls client.get with /bots/:id/errors and the filters', async () => {
+      const query = { page: 2, perPage: 10, errorCode: 'TIMEOUT', sort: 'serviceName' }
+      await api.getErrors('b1', query, headers)
+      expect(client.get).toHaveBeenCalledWith(
+        `/bots/b1/errors?query=${encodeURIComponent(JSON.stringify(query))}`,
+        headers,
+      )
+    })
+
+    it('sends no query string without filters', async () => {
+      await api.getErrors('b1')
+      expect(client.get).toHaveBeenCalledWith('/bots/b1/errors', undefined)
+    })
+  })
+
+  describe('triggerSignal', () => {
+    it('sends the flag in the body', async () => {
+      await api.triggerSignal('b1', 'c1', 'vip', headers)
+      expect(client.post).toHaveBeenCalledWith(
+        '/bots/b1/trigger-signal/c1',
+        { flag: 'vip' },
+        headers,
+      )
+    })
+
+    it('sends no body without a flag', async () => {
+      await api.triggerSignal('b1', 'c1')
+      expect(client.post).toHaveBeenCalledWith('/bots/b1/trigger-signal/c1', undefined, undefined)
+    })
+  })
+
+  describe('requestCallback', () => {
+    it('posts the response data to /bots/:id/request-callback/:pendingRequestId', async () => {
+      await api.requestCallback('b1', 'h1', { status: 'paid' }, headers)
+      expect(client.post).toHaveBeenCalledWith(
+        '/bots/b1/request-callback/h1',
+        { status: 'paid' },
+        headers,
+      )
+    })
+  })
+
+  describe('suggestAgentPrompt', () => {
+    it('posts the agent config to /bots/suggest-agent-prompt', async () => {
+      vi.mocked(client.post).mockResolvedValue('Você é um agente...')
+      const body = {
+        voiceTone: 'formal',
+        languageType: 'simple',
+        function: 'support',
+        companySegment: 'Varejo',
+        companySubject: 'Loja',
+        companyServices: 'Vendas',
+      } as const
+      expect(await api.suggestAgentPrompt(body)).toBe('Você é um agente...')
+      expect(client.post).toHaveBeenCalledWith('/bots/suggest-agent-prompt', body, undefined)
+    })
+  })
+})

package/src/apis/bots/BotsApi.ts

@@ -1,9 +1,165 @@
-import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Bot, CreateBotPayload, UpdateBotPayload } from './types'
+import { BaseApi } from '../../core/BaseApi'
+import type {
+  GetByIdQuery,
+  HasCreate,
+  HasDeleteById,
+  HasGetById,
+  HasUpdateById,
+  ListQuery,
+  Paginated,
+} from '../../core/types'
+import type {
+  Bot,
+  BotErrorsQuery,
+  BotHistory,
+  CreateBotPayload,
+  SuggestAgentPromptPayload,
+  UpdateBotPayload,
+} from './types'
 
-export class BotsApi extends BaseCrudApi<Bot, CreateBotPayload, UpdateBotPayload> {
-  constructor(client: ApiClient) {
-    super(client, '/bots')
+/**
+ * Bots. The list route always paginates (`paginate: false` is ignored), so this class does not
+ * extend `BaseCrudApi`. The contexts travel as a list (`BotContextInput` / `BotParsedContext`),
+ * not as the stored map that `BotVersionsApi` serves.
+ *
+ * `GET /bots/:id/errors/export` is not exposed: it answers a binary xlsx, and `ApiClient` only
+ * handles JSON/text bodies.
+ */
+export class BotsApi
+  extends BaseApi
+  implements
+    HasGetById<Bot>,
+    HasCreate<Bot, CreateBotPayload>,
+    HasUpdateById<Bot, UpdateBotPayload>,
+    HasDeleteById<'OK' | false>
+{
+  public readonly basePath = '/bots'
+
+  /**
+   * Lists the bots of the account. Always paginated, even with `paginate: false`.
+   * @permissions bots.view
+   */
+  getMany(query?: ListQuery<Bot>, headers?: Record<string, string>): Promise<Paginated<Bot>> {
+    return this.client.get<Paginated<Bot>>(`${this.basePath}${this.toQueryString(query)}`, headers)
+  }
+
+  /**
+   * Returns the first bot matching the query, or `null` when none match.
+   * @permissions bots.view
+   */
+  async getOne(query?: ListQuery<Bot>, headers?: Record<string, string>): Promise<Bot | null> {
+    const page = await this.getMany({ ...query, perPage: 1, page: 1 }, headers)
+    return page?.data?.[0] ?? null
+  }
+
+  /**
+   * Returns a bot by ID, with `defaultContexts` (the stored map, as a JSON string). An unknown id
+   * answers 500, not an empty body.
+   * @permissions bots.view
+   */
+  getById(id: string, query?: GetByIdQuery<Bot>, headers?: Record<string, string>): Promise<Bot> {
+    return this.client.get<Bot>(`${this.basePath}/${id}${this.toQueryString(query)}`, headers)
+  }
+
+  /**
+   * Creates a bot and its first version (published, or a draft with `isDraft`). A duplicate name
+   * answers 409, unless the account allows duplicate names. Send `flowJson` with `edges`, or the
+   * bot never sends a message (SD-2323).
+   * @permissions bots.create
+   */
+  create(body: CreateBotPayload, headers?: Record<string, string>): Promise<Bot> {
+    return this.client.post<Bot, CreateBotPayload>(this.basePath, body, headers)
+  }
+
+  /**
+   * Saves the flow (publishing a version, or into the draft with `isDraft`), or only renames the
+   * bot with `onlyUpdateBotName`. Resolves to the bot with `defaultContexts` as an object.
+   * @permissions bots.view OR bots.update
+   */
+  updateById(id: string, body: UpdateBotPayload, headers?: Record<string, string>): Promise<Bot> {
+    return this.client.put<Bot, UpdateBotPayload>(`${this.basePath}/${id}`, body, headers)
+  }
+
+  /**
+   * Deletes a bot and its versions (hard delete). Today resolves to `false` even when the bot was
+   * deleted (the backend destroy returns nothing); it becomes `'OK'` once the destroy returns the
+   * bot, as in the other routes. Do not read the result as success or failure. An unknown id
+   * answers 500.
+   * @permissions bots.view OR bots.destroy
+   */
+  deleteById(id: string, headers?: Record<string, string>): Promise<'OK' | false> {
+    return this.client.delete<'OK' | false>(`${this.basePath}/${id}`, headers)
+  }
+
+  /**
+   * Lists the failed steps of the bot runs, newest first by default. An unknown bot answers an
+   * empty page.
+   * @permissions bots.view
+   */
+  getErrors(
+    id: string,
+    query?: BotErrorsQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<BotHistory>> {
+    return this.client.get<Paginated<BotHistory>>(
+      `${this.basePath}/${id}/errors${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Fires the `API_SIGNAL` trigger of the bot for the contact, with an optional `flag` (read by
+   * the `api_signal_flag` condition). Asynchronous: always resolves with no content, and the
+   * worker only runs it when the contact has an open ticket.
+   * @permissions bots.view
+   */
+  triggerSignal(
+    botId: string,
+    contactId: string,
+    flag?: string,
+    headers?: Record<string, string>,
+  ): Promise<void> {
+    return this.client.post<void, { flag: string } | undefined>(
+      `${this.basePath}/${botId}/trigger-signal/${contactId}`,
+      flag === undefined ? undefined : { flag },
+      headers,
+    )
+  }
+
+  /**
+   * Answers a pending asynchronous `HTTP_REQUEST` action: `body` becomes the response the bot
+   * reads. Resolves with no content. An unknown history answers 404; a history that is not
+   * `PENDING`, or of another bot, answers 400. JSON bodies only (the route also takes text, XML
+   * and CSV), up to 250 KB.
+   * @permissions bots.view
+   */
+  requestCallback(
+    id: string,
+    pendingRequestId: string,
+    body: unknown,
+    headers?: Record<string, string>,
+  ): Promise<void> {
+    return this.client.post<void, unknown>(
+      `${this.basePath}/${id}/request-callback/${pendingRequestId}`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Generates a prompt for an AI agent of the bot. COSTS one AI agent credit of the account and
+   * calls OpenAI. No permission check: any authenticated user. A missing field answers 400; an
+   * option outside the lists, or the AI agent limit of the account reached
+   * (`Agent limit reached`), answers 500.
+   */
+  suggestAgentPrompt(
+    body: SuggestAgentPromptPayload,
+    headers?: Record<string, string>,
+  ): Promise<string> {
+    return this.client.post<string, SuggestAgentPromptPayload>(
+      `${this.basePath}/suggest-agent-prompt`,
+      body,
+      headers,
+    )
   }
 }

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