@ikatec/digisac-api-sdk 4.12.0 → 4.14.0

package/src/apis/absence/types.ts

@@ -1,5 +1,6 @@
 import type { User } from '../users'
 
+/** An absence as `PUT /absence/:id` answers it (the transformer of the backend). */
 export type Absence = {
   id: string
   accountId: string
@@ -8,7 +9,8 @@ export type Absence = {
   endedAt: string | null
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
+  /** @deprecated Not a field of the backend: the model has no soft delete. */
+  deletedAt?: string | null
   // relationships
   user?: User
 }
@@ -16,7 +18,9 @@ export type Absence = {
 export type AbsenceRelationships = 'user'
 
 export type CreateAbsencePayload = {
-  userId: string
+  /** Ignored: the backend creates the absence for the current user. */
+  userId?: string
+  /** Up to 255 characters. */
   reason?: string
 }
 
@@ -24,3 +28,50 @@ export type UpdateAbsencePayload = {
   reason?: string
   endedAt?: string | null
 }
+
+/** Columns the report can be sorted by (an unknown one falls back to the default order). */
+export type AbsenceReportSortField = 'user' | 'createdAt' | 'endedAt'
+
+/**
+ * Query of the absence report (`GET /absence` and `GET /absence/export-csv`). The backend ignores
+ * `where` and `include`: it reads only these fields.
+ */
+export type AbsenceReportQuery = {
+  filters?: {
+    userId?: string
+    reason?: string
+    /** Absences created at or after this date. An invalid date answers 400 `Invalid date.`. */
+    createdAt?: string
+    /** Absences ended at or before this date. */
+    endedAt?: string
+  }
+  sort?: AbsenceReportSortField
+  /** Only `'ASC'` sorts ascending: any other value sorts descending. */
+  order?: 'ASC' | 'DESC'
+  page?: number
+  /** Up to 200 (a larger value is clamped, not refused). Defaults to 15. */
+  perPage?: number
+  /** IANA zone of the dates of the CSV export (e.g. `America/Sao_Paulo`). */
+  timezone?: string
+}
+
+/**
+ * A row of the report: the stored absence with its user, both raw (not transformed).
+ */
+export type AbsenceReportItem = Omit<Absence, 'deletedAt' | 'user'> & {
+  user?: Record<string, unknown>
+}
+
+/** The body of `unlock`: the absence to end (the open one of the user when `id` is absent). */
+export type UnlockAbsencePayload = {
+  id?: string
+  /** Required when `settings.absence.reason_required` is on. */
+  reason?: string
+  /** Required when `settings.absence.password_required` is on: the password of the user. */
+  password?: string
+}
+
+/** What `unlock` answers: the business refusals come with status 200. */
+export type UnlockAbsenceResponse =
+  | { success: true }
+  | { success: false; message: 'INVALID_REASON' | 'INVALID_PASSWORD' }

package/src/apis/activityLog/ActivityLogApi.test.ts

@@ -0,0 +1,44 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ActivityLogApi } from './ActivityLogApi'
+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('ActivityLogApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: ActivityLogApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new ActivityLogApi(client)
+  })
+
+  it('exportCsv calls client.get with /log/export-csv and the period', async () => {
+    vi.mocked(client.get).mockResolvedValue('csv')
+    await api.exportCsv({ filters: { from: '2026-10-01', to: '2026-10-17' } })
+    const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
+    expect(url).toMatch(/^\/log\/export-csv\?/)
+    expect(decodeURIComponent(url)).toContain('"from":"2026-10-01"')
+  })
+
+  it('create posts the stored fields of the log', async () => {
+    const body = { resourceType: 'contact', resourceId: 'c-1', event: 'update', data: { a: 1 } }
+    await api.create(body)
+    expect(client.post).toHaveBeenCalledWith('/log', body, undefined)
+  })
+})

package/src/apis/activityLog/ActivityLogApi.ts

