@ikatec/digisac-api-sdk 4.12.0 → 4.13.0

package/src/apis/notifications/NotificationsApi.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { NotificationsApi } from './NotificationsApi'
+import type { ApiClient } from '../../core/ApiClient'
+
+// ── Mock client factory ──────────────────────────────────────────────
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    requestRaw: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('NotificationsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: NotificationsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new NotificationsApi(client)
+  })
+
+  it('count posts to /notifications/count and resolves the counts as text', async () => {
+    const counts = { count: { total: '3', read: '1', unread: '2' } }
+    vi.mocked(client.post).mockResolvedValue(counts)
+    await expect(api.count()).resolves.toEqual(counts)
+    expect(client.post).toHaveBeenCalledWith('/notifications/count', undefined, undefined)
+  })
+
+  it('read puts to /notifications/:id/read', async () => {
+    await api.read('n-1')
+    expect(client.put).toHaveBeenCalledWith('/notifications/n-1/read', undefined, undefined)
+  })
+
+  it('unread puts to /notifications/:id/unread', async () => {
+    await api.unread('n-1')
+    expect(client.put).toHaveBeenCalledWith('/notifications/n-1/unread', undefined, undefined)
+  })
+
+  it('readMany posts the ids as the body', async () => {
+    await api.readMany(['n-1', 'n-2'])
+    expect(client.post).toHaveBeenCalledWith('/notifications/read-many', ['n-1', 'n-2'], undefined)
+  })
+
+  it('readAll calls client.get with /notifications/read-all', async () => {
+    vi.mocked(client.get).mockResolvedValue({ total: 2, read: 2, unread: 0 })
+    await expect(api.readAll()).resolves.toEqual({ total: 2, read: 2, unread: 0 })
+    expect(client.get).toHaveBeenCalledWith('/notifications/read-all', undefined)
+  })
+
+  it('resetBadgeCount posts to /notifications/reset-badge-count', async () => {
+    vi.mocked(client.post).mockResolvedValue({ success: true })
+    await expect(api.resetBadgeCount()).resolves.toEqual({ success: true })
+    expect(client.post).toHaveBeenCalledWith(
+      '/notifications/reset-badge-count',
+      undefined,
+      undefined,
+    )
+  })
+
+  it('sendAll posts the announcement to /notifications/send-all', async () => {
+    const body = { text: 'Aviso', to: 'admin' as const }
+    await api.sendAll(body)
+    expect(client.post).toHaveBeenCalledWith('/notifications/send-all', body, undefined)
+  })
+})

package/src/apis/notifications/NotificationsApi.ts

@@ -1,8 +1,19 @@
 import type { ApiClient } from '../../core/ApiClient'
 import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Notification, CreateNotificationPayload, UpdateNotificationPayload } from './types'
+import type {
+  Notification,
+  CreateNotificationPayload,
+  UpdateNotificationPayload,
+  NotificationCountsResponse,
+  NotificationReadAllResponse,
+  SendAllNotificationsPayload,
+} from './types'
 
+/**
+ * Notifications of the current user (all of the account with `notification.view.all`). Some types open a modal in the web app as soon as they arrive (`announcement`, `credits-90`,
+ * `credits-100`, `smart-summary`, `warn-service-reconnect`).
+ */
 export class NotificationsApi extends BaseCrudApi<
   Notification,
   CreateNotificationPayload,
@@ -15,10 +26,84 @@ export class NotificationsApi extends BaseCrudApi<
   }
 
   /**
-   * Deletes a notification. Resolves the text `'OK'`; an unknown id answers 500. The route checks
-   * no permission.
+   * Deletes a notification. Resolves the text `'OK'`; an unknown id answers 500.
    */
   override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
     return super.deleteById(id, headers)
   }
