@ikatec/digisac-api-sdk 4.11.0 → 4.13.0

package/src/apis/me/MeApi.ts

@@ -2,6 +2,11 @@ import { BaseApi } from '../../core/BaseApi'
 import type { Account } from '../accounts/types'
 import type { User } from '../users/types'
 import type {
+  AccountAmounts,
+  AccountAmountsQuery,
+  MeAccountQuery,
+  MeQuery,
+  MeStatusResponse,
   RegisterTokenPayload,
   SetOtpSecretKeyPayload,
   TakeoverPayload,
@@ -10,30 +15,74 @@ import type {
   UpdateMeStatusPayload,
 } from './types'
 
+/**
+ * A query object always has an array or an object among its values; the headers only have strings (a header that
+ * comes as `undefined` at runtime stays a header). That tells the two apart in the methods that took only the
+ * headers before and now take a query first.
+ */
+function splitQueryAndHeaders<TQuery extends object>(
+  queryOrHeaders: TQuery | Record<string, string> | undefined,
+  headers: Record<string, string> | undefined,
+): [TQuery | undefined, Record<string, string> | undefined] {
+  const isQuery =
+    !!queryOrHeaders &&
+    Object.values(queryOrHeaders).some((value) => typeof value === 'object' && value !== null)
+  return isQuery
+    ? [queryOrHeaders as TQuery, headers]
+    : [undefined, queryOrHeaders as Record<string, string> | undefined]
+}
+
 export class MeApi extends BaseApi {
   /**
-   * Returns the currently authenticated user, including their roles, departments, and timetable.
+   * Returns the currently authenticated user. Without `include`, the user comes without relations (roles,
+   * departments, timetable, account).
    * @permissions users.view
    */
-  getMe(headers?: Record<string, string>): Promise<User> {
-    return this.client.get<User>('/me', headers)
+  getMe(headers?: Record<string, string>): Promise<User>
+  getMe(query: MeQuery, headers?: Record<string, string>): Promise<User>
+  getMe(
+    queryOrHeaders?: MeQuery | Record<string, string>,
+    headers?: Record<string, string>,
+  ): Promise<User> {
+    const [query, sent] = splitQueryAndHeaders<MeQuery>(queryOrHeaders, headers)
+    return this.client.get<User>(`/me${this.toQueryString(query)}`, sent)
   }
 
-  /** Returns the account associated with the currently authenticated user. */
-  getAccount(headers?: Record<string, string>): Promise<Account> {
-    return this.client.get<Account>('/me/account', headers)
+  /**
+   * Returns the account of the current user. Send `where.id` with the `accountId` of the user (what the web app
+   * does): without it, the route answers 500.
+   */
+  getAccount(headers?: Record<string, string>): Promise<Account>
+  getAccount(query: MeAccountQuery, headers?: Record<string, string>): Promise<Account>
+  getAccount(
+    queryOrHeaders?: MeAccountQuery | Record<string, string>,
+    headers?: Record<string, string>,
+  ): Promise<Account> {
+    const [query, sent] = splitQueryAndHeaders<MeAccountQuery>(queryOrHeaders, headers)
+    return this.client.get<Account>(`/me/account${this.toQueryString(query)}`, sent)
   }
 
   /**
-   * Returns credit and usage amounts for the current account.
-   * Excludes Digisac's own internal credit amounts.
+   * Returns the amounts of the current account named in `filter` (services and/or users). The credit amounts are
+   * never answered here. An account without credits control answers 400.
    */
-  getAccountAmounts(headers?: Record<string, string>): Promise<Record<string, unknown>> {
-    return this.client.get<Record<string, unknown>>('/me/get-account-amounts', headers)
+  getAccountAmounts(headers?: Record<string, string>): Promise<AccountAmounts>
+  getAccountAmounts(
+    query: AccountAmountsQuery,
+    headers?: Record<string, string>,
+  ): Promise<AccountAmounts>
+  getAccountAmounts(
+    queryOrHeaders?: AccountAmountsQuery | Record<string, string>,
+    headers?: Record<string, string>,
+  ): Promise<AccountAmounts> {
+    const [query, sent] = splitQueryAndHeaders<AccountAmountsQuery>(queryOrHeaders, headers)
+    const queryString = query ? this.toQueryString({ filter: query.filter.join(',') }) : ''
+    return this.client.get<AccountAmounts>(`/me/get-account-amounts${queryString}`, sent)
   }
 
   /**
-   * Returns a URL to the Agnus billing/plan management page for the current account.
+   * Returns a URL to the Agnus billing/plan management page for the current account. Calls Agnus (an external
+   * service) and, for accounts without credits control, reports the consumption to it first.
    * @permissions myAccount.myPlan
    */
   getAgnusMyPlanUrl(headers?: Record<string, string>): Promise<{ url: string }> {
@@ -41,39 +90,45 @@ export class MeApi extends BaseApi {
   }
 
   /**
-   * Updates the current user's profile fields such as name, language, and preferences.
-   * If a new password is provided, it is validated against the last 6 password history entries
-   * and all existing access tokens for the user are revoked.
+   * Updates the current user's profile fields such as name, language, and preferences (`data` and `preferences`
+   * replace the stored objects). A new `password` needs `currentPassword` and a recent login, is validated against
+   * the last 6 passwords, and revokes the access tokens with an expiration — including the one of this request.
    */
   updateMe(body: UpdateMePayload, headers?: Record<string, string>): Promise<User> {
     return this.client.put<User, UpdateMePayload>('/me', body, headers)
   }
 
-  /** Updates account-level settings such as name, settings object, wizard progress, and default department. */
+  /**
+   * Updates account-level settings such as name, settings object, wizard progress, and default department. It
+   * applies to the whole account; the default department is required while the tickets are enabled.
+   */
   updateAccount(body: UpdateMeAccountPayload, headers?: Record<string, string>): Promise<Account> {
     return this.client.put<Account, UpdateMeAccountPayload>('/me/account', body, headers)
   }
 
   /**
-   * Updates the presence status of the current user (`online`, `offline`, or `away`).
+   * Updates the presence status of the current user (`online`, `offline`, or `away`) for a `client`.
    * If setting to `online`, validates the user's timetable first — if outside working hours,
-   * the status is set to `offline` instead.
+   * the status is set to `offline` instead. Resolves the status fields of the user.
    */
-  updateStatus(body: UpdateMeStatusPayload, headers?: Record<string, string>): Promise<User> {
-    return this.client.put<User, UpdateMeStatusPayload>('/me/status', body, headers)
+  updateStatus(
+    body: UpdateMeStatusPayload,
+    headers?: Record<string, string>,
+  ): Promise<MeStatusResponse> {
+    return this.client.put<MeStatusResponse, UpdateMeStatusPayload>('/me/status', body, headers)
   }
 
   /**
-   * Extends the grace period for the current account when it has expired or is about to expire.
-   * Returns the updated account.
+   * Extends the grace period for the current account when it has expired or is about to expire, and notifies the
+   * billing webhook. Returns the updated account; an account not in a grace period answers 400.
    */
   extendAccountGracePeriod(headers?: Record<string, string>): Promise<Account> {
     return this.client.post<Account>('/me/account/extend-grace-period', undefined, headers)
   }
 
   /**
-   * Registers a OneSignal push notification token for the current user.
-   * Used to enable push notifications on mobile/web clients.
+   * Registers the push notification tokens of the current user (`data` replaces the whole `data` of the user).
+   * Resolves with no body.
    */
   registerToken(body: RegisterTokenPayload, headers?: Record<string, string>): Promise<void> {
     return this.client.post<void, RegisterTokenPayload>(
@@ -89,8 +144,8 @@ export class MeApi extends BaseApi {
   }
 
   /**
-   * Sets the current user's status to `online` for the given client and emits a takeover event,
-   * which signals other connected sessions to yield control to this one.
+   * Sets the current user's status to `online` for the given client (`'web'` by default) and emits a takeover
+   * event, which signals other connected sessions to yield control to this one. Resolves with no body.
    */
   takeover(body?: TakeoverPayload, headers?: Record<string, string>): Promise<void> {
     return this.client.post<void, TakeoverPayload>('/me/takeover', body, headers)
@@ -107,9 +162,9 @@ export class MeApi extends BaseApi {
   /**
    * Activates OTP (two-factor) authentication for the current user.
    * Requires the `x-digisac-otp` header with a valid TOTP token generated from the secret key
-   * previously set via `setOtpSecretKey`.
+   * previously set via `setOtpSecretKey`. Resolves the text `'OK'`.
    */
-  activateOtpAuth(headers?: Record<string, string>): Promise<boolean> {
-    return this.client.post<boolean>('/me/activate-otp-auth', undefined, headers)
+  activateOtpAuth(headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>('/me/activate-otp-auth', undefined, headers)
   }
 }

package/src/apis/me/types.ts

@@ -2,9 +2,68 @@ import type { AccountSettings } from '../accounts/types'
 import type { UserPreferences } from '../users/types'
 import type { UserStatus } from '../users/types'
 
+/** The client of the session that sets the status: the web app or the mobile app. */
+export type MeClient = 'web' | 'app'
+
+/** Query of `GET /me`: without `include`, the user comes without relations. */
+export type MeQuery = {
+  include?: (
+    | 'roles'
+    | 'departments'
+    | 'timetable'
+    | 'account'
+    | 'permissions'
+    | 'organizations'
+    | (string & {})
+  )[]
+  attributes?: string[]
+}
+
+/** Query of `GET /me/account`: `where.id` is the id of the account of the user (`accountId` of `getMe`). */
+export type MeAccountQuery = {
+  where: { id: string }
+  include?: string[]
+  attributes?: string[]
+}
+
+export type AccountAmountsFilter = 'services.amounts' | 'users.amounts'
+
+/** Query of `GET /me/get-account-amounts`: which amounts to answer (the credit amounts are never answered). */
+export type AccountAmountsQuery = {
+  filter: AccountAmountsFilter[]
+}
+
+export type UsersAmounts = {
+  planBase: number
+  additional: number
+  totalContracted: number
+  planBaseConsumed: number
+  additionalConsumed: number
+  totalConsumed: number
+  available: number
+}
+
+export type AccountAmounts = {
+  accountId: string
+  servicesAmounts?: Record<string, unknown>
+  usersAmounts?: UsersAmounts
+}
+
+/** What `updateStatus` answers: the status fields of the user, not the whole user. */
+export type MeStatusResponse = {
+  id: string
+  updatedAt: string
+  status: UserStatus
+  clientsStatus: Partial<Record<MeClient, UserStatus>>
+  language: string
+  account?: unknown
+}
+
 export type UpdateMePayload = {
   name?: string
   password?: string
+  /** Required with `password`: the current password of the user. */
+  currentPassword?: string
   language?: string
   preferences?: UserPreferences
   otpAuthActive?: boolean
@@ -14,22 +73,34 @@ export type UpdateMePayload = {
 
 export type UpdateMeStatusPayload = {
   status: UserStatus
-  client?: string
+  /** Required by the backend (400 without it). */
+  client?: MeClient
 }
 
+/**
+ * Merged over the account. The default department is required while the tickets are enabled
+ * (`settings.ticketsEnabled`; 400 `DEFAULT_DEPARTMENT_REQUIRED`).
+ */
 export type UpdateMeAccountPayload = {
   name?: string
   settings?: Partial<AccountSettings>
-  wizardProgress?: string
+  wizardProgress?: 'notStarted' | 'started' | 'finished' | (string & {})
   defaultDepartmentId?: string
+  defaultDepartment?: { id: string }
 }
 
 export type TakeoverPayload = {
-  client?: string
+  /** Defaults to `'web'`. */
+  client?: MeClient
 }
 
 export type SetOtpSecretKeyPayload = {
   secretKey: string
 }
 
-export type RegisterTokenPayload = Record<string, unknown>
+/** The push tokens of the user. `data` REPLACES the whole `data` of the user (it is not merged). */
+export type RegisterTokenPayload = {
+  data?: { oneSignalToken?: string; expoPushToken?: string | null; fromApp?: boolean }
+  /** The backend ignores the call when it is `true`. */
+  isClientUser?: boolean
+}

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 = {