@ikatec/digisac-api-sdk 4.13.0 → 4.15.0

package/src/apis/contacts/types.ts

@@ -1,10 +1,11 @@
+import type { CustomField, CustomFieldType } from '../customFields/types'
 import type { Department } from '../departments/types'
 import type { Person } from '../people/types'
 import type { Service } from '../services/types'
 import type { Tag } from '../tags/types'
 import type { Ticket } from '../tickets/types'
 import type { User } from '../users/types'
-import type { IncludeItem, ListQuery, WhereClause } from '../../core/types'
+import type { GetByIdQuery, IncludeItem, ListQuery, WhereClause } from '../../core/types'
 
 export type ContactStatus = 'online' | 'offline' | 'absent'
 export type ContactOrigin = 'api' | 'app' | 'campaign' | 'driver' | 'import' | 'web'
@@ -95,6 +96,56 @@ export type ContactDataBlock = {
   description: string
 }
 
+/**
+ * A value of a custom field of the contact, as `include: ['customFieldValues']` answers it (the
+ * stored row).
+ */
+export type CustomFieldValue = {
+  id: string
+  customFieldId: string
+  /** The contact. */
+  relatedId: string
+  relatedType: string | null
+  /**
+   * The value as stored: text, or JSON text for the composite types (`date-range`, `hour-range`,
+   * `numeric`, `monetary`, `phone`, `postal-code`).
+   */
+  value: string
+  createdAt: string
+  updatedAt: string
+  deletedAt: string | null
+  // relationships
+  customField?: CustomField
+}
+
+/**
+ * A custom field of the contact as `formatCustomFields: true` answers it, keyed by the name of the
+ * field in `Contact.customFields`.
+ */
+export type FormattedCustomField = {
+  name: string
+  /** The value, parsed from JSON for the composite types. */
+  value: unknown
+  /** Id of the value. */
+  id: string
+  type: CustomFieldType
+  /** Id of the field. */
+  fieldId: string
+  /** When the field was created. */
+  createdAt: string
+}
+
+/** A custom field value sent in the create or update of a contact. */
+export type ContactCustomFieldInput = {
+  /**
+   * Id of the custom field (`CustomField.id`, `FormattedCustomField.fieldId` or
+   * `CustomFieldValue.customFieldId`), not the id of the value.
+   */
+  id: string
+  /** Text, or an object for the composite types (stored as JSON). */
+  value: unknown
+}
+
 export type Contact = {
   id: string
   idFromService: string | null
@@ -139,6 +190,13 @@ export type Contact = {
   person?: Person | null
   tags?: Tag[]
   currentTicket?: Ticket | null
+  /** With `include: ['customFieldValues']`, unless `formatCustomFields` is set. */
+  customFieldValues?: CustomFieldValue[]
+  /**
+   * With `formatCustomFields: true` and the include
+   * `{ model: 'customFieldValues', include: ['customField'] }`: the values keyed by the field name.
+   */
+  customFields?: Record<string, FormattedCustomField>
 }
 
 export type ContactRelationships =
@@ -148,6 +206,23 @@ export type ContactRelationships =
   | 'person'
   | 'tags'
   | 'currentTicket'
+  | 'customFieldValues'
+  | 'customFields'
+
+type FormatCustomFieldsOption = {
+  /**
+   * Answers `customFields` keyed by the field name instead of the raw `customFieldValues` (with the
+   * include `{ model: 'customFieldValues', include: ['customField'] }`; without the nested
+   * `customField`, `customFields` comes empty).
+   */
+  formatCustomFields?: boolean
+}
+
+/** Query of `ContactsApi.getById`. */
+export type ContactGetByIdQuery = GetByIdQuery<Contact> & FormatCustomFieldsOption
+
+/** Query of `ContactsApi.getMany` and `getOne`. */
+export type ContactListQuery = ListQuery<Contact> & FormatCustomFieldsOption
 
 export type CreateContactPayload = {
   name?: string
@@ -160,6 +235,8 @@ export type CreateContactPayload = {
   data?: ContactData
   note?: string
   origin?: ContactOrigin
+  /** Values of the custom fields of the account. An id that is not a custom field answers 400. */
+  customFields?: ContactCustomFieldInput[]
 }
 
 export type UpdateContactPayload = {
@@ -174,6 +251,11 @@ export type UpdateContactPayload = {
   block?: boolean
   /** Tag IDs to associate with the contact. */
   tagIds?: string[]
+  /**
+   * Values of the custom fields of the account: a value of the same field is updated. An id that is
+   * not a custom field is skipped.
+   */
+  customFields?: ContactCustomFieldInput[]
 }
 
 /** Result of `ContactsApi.summarizeTicket`. */

package/src/apis/files/FilesApi.test.ts

@@ -97,6 +97,27 @@ describe('FilesApi', () => {
     })
   })
 
+  describe('duplicateFile', () => {
+    it('calls client.post with /files/duplicate-file and resolves the id of the copy', async () => {
+      vi.mocked(client.post).mockResolvedValue('file-2')
+      const result = await api.duplicateFile({ fileId: 'file-1' })
+      expect(client.post).toHaveBeenCalledWith(
+        '/files/duplicate-file',
+        { fileId: 'file-1' },
+        undefined,
+      )
+      expect(result).toBe('file-2')
+    })
+
+    it('sends urlToUpload and serviceId in the body and forwards custom headers', async () => {
+      vi.mocked(client.post).mockResolvedValue('file-1')
+      const headers = { 'X-Req': 'r-1' }
+      const body = { fileId: 'file-1', urlToUpload: URL_TO_UPLOAD, serviceId: 'svc-1' }
+      await api.duplicateFile(body, headers)
+      expect(client.post).toHaveBeenCalledWith('/files/duplicate-file', body, headers)
+    })
+  })
+
   describe('deleteById', () => {
     it('calls client.delete with /files/:id and resolves { success }', async () => {
       vi.mocked(client.delete).mockResolvedValue({ success: true })

package/src/apis/files/FilesApi.ts

@@ -9,6 +9,7 @@ import type {
   CreateToUploadPayload,
   CreateToUploadResult,
   DeleteFileResult,
+  DuplicateFilePayload,
 } from './types'
 
 /**
@@ -85,7 +86,8 @@ export class FilesApi extends BaseCrudApi<
    * Creates the record of a file and returns the signed URL to upload its content: send the
    * content with {@link upload}. An audio that must be converted (a voice message for the
    * connection) is sent in `base64` instead, and then no `urlToUpload` is returned. `name` and
-   * `mimetype` are required (500 without them; an audio without `name` is named `recording`).
+   * `mimetype` are required (500 without them; an audio without `name` is named `recording`). With
+   * `serviceId`, an extension the account blocks for the type of the connection answers 403.
    */
   createToUpload(
     body: CreateToUploadPayload,
@@ -98,6 +100,22 @@ export class FilesApi extends BaseCrudApi<
     )
   }
 
+  /**
+   * Copies the content of a file. With `urlToUpload` (the signed URL of a record created by
+   * {@link createToUpload} with the same `mimetype` as the file copied), the content is sent to that
+   * record and the answer is the `fileId` given; without it, a new record (`attachedType`
+   * `'message.file'`) is created with the copied content and its id is the answer, and with
+   * `serviceId` an extension the account blocks for the type of the connection answers 403. An
+   * unknown `fileId` answers 500.
+   */
+  duplicateFile(body: DuplicateFilePayload, headers?: Record<string, string>): Promise<string> {
+    return this.client.post<string, DuplicateFilePayload>(
+      `${this.basePath}/duplicate-file`,
+      body,
+      headers,
+    )
+  }
+
   /**
    * Uploads the content of a file to the `urlToUpload` returned by {@link createToUpload}. The URL
    * is signed by the storage, so the request goes straight to it, without the API token (the

package/src/apis/files/types.ts

@@ -74,7 +74,10 @@ export type CreateToUploadPayload = {
   mimetype: string
   /** What the file is attached to, e.g. `'message.file'` (default), `'campaign.file'`, `'quickreply.file'`. */
   attachedType?: string
-  /** Connection that will send the file (used to decide the audio conversion). */
+  /**
+   * Connection that will send the file: used to decide the audio conversion and to apply the
+   * extensions the account blocks for its type (403).
+   */
   serviceId?: string
   /** Audio sent as a voice message (default `true`). */
   isPtt?: boolean
@@ -93,6 +96,22 @@ export type CreateToUploadResult = {
   mimetype: string
 }
 
+/** Body of `FilesApi.duplicateFile`. */
+export type DuplicateFilePayload = {
+  /** The file whose content is copied. */
+  fileId: string
+  /**
+   * Signed URL of a record created by `FilesApi.createToUpload`, with the same `mimetype` as the file
+   * copied, to receive the content. Without it, a new record is created with the copied content.
+   */
+  urlToUpload?: string
+  /**
+   * Connection that will send the new record (used only without `urlToUpload`): the extensions the
+   * account blocks for its type apply.
+   */
+  serviceId?: string
+}
+
 /** Result of `FilesApi.deleteById`. */
 export type DeleteFileResult = {
   success: boolean

package/src/apis/notifications/types.ts

@@ -78,8 +78,10 @@ export type Notification = {
   label: string | null
   config: NotificationConfig | null
   attachedType: string | null
-  attachedId: string | null
-  notificationReadId: string | null
+  /** @deprecated Not answered: the model has no such column, so the transformer never sends it. */
+  attachedId?: string | null
+  /** @deprecated Not answered: the model has no such column, so the transformer never sends it. */
+  notificationReadId?: string | null
   contactId: string | null
   userId: string
   accountId: string
@@ -93,7 +95,8 @@ export type Notification = {
   schedule?: Schedule | null
   /** @deprecated Not served: the model has no such association, so it never comes. */
   contact?: Contact | null
-  notificationRead?: NotificationRead | null
+  /** The read receipts of the notification (a list: `[]` while it was never read). */
+  notificationRead?: NotificationRead[]
 }
 
 /** The backend serves `user`, `schedule` and `notificationRead` (`contact` is never answered). */

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

@@ -54,7 +54,14 @@ import { AcceptanceTermsApi } from './acceptanceTerms/AcceptanceTermsApi'
 import { CategoriesApi } from './categories/CategoriesApi'
 import { ContactBlockListsApi } from './contactBlockLists/ContactBlockListsApi'
 import { ContactBlockListsControlsApi } from './contactBlockListsControls/ContactBlockListsControlsApi'
-import type { SummarizeTicketResult } from './contacts/types'
+import type {
+  Contact,
+  CustomFieldValue,
+  FormattedCustomField,
+  SummarizeTicketResult,
+} from './contacts/types'
+import { AuthHistoryApi } from './authHistory/AuthHistoryApi'
+import type { AuthHistoryEvent } from './authHistory/types'
 import { CustomFieldsApi } from './customFields/CustomFieldsApi'
 import { DepartmentsApi } from './departments/DepartmentsApi'
 import type { Department } from './departments/types'
@@ -71,7 +78,11 @@ import { KnowledgeBaseApi } from './knowledgeBase/KnowledgeBaseApi'
 import { KnowledgeBaseItemApi } from './knowledgeBaseItem/KnowledgeBaseItemApi'
 import { MessagesApi } from './messages/MessagesApi'
 import { NotificationsApi } from './notifications/NotificationsApi'
-import type { NotificationCountsResponse } from './notifications/types'
+import type {
+  Notification,
+  NotificationCountsResponse,
+  NotificationRead,
+} from './notifications/types'
 import { AbsenceApi } from './absence/AbsenceApi'
 import type { AbsenceReportItem, UnlockAbsenceResponse } from './absence/types'
 import { ActivityLogApi } from './activityLog/ActivityLogApi'
@@ -749,3 +760,50 @@ expectType<Promise<Sticker>>(new StickersApi(client).create({ base64: 'iVBOR', n
 expectError(new StickersApi(client).create({ type: 'created' }))
 expectType<Promise<'OK' | false>>(new StickersApi(client).remove('s-1'))
 expectAssignable<Parameters<StickersApi['getMany']>[0]>({ include: ['file'] })
+
+// ── QARC-1010 (4.13.1): the shapes observed on qa-rc ─────────────────
+
+declare const notification: Notification
+expectType<NotificationRead[] | undefined>(notification.notificationRead)
+expectType<string | null | undefined>(notification.attachedId)
+declare const sticker: Sticker
+expectAssignable<Sticker>({ ...sticker, originMessage: null })
+expectAssignable<Promise<{ message: string }>>(
+  new ServicesApi(client).accessManagement('s-1', { userIds: ['u-1'], deny: true }),
+)
+expectAssignable<Awaited<ReturnType<ServicesApi['accessManagement']>>>({
+  message: '2 users allowed access.',
+})
+expectNotAssignable<Awaited<ReturnType<ServicesApi['accessManagement']>>>({ message: 'denied' })
+expectError(new ServicesApi(client).accessManagement('s-1', { userIds: ['u-1'] }))
+
+// ── QARC-1015 (4.15.0): custom fields of the contact, file copy, logout event ─────
+
+expectAssignable<Parameters<ContactsApi['create']>[0]>({
+  serviceId: 's-1',
+  customFields: [
+    { id: 'f-1', value: 'text' },
+    { id: 'f-2', value: { value: '10,50', identifier: 'BRL', min: '', max: '' } },
+  ],
+})
+expectAssignable<Parameters<ContactsApi['updateById']>[1]>({
+  customFields: [{ id: 'f-1', value: 'new' }],
+})
+expectError(
+  new ContactsApi(client).create({ serviceId: 's-1', customFields: [{ value: 'no id' }] }),
+)
+expectAssignable<Parameters<ContactsApi['getById']>[1]>({
+  include: [{ model: 'customFieldValues', include: ['customField'] }],
+  formatCustomFields: true,
+})
+declare const contactWithFields: Contact
+expectType<CustomFieldValue[] | undefined>(contactWithFields.customFieldValues)
+expectType<Record<string, FormattedCustomField> | undefined>(contactWithFields.customFields)
+expectAssignable<Parameters<ContactsApi['getMany']>[0]>({
+  include: [{ model: 'customFieldValues', include: ['customField'] }],
+  formatCustomFields: true,
+})
+expectType<Promise<string>>(new FilesApi(client).duplicateFile({ fileId: 'file-1' }))
+expectError(new FilesApi(client).duplicateFile({ urlToUpload: 'https://storage' }))
+expectType<Promise<void>>(new AuthHistoryApi(client).registerLogout())
+expectAssignable<AuthHistoryEvent>('2fa_disabled')

package/src/apis/services/ServicesApi.test.ts

@@ -91,4 +91,15 @@ describe('ServicesApi', () => {
       })
     },
   )
+
+  describe('accessManagement', () => {
+    it('posts the users and the deny flag to /services/:id/access-management', async () => {
+      vi.mocked(client.post).mockResolvedValue({ message: '1 users denied access.' })
+      const body = { userIds: ['u-1'], deny: true }
+      await expect(api.accessManagement('svc-1', body)).resolves.toEqual({
+        message: '1 users denied access.',
+      })
+      expect(client.post).toHaveBeenCalledWith('/services/svc-1/access-management', body, undefined)
+    })
+  })
 })

package/src/apis/services/ServicesApi.ts

@@ -6,6 +6,8 @@ import type {
   ServiceLimits,
   UpdateServicePayload,
   ArchiveServicePayload,
+  ServiceAccessManagementPayload,
+  ServiceAccessManagementResponse,
 } from './types'
 
 export class ServicesApi extends ArchivableCrudApi<
@@ -109,4 +111,23 @@ export class ServicesApi extends ArchivableCrudApi<
   restart(id: string, headers?: Record<string, string>): Promise<'OK'> {
     return this.client.post<'OK'>(`${this.basePath}/${id}/restart`, undefined, headers)
   }
+
+  /**
+   * Denies the connection to users (`deny: true`) or gives it back (`deny: false`); the admins are skipped. Denying
+   * transfers the open tickets of those users in the connection. The rows are read with
+   * `ServiceAccessManagementApi.getMany`. An unknown connection answers 404 `Service not found.`; a missing
+   * `userIds` or a `deny` that is not a boolean answers 400.
+   * @permissions users.update AND services.operate
+   */
+  accessManagement(
+    id: string,
+    body: ServiceAccessManagementPayload,
+    headers?: Record<string, string>,
+  ): Promise<ServiceAccessManagementResponse> {
+    return this.client.post<ServiceAccessManagementResponse, ServiceAccessManagementPayload>(
+      `${this.basePath}/${id}/access-management`,
+      body,
+      headers,
+    )
+  }
 }

package/src/apis/services/types.ts

@@ -292,3 +292,15 @@ export type ServiceLimit = {
 
 /** Connections used and allowed by the account plan, by connection type. */
 export type ServiceLimits = Partial<Record<ServiceType, ServiceLimit>>
+
+/** The body of `accessManagement`: the users to deny (or give back) the connection to. */
+export type ServiceAccessManagementPayload = {
+  userIds: string[]
+  /** `true` denies the connection to the users (their open tickets in it are transferred); `false` gives it back. */
+  deny: boolean
+}
+
+/** What `accessManagement` answers: how many users were denied or given back the connection (no admin is counted). */
+export type ServiceAccessManagementResponse = {
+  message: `${number} users denied access.` | `${number} users allowed access.`
+}

package/src/apis/stickers/types.ts

@@ -1,4 +1,5 @@
 import type { File } from '../files/types'
+import type { Message } from '../messages/types'
 import type { User } from '../users/types'
 
 /** A sticker of the account (every user of the account sees it). */
@@ -19,6 +20,8 @@ export type Sticker = {
   user?: User
   /** The image (webp) of the sticker. */
   file?: File
+  /** The message the sticker came from (`add`); `null` on a sticker uploaded with `create`. */
+  originMessage?: Message | null
 }
 
 /** The backend serves only `file` (`user` is dropped). */

package/src/core/BaseReadApi.ts

@@ -4,8 +4,8 @@ import type { GetByIdQuery, HasGetById, HasGetMany, ListQuery, Paginated } from
 
 /**
  * Generic read-only resource: `getMany`, `getOne` and `getById` under `basePath`. Base of
- * `BaseCrudApi`, and of the resources the backend only serves for reading (e.g. permissions,
- * auth history).
+ * `BaseCrudApi`, and of the resources the backend serves for reading, plus their own actions (e.g.
+ * permissions, auth history).
  */
 export class BaseReadApi<TResponse, TQuery extends ListQuery<TResponse> = ListQuery<TResponse>>
   extends BaseApi