+
+  /**
+   * Counts the notifications the user sees: `{ count: { total, read, unread } }`, as TEXT.
+   */
+  count(headers?: Record<string, string>): Promise<NotificationCountsResponse> {
+    return this.client.post<NotificationCountsResponse>(
+      `${this.basePath}/count`,
+      undefined,
+      headers,
+    )
+  }
+
+  /**
+   * Marks a notification as read for the current user and resolves the new counts. An unknown id answers
+   * 400 `Notification not found.`.
+   */
+  read(id: string, headers?: Record<string, string>): Promise<NotificationCountsResponse> {
+    return this.client.put<NotificationCountsResponse>(
+      `${this.basePath}/${id}/read`,
+      undefined,
+      headers,
+    )
+  }
+
+  /**
+   * Marks a notification as unread for the current user and resolves the new counts. An unknown id
+   * answers 400 `Notification not found.`.
+   */
+  unread(id: string, headers?: Record<string, string>): Promise<NotificationCountsResponse> {
+    return this.client.put<NotificationCountsResponse>(
+      `${this.basePath}/${id}/unread`,
+      undefined,
+      headers,
+    )
+  }
+
+  /**
+   * Marks the notifications of `ids` as read. Resolves with no body; a body that is not an array answers
+   * 500 `Body must be an array of notification IDs`.
+   */
+  readMany(ids: string[], headers?: Record<string, string>): Promise<void> {
+    return this.client.post<void, string[]>(`${this.basePath}/read-many`, ids, headers)
+  }
+
+  /**
+   * Marks every notification the user sees as read (a GET that writes: it recreates the read receipts of
+   * the user) and resolves the counts, as numbers.
+   */
+  readAll(headers?: Record<string, string>): Promise<NotificationReadAllResponse> {
+    return this.client.get<NotificationReadAllResponse>(`${this.basePath}/read-all`, headers)
+  }
+
+  /** Clears the push badge counter of the current user. Resolves `{ success: true }`. */
+  resetBadgeCount(headers?: Record<string, string>): Promise<{ success: true }> {
+    return this.client.post<{ success: true }>(
+      `${this.basePath}/reset-badge-count`,
+      undefined,
+      headers,
+    )
+  }
+
+  /**
+   * SENDS an announcement (`type: 'announcement'`, which opens a modal in the web app) to every user of
+   * the account, or only to the admins with `to: 'admin'`. Resolves `{ message: 'Notificações enviadas' }` before the notifications are created.
+   */
+  sendAll(
+    body: SendAllNotificationsPayload,
+    headers?: Record<string, string>,
+  ): Promise<{ message: string }> {
+    return this.client.post<{ message: string }, SendAllNotificationsPayload>(
+      `${this.basePath}/send-all`,
+      body,
+      headers,
+    )
+  }
 }

package/src/apis/notifications/types.ts

@@ -13,46 +13,104 @@ export type NotificationType =
   | 'undefined'
   | 'waba-health-warning'
   | 'waba-health-block'
+  | 'kanban-board-initialized'
+  | 'users-bulk-archive-blocked'
+  | 'user-import'
+  | 'credits-90'
+  | 'credits-100'
+  | 'smart-summary'
+  | 'warn-service-reconnect'
 
