@ikatec/digisac-api-sdk 4.3.0 → 4.4.1

package/src/apis/users/UsersApi.test.ts

@@ -0,0 +1,228 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { UsersApi } from './UsersApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type {
+  BulkUsersStatusPreview,
+  BulkUsersStatusResult,
+  ImportUsersResult,
+  User,
+  UserImportFile,
+  ValidateUserImportResult,
+} 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 user: User = {
+  id: 'usr-1',
+  name: 'Alice',
+  email: 'alice@example.com',
+  phoneNumber: null,
+  branch: null,
+  isClientUser: false,
+  language: 'pt-BR',
+  isFirstLogin: false,
+  status: 'offline',
+  clientsStatus: { web: 'offline', app: 'offline' },
+  isActiveInternalChat: false,
+  internalChatToken: null,
+  noteReference: false,
+  data: {},
+  passwordExpiresAt: null,
+  otpAuthActive: false,
+  preferences: {},
+  archivedAt: null,
+  accountId: 'acc-1',
+  timetableId: null,
+  createdAt: '2024-01-01T00:00:00Z',
+  updatedAt: '2024-01-01T00:00:00Z',
+  deletedAt: null,
+}
+
+const file: UserImportFile = { id: 'f1', name: 'users.csv', mimetype: 'text/csv' }
+const headers = { 'X-Custom': 'value' }
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('UsersApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: UsersApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new UsersApi(client)
+  })
+
+  describe('archive (ArchivableCrudApi)', () => {
+    it('keeps the plain PUT { archivedAt } used by the cleanup of the test suites', async () => {
+      await api.archive('usr-1')
+      const [url, body] = vi.mocked(client.put).mock.calls[0] ?? []
+      expect(url).toBe('/users/usr-1')
+      expect(body).toEqual({ archivedAt: expect.any(String) })
+    })
+  })
+
+  describe('archiveWithValidation', () => {
+    it('calls client.post with /users/:id/archive and { archive: true }', async () => {
+      const archived = { ...user, archivedAt: '2026-01-01T00:00:00Z' }
+      vi.mocked(client.post).mockResolvedValue(archived)
+      const result = await api.archiveWithValidation('usr-1', { archive: true })
+      expect(client.post).toHaveBeenCalledWith('/users/usr-1/archive', { archive: true }, undefined)
+      expect(result).toEqual(archived)
+    })
+
+    it('restores with { archive: false } and forwards custom headers', async () => {
+      await api.archiveWithValidation('usr-1', { archive: false }, headers)
+      expect(client.post).toHaveBeenCalledWith('/users/usr-1/archive', { archive: false }, headers)
+    })
+  })
+
+  describe('previewBulkStatus', () => {
+    it('calls client.post with /users/bulk-status/preview and body', async () => {
+      const preview: BulkUsersStatusPreview = {
+        scenario: 'allEligible',
+        totalSelected: 1,
+        noop: 0,
+        eligible: 1,
+        blocked: 0,
+        blockedSelf: false,
+        planSlotsAvailable: 10,
+      }
+      vi.mocked(client.post).mockResolvedValue(preview)
+      const body = { ids: ['usr-1'], archive: false }
+      const result = await api.previewBulkStatus(body)
+      expect(client.post).toHaveBeenCalledWith('/users/bulk-status/preview', body, undefined)
+      expect(result).toEqual(preview)
+    })
+  })
+
+  describe('bulkStatus', () => {
+    it('calls client.post with /users/bulk-status and body', async () => {
+      const response: BulkUsersStatusResult = {
+        changed: 1,
+        noop: 0,
+        blocked: 0,
+        failed: 0,
+        changedIds: ['usr-1'],
+        missingIds: [],
+      }
+      vi.mocked(client.post).mockResolvedValue(response)
+      const body = { ids: ['usr-1'], archive: true }
+      const result = await api.bulkStatus(body, headers)
+      expect(client.post).toHaveBeenCalledWith('/users/bulk-status', body, headers)
+      expect(result).toEqual(response)
+    })
+  })
+
+  describe('exportCsv', () => {
+    it('calls client.post with /users/export and resolves to the CSV text', async () => {
+      const csv = 'Nome,E-mail\nAlice,alice@example.com\n'
+      vi.mocked(client.post).mockResolvedValue(csv)
+      const result = await api.exportCsv({ filter: 'active' })
+      expect(client.post).toHaveBeenCalledWith('/users/export', { filter: 'active' }, undefined)
+      expect(result).toBe(csv)
+    })
+  })
+
+  describe('validateImport', () => {
+    it('calls client.post with /users/import/validate and the file', async () => {
+      const response: ValidateUserImportResult = {
+        licenses: { requestedRows: 1, available: 5, exceeded: false },
+        columns: {
+          required: [{ name: 'Nome', found: true }],
+          missingRequired: [],
+          optionalFound: [],
+        },
+        rows: { total: 1, valid: 1, invalid: 0, hasInvalid: false },
+        rowsWithOptionalColumns: { total: 1, valid: 1, invalid: 0, hasInvalid: false },
+      }
+      vi.mocked(client.post).mockResolvedValue(response)
+      const result = await api.validateImport({ file })
+      expect(client.post).toHaveBeenCalledWith('/users/import/validate', { file }, undefined)
+      expect(result).toEqual(response)
+    })
+  })
+
+  describe('startImport', () => {
+    it('calls client.post with /users/import and body', async () => {
+      const response: ImportUsersResult = { importId: 'imp-1' }
+      vi.mocked(client.post).mockResolvedValue(response)
+      const body = { file, useOptionalColumns: true }
+      const result = await api.startImport(body, headers)
+      expect(client.post).toHaveBeenCalledWith('/users/import', body, headers)
+      expect(result).toEqual(response)
+    })
+  })
+
+  describe('disableOtpAuth', () => {
+    it('calls client.post with /users/:id/disable-otp-auth and no body', async () => {
+      vi.mocked(client.post).mockResolvedValue(user)
+      const result = await api.disableOtpAuth('usr-1')
+      expect(client.post).toHaveBeenCalledWith(
+        '/users/usr-1/disable-otp-auth',
+        undefined,
+        undefined,
+      )
+      expect(result).toEqual(user)
+    })
+  })
+
+  describe('enableAccess', () => {
+    it('calls client.post with /users/:id/enable-access and no body', async () => {
+      const response = { success: true, message: 'User access enabled successfully' }
+      vi.mocked(client.post).mockResolvedValue(response)
+      const result = await api.enableAccess('usr-1', headers)
+      expect(client.post).toHaveBeenCalledWith('/users/usr-1/enable-access', undefined, headers)
+      expect(result).toEqual(response)
+    })
+  })
+
+  describe('getPinnedContacts', () => {
+    it('calls client.get with /users/pin', async () => {
+      vi.mocked(client.get).mockResolvedValue([])
+      const result = await api.getPinnedContacts()
+      expect(client.get).toHaveBeenCalledWith('/users/pin', undefined)
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('togglePinContact', () => {
+    it('calls client.patch with /users/pin and resolves to the link rows when pinning', async () => {
+      const links = [
+        { userId: 'usr-1', contactId: 'c1', createdAt: '2026-01-01', updatedAt: '2026-01-01' },
+      ]
+      vi.mocked(client.patch).mockResolvedValue(links)
+      const result = await api.togglePinContact({ contactId: 'c1' })
+      expect(client.patch).toHaveBeenCalledWith('/users/pin', { contactId: 'c1' }, undefined)
+      expect(result).toEqual(links)
+    })
+
+    it('resolves to the number of removed links when unpinning', async () => {
+      vi.mocked(client.patch).mockResolvedValue(1)
+      await expect(api.togglePinContact({ contactId: 'c1' }, headers)).resolves.toBe(1)
+      expect(client.patch).toHaveBeenCalledWith('/users/pin', { contactId: 'c1' }, headers)
+    })
+  })
+
+  describe('error propagation', () => {
+    it('propagates errors from archiveWithValidation', async () => {
+      vi.mocked(client.post).mockRejectedValue(new Error('Bad request'))
+      await expect(api.archiveWithValidation('usr-1', { archive: true })).rejects.toThrow(
+        'Bad request',
+      )
+    })
+  })
+})

package/src/apis/users/UsersApi.ts

@@ -1,9 +1,160 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
-import type { User, CreateUserPayload, UpdateUserPayload } from './types'
+import type { Contact } from '../contacts/types'
+import type {
+  ArchiveUserPayload,
+  BulkUsersStatusPayload,
+  BulkUsersStatusPreview,
+  BulkUsersStatusResult,
+  CreateUserPayload,
+  EnableUserAccessResult,
+  ExportUsersPayload,
+  ImportUsersPayload,
+  ImportUsersResult,
+  TogglePinContactPayload,
+  TogglePinContactResult,
+  UpdateUserPayload,
+  User,
+  ValidateUserImportPayload,
+  ValidateUserImportResult,
+} from './types'
 
 export class UsersApi extends ArchivableCrudApi<User, CreateUserPayload, UpdateUserPayload> {
   constructor(client: ApiClient) {
     super(client, '/users')
   }
+
+  /**
+   * Archives or restores a user through the dedicated route used by the UI, which also
+   * sets the user offline and ends its sessions. The route enforces the business rules that
+   * {@link archive}/{@link unarchive} (a plain `PUT { archivedAt }`) skip:
+   * - archiving refuses (403) a user referenced by a bot or with open tickets;
+   * - restoring refuses (402) when the plan has no free user slot.
+   * @permissions users.view OR users.archive
+   */
+  archiveWithValidation(
+    id: string,
+    body: ArchiveUserPayload,
+    headers?: Record<string, string>,
+  ): Promise<User> {
+    return this.client.post<User, ArchiveUserPayload>(
+      `${this.basePath}/${id}/archive`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Previews a bulk archive/unarchive without changing anything.
+   * @permissions users.archive
+   */
+  previewBulkStatus(
+    body: BulkUsersStatusPayload,
+    headers?: Record<string, string>,
+  ): Promise<BulkUsersStatusPreview> {
+    return this.client.post<BulkUsersStatusPreview, BulkUsersStatusPayload>(
+      `${this.basePath}/bulk-status/preview`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Archives or unarchives up to 100 users at once.
+   * @permissions users.archive
+   */
+  bulkStatus(
+    body: BulkUsersStatusPayload,
+    headers?: Record<string, string>,
+  ): Promise<BulkUsersStatusResult> {
+    return this.client.post<BulkUsersStatusResult, BulkUsersStatusPayload>(
+      `${this.basePath}/bulk-status`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Exports the users of the account as CSV. Resolves to the CSV text.
+   * @permissions users.export
+   */
+  exportCsv(body: ExportUsersPayload, headers?: Record<string, string>): Promise<string> {
+    return this.client.post<string, ExportUsersPayload>(`${this.basePath}/export`, body, headers)
+  }
+
+  /**
+   * Validates a CSV file previously uploaded through `FilesApi` before importing it.
+   * @permissions users.create
+   */
+  validateImport(
+    body: ValidateUserImportPayload,
+    headers?: Record<string, string>,
+  ): Promise<ValidateUserImportResult> {
+    return this.client.post<ValidateUserImportResult, ValidateUserImportPayload>(
+      `${this.basePath}/import/validate`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Starts the import of a CSV file previously uploaded through `FilesApi`. The import runs
+   * in the background (the route answers `202 Accepted`).
+   * @permissions users.create
+   */
+  startImport(
+    body: ImportUsersPayload,
+    headers?: Record<string, string>,
+  ): Promise<ImportUsersResult> {
+    return this.client.post<ImportUsersResult, ImportUsersPayload>(
+      `${this.basePath}/import`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Turns off the two-factor authentication (OTP) of a user.
+   * @permissions users.update AND myAccount.update
+   */
+  disableOtpAuth(id: string, headers?: Record<string, string>): Promise<User> {
+    return this.client.post<User>(`${this.basePath}/${id}/disable-otp-auth`, undefined, headers)
+  }
+
+  /**
+   * Clears the login throttling of a user blocked by too many failed attempts.
+   * @permissions users.update
+   */
+  enableAccess(id: string, headers?: Record<string, string>): Promise<EnableUserAccessResult> {
+    return this.client.post<EnableUserAccessResult>(
+      `${this.basePath}/${id}/enable-access`,
+      undefined,
+      headers,
+    )
+  }
+
+  /**
+   * Returns the contacts pinned by the logged user.
+   * @permissions contacts.pin
+   */
+  getPinnedContacts(headers?: Record<string, string>): Promise<Contact[]> {
+    return this.client.get<Contact[]>(`${this.basePath}/pin`, headers)
+  }
+
+  /**
+   * Pins the contact for the logged user, or unpins it when already pinned. A user can pin
+   * up to 3 contacts. Resolves to the created link rows when pinning, or to the number of
+   * removed links when unpinning.
+   * @permissions contacts.pin
+   */
+  togglePinContact(
+    body: TogglePinContactPayload,
+    headers?: Record<string, string>,
+  ): Promise<TogglePinContactResult> {
+    return this.client.patch<TogglePinContactResult, TogglePinContactPayload>(
+      `${this.basePath}/pin`,
+      body,
+      headers,
+    )
+  }
 }

package/src/apis/users/types.ts

@@ -9,21 +9,39 @@ export type UserPreferences = {
   isShowTagsChat?: boolean
 }
 
+export type UserData = {
+  /** Push token of the mobile app; cleared (`null`) when the user is archived. */
+  expoPushToken?: string | null
+  [key: string]: unknown
+}
+
+/** A connection the user is restricted to (`GET /users/:id` of a non-admin user). */
+export type UserRestrictedService = {
+  id: string
+  name: string
+}
+
+/**
+ * A user as the API answers it (`userTransformer`). `isSuperAdmin`, `active` and `offlineAt` exist in
+ * the database but are never answered.
+ */
 export type User = {
   id: string
   name: string
   email: string
   phoneNumber: string | null
   branch: string | null
-  isSuperAdmin: boolean
   isClientUser: boolean
-  active: boolean
   language: string
   isFirstLogin: boolean
   status: UserStatus
   clientsStatus: Record<string, string> | null
-  offlineAt: string | null
   isActiveInternalChat: boolean
+  /** Token of the internal chat; `null` right after the creation, regenerated on every write of the user. */
+  internalChatToken: string | null
+  /** Set by the backend from an internal flag of the user. */
+  noteReference: boolean
+  data: UserData
   passwordExpiresAt: string | null
   otpAuthActive: boolean | null
   preferences: UserPreferences
@@ -37,6 +55,8 @@ export type User = {
   timetable?: Timetable | null
   roles?: Role[]
   departments?: Department[]
+  /** Only in `GET /users/:id`, for a user without an admin role. */
+  restrictedServices?: UserRestrictedService[]
 }
 
 export type UserRelationships = 'timetable' | 'roles' | 'departments'
@@ -69,3 +89,124 @@ export type UpdateUserPayload = {
   language?: string
   archivedAt?: string | null
 }
+
+/** Body for `POST /users/:id/archive`. */
+export type ArchiveUserPayload = {
+  /** `true` archives the user; `false` restores it. */
+  archive: boolean
+}
+
+/** Body for `POST /users/bulk-status` and `POST /users/bulk-status/preview` (1 to 100 IDs). */
+export type BulkUsersStatusPayload = {
+  ids: string[]
+  archive: boolean
+}
+
+export type BulkUsersStatusScenario =
+  | 'emptySelection'
+  | 'noneEligible'
+  | 'allEligible'
+  | 'partiallyBlocked'
+  | 'onlySelfBlocked'
+  | 'planLimitExceeded'
+
+/** Read-only preview of a bulk status change: nothing is written. */
+export type BulkUsersStatusPreview = {
+  scenario: BulkUsersStatusScenario
+  totalSelected: number
+  /** Users already in the target status. */
+  noop: number
+  eligible: number
+  /** Users that cannot change (e.g. referenced by a bot, or the acting user). */
+  blocked: number
+  blockedSelf: boolean
+  /** Free plan slots when unarchiving; `null` when archiving. */
+  planSlotsAvailable: number | null
+}
+
+export type BulkUsersStatusResult = {
+  changed: number
+  noop: number
+  blocked: number
+  failed: number
+  changedIds: string[]
+  /** IDs of the batch that no longer exist in the account. */
+  missingIds: string[]
+}
+
+/** Body for `POST /users/export`. */
+export type ExportUsersPayload = {
+  filter: 'all' | 'active' | 'archived'
+}
+
+/** A file previously uploaded through `FilesApi`. */
+export type UserImportFile = {
+  id: string
+  name: string
+  mimetype: string
+  url?: string
+  urlToUpload?: string
+}
+
+/** Body for `POST /users/import/validate`. */
+export type ValidateUserImportPayload = {
+  file: UserImportFile
+}
+
+export type UserImportRowsSummary = {
+  total: number
+  valid: number
+  invalid: number
+  hasInvalid: boolean
+}
+
+export type ValidateUserImportResult = {
+  licenses: {
+    requestedRows: number
+    available: number
+    exceeded: boolean
+  }
+  columns: {
+    required: { name: string; found: boolean }[]
+    missingRequired: string[]
+    optionalFound: string[]
+  }
+  rows: UserImportRowsSummary
+  /** Same rows validated with the optional columns applied. */
+  rowsWithOptionalColumns: UserImportRowsSummary
+}
+
+/** Body for `POST /users/import`. */
+export type ImportUsersPayload = {
+  file: UserImportFile
+  useOptionalColumns?: boolean
+}
+
+/** The import runs in the background (the route answers `202 Accepted`). */
+export type ImportUsersResult = {
+  importId: string
+}
+
+export type EnableUserAccessResult = {
+  success: boolean
+  message: string
+}
+
+/** Body for `PATCH /users/pin`: toggles the pin of a contact for the logged user (max. 3). */
+export type TogglePinContactPayload = {
+  contactId: string
+}
+
+/** Link row returned by `PATCH /users/pin` when the contact gets pinned. */
+export type UserPinnedContactLink = {
+  userId: string
+  contactId: string
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * Result of `PATCH /users/pin`: the created link rows when the contact gets pinned, or the
+ * number of removed links when it gets unpinned.
+ */
+export type TogglePinContactResult = UserPinnedContactLink[] | number