@ikatec/digisac-api-sdk 4.1.0 → 4.3.0

package/src/apis/dashboard/DashboardApi.ts

@@ -0,0 +1,146 @@
+import { BaseApi } from '../../core/BaseApi'
+import type {
+  DashboardDepartmentItem,
+  DashboardGeneral,
+  DashboardGrouped,
+  DashboardPeriodItem,
+  DashboardQuery,
+  DashboardServiceItem,
+  DashboardTopicItem,
+  DashboardUserItem,
+  DashboardWithTotals,
+} from './types'
+
+/**
+ * Service statistics ("Estatísticas de atendimento"). The `/dashboard` routes only require an
+ * authenticated user (no permission check). Every route takes the same {@link DashboardQuery}
+ * filters; the grouped routes answer one item per day, user, department, topic or connection.
+ */
+export class DashboardApi extends BaseApi {
+  public readonly basePath = '/dashboard'
+
+  /** Message, ticket, contact and time counts of the period (`GET /dashboard/general`). */
+  getGeneral(query?: DashboardQuery, headers?: Record<string, string>): Promise<DashboardGeneral> {
+    return this.client.get<DashboardGeneral>(
+      `${this.basePath}/general${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * The counts of each bucket of the period (`GET /dashboard/by-period`): one item per day by default,
+   * or per `grouping` (hour, week, month, year). With `withTotals: true` the answer is
+   * `{ totals, items }`.
+   */
+  getByPeriod(
+    query: DashboardQuery & { withTotals: true },
+    headers?: Record<string, string>,
+  ): Promise<DashboardGrouped<DashboardPeriodItem>>
+  getByPeriod(
+    query?: DashboardQuery & { withTotals?: false },
+    headers?: Record<string, string>,
+  ): Promise<DashboardPeriodItem[]>
+  /** When `withTotals` is only known at runtime (e.g. a `boolean` variable). */
+  getByPeriod(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>>
+  getByPeriod(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>> {
+    return this.getGrouped<DashboardPeriodItem>('by-period', query, headers)
+  }
+
+  /**
+   * The counts of each user of the period (`GET /dashboard/by-user`). With `withTotals: true` the
+   * answer is `{ totals, items }`.
+   */
+  getByUser(
+    query: DashboardQuery & { withTotals: true },
+    headers?: Record<string, string>,
+  ): Promise<DashboardGrouped<DashboardUserItem>>
+  getByUser(
+    query?: DashboardQuery & { withTotals?: false },
+    headers?: Record<string, string>,
+  ): Promise<DashboardUserItem[]>
+  /** When `withTotals` is only known at runtime (e.g. a `boolean` variable). */
+  getByUser(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardUserItem[] | DashboardGrouped<DashboardUserItem>>
+  getByUser(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardUserItem[] | DashboardGrouped<DashboardUserItem>> {
+    return this.getGrouped<DashboardUserItem>('by-user', query, headers)
+  }
+
+  /**
+   * The counts of each department of the period (`GET /dashboard/by-department`). With
+   * `withTotals: true` the answer is `{ totals, items }`.
+   */
+  getByDepartment(
+    query: DashboardQuery & { withTotals: true },
+    headers?: Record<string, string>,
+  ): Promise<DashboardGrouped<DashboardDepartmentItem>>
+  getByDepartment(
+    query?: DashboardQuery & { withTotals?: false },
+    headers?: Record<string, string>,
+  ): Promise<DashboardDepartmentItem[]>
+  /** When `withTotals` is only known at runtime (e.g. a `boolean` variable). */
+  getByDepartment(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardDepartmentItem[] | DashboardGrouped<DashboardDepartmentItem>>
+  getByDepartment(
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<DashboardDepartmentItem[] | DashboardGrouped<DashboardDepartmentItem>> {
+    return this.getGrouped<DashboardDepartmentItem>('by-department', query, headers)
+  }
+
+  /**
+   * The counts of each ticket topic of the period (`GET /dashboard/by-topic`). Does not take
+   * `withTotals` (the backend ignores it).
+   */
+  getByTopic(
+    query?: DashboardQuery,
+    headers?: Record<string, string>,
+  ): Promise<DashboardTopicItem[]> {
+    return this.client.get<DashboardTopicItem[]>(
+      `${this.basePath}/by-topic${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * The counts of each connection of the period (`GET /dashboard/by-service`). Does not take
+   * `withTotals` (the backend ignores it).
+   */
+  getByService(
+    query?: DashboardQuery,
+    headers?: Record<string, string>,
+  ): Promise<DashboardServiceItem[]> {
+    return this.client.get<DashboardServiceItem[]>(
+      `${this.basePath}/by-service${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * `withTotals` is only sent when `true`: the backend reads it with a truthiness check, so in the
+   * `qs` format a serialized `withTotals=false` (the string `'false'`) would wrap the answer anyway.
+   */
+  private getGrouped<TItem>(
+    route: string,
+    query?: DashboardQuery & DashboardWithTotals,
+    headers?: Record<string, string>,
+  ): Promise<TItem[] | DashboardGrouped<TItem>> {
+    const { withTotals, ...filters } = query ?? {}
+    return this.client.get<TItem[] | DashboardGrouped<TItem>>(
+      `${this.basePath}/${route}${this.toQueryString(withTotals ? { ...filters, withTotals: true } : filters)}`,
+      headers,
+    )
+  }
+}

package/src/apis/dashboard/index.ts

@@ -0,0 +1,2 @@
+export { DashboardApi } from './DashboardApi'
+export type * from './types'

package/src/apis/dashboard/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Granularity of the by-period items (`grouping`). Default: `daily`. Whatever the granularity, the
+ * `name` of each item is its day (`dd/MM/yyyy`), so with `hourly` the items of one day share the same
+ * `name` (they come in chronological order).
+ */
+export type DashboardGrouping = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly'
+
+/**
+ * Filters of the service statistics (`/dashboard`). Every field is optional; the period defaults to
+ * the last 7 days.
+ */
+export type DashboardQuery = {
+  /** ISO date-time. Default: 7 days ago, 00:00. */
+  startPeriod?: string
+  /** ISO date-time. Default: the end of the `startPeriod` day (or of today). */
+  endPeriod?: string
+  /** Which ticket date the period filters: opening (default) or closing. */
+  periodType?: 'openDate' | 'closeDate'
+  /** Ticket status (`closed`, not `close`). */
+  status?: 'all' | 'open' | 'closed'
+  /**
+   * A department id, a list of ids, or `all`. Only applied together with `departmentParticipation`:
+   * without it the backend ignores `departmentId` and answers the totals of every department.
+   */
+  departmentId?: string | string[]
+  /**
+   * Whether the department must be the ticket's last one or any one it went through. Required for
+   * `departmentId` to filter; sent WITHOUT `departmentId`, it filters the tickets with no department.
+   */
+  departmentParticipation?: 'last' | 'middle'
+  /**
+   * A user id, a list of ids, or `all`. Only applied together with `userParticipation`: without it
+   * the backend ignores `userId` and answers the totals of every user.
+   */
+  userId?: string | string[]
+  /**
+   * Whether the user must be the ticket's last one or any one it went through. Required for `userId`
+   * to filter; sent WITHOUT `userId`, it filters the tickets with no user.
+   */
+  userParticipation?: 'last' | 'middle'
+  userStatus?: 'active' | 'archived' | 'all'
+  serviceId?: string | string[]
+  tagId?: string | string[]
+  ticketTopicId?: string | string[]
+  /**
+   * Granularity of the `getByPeriod` items (the other routes ignore it). Default: `daily`. See
+   * {@link DashboardGrouping} for the `name` of the items.
+   */
+  grouping?: DashboardGrouping
+}
+
+/**
+ * `withTotals: true` makes `getByPeriod`, `getByUser` and `getByDepartment` answer `{ totals, items }`,
+ * where `totals` are the `getGeneral` counts of the same filters (`getByTopic` and `getByService` do
+ * not take it). Kept out of `DashboardQuery` so a query without it keeps the plain array overload.
+ * Only sent to the backend when `true`.
+ */
+export type DashboardWithTotals = { withTotals?: boolean }
+
+/** `GET /dashboard/general` — counts of the period. Times are in seconds. */
+export type DashboardGeneral = {
+  sentMessagesCount: number
+  receivedMessagesCount: number
+  totalMessagesCount: number
+  openedTicketsCount: number
+  closedTicketsCount: number
+  totalTicketsCount: number
+  waitingTime: number
+  waitingTimeAfterBot: number
+  waitingTimeAvg: number
+  ticketTime: number
+  contactsCount: number
+}
+
+/**
+ * Counts shared by the grouped routes (`by-period`, `by-user`, `by-department`, `by-topic`,
+ * `by-service`). The backend builds each item from the rows it found, so a count is ABSENT (not 0)
+ * when the group has no row for it: read them with a default. Times are in seconds.
+ */
+export type DashboardGroupCounts = {
+  sentMessagesCount?: number
+  receivedMessagesCount?: number
+  openedTicketsCount?: number
+  closedTicketsCount?: number
+  waitingTime?: number
+  ticketTime?: number
+  contactsCount?: number
+}
+
+/** `GET /dashboard/by-period` — the counts of one day of the period (`name` as `dd/MM/yyyy`). */
+export type DashboardPeriodItem = DashboardGroupCounts & {
+  name: string
+  totalMessagesCount?: number
+  totalTicketsCount?: number
+  waitingTimeAfterBot?: number
+  waitingTimeAvg?: number
+}
+
+/** `GET /dashboard/by-user` — the counts of one user (`name` is the user's name). */
+export type DashboardUserItem = DashboardGroupCounts & {
+  name: string
+  ticketTopicsCount?: number
+}
+
+/** `GET /dashboard/by-department` — the counts of one department (`name` is its name). */
+export type DashboardDepartmentItem = DashboardGroupCounts & {
+  name: string
+  ticketTopicsCount?: number
+}
+
+/** `GET /dashboard/by-topic` — the counts of one ticket topic (`name` is the topic's name). */
+export type DashboardTopicItem = DashboardGroupCounts & {
+  name: string
+  waitingTimeAfterBot?: number
+  waitingTimeAvg?: number
+}
+
+/** `GET /dashboard/by-service` — the counts of one connection (`name` is the connection's name). */
+export type DashboardServiceItem = DashboardGroupCounts & {
+  name: string
+  waitingTimeAfterBot?: number
+  waitingTimeAvg?: number
+  ticketTopicsCount?: number
+}
+
+/** Answer of `getByPeriod`, `getByUser` and `getByDepartment` with `withTotals: true`. */
+export type DashboardGrouped<TItem> = {
+  /** The `getGeneral` counts of the same filters. */
+  totals: DashboardGeneral
+  items: TItem[]
+}

package/src/apis/holiday/types.ts

@@ -1,25 +1,53 @@
+import type { Account } from '../accounts/types'
+import type { File } from '../files/types'
+
+/**
+ * A holiday: the account's services answer `message` during the period `from`–`to`.
+ * Holidays are soft-deleted, but `deletedAt` is never returned.
+ */
 export type Holiday = {
   id: string
   name: string
   from: string
   to: string
   message: string
+  /** Whether the period is over. */
+  expired: boolean
+  /** Number of attached files (computed on the listing, derived from `files` on the detail). */
+  filesCount: number
+  /**
+   * Attached files — always an array. Only loaded on `getById` (or when listed with
+   * `include: ['files']`): `getMany` answers `[]` even when the holiday has files, so use
+   * `filesCount` there.
+   */
+  files: File[]
   accountId: string
   createdAt: string
-  updatedAt: string | null
-  deletedAt: string | null
+  /** Virtual attribute of the model — may be absent. */
+  updatedAt?: string | null
+  // relationships
+  account?: Account
 }
 
+export type HolidayRelationships = 'account' | 'files'
+
+/** A file attached by id (up to 10 per holiday). */
+export type HolidayFileRef = { id: string }
+
 export type CreateHolidayPayload = {
+  /** Up to 255 characters. */
   name: string
+  /** Date string. A period overlapping another holiday answers 402 "Holiday time already exists.". */
   from: string
+  /** Date string. */
   to: string
+  /** Up to 1024 characters. */
   message: string
+  files?: HolidayFileRef[]
 }
 
-export type UpdateHolidayPayload = {
-  name?: string
-  from?: string
-  to?: string
-  message?: string
-}
+/**
+ * The backend requires name, from, to and message on every update (same validator as the create).
+ * Omitting `files` keeps the current attachments.
+ */
+export type UpdateHolidayPayload = CreateHolidayPayload

package/src/apis/index.ts

@@ -15,6 +15,7 @@ export * from './contactBlockListsControls'
 export * from './contacts'
 export * from './creditMovements'
 export * from './customFields'
+export * from './dashboard'
 export * from './departments'
 export * from './distribution'
 export * from './files'
@@ -29,6 +30,7 @@ export * from './knowledgeBaseItem'
 export * from './me'
 export * from './messages'
 export * from './notifications'
+export * from './now'
 export * from './organizations'
 export * from './people'
 export * from './permissions'

package/src/apis/now/NowApi.test.ts

@@ -0,0 +1,125 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { NowApi } from './NowApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type {
+  NowAttendanceResume,
+  NowDepartmentResume,
+  NowResponse,
+  NowResumeTotals,
+} 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(),
+  }
+}
+
+// ── Fixtures ─────────────────────────────────────────────────────────
+
+const resume: NowResponse<NowResumeTotals> = {
+  totals: {
+    openTickets: 3,
+    queueTickets: 1,
+    usersWithAttendance: 2,
+    usersWithoutAttendance: 1,
+    averageOpenTicketsTime: '125.5',
+    averageOpenTicketsWaitTime: 0,
+    onlineUsersCount: 2,
+    offlineUsersCount: 4,
+    absentUsersCount: 0,
+  },
+}
+const attendance: NowResponse<NowAttendanceResume[]> = {
+  totals: [{ name: 'Ana', departments: ['Suporte'], status: 'online', ticketsOpenCount: 2 }],
+}
+const departments: NowResponse<NowDepartmentResume[]> = {
+  totals: [
+    {
+      name: 'Suporte',
+      onlineUserCount: 1,
+      offlineUserCount: 0,
+      absentUserCount: 0,
+      onQueueTicketCount: 1,
+      openTicketCount: 2,
+    },
+  ],
+}
+
+const jsonQuery = (query: object) => `?query=${encodeURIComponent(JSON.stringify(query))}`
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('NowApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: NowApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new NowApi(client)
+  })
+
+  it('has no CRUD routes', () => {
+    expect(api.basePath).toBe('/now')
+    expect(api).not.toHaveProperty('getMany')
+    expect(api).not.toHaveProperty('create')
+  })
+
+  describe('getResume', () => {
+    it('calls client.get with /now/resume and no query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(resume)
+      const result = await api.getResume()
+      expect(client.get).toHaveBeenCalledWith('/now/resume', undefined)
+      expect(result).toEqual(resume)
+    })
+
+    it('sends the department/user filters in the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(resume)
+      await api.getResume({ departmentId: ['d1', 'd2'], userId: 'u1' })
+      expect(client.get).toHaveBeenCalledWith(
+        `/now/resume${jsonQuery({ departmentId: ['d1', 'd2'], userId: 'u1' })}`,
+        undefined,
+      )
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(resume)
+      const headers = { 'X-Custom': 'h' }
+      await api.getResume(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/now/resume', headers)
+    })
+  })
+
+  describe('getAttendanceResume', () => {
+    it('calls client.get with /now/attendance-resume', async () => {
+      vi.mocked(client.get).mockResolvedValue(attendance)
+      const result = await api.getAttendanceResume({ departmentId: 'd1' })
+      expect(client.get).toHaveBeenCalledWith(
+        `/now/attendance-resume${jsonQuery({ departmentId: 'd1' })}`,
+        undefined,
+      )
+      expect(result).toEqual(attendance)
+    })
+  })
+
+  describe('getDepartmentsResume', () => {
+    it('calls client.get with /now/departments-resume', async () => {
+      vi.mocked(client.get).mockResolvedValue(departments)
+      const result = await api.getDepartmentsResume()
+      expect(client.get).toHaveBeenCalledWith('/now/departments-resume', undefined)
+      expect(result).toEqual(departments)
+    })
+
+    it('propagates errors from client.get', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Forbidden'))
+      await expect(api.getDepartmentsResume()).rejects.toThrow('Forbidden')
+    })
+  })
+})

package/src/apis/now/NowApi.ts

@@ -0,0 +1,59 @@
+import { BaseApi } from '../../core/BaseApi'
+import type {
+  NowAttendanceResume,
+  NowDepartmentResume,
+  NowQuery,
+  NowResponse,
+  NowResumeTotals,
+} from './types'
+
+/**
+ * The "Agora" (now) overview: live totals of tickets and attendants. Every route requires
+ * `overview.now.view.all` or `overview.now.view.departments` (the latter is scoped to the user's
+ * departments).
+ */
+export class NowApi extends BaseApi {
+  public readonly basePath = '/now'
+
+  /**
+   * Account totals: open/queued tickets, attendants with/without attendance and online/offline/absent users.
+   * @permissions overview.now.view.all | overview.now.view.departments
+   */
+  getResume(
+    query?: NowQuery,
+    headers?: Record<string, string>,
+  ): Promise<NowResponse<NowResumeTotals>> {
+    return this.client.get<NowResponse<NowResumeTotals>>(
+      `${this.basePath}/resume${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Per-attendant totals (name, departments, status and open tickets).
+   * @permissions overview.now.view.all | overview.now.view.departments
+   */
+  getAttendanceResume(
+    query?: NowQuery,
+    headers?: Record<string, string>,
+  ): Promise<NowResponse<NowAttendanceResume[]>> {
+    return this.client.get<NowResponse<NowAttendanceResume[]>>(
+      `${this.basePath}/attendance-resume${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Per-department totals (online/offline/absent users, queued and open tickets).
+   * @permissions overview.now.view.all | overview.now.view.departments
+   */
+  getDepartmentsResume(
+    query?: NowQuery,
+    headers?: Record<string, string>,
+  ): Promise<NowResponse<NowDepartmentResume[]>> {
+    return this.client.get<NowResponse<NowDepartmentResume[]>>(
+      `${this.basePath}/departments-resume${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+}

package/src/apis/now/index.ts

@@ -0,0 +1,2 @@
+export { NowApi } from './NowApi'
+export type * from './types'

package/src/apis/now/types.ts

@@ -0,0 +1,47 @@
+import type { User } from '../users/types'
+
+/**
+ * Filters of the "Agora" (now) overview. Each accepts one id, an array or a comma-separated list.
+ * A user with only `overview.now.view.departments` gets 403 for departments/users outside their
+ * departments.
+ */
+export type NowQuery = {
+  departmentId?: string | string[]
+  userId?: string | string[]
+}
+
+/** Every `/now` route answers its data under `totals`. */
+export type NowResponse<T> = { totals: T }
+
+export type NowResumeTotals = {
+  openTickets: number
+  queueTickets: number
+  usersWithAttendance: number
+  usersWithoutAttendance: number
+  /** Postgres `avg()` — a numeric string, or `0` when there is no data. */
+  averageOpenTicketsTime: number | string
+  /** Postgres `avg()` — a numeric string, or `0` when there is no data. */
+  averageOpenTicketsWaitTime: number | string
+  onlineUsersCount: number
+  offlineUsersCount: number
+  absentUsersCount: number
+}
+
+/** One entry per department. */
+export type NowDepartmentResume = {
+  name: string
+  onlineUserCount: number
+  offlineUserCount: number
+  absentUserCount: number
+  onQueueTicketCount: number
+  openTicketCount: number
+}
+
+/** One entry per attendant (user). */
+export type NowAttendanceResume = {
+  name?: string
+  /** Department names — `0` when the attendant has no department. */
+  departments: string[] | 0
+  status?: User['status']
+  ticketsOpenCount: number
+}

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

@@ -0,0 +1,39 @@
+import { expectError } from 'tsd'
+import type { ApiClient } from '../core/ApiClient'
+import { PersonalAccessTokensApi } from './personalAccessTokens/PersonalAccessTokensApi'
+import { RolesApi } from './roles/RolesApi'
+import { TimetableApi } from './timetable/TimetableApi'
+
+declare const client: ApiClient
+
+// ── roles: the backend drops `permissionIds` in silence ─────────────
+
+const roles = new RolesApi(client)
+roles.create({ displayName: 'Supervisor', permissions: ['p-1', { id: 'p-2' }] })
+expectError(roles.create({ displayName: 'Supervisor', permissionIds: ['p-1'] }))
+expectError(roles.updateById('r-1', { permissions: ['p-1'] }))
+
+// ── timetable: the old workPlan shape answers 400 ───────────────────
+
+const timetable = new TimetableApi(client)
+timetable.create({
+  name: 'Business hours',
+  previousTimeToNotification: 15,
+  workPlan: [{ start: '08:00', end: '18:00', weekDays: ['mon'] }],
+})
+expectError(
+  timetable.create({
+    name: 'Business hours',
+    previousTimeToNotification: 15,
+    workPlan: [{ day: 1, start: '08:00', end: '18:00', active: true }],
+  }),
+)
+expectError(timetable.updateById('t-1', { name: 'Business hours' }))
+
+// ── personal access tokens: `expiresIn` is the only lifetime accepted ─
+
+const tokens = new PersonalAccessTokensApi(client)
+tokens.create({ name: 'CI', expiresIn: '90d' })
+expectError(tokens.create({ name: 'CI', accessTokenExpiresAt: '2030-01-01T00:00:00Z' }))
+expectError(tokens.create({ name: 'CI', expiresIn: '7d' }))
+expectError(tokens.updateById('t-1', { scope: '*' }))