@ikatec/digisac-api-sdk 4.10.0 → 4.12.0

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

@@ -18,6 +18,10 @@ import type {
 import { CardsApi } from './cards/CardsApi'
 import { ContactsApi } from './contacts/ContactsApi'
 import { InteractiveMessagesApi } from './interactiveMessages/InteractiveMessagesApi'
+import { MeApi } from './me/MeApi'
+import type { AccountAmounts, MeStatusResponse } from './me/types'
+import { TranscriptsApi } from './transcripts/TranscriptsApi'
+import { WhatsappBusinessTemplatesApi } from './whatsappBusinessTemplates/WhatsappBusinessTemplatesApi'
 import type {
   ChannelRedirect,
   CtaUrlInteractiveMessageContent,
@@ -54,6 +58,8 @@ import type { SummarizeTicketResult } from './contacts/types'
 import { CustomFieldsApi } from './customFields/CustomFieldsApi'
 import { DepartmentsApi } from './departments/DepartmentsApi'
 import type { Department } from './departments/types'
+import type { Distribution } from './distribution/types'
+import type { ContactBlockList } from './contactBlockLists/types'
 import { DistributionApi } from './distribution/DistributionApi'
 import { FilesApi } from './files/FilesApi'
 import type { CreateToUploadResult, DeleteFileResult, File } from './files/types'
@@ -68,7 +74,7 @@ import { NotificationsApi } from './notifications/NotificationsApi'
 import { OrganizationsApi } from './organizations/OrganizationsApi'
 import { PeopleApi } from './people/PeopleApi'
 import { ServicesApi } from './services/ServicesApi'
-import type { UpdateUserPayload } from './users/types'
+import type { UpdateUserPayload, User } from './users/types'
 import { WebhooksApi } from './webhooks/WebhooksApi'
 
 declare const client: ApiClient
@@ -208,7 +214,10 @@ expectError(
 )
 
 declare const interactiveMessage: InteractiveMessage
-expectType<'list' | 'button' | 'cta_url' | 'request_contact_info'>(interactiveMessage.type)
+// `type` is not a field of the backend (deprecated, optional): the type is `interactive.type`.
+expectType<'list' | 'button' | 'cta_url' | 'request_contact_info' | undefined>(
+  interactiveMessage.type,
+)
 if (interactiveMessage.interactive.type === 'cta_url') {
   expectType<CtaUrlInteractiveMessageContent>(interactiveMessage.interactive)
   expectType<string>(interactiveMessage.interactive.action.parameters.url)
@@ -545,6 +554,89 @@ expectType<Promise<'OK'>>(new ContactBlockListsControlsApi(client).deleteById('c
 expectType<Promise<boolean>>(new RolesApi(client).deleteById('r-1'))
 expectType<Promise<void>>(new AcceptanceTermsApi(client).deleteById('t-1'))
 expectType<Promise<void>>(new DistributionApi(client).deleteById('d-1'))
+
+// ── QARC-1009: /me, transcripts, interactive messages, templates ─────
+
+expectType<Promise<'OK'>>(new MeApi(client).activateOtpAuth({ 'x-digisac-otp': '123456' }))
+expectType<Promise<MeStatusResponse>>(
+  new MeApi(client).updateStatus({ status: 'offline', client: 'web' }),
+)
+expectType<Promise<AccountAmounts>>(
+  new MeApi(client).getAccountAmounts({ filter: ['users.amounts'] }),
+)
+expectType<Promise<User>>(new MeApi(client).getMe({ include: ['account'] }))
+expectError(new MeApi(client).updateStatus({ status: 'offline', client: 'desktop' }))
+expectType<Promise<void>>(new TranscriptsApi(client).transcribe('m-1'))
+expectType<Promise<{ count: number }>>(new InteractiveMessagesApi(client).count())
+expectType<Promise<{ count: number }>>(new WhatsappBusinessTemplatesApi(client).count())
+expectType<Promise<'OK'>>(new WhatsappBusinessTemplatesApi(client).refreshTemplates())
+expectError(
+  new WhatsappBusinessTemplatesApi(client).create({
+    name: 'qa',
+    internalName: 'QA',
+    components: [],
+    serviceId: 's-1',
+    messageType: 'text_only',
+    language: 'pt_BR',
+    category: 'UTILITY',
+  }),
+)
+
+// ── create/updateById: what each route really answers (QARC-1008) ─────
+
+expectType<Promise<Distribution | undefined>>(
+  new DistributionApi(client).create({
+    name: 'd',
+    maxNum: 1,
+    redistributeAll: false,
+    departments: [{ id: 'dep-1' }],
+  }),
+)
+expectType<Promise<Distribution | Department[]>>(
+  new DistributionApi(client).updateById('d-1', {
+    name: 'd',
+    roles: [{ id: 'r-1' }],
+    departments: [],
+  }),
+)
+expectType<Promise<Record<string, never>>>(
+  new IntegrationsApi(client).create({ type: 'menu_button', text: 'x' }),
+)
+expectType<Promise<Record<string, never>>>(
+  new IntegrationsApi(client).updateById('i-1', { text: 'x' }),
+)
+expectType<Promise<void>>(
+  new ContactBlockListsControlsApi(client).create({
+    reason: 'r',
+    servicesIds: ['s-1'],
+    contactBlockListsIds: ['l-1'],
+    action: 'block',
+    revertExceptions: false,
+  }),
+)
+expectType<Promise<{ count: number }>>(
+  new ContactBlockListsApi(client).count({ where: { name: 'x' } }),
+)
+expectType<Promise<{ count: number }>>(new ContactBlockListsControlsApi(client).count())
+expectType<Promise<Paginated<ContactBlockList>>>(
+  new ContactBlockListsApi(client).getMany({ include: ['importFile'] }),
+)
+expectError(
+  new DistributionApi(client).create({
+    name: 'd',
+    maxNum: 1,
+    redistributeAll: false,
+    departments: ['dep-1'],
+  }),
+)
+expectError(
+  new ContactBlockListsControlsApi(client).create({
+    reason: 'r',
+    servicesIds: [],
+    contactBlockListsIds: [],
+    action: 'remove',
+  }),
+)
 expectType<Promise<false>>(new KnowledgeBaseApi(client).deleteById('k-1'))
 expectType<Promise<false>>(new KnowledgeBaseItemApi(client).deleteById('k-1'))
 expectType<Promise<DeleteFileResult>>(new FilesApi(client).deleteById('f-1'))

package/src/apis/transcripts/TranscriptsApi.test.ts

@@ -1,7 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { TranscriptsApi } from './TranscriptsApi'
 import type { ApiClient } from '../../core/ApiClient'
-import type { TranscriptResponse } from './types'
 
 // ── Mock client factory ──────────────────────────────────────────────
 
@@ -28,36 +27,30 @@ describe('TranscriptsApi', () => {
     api = new TranscriptsApi(client)
   })
 
-  // ── getById ──────────────────────────────────────────────────────
-
-  describe('getById', () => {
-    it('calls client.get with /transcripts/:id', async () => {
-      const response: TranscriptResponse = {
-        id: 'msg-1',
-        isTranscribing: true,
-        transcribeError: false,
-      }
-      vi.mocked(client.get).mockResolvedValue(response)
-      const result = await api.getById('msg-1')
+  describe('transcribe', () => {
+    it('calls client.get with /transcripts/:messageId and resolves the empty answer', async () => {
+      vi.mocked(client.get).mockResolvedValue(undefined)
+      await expect(api.transcribe('msg-1')).resolves.toBeUndefined()
       expect(client.get).toHaveBeenCalledWith('/transcripts/msg-1', undefined)
-      expect(result).toEqual(response)
     })
 
     it('forwards custom headers', async () => {
-      const response: TranscriptResponse = {
-        id: 'msg-2',
-        isTranscribing: false,
-        transcribeError: true,
-      }
-      vi.mocked(client.get).mockResolvedValue(response)
       const headers = { 'X-Custom': 'h' }
-      await api.getById('msg-2', headers)
+      await api.transcribe('msg-2', headers)
       expect(client.get).toHaveBeenCalledWith('/transcripts/msg-2', headers)
     })
 
     it('propagates errors from client.get', async () => {
       vi.mocked(client.get).mockRejectedValue(new Error('Not found'))
-      await expect(api.getById('missing')).rejects.toThrow('Not found')
+      await expect(api.transcribe('missing')).rejects.toThrow('Not found')
+    })
+  })
+
+  describe('getById (deprecated)', () => {
+    it('starts the transcription through the same route', async () => {
+      vi.mocked(client.get).mockResolvedValue(undefined)
+      await expect(api.getById('msg-3')).resolves.toBeUndefined()
+      expect(client.get).toHaveBeenCalledWith('/transcripts/msg-3', undefined)
     })
   })
 })

package/src/apis/transcripts/TranscriptsApi.ts

@@ -1,12 +1,21 @@
 import { BaseApi } from '../../core/BaseApi'
-import type { HasGetById } from '../../core/types'
-import type { TranscriptResponse } from './types'
 
-export class TranscriptsApi extends BaseApi implements HasGetById<TranscriptResponse> {
+export class TranscriptsApi extends BaseApi {
   private readonly basePath = '/transcripts'
 
-  /** Triggers audio transcription for a message by dispatching an async job, and marks it as transcribing. */
-  getById(id: string, headers?: Record<string, string>): Promise<TranscriptResponse> {
-    return this.client.get<TranscriptResponse>(`${this.basePath}/${id}`, headers)
+  /**
+   * Starts the transcription of the audio of a message: marks the message as transcribing and dispatches an async
+   * job, which calls the transcription service (AI) and debits the AI credits of the account. Resolves with no body;
+   * the result shows on the message. An unknown message answers 500.
+   */
+  transcribe(messageId: string, headers?: Record<string, string>): Promise<void> {
+    return this.client.get<void>(`${this.basePath}/${messageId}`, headers)
+  }
+
+  /**
+   * @deprecated Not a read: it starts the transcription of the message. Use {@link transcribe}.
+   */
+  getById(id: string, headers?: Record<string, string>): Promise<void> {
+    return this.transcribe(id, headers)
   }
 }

package/src/apis/transcripts/types.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated The route answers no body: `TranscriptsApi.transcribe` (and `getById`) resolve `undefined`. The
+ * transcription status shows on the message (`isTranscribing`, `transcribeError`).
+ */
 export type TranscriptResponse = {
   id: string
   isTranscribing: boolean

package/src/apis/whatsappBusinessTemplates/WhatsappBusinessTemplatesApi.test.ts

@@ -0,0 +1,86 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { WhatsappBusinessTemplatesApi } from './WhatsappBusinessTemplatesApi'
+import type { ApiClient } from '../../core/ApiClient'
+
+// ── 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('WhatsappBusinessTemplatesApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: WhatsappBusinessTemplatesApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new WhatsappBusinessTemplatesApi(client)
+  })
+
+  it('count calls client.get with /whatsapp-business-templates/count', async () => {
+    vi.mocked(client.get).mockResolvedValue({ count: 2 })
+    await expect(api.count()).resolves.toEqual({ count: 2 })
+    expect(client.get).toHaveBeenCalledWith('/whatsapp-business-templates/count', undefined)
+  })
+
+  it('getHsmLimit calls client.get with /whatsapp-business-templates/:accountId/hsmLimit', async () => {
+    const limit = { hsmLimit: 10, hsmUsedLimit: 3, hasLimit: 7 }
+    vi.mocked(client.get).mockResolvedValue(limit)
+    await expect(api.getHsmLimit('acc-1')).resolves.toEqual(limit)
+    expect(client.get).toHaveBeenCalledWith(
+      '/whatsapp-business-templates/acc-1/hsmLimit',
+      undefined,
+    )
+  })
+
+  it('sendToReview posts to /whatsapp-business-templates/:id/send-to-review', async () => {
+    await api.sendToReview('t-1')
+    expect(client.post).toHaveBeenCalledWith(
+      '/whatsapp-business-templates/t-1/send-to-review',
+      undefined,
+      undefined,
+    )
+  })
+
+  it('refreshTemplates posts to /whatsapp-business-templates/refresh-templates and resolves OK', async () => {
+    vi.mocked(client.post).mockResolvedValue('OK')
+    await expect(api.refreshTemplates()).resolves.toBe('OK')
+    expect(client.post).toHaveBeenCalledWith(
+      '/whatsapp-business-templates/refresh-templates',
+      undefined,
+      undefined,
+    )
+  })
+
+  it('resume calls client.get with /whatsapp-business-templates/resume', async () => {
+    vi.mocked(client.get).mockResolvedValue([])
+    await expect(api.resume()).resolves.toEqual([])
+    expect(client.get).toHaveBeenCalledWith('/whatsapp-business-templates/resume', undefined)
+  })
+
+  it('create posts the draft with status and namespace', async () => {
+    const body = {
+      name: 'qa_template',
+      internalName: 'QA',
+      status: '',
+      namespace: '',
+      components: [{ type: 'BODY' as const, text: 'Olá' }],
+      serviceId: 's-1',
+      messageType: 'text_only' as const,
+      language: 'pt_BR' as const,
+      category: 'UTILITY' as const,
+    }
+    await api.create(body)
+    expect(client.post).toHaveBeenCalledWith('/whatsapp-business-templates', body, undefined)
+  })
+})

package/src/apis/whatsappBusinessTemplates/WhatsappBusinessTemplatesApi.ts

@@ -1,17 +1,91 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type {
   WhatsappBusinessTemplate,
   CreateWhatsappBusinessTemplatePayload,
   UpdateWhatsappBusinessTemplatePayload,
+  WhatsappBusinessTemplateHsmLimit,
 } from './types'
 
+/**
+ * WhatsApp Business templates. Create, update, reads and count are local; `sendToReview`, `refreshTemplates`,
+ * `resume` and the delete of a template of a `whatsapp-business` connection call the provider (Meta, 360Dialog).
+ * `getById` answers `null` for an unknown id.
+ */
 export class WhatsappBusinessTemplatesApi extends BaseCrudApi<
   WhatsappBusinessTemplate,
   CreateWhatsappBusinessTemplatePayload,
-  UpdateWhatsappBusinessTemplatePayload
+  UpdateWhatsappBusinessTemplatePayload,
+  ListQuery<WhatsappBusinessTemplate>,
+  unknown
 > {
   constructor(client: ApiClient) {
     super(client, '/whatsapp-business-templates')
   }
+
+  /**
+   * Counts the templates matching the query.
+   * @permissions hsm.view
+   */
+  count(
+    query?: ListQuery<WhatsappBusinessTemplate>,
+    headers?: Record<string, string>,
+  ): Promise<{ count: number }> {
+    return this.client.get<{ count: number }>(
+      `${this.basePath}/count${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Reads the template limit of the plan of the account. Send the `accountId` of the current user: the route is
+   * outside the error handler of the backend, so an unknown id gets no answer (the request waits for the timeout).
+   * @permissions hsm.view
+   */
+  getHsmLimit(
+    accountId: string,
+    headers?: Record<string, string>,
+  ): Promise<WhatsappBusinessTemplateHsmLimit> {
+    return this.client.get<WhatsappBusinessTemplateHsmLimit>(
+      `${this.basePath}/${accountId}/hsmLimit`,
+      headers,
+    )
+  }
+
+  /**
+   * Deletes a template. On a `whatsapp-business` connection it goes to the provider (and answers what it answers);
+   * a draft of another connection type is deleted locally (answers the stored template). An unknown id answers 500.
+   * @permissions hsm.view OR hsm.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<unknown> {
+    return super.deleteById(id, headers)
+  }
+
+  /**
+   * SENDS the template to Meta for approval (through the provider of the connection). An unknown or archived
+   * template answers 500 before anything is sent.
+   * @permissions hsm.view OR hsm.send OR hsm.send.before.expire
+   */
+  sendToReview(id: string, headers?: Record<string, string>): Promise<unknown> {
+    return this.client.post<unknown>(`${this.basePath}/${id}/send-to-review`, undefined, headers)
+  }
+
+  /**
+   * Reads the templates of the connected `whatsapp-business` connections from the provider and syncs them (it may
+   * archive the local templates the provider no longer has). Resolves the text `'OK'`.
+   * @permissions hsm.view
+   */
+  refreshTemplates(headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/refresh-templates`, undefined, headers)
+  }
+
+  /**
+   * Reads the template balance from 360Dialog. The backend looks for the 360Dialog connection on the whole platform,
+   * not only in the account, and calls 360Dialog when it finds one.
+   * @permissions hsm.view
+   */
+  resume(headers?: Record<string, string>): Promise<Record<string, unknown>[]> {
+    return this.client.get<Record<string, unknown>[]>(`${this.basePath}/resume`, headers)
+  }
 }

package/src/apis/whatsappBusinessTemplates/types.ts

@@ -10,7 +10,8 @@ export type WhatsappBusinessTemplateHeaderFormat = 'TEXT' | 'IMAGE' | 'VIDEO' |
 
 export type WhatsappBusinessTemplateButton = {
   type: string
-  text: string
+  /** Overwritten by the backend on `REQUEST_CONTACT_INFO` buttons. */
+  text?: string
   url?: string
   params?: string[]
   phone_number?: string
@@ -44,11 +45,40 @@ export type WhatsappBusinessTemplate = {
   createdAt: string
   updatedAt: string
   deletedAt: string | null
+  /** Only the listing includes it by default; `getById` answers it with `include: ['fileExample']`. */
+  fileExample?: WhatsappBusinessTemplateFileExample | null
+  // relationships
+  service?: Record<string, unknown>
+  account?: Record<string, unknown>
+}
+
+/** The media example of a template with a media header. */
+export type WhatsappBusinessTemplateFileExample = Record<string, unknown>
+
+/** The media example sent on create/update (`base64Url` as a data URL). */
+export type WhatsappBusinessTemplateFileExampleInput = {
+  fileName: string
+  base64Url: string
+  mimetype: string
 }
 
+export type WhatsappBusinessTemplateHsmLimit = {
+  hsmLimit: number
+  hsmUsedLimit: number
+  /** The balance left (a number), or `true` when the account has no limit. */
+  hasLimit: number | boolean
+}
+
+/**
+ * Stored locally (nothing goes to Meta until `sendToReview`). `status` is `''` for a draft and `namespace` is `''`
+ * until Meta answers — both are required by the database (500 without them).
+ */
 export type CreateWhatsappBusinessTemplatePayload = {
   name: string
   internalName: string
+  status: string
+  namespace: string
+  fileExample?: WhatsappBusinessTemplateFileExampleInput
   components: WhatsappBusinessTemplateComponent[]
   serviceId: string
   messageType: WhatsappBusinessTemplateMessageType
@@ -56,7 +86,14 @@ export type CreateWhatsappBusinessTemplatePayload = {
   category: WhatsappBusinessTemplateCategory
 }
 
+/**
+ * The backend validates the same 7 fields of the create on the update (`name`, `internalName`, `components`,
+ * `serviceId`, `messageType`, `language`, `category`), but ignores `name`.
+ */
 export type UpdateWhatsappBusinessTemplatePayload = {
+  status?: string
+  namespace?: string
+  fileExample?: WhatsappBusinessTemplateFileExampleInput
   name?: string
   internalName?: string
   components?: WhatsappBusinessTemplateComponent[]

package/src/core/BaseCrudApi.test-d.ts

@@ -1,7 +1,7 @@
 import { expectError, expectType } from 'tsd'
 import type { ApiClient } from './ApiClient'
 import { BaseCrudApi } from './BaseCrudApi'
-import type { Paginated } from './types'
+import type { ListQuery, Paginated } from './types'
 
 // ── Test model ──────────────────────────────────────────────────────
 
@@ -40,6 +40,16 @@ expectType<Promise<Item>>(api.create({ name: 'x' }))
 expectType<Promise<Item>>(api.updateById('1', {}))
 expectType<Promise<Item>>(api.deleteById('1'))
 
+// Routes that do not answer the resource on create/update (TCreateResponse, TUpdateResponse)
+const writes = new BaseCrudApi<Item, CreateItem, UpdateItem, ListQuery<Item>, 'OK', void, Item[]>(
+  client,
+  '/items',
+)
+expectType<Promise<void>>(writes.create({ name: 'x' }))
+expectType<Promise<Item[]>>(writes.updateById('1', {}))
+expectType<Promise<'OK'>>(writes.deleteById('1'))
+expectType<Promise<Item>>(writes.getById('1'))
+
 expectError(api.create({}))
 expectError(api.create({ name: 1 }))
 expectError(api.updateById('1', { name: 1 }))

package/src/core/BaseCrudApi.ts

@@ -16,7 +16,9 @@ export type {
 
 /**
  * Generic CRUD resource: the reads of `BaseReadApi` plus `create`, `updateById` and `deleteById`.
- * `TDeleteResponse` is what `deleteById` resolves to (most routes answer the text `'OK'`).
+ * `TDeleteResponse` is what `deleteById` resolves to (most routes answer the text `'OK'`);
+ * `TCreateResponse` and `TUpdateResponse` are what `create` and `updateById` resolve to, for the routes
+ * that do not answer the resource (an empty body, `{}`, another model).
  */
 export class BaseCrudApi<
   TResponse,
@@ -24,24 +26,31 @@ export class BaseCrudApi<
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
   TDeleteResponse = TResponse,
+  TCreateResponse = TResponse,
+  TUpdateResponse = TResponse,
 >
   extends BaseReadApi<TResponse, TQuery>
-  implements CrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse>
+  implements
+    CrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse, TCreateResponse, TUpdateResponse>
 {
   /**
    * Creates a new resource.
    * @permissions $resourceName.create
    */
-  create(body: TCreate, headers?: Record<string, string>): Promise<TResponse> {
-    return this.client.post<TResponse, TCreate>(this.basePath, body, headers)
+  create(body: TCreate, headers?: Record<string, string>): Promise<TCreateResponse> {
+    return this.client.post<TCreateResponse, TCreate>(this.basePath, body, headers)
   }
 
   /**
    * Updates an existing resource by ID.
    * @permissions $resourceName.update
    */
-  updateById(id: string, body: TUpdate, headers?: Record<string, string>): Promise<TResponse> {
-    return this.client.put<TResponse, TUpdate>(`${this.basePath}/${id}`, body, headers)
+  updateById(
+    id: string,
+    body: TUpdate,
+    headers?: Record<string, string>,
+  ): Promise<TUpdateResponse> {
+    return this.client.put<TUpdateResponse, TUpdate>(`${this.basePath}/${id}`, body, headers)
   }
 
   /**

package/src/core/types.ts

@@ -160,8 +160,10 @@ export type CrudApi<
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
   TDeleteResponse = TResponse,
+  TCreateResponse = TResponse,
+  TUpdateResponse = TResponse,
 > = HasGetMany<TResponse, TQuery> &
   HasGetById<TResponse> &
-  HasCreate<TResponse, TCreate> &
-  HasUpdateById<TResponse, TUpdate> &
+  HasCreate<TCreateResponse, TCreate> &
+  HasUpdateById<TUpdateResponse, TUpdate> &
   HasDeleteById<TDeleteResponse>