@ikatec/digisac-api-sdk 4.5.1 → 4.6.0

package/src/apis/botVersions/BotVersionsApi.test.ts

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ApiClient } from '../../core/ApiClient'
+import { BotVersionsApi } from './BotVersionsApi'
+
+// ── 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('BotVersionsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: BotVersionsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new BotVersionsApi(client)
+  })
+
+  it('getMany lists the versions of a bot', async () => {
+    const query = { where: { botId: 'b1' }, paginate: false } as const
+    vi.mocked(client.get).mockResolvedValue([{ id: 'v1' }])
+    expect(await api.getMany(query)).toEqual([{ id: 'v1' }])
+    expect(client.get).toHaveBeenCalledWith(
+      `/bot-versions?query=${encodeURIComponent(JSON.stringify(query))}`,
+      undefined,
+    )
+  })
+
+  it('getOne filters by id, the replacement of the deprecated getById', async () => {
+    vi.mocked(client.get).mockResolvedValue([{ id: 'v1' }])
+    expect(await api.getOne({ where: { id: 'v1' } })).toEqual({ id: 'v1' })
+  })
+
+  it('keeps the deprecated write methods calling their routes', async () => {
+    await api.create({ botId: 'b1' })
+    expect(client.post).toHaveBeenCalledWith('/bot-versions', { botId: 'b1' }, undefined)
+    await api.deleteById('v1')
+    expect(client.delete).toHaveBeenCalledWith('/bot-versions/v1', undefined)
+  })
+})

package/src/apis/botVersions/BotVersionsApi.ts

@@ -1,7 +1,14 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
+import type { GetByIdQuery } from '../../core/types'
 import type { BotVersion, CreateBotVersionPayload, UpdateBotVersionPayload } from './types'
 
+/**
+ * Versions of the bots, with the contexts in the stored map form. The backend only serves the
+ * list (`getMany`/`getOne`, filter by `where.botId`; `paginate: false` is honored), under the
+ * `bots.view` permission: the versions are created and published by `BotsApi.create`/`updateById`.
+ * `include` is dropped (empty whitelist), so the relationships never come.
+ */
 export class BotVersionsApi extends BaseCrudApi<
   BotVersion,
   CreateBotVersionPayload,
@@ -10,4 +17,38 @@ export class BotVersionsApi extends BaseCrudApi<
   constructor(client: ApiClient) {
     super(client, '/bot-versions')
   }
+
+  /**
+   * @deprecated Not served: the backend only serves GET /bot-versions (list): this route answers
+   * 404. Use `getOne({ where: { id } })`.
+   */
+  override getById(
+    id: string,
+    query?: GetByIdQuery<BotVersion>,
+    headers?: Record<string, string>,
+  ): Promise<BotVersion> {
+    return super.getById(id, query, headers)
+  }
+
+  /** @deprecated Not served: the backend only serves GET /bot-versions (list): this route answers 404. Save the bot through `BotsApi`. */
+  override create(
+    body: CreateBotVersionPayload,
+    headers?: Record<string, string>,
+  ): Promise<BotVersion> {
+    return super.create(body, headers)
+  }
+
+  /** @deprecated Not served: the backend only serves GET /bot-versions (list): this route answers 404. Save the bot through `BotsApi`. */
+  override updateById(
+    id: string,
+    body: UpdateBotVersionPayload,
+    headers?: Record<string, string>,
+  ): Promise<BotVersion> {
+    return super.updateById(id, body, headers)
+  }
+
+  /** @deprecated Not served: the backend only serves GET /bot-versions (list): this route answers 404. */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<BotVersion> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/botVersions/types.ts

@@ -19,11 +19,15 @@ export type BotVersion = {
   updatedAt: string
   deletedAt: string | null
   // relationships
+  /** @deprecated Never comes: the route drops every `include` (empty whitelist). */
   bot?: Bot
+  /** @deprecated Never comes: the route drops every `include` (empty whitelist). */
   createdBy?: User | null
+  /** @deprecated Never comes: the route drops every `include` (empty whitelist). */
   publishedBy?: User | null
 }
 
+/** @deprecated The route drops every `include` (empty whitelist). */
 export type BotVersionRelationships = 'bot' | 'createdBy' | 'publishedBy'
 
 export type CreateBotVersionPayload = {

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