@@ -1,20 +1,39 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { ActivityLog, CreateActivityLogPayload, UpdateActivityLogPayload } from './types'
+import type {
+  ActivityLog,
+  ActivityLogListQuery,
+  CreateActivityLogPayload,
+  UpdateActivityLogPayload,
+} from './types'
 
 /**
  * Activity log of the account (stored in MongoDB: the routes answer 503 when it is unavailable).
- * The backend serves `GET /log`, `GET /log/:id` and `POST /log`; there is no update or delete.
+ * The backend serves `GET /log`, `GET /log/export-csv`, `GET /log/:id` and `POST /log`; there is no update
+ * or delete, so an entry created is permanent. `GET /log/:id` takes a MongoDB
+ * id (an UUID answers 500).
  */
 export class ActivityLogApi extends BaseCrudApi<
   ActivityLog,
   CreateActivityLogPayload,
-  UpdateActivityLogPayload
+  UpdateActivityLogPayload,
+  ActivityLogListQuery
 > {
   constructor(client: ApiClient) {
     super(client, '/log')
   }
 
+  /**
+   * Exports the entries of the period (`filters.from`/`filters.to`) as CSV, sent as the attachment
+   * `exportation.csv`.
+   */
+  exportCsv(query: ActivityLogListQuery, headers?: Record<string, string>): Promise<string> {
+    return this.client.get<string>(
+      `${this.basePath}/export-csv${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
   /** @deprecated Not served: the backend has no PUT /log/:id, so this route answers 404. */
   override updateById(
     id: string,

package/src/apis/activityLog/types.ts

@@ -1,22 +1,61 @@
+import type { ListQuery } from '../../core/types'
+
+/**
+ * An entry of the activity log (MongoDB). The stored fields are `resourceType`, `resourceId`, `event`,
+ * `userId`, `accessTokenId` and `data`. `create` and `getById` answer through a transformer that keeps only
+ * `id`, `accountId`, `createdAt` and `updatedAt`; the list answers every stored field plus `user`.
+ */
 export type ActivityLog = {
   id: string
   accountId: string
-  userId: string | null
-  action: string
-  entity: string
-  entityId: string | null
-  data: Record<string, unknown>
+  resourceType?: string
+  resourceId?: string | null
+  event?: string
+  userId?: string | null
+  accessTokenId?: string | null
+  data?: Record<string, unknown>
   createdAt: string
   updatedAt: string
+  /** On the list: the user of the entry. */
+  user?: { id: string; name: string }
+  /** @deprecated Not a field of the backend (it is dropped on create): use `event`. */
+  action?: string
+  /** @deprecated Not a field of the backend (it is dropped on create): use `resourceType`. */
+  entity?: string
+  /** @deprecated Not a field of the backend (it is dropped on create): use `resourceId`. */
+  entityId?: string | null
 }
 
 export type CreateActivityLogPayload = {
-  action: string
-  entity: string
-  entityId?: string
+  resourceType?: string
+  resourceId?: string
+  event?: string
+  userId?: string
+  accessTokenId?: string
   data?: Record<string, unknown>
+  /** @deprecated Dropped by the backend (not a field of the log): use `event`. */
+  action?: string
+  /** @deprecated Dropped by the backend (not a field of the log): use `resourceType`. */
+  entity?: string
+  /** @deprecated Dropped by the backend (not a field of the log): use `resourceId`. */
+  entityId?: string
 }
 
 export type UpdateActivityLogPayload = {
   data?: Record<string, unknown>
 }
+
+/**
+ * Query of the list and of the CSV export. The backend requires `filters.from` and `filters.to` (the
+ * period of `createdAt`); the other `filters` match the stored fields.
+ */
+export type ActivityLogListQuery = ListQuery<ActivityLog> & {
+  filters?: {
+    from?: string
+    to?: string
+    resourceType?: string
+    resourceId?: string
+    event?: string
+    userId?: string
+  }
+}

package/src/apis/creditMovements/CreditMovementsApi.test.ts

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { CreditMovementsApi } from './CreditMovementsApi'
+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('CreditMovementsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: CreditMovementsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new CreditMovementsApi(client)
+  })
+
+  it('balances calls client.get with /credit-movements/balances', async () => {
+    await api.balances()
+    expect(client.get).toHaveBeenCalledWith('/credit-movements/balances', undefined)
+  })
+
+  it('balance posts the service type to /credit-movements/balance', async () => {
+    vi.mocked(client.post).mockResolvedValue(20)
+    await expect(api.balance('sms-wavy')).resolves.toBe(20)
+    expect(client.post).toHaveBeenCalledWith(
+      '/credit-movements/balance',
+      { serviceType: 'sms-wavy' },
+      undefined,
+    )
+  })
+
+  it('balancesV2 serializes the period', async () => {
+    await api.balancesV2({ from: '2026-10-01', to: '2026-10-17' })
+    const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
+    expect(url).toMatch(/^\/credit-movements\/v2\/balances\?/)
+    expect(decodeURIComponent(url)).toContain('"from":"2026-10-01"')
+  })
+
+  it('balancesV2 sends no query without a period', async () => {
+    await api.balancesV2()
+    expect(client.get).toHaveBeenCalledWith('/credit-movements/v2/balances', undefined)
+  })
+
+  it('totalServices serializes the filters and the page', async () => {
+    await api.totalServices({
+      filters: { from: '2026-10-01', to: '2026-10-17', serviceType: 'summary' },
+      page: 1,
+    })
+    const url = vi.mocked(client.get).mock.calls[0]?.[0] as string
+    expect(url).toMatch(/^\/credit-movements\/total-services\?/)
+    expect(decodeURIComponent(url)).toContain('"page":1')
+  })
+
+  it('exportXlsx resolves the binary body of requestRaw', async () => {
+    const requestRaw = vi.fn().mockResolvedValue(new Response(new ArrayBuffer(4)))
+    client.requestRaw = requestRaw
+    const result = await api.exportXlsx({
+      from: '2026-10-01',
+      to: '2026-10-17',
+      where: { $and: [] },
+    })
+    expect(result.byteLength).toBe(4)
+    const [method, url] = requestRaw.mock.calls[0] ?? []
+    expect(method).toBe('GET')
+    expect(url).toMatch(/^\/credit-movements\/export\?/)
+  })
+
+  it('exportXlsx refuses a client without requestRaw', async () => {
+    const withoutRaw: ApiClient = { ...client, requestRaw: undefined }
+    await expect(
+      new CreditMovementsApi(withoutRaw).exportXlsx({ from: 'a', to: 'b', where: { $and: [] } }),
+    ).rejects.toThrow('requestRaw')
+  })
+})

package/src/apis/creditMovements/CreditMovementsApi.ts

@@ -4,12 +4,19 @@ import type {
   CreditMovement,
   CreateCreditMovementPayload,
   UpdateCreditMovementPayload,
+  CreditBalances,
+  CreditBalanceV2,
+  CreditBalancesV2Query,
+  CreditMovementServiceType,
+  CreditMovementsExportQuery,
+  CreditTotalServices,
+  CreditTotalServicesQuery,
 } from './types'
 
 /**
  * Credit movements of the account (SMS and AI credits), only for reading: the writes are super
- * admin routes (`/admin/credit-movements`). The backend serves only `GET /credit-movements` and
- * `GET /credit-movements/:id`.
+ * admin routes (`/admin/credit-movements`). Besides the list and the read by id, the backend serves the
+ * balances, the totals per connection and the xlsx export.
  */
 export class CreditMovementsApi extends BaseCrudApi<
   CreditMovement,
@@ -41,4 +48,68 @@ export class CreditMovementsApi extends BaseCrudApi<
   override deleteById(id: string, headers?: Record<string, string>): Promise<CreditMovement> {
     return super.deleteById(id, headers)
   }
+
+  /** The balance of each service type of the account. */
+  balances(headers?: Record<string, string>): Promise<CreditBalances> {
+    return this.client.get<CreditBalances>(`${this.basePath}/balances`, headers)
+  }
+
+  /**
+   * The balance of one service type (a read, despite the POST). Without `serviceType` the route answers 500.
+   */
+  balance(
+    serviceType: CreditMovementServiceType,
+    headers?: Record<string, string>,
+  ): Promise<number> {
+    return this.client.post<number, { serviceType: CreditMovementServiceType }>(
+      `${this.basePath}/balance`,
+      { serviceType },
+      headers,
+    )
+  }
+
+  /** The balances of the period by service type and connection (`ins` without the trial credits). */
+  balancesV2(
+    query?: CreditBalancesV2Query,
+    headers?: Record<string, string>,
+  ): Promise<Record<CreditMovementServiceType, CreditBalanceV2>> {
+    return this.client.get<Record<CreditMovementServiceType, CreditBalanceV2>>(
+      `${this.basePath}/v2/balances${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * The total of credits of each connection in the period (five per page). Resolves `undefined` (no body)
+   * when `filters.from`, `filters.to`, `filters.serviceType` or `page` is missing.
+   */
+  totalServices(
+    query: CreditTotalServicesQuery,
+    headers?: Record<string, string>,
+  ): Promise<CreditTotalServices | undefined> {
+    return this.client.get<CreditTotalServices | undefined>(
+      `${this.basePath}/total-services${this.toQueryString(query)}`,
+      headers,
+    )
+  }
+
+  /**
+   * Exports the movements of the period as an xlsx workbook (binary). Needs a client with `requestRaw`.
+   * Without `where.$and` the route answers 500.
+   */
+  async exportXlsx(
+    query: CreditMovementsExportQuery,
+    headers?: Record<string, string>,
+  ): Promise<ArrayBuffer> {
+    if (!this.client.requestRaw) {
+      throw new Error('exportXlsx needs a client with requestRaw (the answer is a binary xlsx)')
+    }
+    const response = await this.client.requestRaw(
+      'GET',
+      `${this.basePath}/export${this.toQueryString(query)}`,
+      undefined,
+      headers,
+    )
+    return response.arrayBuffer()
+  }
 }

package/src/apis/creditMovements/types.ts

@@ -26,6 +26,7 @@ export type CreditMovementOrigin =
   | 'additional'
   | 'agent'
 
+/** A movement as the transformer answers it (no `userId`; the relations are never served). */
 export type CreditMovement = {
   id: string
   type: CreditMovementType
@@ -33,19 +34,90 @@ export type CreditMovement = {
   serviceType: CreditMovementServiceType
   origin: CreditMovementOrigin | null
   accountId: string
-  serviceId: string
-  userId: string | null
+  /** `null` on the movements of the account (e.g. the trial SMS credits of a new account). */
+  serviceId: string | null
+  /** @deprecated Not answered: the transformer of the backend does not send it. */
+  userId?: string | null
   campaignId: string | null
   createdAt: string
   updatedAt: string
   // relationships
+  /** @deprecated Not served: the include is dropped by the backend. */
   service?: Service
+  /** @deprecated Not served: the include is dropped by the backend. */
   user?: User | null
+  /** @deprecated Not served: the include is dropped by the backend. */
   campaign?: Campaign | null
 }
 
+/** None is served: the backend drops every include of this route. */
 export type CreditMovementRelationships = 'service' | 'user' | 'campaign'
 
+/** The balance of each service type (`balances`): the movements in minus the movements out. */
+export type CreditBalances = Record<CreditMovementServiceType, number>
+
+/** The totals of a service type in `balancesV2`. */
+export type CreditBalanceTotals = {
+  ins: number
+  outs: number
+  balance: number
+  used: number
+  contractedCredits?: number
+  additionalCredits?: number
+  realConsumption?: number
+}
+
+/**
+ * A service type in `balancesV2`: `all` with the totals, `history` with the rows of the period, and one
+ * key per connection name with its totals. The `ins` count the credits of the plan (`plan.ai`) and the
+ * additional ones: the trial SMS credits are not counted (they show in `balances`).
+ */
+export type CreditBalanceV2 = {
+  all: CreditBalanceTotals
+  history?: Record<string, unknown>[]
+  [serviceName: string]: unknown
+}
+
+export type CreditBalancesV2Query = {
+  from?: string
+  to?: string
+  serviceId?: string
+}
+
+/**
+ * Query of `totalServices`: without `filters.from`, `filters.to`, `filters.serviceType` and `page` the route
+ * answers 200 with no body.
+ */
+export type CreditTotalServicesQuery = {
+  filters: {
+    from: string
+    to: string
+    serviceType: CreditMovementServiceType
+    servicesIds?: string[]
+  }
+  /** From 1 (`0` answers 500 `Invalid param`). Five connections per page. */
+  page: number
+}
+
+/** The total of credits of each connection in the period, five per page (the counts come as text). */
+export type CreditTotalServices = {
+  data: { id: string; name: string; total: string }[]
+  total: string
+  limit: number
+  skip: number
+  currentPage: string | number
+  lastPage: number
+  from: number
+  to: number
+}
+
+/** Query of `exportXlsx`: the period and the conditions in `where.$and` (required by the backend). */
+export type CreditMovementsExportQuery = {
+  from: string
+  to: string
+  where: { $and: Record<string, unknown>[] }
+}
+
 export type CreateCreditMovementPayload = {
   type: CreditMovementType
   serviceType: CreditMovementServiceType

package/src/apis/knowledgeBase/KnowledgeBaseApi.test.ts

@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { KnowledgeBaseApi } from './KnowledgeBaseApi'
+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('KnowledgeBaseApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: KnowledgeBaseApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new KnowledgeBaseApi(client)
+  })
+
+  it('saveWithItems posts the base with its items', async () => {
+    const body = { name: 'QA', items: [], deleteItemIds: [] }
+    await api.saveWithItems(body)
+    expect(client.post).toHaveBeenCalledWith('/knowledge-base/save-with-items', body, undefined)
+  })
+
+  it('suggestByMessage posts the message to /knowledge-base/suggest-by-message', async () => {
+    await api.suggestByMessage({ messageId: 'm-1' })
+    expect(client.post).toHaveBeenCalledWith(
+      '/knowledge-base/suggest-by-message',
+      { messageId: 'm-1' },
+      undefined,
+    )
+  })
+
+  it('suggestByTicket posts the ticket to /knowledge-base/suggest-by-ticket', async () => {
+    await api.suggestByTicket({ ticketId: 't-1', outsideTheKnowledgeBase: true })
+    expect(client.post).toHaveBeenCalledWith(
+      '/knowledge-base/suggest-by-ticket',
+      { ticketId: 't-1', outsideTheKnowledgeBase: true },
+      undefined,
+    )
+  })
+})

package/src/apis/knowledgeBase/KnowledgeBaseApi.ts

@@ -1,8 +1,22 @@
 import type { ApiClient } from '../../core/ApiClient'
 import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { KnowledgeBase, CreateKnowledgeBasePayload, UpdateKnowledgeBasePayload } from './types'
+import type {
+  KnowledgeBase,
+  CreateKnowledgeBasePayload,
+  UpdateKnowledgeBasePayload,
+  KnowledgeBaseSuggestion,
+  SaveKnowledgeBaseWithItemsPayload,
+  SavedKnowledgeBase,
+  SuggestByMessagePayload,
+  SuggestByTicketPayload,
+} from './types'
 
+/**
+ * Knowledge bases of the AI (copilot). The CRUD of a base without items only touches the database; an item
+ * VECTORIZES its content in the AI service, and the suggestions call the AI and DEBIT the copilot credits of
+ * the account.
+ */
 export class KnowledgeBaseApi extends BaseCrudApi<
   KnowledgeBase,
   CreateKnowledgeBasePayload,
@@ -22,4 +36,50 @@ export class KnowledgeBaseApi extends BaseCrudApi<
   override deleteById(id: string, headers?: Record<string, string>): Promise<false> {
     return super.deleteById(id, headers)
   }
+
+  /**
+   * Creates a base, or updates the one of `id`, with its items, in a transaction. Each item VECTORIZES its
+   * content in the AI service (with `items: []` only the database is touched). Resolves the stored base
+   * (raw). A body out of the schema answers 500 with the issues of the validation.
+   */
+  saveWithItems(
+    body: SaveKnowledgeBaseWithItemsPayload,
+    headers?: Record<string, string>,
+  ): Promise<SavedKnowledgeBase> {
+    return this.client.post<SavedKnowledgeBase, SaveKnowledgeBaseWithItemsPayload>(
+      `${this.basePath}/save-with-items`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Suggests an answer to a message with the AI (copilot) and DEBITS the copilot credits of the account; an
+   * audio is transcribed first (charged too).
+   */
+  suggestByMessage(
+    body: SuggestByMessagePayload,
+    headers?: Record<string, string>,
+  ): Promise<KnowledgeBaseSuggestion> {
+    return this.client.post<KnowledgeBaseSuggestion, SuggestByMessagePayload>(
+      `${this.basePath}/suggest-by-message`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Suggests an answer to a ticket with the AI (copilot) and DEBITS the copilot credits of the account; the
+   * audios of the ticket are transcribed first (charged too).
+   */
+  suggestByTicket(
+    body: SuggestByTicketPayload,
+    headers?: Record<string, string>,
+  ): Promise<KnowledgeBaseSuggestion> {
+    return this.client.post<KnowledgeBaseSuggestion, SuggestByTicketPayload>(
+      `${this.basePath}/suggest-by-ticket`,
+      body,
+      headers,
+    )
+  }
 }