@ikatec/digisac-api-sdk 4.0.0 → 4.2.0

package/src/apis/authHistory/AuthHistoryApi.ts

@@ -1,43 +1,17 @@
-import qs from 'qs'
 import type { ApiClient } from '../../core/ApiClient'
-import type { ListQuery, Paginated, HasGetMany, HasGetById } from '../../core/types'
+import { BaseReadApi } from '../../core/BaseReadApi'
 import type { AuthHistory } from './types'
 
-export class AuthHistoryApi implements HasGetMany<AuthHistory>, HasGetById<AuthHistory> {
-  private readonly client: ApiClient
-
+/**
+ * Authentication events (auth, password_change, logout), read-only (guarded by
+ * `authHistory.view`). Non-admin users can only see and access their own records.
+ *
+ * Since 4.2 `getById` has the base signature `(id, query?, headers?)`: a call written as
+ * `getById(id, headers)` with the headers in a variable still compiles, but the headers are sent
+ * as the query string — move them to the third argument.
+ */
+export class AuthHistoryApi extends BaseReadApi<AuthHistory> {
   constructor(client: ApiClient) {
-    this.client = client
-  }
-
-  /**
-   * Returns a paginated list of authentication events (auth, password_change, logout). Non-admin users can only see their own records.
-   * @permissions authHistory.view
-   */
-  getMany(
-    query: ListQuery<AuthHistory> & { paginate: false },
-    headers?: Record<string, string>,
-  ): Promise<AuthHistory[]>
-  getMany(
-    query?: ListQuery<AuthHistory> & { paginate?: true },
-    headers?: Record<string, string>,
-  ): Promise<Paginated<AuthHistory>>
-  getMany(
-    query?: ListQuery<AuthHistory>,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<AuthHistory> | AuthHistory[]> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
-    return this.client.get<Paginated<AuthHistory> | AuthHistory[]>(
-      `/auth-history${queryString}`,
-      headers,
-    )
-  }
-
-  /**
-   * Returns a single authentication event by its ID. Non-admin users can only access their own records.
-   * @permissions authHistory.view
-   */
-  getById(id: string, headers?: Record<string, string>): Promise<AuthHistory> {
-    return this.client.get<AuthHistory>(`/auth-history/${id}`, headers)
+    super(client, '/auth-history')
   }
 }

package/src/apis/authHistory/types.ts

@@ -8,9 +8,10 @@ export type AuthHistory = {
   event: AuthHistoryEvent
   userId: string
   accountId: string
-  branch: string
-  originIP: string
-  originUA: string
+  /** Nullable in the database. */
+  originIP: string | null
+  /** Nullable in the database. */
+  originUA: string | null
   createdAt: string
   updatedAt: string
   // relationships

package/src/apis/campaigns/CampaignsApi.test.ts

@@ -96,7 +96,7 @@ describe('CampaignsApi', () => {
       await api.getMany({ page: 2, perPage: 5 })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
       expect(url).toContain('/campaigns?')
-      expect(url).toContain('page=2')
+      expect(decodeURIComponent(url)).toContain('"page":2')
     })
 
     it('forwards custom headers', async () => {

package/src/apis/clientFeedback/ClientFeedbackApi.ts

@@ -1,15 +1,13 @@
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { HasCreate } from '../../core/types'
 import type { ClientFeedback, CreateClientFeedbackPayload } from './types'
 
-export class ClientFeedbackApi implements HasCreate<ClientFeedback, CreateClientFeedbackPayload> {
-  private readonly client: ApiClient
+export class ClientFeedbackApi
+  extends BaseApi
+  implements HasCreate<ClientFeedback, CreateClientFeedbackPayload>
+{
   private readonly basePath = '/client-feedback'
 
-  constructor(client: ApiClient) {
-    this.client = client
-  }
-
   /** Creates a client feedback record for a ticket (accountId, ticketId, and feedback text are required). */
   create(
     body: CreateClientFeedbackPayload,

package/src/apis/contacts/ContactsApi.test.ts

@@ -103,7 +103,7 @@ describe('ContactsApi', () => {
       await api.getMany({ page: 2, perPage: 5 })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
       expect(url).toContain('/contacts?')
-      expect(url).toContain('page=2')
+      expect(decodeURIComponent(url)).toContain('"page":2')
     })
 
     it('forwards custom headers', async () => {

package/src/apis/contacts/ContactsApi.ts

@@ -35,7 +35,7 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
    * @permissions contacts.view
    */
   count(query?: CountContactsQuery, headers?: Record<string, string>): Promise<{ count: number }> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<{ count: number }>(`${this.basePath}/count${queryString}`, headers)
   }
 
@@ -62,7 +62,7 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
     query?: ListQuery<Contact>,
     headers?: Record<string, string>,
   ): Promise<Paginated<Contact>> {
-    const queryString = query ? `?${qs.stringify(query)}` : ''
+    const queryString = this.toQueryString(query)
     return this.client.get<Paginated<Contact>>(`${this.basePath}/forward${queryString}`, headers)
   }
 

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/me/MeApi.ts

@@ -1,4 +1,4 @@
-import type { ApiClient } from '../../core/ApiClient'
+import { BaseApi } from '../../core/BaseApi'
 import type { Account } from '../accounts/types'
 import type { User } from '../users/types'
 import type {
@@ -10,13 +10,7 @@ import type {
   UpdateMeStatusPayload,
 } from './types'
 
-export class MeApi {
-  protected readonly client: ApiClient
-
-  constructor(client: ApiClient) {
-    this.client = client
-  }
-
+export class MeApi extends BaseApi {
   /**
    * Returns the currently authenticated user, including their roles, departments, and timetable.
    * @permissions users.view

package/src/apis/messages/MessagesApi.test.ts

@@ -87,8 +87,8 @@ describe('MessagesApi', () => {
       await api.getMany({ page: 2, perPage: 5 })
       const url = vi.mocked(client.get).mock.calls[0][0] as string
       expect(url).toContain('/messages?')
-      expect(url).toContain('page=2')
-      expect(url).toContain('perPage=5')
+      expect(decodeURIComponent(url)).toContain('"page":2')
+      expect(decodeURIComponent(url)).toContain('"perPage":5')
     })
 
     it('forwards custom headers', async () => {

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'