@ikatec/digisac-api-sdk 4.1.0 → 4.2.0

package/src/apis/customFields/types.ts

@@ -17,33 +17,29 @@ export type CustomFieldType =
   | 'list'
 
 export type CustomFieldOption = {
-  id?: string
-  label?: string
+  id?: string | null
+  label?: string | null
 }
 
-/** Settings for `list` and `checkbox` types: a list of selectable options. */
-export type CustomFieldListSettings = {
-  options: CustomFieldOption[]
+/**
+ * Settings of a custom field — a free JSONB the backend does not validate, echoed back as sent.
+ * The fields below are the ones the web app form sends (`front/src/pages/custom-fields/components/
+ * form.tsx`): `options` for the `list` and `checkbox` types, `min`/`max` for `numeric` and `monetary`,
+ * `currency` for `monetary`, `maxLength` for `text` and `long-text`, and `placeholder` for the inputs.
+ */
+export type CustomFieldSettings = {
+  options?: CustomFieldOption[]
+  placeholder?: string | null
+  currency?: string | null
+  maxLength?: number | null
+  min?: string | null
+  max?: string | null
 }
 
-/** Settings for `monetary` type: optional min/max value constraints. */
-export type CustomFieldMonetarySettings = {
-  options: CustomFieldOption[]
-  min?: string
-  max?: string
-}
-
-/** Settings for `text` and `long-text` types: optional max length constraint. */
-export type CustomFieldTextSettings = {
-  options: CustomFieldOption[]
-  maxLength?: number
-}
-
-export type CustomFieldSettings =
-  | CustomFieldListSettings
-  | CustomFieldMonetarySettings
-  | CustomFieldTextSettings
-
+/**
+ * A custom field of the account. Custom fields are soft-deleted, but `deletedAt` is never returned
+ * (customFieldsTransformer).
+ */
 export type CustomField = {
   id: string
   name: string
@@ -55,7 +51,6 @@ export type CustomField = {
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
 }
 
 export type CreateCustomFieldPayload = {
@@ -64,12 +59,13 @@ export type CreateCustomFieldPayload = {
   allowed: 'contacts'
   showOnRegister?: boolean
   required?: boolean
-  settings?: CustomFieldSettings
+  settings?: CustomFieldSettings | null
 }
 
 export type UpdateCustomFieldPayload = {
   name?: string
   type?: CustomFieldType
+  allowed?: 'contacts'
   showOnRegister?: boolean
   required?: boolean
   settings?: CustomFieldSettings | null

package/src/apis/dashboard/DashboardApi.test.ts

@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DashboardApi } from './DashboardApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type { DashboardGeneral } 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 general: DashboardGeneral = {
+  sentMessagesCount: 10,
+  receivedMessagesCount: 5,
+  totalMessagesCount: 15,
+  openedTicketsCount: 2,
+  closedTicketsCount: 3,
+  totalTicketsCount: 5,
+  waitingTime: 60,
+  waitingTimeAfterBot: 30,
+  waitingTimeAvg: 45,
+  ticketTime: 600,
+  contactsCount: 4,
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('DashboardApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: DashboardApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new DashboardApi(client)
+  })
+
+  it('has no CRUD routes', () => {
+    expect(api.basePath).toBe('/dashboard')
+    expect(api).not.toHaveProperty('getMany')
+  })
+
+  describe('getGeneral', () => {
+    it('calls client.get with /dashboard/general and no query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(general)
+      const result = await api.getGeneral()
+      expect(client.get).toHaveBeenCalledWith('/dashboard/general', undefined)
+      expect(result).toEqual(general)
+    })
+
+    it('sends the filters in the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(general)
+      const query = {
+        startPeriod: '2026-09-01T00:00:00.000Z',
+        endPeriod: '2026-09-07T23:59:59.999Z',
+        status: 'closed' as const,
+        departmentId: ['d1'],
+      }
+      await api.getGeneral(query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/general?query=${encodeURIComponent(JSON.stringify(query))}`,
+        undefined,
+      )
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(general)
+      const headers = { 'X-Custom': 'h' }
+      await api.getGeneral(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/general', headers)
+    })
+  })
+})

package/src/apis/dashboard/DashboardApi.ts

@@ -0,0 +1,18 @@
+import { BaseApi } from '../../core/BaseApi'
+import type { DashboardGeneral, DashboardQuery } from './types'
+
+/**
+ * Service statistics ("Estatísticas de atendimento"). The `/dashboard` routes only require an
+ * authenticated user (no permission check).
+ */
+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,
+    )
+  }
+}

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,53 @@
+/**
+ * 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[]
+}
+
+/** `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
+}

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: '*' }))

package/src/apis/payloads.test.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ApiClient } from '../core/ApiClient'
+import { PersonalAccessTokensApi } from './personalAccessTokens/PersonalAccessTokensApi'
+import { RolesApi } from './roles/RolesApi'
+import { TimetableApi } from './timetable/TimetableApi'
+
+// Pins the body keys the backend reads: a key it does not know is dropped in silence, so a
+// regression would only show up as missing data (e.g. a role created without permissions).
+
+// ── 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('payloads sent to the backend', () => {
+  let client: ReturnType<typeof createMockClient>
+
+  beforeEach(() => {
+    client = createMockClient()
+  })
+
+  describe('RolesApi', () => {
+    it('create sends the permissions under `permissions`', async () => {
+      await new RolesApi(client).create({
+        displayName: 'Supervisor',
+        permissions: ['p-1', { id: 'p-2' }],
+      })
+      expect(client.post).toHaveBeenCalledWith(
+        '/roles',
+        { displayName: 'Supervisor', permissions: ['p-1', { id: 'p-2' }] },
+        undefined,
+      )
+    })
+
+    it('updateById sends displayName and the permissions under `permissions`', async () => {
+      await new RolesApi(client).updateById('r-1', {
+        displayName: 'Supervisor',
+        permissions: ['p-1'],
+      })
+      expect(client.put).toHaveBeenCalledWith(
+        '/roles/r-1',
+        { displayName: 'Supervisor', permissions: ['p-1'] },
+        undefined,
+      )
+    })
+  })
+
+  describe('TimetableApi', () => {
+    it('create sends the workPlan as { start, end, weekDays }', async () => {
+      const body = {
+        name: 'Business hours',
+        previousTimeToNotification: 15,
+        workPlan: [{ start: '08:00', end: '18:00', weekDays: ['mon' as const, 'fri' as const] }],
+      }
+      await new TimetableApi(client).create(body)
+      expect(client.post).toHaveBeenCalledWith('/timetable', body, undefined)
+    })
+  })
+
+  describe('PersonalAccessTokensApi', () => {
+    it('create sends the lifetime under `expiresIn`', async () => {
+      await new PersonalAccessTokensApi(client).create({ name: 'CI', expiresIn: '90d' })
+      expect(client.post).toHaveBeenCalledWith(
+        '/me/tokens',
+        { name: 'CI', expiresIn: '90d' },
+        undefined,
+      )
+    })
+  })
+})