-/** Present on pipeline-related notifications. */
+/** Extra data of the notification; the pipeline notifications carry the pipeline ids. */
 export type NotificationConfig = {
-  pipelineId: string
-  pipelineAutomationId: string
+  pipelineId?: string
+  pipelineAutomationId?: string
+  [key: string]: unknown
+}
+
+/** The read receipt of a notification for the current user. */
+export type NotificationRead = {
+  id: string
+  notificationId: string
+  userId: string
+  readAt: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * Counts of the notifications the user sees (all of the account with `notification.view.all`).
+ * They come as TEXT: the backend answers the `COUNT` of the database as is (e.g. `"43"`).
+ */
+export type NotificationCounts = {
+  total: string
+  read: string
+  unread: string
+}
+
+/** What `read`, `unread` and `count` answer. */
+export type NotificationCountsResponse = {
+  count: NotificationCounts
+}
+
+/** What `readAll` answers: the counts after marking everything as read, as numbers. */
+export type NotificationReadAllResponse = {
+  total: number
+  read: number
+  unread: number
+}
+
+/** The body of `sendAll`: `to: 'admin'` sends only to the admins; any other value sends to every user. */
+export type SendAllNotificationsPayload = {
+  /** Up to 255 characters. */
+  text: string
+  to: 'admin' | 'all' | (string & {})
+  image?: string
 }
 
 export type Notification = {
   id: string
   text: string
   type: NotificationType | null
-  read: boolean
+  /** `null` on the announcements of `sendAll` until they are read. */
+  read: boolean | null
   image: string | null
   label: string | null
   config: NotificationConfig | null
   attachedType: string | null
+  attachedId: string | null
+  notificationReadId: string | null
   contactId: string | null
   userId: string
   accountId: string
   scheduleId: string | null
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
+  /** @deprecated Not answered: the transformer of the backend does not send it. */
+  deletedAt?: string | null
   // relationships
   user?: User
   schedule?: Schedule | null
+  /** @deprecated Not served: the model has no such association, so it never comes. */
   contact?: Contact | null
+  notificationRead?: NotificationRead | null
 }
 
-export type NotificationRelationships = 'user' | 'schedule' | 'contact'
+/** The backend serves `user`, `schedule` and `notificationRead` (`contact` is never answered). */
+export type NotificationRelationships = 'user' | 'schedule' | 'contact' | 'notificationRead'
 
 export type CreateNotificationPayload = {
+  /** Up to 255 characters. */
   text: string
-  userId: string
+  /** Ignored: the backend creates the notification for the current user. */
+  userId?: string
   type?: NotificationType
   label?: string
   config?: NotificationConfig
   attachedType?: string
   contactId?: string
   scheduleId?: string
+  image?: string
 }
 
 export type UpdateNotificationPayload = {

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

@@ -71,6 +71,14 @@ import { KnowledgeBaseApi } from './knowledgeBase/KnowledgeBaseApi'
 import { KnowledgeBaseItemApi } from './knowledgeBaseItem/KnowledgeBaseItemApi'
 import { MessagesApi } from './messages/MessagesApi'
 import { NotificationsApi } from './notifications/NotificationsApi'
+import type { NotificationCountsResponse } from './notifications/types'
+import { AbsenceApi } from './absence/AbsenceApi'
+import type { AbsenceReportItem, UnlockAbsenceResponse } from './absence/types'
+import { ActivityLogApi } from './activityLog/ActivityLogApi'
+import { CreditMovementsApi } from './creditMovements/CreditMovementsApi'
+import type { CreditBalances, CreditTotalServices } from './creditMovements/types'
+import { StickersApi } from './stickers/StickersApi'
+import type { Sticker } from './stickers/types'
 import { OrganizationsApi } from './organizations/OrganizationsApi'
 import { PeopleApi } from './people/PeopleApi'
 import { ServicesApi } from './services/ServicesApi'
@@ -703,3 +711,41 @@ expectAssignable<ApiClient>({
   patch: async <T>() => undefined as T,
   delete: async <T>() => undefined as T,
 })
+
+// ── QARC-1010: notifications, absence, log, knowledge base, credits, stickers ─────
+
+expectType<Promise<NotificationCountsResponse>>(new NotificationsApi(client).count())
+expectType<Promise<string>>(new NotificationsApi(client).count().then(({ count }) => count.total))
+expectError(new NotificationsApi(client).sendAll({ to: 'admin' }))
+expectType<Promise<void>>(new NotificationsApi(client).readMany(['n-1']))
+expectType<Promise<Paginated<AbsenceReportItem>>>(
+  new AbsenceApi(client).report({ filters: { reason: 'x' }, order: 'ASC' }),
+)
+expectType<Promise<UnlockAbsenceResponse>>(new AbsenceApi(client).unlock({}))
+expectError(new AbsenceApi(client).report({ sort: 'name' }))
+expectType<Promise<string>>(
+  new ActivityLogApi(client).exportCsv({ filters: { from: 'a', to: 'b' } }),
+)
+expectAssignable<Parameters<ActivityLogApi['create']>[0]>({
+  resourceType: 'contact',
+  event: 'update',
+})
+expectType<Promise<true>>(new KnowledgeBaseItemApi(client).deleteMany(['i-1']))
+expectError(
+  new KnowledgeBaseApi(client).saveWithItems({ name: 'qa', items: [{ name: 'x', type: 'pdf' }] }),
+)
+expectType<Promise<CreditBalances>>(new CreditMovementsApi(client).balances())
+expectType<Promise<number>>(new CreditMovementsApi(client).balance('sms-wavy'))
+expectType<Promise<CreditTotalServices | undefined>>(
+  new CreditMovementsApi(client).totalServices({
+    filters: { from: 'a', to: 'b', serviceType: 'summary' },
+    page: 1,
+  }),
+)
+expectType<Promise<ArrayBuffer>>(
+  new CreditMovementsApi(client).exportXlsx({ from: 'a', to: 'b', where: { $and: [] } }),
+)
+expectType<Promise<Sticker>>(new StickersApi(client).create({ base64: 'iVBOR', name: 'qa' }))
+expectError(new StickersApi(client).create({ type: 'created' }))
+expectType<Promise<'OK' | false>>(new StickersApi(client).remove('s-1'))
+expectAssignable<Parameters<StickersApi['getMany']>[0]>({ include: ['file'] })

package/src/apis/serviceAccessManagement/ServiceAccessManagementApi.ts

@@ -6,7 +6,10 @@ export class ServiceAccessManagementApi
   extends BaseApi
   implements HasGetMany<ServiceAccessManagement>
 {
-  /** Returns a paginated list of which users have access to which services. */
+  /**
+   * The connections denied to each user (one row per user × connection, written by
+   * `POST /services/:id/access-management`), raw. Filter by the `serviceId` or `userId` you want.
+   */
   getMany(
     query: ListQuery<ServiceAccessManagement> & { paginate: false },
     headers?: Record<string, string>,

package/src/apis/serviceAccessManagement/types.ts

@@ -6,8 +6,11 @@ export type ServiceAccessManagement = {
   serviceId: string
   createdAt: string
   // relationships
+  /** @deprecated Not served: the backend drops every include of this route. */
   user?: User
+  /** @deprecated Not served: the backend drops every include of this route. */
   service?: Service
 }
 
+/** None is served: the backend drops every include of this route. */
 export type ServiceAccessManagementRelationships = 'user' | 'service'

package/src/apis/stickerUsers/StickerUsersApi.ts

@@ -4,7 +4,9 @@ import type { StickerUser } from './types'
 
 export class StickerUsersApi extends BaseApi implements HasGetMany<StickerUser> {
   /**
-   * Returns a paginated list of sticker-user associations with their related file.
+   * The stickers the current user sent recently (`lastSendAt`), paginated; only the `file` include is
+   * served. A row is written when the user sends a message of type `sticker` (in the background, after the
+   * send).
    * @permissions stickers.send
    */
   getMany(

package/src/apis/stickerUsers/types.ts

@@ -10,9 +10,13 @@ export type StickerUser = {
   createdAt: string
   updatedAt: string
   // relationships
+  /** @deprecated Not served: the backend only serves the `file` include. */
   sticker?: Sticker
+  /** @deprecated Not served: the backend only serves the `file` include. */
   user?: User
+  /** The image of the sticker. */
   file?: File
 }
 
+/** The backend serves only `file` (`sticker` and `user` are dropped). */
 export type StickerUserRelationships = 'sticker' | 'user' | 'file'

package/src/apis/stickers/StickersApi.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { StickersApi } from './StickersApi'
+import type { ApiClient } from '../../core/ApiClient'
+
+// ── Mock client factory ──────────────────────────────────────────────
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    requestRaw: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('StickersApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: StickersApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new StickersApi(client)
+  })
+
+  it('create posts the image to /stickers', async () => {
+    await api.create({ base64: 'iVBOR', name: 'qa' })
+    expect(client.post).toHaveBeenCalledWith(
+      '/stickers',
+      { base64: 'iVBOR', name: 'qa' },
+      undefined,
+    )
+  })
+
+  it('exist serializes the message and the checksum', async () => {
+    vi.mocked(client.get).mockResolvedValue({})
+    await expect(api.exist({ messageId: 'm-1', fileChecksum: 'abc' })).resolves.toEqual({})
+    const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
+    expect(url).toMatch(/^\/stickers\/exist\?/)
+    expect(decodeURIComponent(url)).toContain('"fileChecksum":"abc"')
+  })
+
+  it('add posts the message to /stickers/add', async () => {
+    await api.add('m-1')
+    expect(client.post).toHaveBeenCalledWith('/stickers/add', { messageId: 'm-1' }, undefined)
+  })
+
+  it('remove deletes /stickers/remove/:stickerId', async () => {
+    vi.mocked(client.delete).mockResolvedValue('OK')
+    await expect(api.remove('s-1')).resolves.toBe('OK')
+    expect(client.delete).toHaveBeenCalledWith('/stickers/remove/s-1', undefined)
+  })
+})

package/src/apis/stickers/StickersApi.ts

@@ -1,12 +1,18 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { GetByIdQuery } from '../../core/types'
-import type { Sticker, CreateStickerPayload, UpdateStickerPayload } from './types'
+import type {
+  Sticker,
+  CreateStickerPayload,
+  UpdateStickerPayload,
+  StickerExistQuery,
+} from './types'
 
 /**
- * Stickers of the account. The backend serves `GET /stickers` and `POST /stickers` (plus
- * `GET /stickers/exist`, `POST /stickers/add` and `DELETE /stickers/remove/:stickerId`); there is
- * no read by id, update nor `DELETE /stickers/:id`.
+ * Stickers of the account: every user of the account sees them. The backend serves `GET /stickers`,
+ * `POST /stickers`, `GET /stickers/exist`, `POST /stickers/add` and `DELETE /stickers/remove/:stickerId`;
+ * there is no read by id, update nor `DELETE /stickers/:id`. The list accepts only the `file` include.
+ * @permissions stickers.send (list) · stickers.management (create, exist, add, remove)
  */
 export class StickersApi extends BaseCrudApi<Sticker, CreateStickerPayload, UpdateStickerPayload> {
   constructor(client: ApiClient) {
@@ -38,4 +44,40 @@ export class StickersApi extends BaseCrudApi<Sticker, CreateStickerPayload, Upda
   override deleteById(id: string, headers?: Record<string, string>): Promise<Sticker> {
     return super.deleteById(id, headers)
   }
+
+  /**
+   * Finds the sticker of the account that came from the message, or from the file of `fileChecksum` or
+   * `filehash`. Resolves `{ stickerId }`, or `{}` when there is none; without `messageId` it answers 500
+   * `Invalid message ID`.
+   */
+  exist(
+    query: StickerExistQuery,
+    headers?: Record<string, string>,
+  ): Promise<{ stickerId?: string }> {
+    return this.client.get<{ stickerId?: string }>(
+      `${this.basePath}/exist${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Turns the file of a message of the account into a sticker (`type: 'added'`). Idempotent: a sticker that
+   * already came from the message (or its file) is answered as is, and a removed one is restored. A message
+   * without file answers 500 `Message or file not found`.
+   */
+  add(messageId: string, headers?: Record<string, string>): Promise<Sticker> {
+    return this.client.post<Sticker, { messageId: string }>(
+      `${this.basePath}/add`,
+      { messageId },
+      headers,
+    )
+  }
+
+  /**
+   * Removes a sticker of the account (soft delete; its file stays in the storage) and clears it from the
+   * recent stickers of every user. Resolves the text `'OK'`, or `false` when there is no such sticker.
+   */
+  remove(stickerId: string, headers?: Record<string, string>): Promise<'OK' | false> {
+    return this.client.delete<'OK' | false>(`${this.basePath}/remove/${stickerId}`, headers)
+  }
 }

package/src/apis/stickers/types.ts

@@ -1,8 +1,11 @@
+import type { File } from '../files/types'
 import type { User } from '../users/types'
 
+/** A sticker of the account (every user of the account sees it). */
 export type Sticker = {
   id: string
-  type: string
+  /** `'created'` (uploaded with `create`) or `'added'` (taken from a message with `add`). */
+  type: 'created' | 'added' | (string & {})
   originFileChecksum: string | null
   originFilehash: string | null
   originMessageId: string | null
@@ -10,20 +13,42 @@ export type Sticker = {
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
+  deletedAt?: string | null
   // relationships
+  /** @deprecated Not served: the backend only serves the `file` include. */
   user?: User
+  /** The image (webp) of the sticker. */
+  file?: File
 }
 
-export type StickerRelationships = 'user'
+/** The backend serves only `file` (`user` is dropped). */
+export type StickerRelationships = 'user' | 'file'
 
+/**
+ * Uploads an image as a sticker: the backend converts it to a 512x512 webp (413 when it ends up too large:
+ * 100KB static, 500KB animated). `base64` without the `data:...;base64,` prefix.
+ */
 export type CreateStickerPayload = {
-  type: string
+  base64: string
+  /** The name of the file (`<name>.webp`). */
+  name: string
+  /** @deprecated Ignored by the backend: a created sticker is always `'created'`. */
+  type?: string
+  /** @deprecated Ignored by the backend: use `add` to take a sticker from a message. */
   originMessageId?: string
+  /** @deprecated Ignored by the backend. */
   originFileChecksum?: string
+  /** @deprecated Ignored by the backend. */
   originFilehash?: string
 }
 
 export type UpdateStickerPayload = {
   type?: string
 }
+
+/** Query of `exist`: finds a sticker of the account by the message or by the file it came from. */
+export type StickerExistQuery = {
+  messageId: string
+  fileChecksum?: string
+  filehash?: string
+}

package/src/apis/whatsappBusinessTemplates/WhatsappBusinessTemplatesApi.ts

@@ -81,8 +81,7 @@ export class WhatsappBusinessTemplatesApi extends BaseCrudApi<
   }
 
   /**
-   * 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.
+   * Reads the template balance from 360Dialog (an external call, when there is a 360Dialog connection).
    * @permissions hsm.view
    */
   resume(headers?: Record<string, string>): Promise<Record<string, unknown>[]> {