@ikatec/digisac-api-sdk 4.9.0 → 4.11.0

package/src/apis/people/PeopleApi.ts

@@ -1,9 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Person, CreatePersonPayload, UpdatePersonPayload } from './types'
 
-export class PeopleApi extends BaseCrudApi<Person, CreatePersonPayload, UpdatePersonPayload> {
+export class PeopleApi extends BaseCrudApi<
+  Person,
+  CreatePersonPayload,
+  UpdatePersonPayload,
+  ListQuery<Person>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/people')
   }
+
+  /**
+   * Deletes a person. Resolves the text `'OK'`.
+   * @permissions people.view OR people.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/planAiHistory/PlanAiHistoryApi.ts

@@ -2,6 +2,10 @@ import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { PlanAiHistory, CreatePlanAiHistoryPayload, UpdatePlanAiHistoryPayload } from './types'
 
+/**
+ * History of the AI products of the plan, only for reading: the records are written by super admin
+ * actions. The backend serves only `GET /plan-ai-history` and `GET /plan-ai-history/:id`.
+ */
 export class PlanAiHistoryApi extends BaseCrudApi<
   PlanAiHistory,
   CreatePlanAiHistoryPayload,
@@ -10,4 +14,26 @@ export class PlanAiHistoryApi extends BaseCrudApi<
   constructor(client: ApiClient) {
     super(client, '/plan-ai-history')
   }
+
+  /** @deprecated Not served: the backend has no POST /plan-ai-history, so this route answers 404. */
+  override create(
+    body: CreatePlanAiHistoryPayload,
+    headers?: Record<string, string>,
+  ): Promise<PlanAiHistory> {
+    return super.create(body, headers)
+  }
+
+  /** @deprecated Not served: the backend has no PUT /plan-ai-history/:id, so this route answers 404. */
+  override updateById(
+    id: string,
+    body: UpdatePlanAiHistoryPayload,
+    headers?: Record<string, string>,
+  ): Promise<PlanAiHistory> {
+    return super.updateById(id, body, headers)
+  }
+
+  /** @deprecated Not served: the backend has no DELETE /plan-ai-history/:id, so this route answers 404. */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<PlanAiHistory> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/roles/RolesApi.ts

@@ -6,9 +6,18 @@ export class RolesApi extends BaseCrudApi<
   Role,
   CreateRolePayload,
   UpdateRolePayload,
-  RolesListQuery
+  RolesListQuery,
+  boolean
 > {
   constructor(client: ApiClient) {
     super(client, '/roles')
   }
+
+  /**
+   * Deletes a role. Resolves `true`.
+   * @permissions roles.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<boolean> {
+    return super.deleteById(id, headers)
+  }
 }

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

@@ -46,4 +46,49 @@ describe('ServicesApi', () => {
       expect(client.get).toHaveBeenCalledWith('/services/limits', headers)
     })
   })
+
+  describe('archiveWithValidation', () => {
+    it('calls client.post with /services/:id/archive, the archive flag and the type', async () => {
+      vi.mocked(client.post).mockResolvedValue({})
+      const result = await api.archiveWithValidation('svc-1', { archive: true, type: 'sms-wavy' })
+      expect(client.post).toHaveBeenCalledWith(
+        '/services/svc-1/archive',
+        { archive: true, type: 'sms-wavy' },
+        undefined,
+      )
+      expect(result).toEqual({})
+    })
+
+    it('restores with { archive: false } and forwards custom headers', async () => {
+      const headers = { 'X-Custom': 'value' }
+      await api.archiveWithValidation('svc-1', { archive: false, type: 'whatsapp' }, headers)
+      expect(client.post).toHaveBeenCalledWith(
+        '/services/svc-1/archive',
+        { archive: false, type: 'whatsapp' },
+        headers,
+      )
+    })
+  })
+
+  describe.each(['takeover', 'logout', 'shutdown', 'start', 'restart'] as const)(
+    '%s',
+    (operation) => {
+      it(`calls client.post with /services/:id/${operation} and resolves 'OK'`, async () => {
+        vi.mocked(client.post).mockResolvedValue('OK')
+        const result = await api[operation]('svc-1')
+        expect(client.post).toHaveBeenCalledWith(
+          `/services/svc-1/${operation}`,
+          undefined,
+          undefined,
+        )
+        expect(result).toBe('OK')
+      })
+
+      it('forwards custom headers', async () => {
+        const headers = { 'X-Custom': 'value' }
+        await api[operation]('svc-1', headers)
+        expect(client.post).toHaveBeenCalledWith(`/services/svc-1/${operation}`, undefined, headers)
+      })
+    },
+  )
 })

package/src/apis/services/ServicesApi.ts

@@ -1,6 +1,12 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
-import type { Service, CreateServicePayload, ServiceLimits, UpdateServicePayload } from './types'
+import type {
+  Service,
+  CreateServicePayload,
+  ServiceLimits,
+  UpdateServicePayload,
+  ArchiveServicePayload,
+} from './types'
 
 export class ServicesApi extends ArchivableCrudApi<
   Service,
@@ -19,4 +25,88 @@ export class ServicesApi extends ArchivableCrudApi<
   getLimits(headers?: Record<string, string>): Promise<ServiceLimits> {
     return this.client.get<ServiceLimits>(`${this.basePath}/limits`, headers)
   }
+
+  /**
+   * @deprecated The backend does not archive a connection by `PUT { archivedAt }`: the PUT
+   * requires `type` (400 without it) and ignores `archivedAt`. Use {@link archiveWithValidation}.
+   */
+  override archive(id: string, headers?: Record<string, string>): Promise<Service> {
+    return super.archive(id, headers)
+  }
+
+  /**
+   * @deprecated The backend does not restore a connection by `PUT { archivedAt: null }`: the PUT
+   * requires `type` (400 without it) and ignores `archivedAt`. Use {@link archiveWithValidation}.
+   */
+  override unarchive(id: string, headers?: Record<string, string>): Promise<Service> {
+    return super.unarchive(id, headers)
+  }
+
+  /**
+   * Archives (`archive: true`) or restores (`archive: false`) a connection through the route used
+   * by the UI. Archiving shuts the connection down, closes its open tickets, marks its schedules
+   * as done and cancels its campaigns; restoring checks the plan limit of the `type` (400 when it
+   * is full).
+   *
+   * Resolves `{}` before the work is done (the route does not await it): poll `getById` until
+   * `archivedAt` changes. Send the `type` of the connection: without it the request is never
+   * answered.
+   * @permissions services.disabled
+   */
+  archiveWithValidation(
+    id: string,
+    body: ArchiveServicePayload,
+    headers?: Record<string, string>,
+  ): Promise<Record<string, never>> {
+    return this.client.post<Record<string, never>, ArchiveServicePayload>(
+      `${this.basePath}/${id}/archive`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Takes the session of the connection over to this server. Resolves the text `'OK'`; an
+   * unknown id answers 404 `Service not found.`.
+   * @permissions services.operate
+   */
+  takeover(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/takeover`, undefined, headers)
+  }
+
+  /**
+   * Logs the connection out of the messaging service. Resolves the text `'OK'`; an unknown id
+   * answers 404 `Service not found.`.
+   * @permissions services.operate
+   */
+  logout(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/logout`, undefined, headers)
+  }
+
+  /**
+   * Shuts the connection down. Resolves the text `'OK'`; an unknown id answers 404
+   * `Service not found.`.
+   * @permissions services.operate
+   */
+  shutdown(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/shutdown`, undefined, headers)
+  }
+
+  /**
+   * Starts the connection. Resolves the text `'OK'`; an unknown id answers 404
+   * `Service not found.`.
+   * @permissions services.operate
+   */
+  start(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/start`, undefined, headers)
+  }
+
+  /**
+   * Restarts the connection. Resolves the text `'OK'`; an unknown id answers 404
+   * `Service not found.`.
+   * @permissions services.operate
+   */
+  restart(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/restart`, undefined, headers)
+  }
 }

package/src/apis/services/types.ts

@@ -253,6 +253,8 @@ export type ServiceRelationships = 'bot' | 'defaultDepartment'
 export type CreateServicePayload = {
   name: string
   type: ServiceType
+  /** Send `null`: without it the duplicate-name check never answers (SUS-3784). */
+  archivedAt?: null
   data?: ServiceData
   settings?: ServiceSettings
   defaultDepartmentId?: string
@@ -260,14 +262,28 @@ export type CreateServicePayload = {
 }
 
 export type UpdateServicePayload = {
+  /** Required by the backend (400 without it), although optional here for compatibility. */
+  type?: ServiceType
   name?: string
   data?: ServiceData
   settings?: ServiceSettings
   defaultDepartmentId?: string | null
   botId?: string | null
+  /**
+   * Ignored by the backend (archive through `ServicesApi.archiveWithValidation`). Send `null`
+   * with a `name`: without `archivedAt` the duplicate-name check never answers (SUS-3784).
+   */
   archivedAt?: string | null
 }
 
+/** Body of `ServicesApi.archiveWithValidation`. */
+export type ArchiveServicePayload = {
+  /** `true` archives, `false` restores. */
+  archive: boolean
+  /** The type of the connection, used by the plan limit check (the request hangs without it). */
+  type: ServiceType
+}
+
 export type ServiceLimit = {
   used: number
   total: number

package/src/apis/stickers/StickersApi.ts

@@ -1,9 +1,41 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
+import type { GetByIdQuery } from '../../core/types'
 import type { Sticker, CreateStickerPayload, UpdateStickerPayload } from './types'
 
+/**
+ * Stickers of the account. The backend serves `GET /stickers` and `POST /stickers` (plus
+ * `GET /stickers/exist`, `POST /stickers/add` and `DELETE /stickers/remove/:stickerId`); there is
+ * no read by id, update nor `DELETE /stickers/:id`.
+ */
 export class StickersApi extends BaseCrudApi<Sticker, CreateStickerPayload, UpdateStickerPayload> {
   constructor(client: ApiClient) {
     super(client, '/stickers')
   }
+
+  /** @deprecated Not served: the backend has no GET /stickers/:id, so this route answers 404. */
+  override getById(
+    id: string,
+    query?: GetByIdQuery<Sticker>,
+    headers?: Record<string, string>,
+  ): Promise<Sticker> {
+    return super.getById(id, query, headers)
+  }
+
+  /** @deprecated Not served: the backend has no PUT /stickers/:id, so this route answers 404. */
+  override updateById(
+    id: string,
+    body: UpdateStickerPayload,
+    headers?: Record<string, string>,
+  ): Promise<Sticker> {
+    return super.updateById(id, body, headers)
+  }
+
+  /**
+   * @deprecated Not served: the backend has no DELETE /stickers/:id (it removes a sticker by
+   * `DELETE /stickers/remove/:stickerId`), so this route answers 404.
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<Sticker> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/tags/TagsApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { ContactsSelection } from '../contacts/types'
 import type {
@@ -9,11 +10,25 @@ import type {
   UpdateTagPayload,
 } from './types'
 
-export class TagsApi extends BaseCrudApi<Tag, CreateTagPayload, UpdateTagPayload> {
+export class TagsApi extends BaseCrudApi<
+  Tag,
+  CreateTagPayload,
+  UpdateTagPayload,
+  ListQuery<Tag>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/tags')
   }
 
+  /**
+   * Deletes a tag. Resolves the text `'OK'`; an unknown id answers 500.
+   * @permissions tags.view OR tags.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
+
   /**
    * Adds the tag to every contact of the account that matches the selection. Resolves to `'OK'`,
    * or `false` when every contact already had the tag.

package/src/apis/timetable/TimetableApi.ts

@@ -1,13 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Timetable, CreateTimetablePayload, UpdateTimetablePayload } from './types'
 
 export class TimetableApi extends BaseCrudApi<
   Timetable,
   CreateTimetablePayload,
-  UpdateTimetablePayload
+  UpdateTimetablePayload,
+  ListQuery<Timetable>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/timetable')
   }
+
+  /**
+   * Deletes a timetable. Resolves the text `'OK'`.
+   * @permissions timetables.view OR timetables.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/users/UsersApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
 import type { Contact } from '../contacts/types'
 import type {
@@ -19,11 +20,26 @@ import type {
   ValidateUserImportResult,
 } from './types'
 
-export class UsersApi extends ArchivableCrudApi<User, CreateUserPayload, UpdateUserPayload> {
+export class UsersApi extends ArchivableCrudApi<
+  User,
+  CreateUserPayload,
+  UpdateUserPayload,
+  ListQuery<User>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/users')
   }
 
+  /**
+   * Deletes a user (removes it as the default user of the contacts and deletes its webhooks first).
+   * Resolves the text `'OK'`.
+   * @permissions users.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
+
   /**
    * 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

package/src/apis/users/types.ts

@@ -71,7 +71,10 @@ export type CreateUserPayload = {
   isClientUser?: boolean
   roles?: string[]
   departments?: string[]
+  /** @deprecated Not read by the backend: restrict the connections with `restrictedServices`. */
   services?: string[]
+  /** Connections the user cannot access, as `{ value: serviceId }`. */
+  restrictedServices?: { value: string }[]
   scheduleId?: string
 }
 
@@ -83,7 +86,15 @@ export type UpdateUserPayload = {
   isClientUser?: boolean
   roles?: string[]
   departments?: string[]
+  /** @deprecated Not read by the backend: restrict the connections with `restrictedServices`. */
   services?: string[]
+  /**
+   * Connections the user cannot access, as `{ value: serviceId }`. Every update without it (and
+   * every update of an admin) clears the restrictions of the user.
+   */
+  restrictedServices?: { value: string }[]
+  /** New password of the user. */
+  password?: string
   timetableId?: string | null
   preferences?: UserPreferences
   language?: string

package/src/apis/webhooks/WebhooksApi.ts

@@ -1,9 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Webhook, CreateWebhookPayload, UpdateWebhookPayload } from './types'
 
-export class WebhooksApi extends BaseCrudApi<Webhook, CreateWebhookPayload, UpdateWebhookPayload> {
+export class WebhooksApi extends BaseCrudApi<
+  Webhook,
+  CreateWebhookPayload,
+  UpdateWebhookPayload,
+  ListQuery<Webhook>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/me/webhooks')
   }
+
+  /**
+   * Deletes a webhook. Resolves the text `'OK'`; an unknown id answers 500.
+   * @permissions settingsApi.update
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/core/ApiClient.ts

@@ -32,4 +32,28 @@ export interface ApiClient {
     endpoint: string,
     headers?: Record<string, string>,
   ): Promise<TResponse>
+  /**
+   * Like {@link request}, but resolves the raw `Response` of a successful (2xx) call instead of
+   * the parsed body, for the routes whose headers matter (`Content-Type`, `Content-Disposition`)
+   * or whose body is binary (xlsx, pdf, files). Non-2xx still throws the `ApiError` subclass.
+   * Optional: a custom client without it cannot call the API methods that need the raw response.
+   */
+  requestRaw?<TBody = unknown>(
+    method: HttpMethod,
+    endpoint: string,
+    body?: TBody,
+    headers?: Record<string, string>,
+  ): Promise<Response>
+  /**
+   * Sends a request to an absolute URL outside the API (e.g. the signed storage URL of
+   * `FilesApi.upload`): no base URL, no `Authorization` header and no JSON serialization, `body`
+   * goes as is. Resolves the raw `Response` of a 2xx answer; non-2xx throws the `ApiError`
+   * subclass. Optional: without it, the API methods that need it send through the global `fetch`.
+   */
+  requestExternal?(
+    method: HttpMethod,
+    url: string,
+    body?: BodyInit,
+    headers?: Record<string, string>,
+  ): Promise<Response>
 }

package/src/core/ArchivableCrudApi.ts

@@ -17,7 +17,8 @@ export class ArchivableCrudApi<
   TCreate,
   TUpdate extends { archivedAt?: string | null } = TCreate & { archivedAt?: string | null },
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
-> extends BaseCrudApi<TResponse, TCreate, TUpdate, TQuery> {
+  TDeleteResponse = TResponse,
+> extends BaseCrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse> {
   constructor(client: ApiClient, basePath: string) {
     super(client, basePath)
   }

package/src/core/BaseApiClient.test.ts

@@ -498,4 +498,102 @@ describe('BaseApiClient', () => {
       errorClass: 'AccessDenied',
     })
   })
+
+  // ── requestRaw ───────────────────────────────────────────────────
+
+  describe('requestRaw', () => {
+    it('resolves the raw Response of a 2xx answer, with the headers and body untouched', async () => {
+      const spy = mockFetch({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/pdf', 'Content-Disposition': 'attachment' },
+        body: '%PDF-1.4',
+      })
+      client.setAccessToken('token-1')
+      const response = await client.requestRaw('GET', '/terms/t-1/export-pdf')
+      expect(spy).toHaveBeenCalledWith(
+        'https://api.example.com/terms/t-1/export-pdf',
+        expect.objectContaining({
+          method: 'GET',
+          headers: expect.objectContaining({ Authorization: 'Bearer token-1' }),
+        }),
+      )
+      expect(response.status).toBe(200)
+      expect(response.headers.get('Content-Type')).toBe('application/pdf')
+      expect(await response.text()).toBe('%PDF-1.4')
+    })
+
+    it('sends the JSON body and the custom headers', async () => {
+      const spy = mockFetch({ ok: true, status: 200, statusText: 'OK', body: 'a;b' })
+      await client.requestRaw('POST', '/export', { where: { id: '1' } }, { 'X-Custom': 'v' })
+      expect(spy).toHaveBeenCalledWith(
+        'https://api.example.com/export',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ where: { id: '1' } }),
+          headers: expect.objectContaining({ 'X-Custom': 'v' }),
+        }),
+      )
+    })
+
+    it('throws the ApiError subclass of a non-2xx answer', async () => {
+      mockFetch({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ error: 'NotFoundHttpError', message: 'Route not found.' }),
+      })
+      await expect(client.requestRaw('GET', '/missing')).rejects.toBeInstanceOf(NotFoundError)
+    })
+
+    it('throws ApiConnectionError when the request fails', async () => {
+      vi.spyOn(globalThis, 'fetch').mockRejectedValue(new TypeError('fetch failed'))
+      await expect(client.requestRaw('GET', '/down')).rejects.toBeInstanceOf(ApiConnectionError)
+    })
+  })
+
+  // ── requestExternal ──────────────────────────────────────────────
+
+  describe('requestExternal', () => {
+    const SIGNED_URL = 'https://storage.example.com/acc-1/file-1.csv?X-Amz-Signature=secret'
+
+    it('sends the body as is to the absolute URL, without the token nor the JSON Content-Type', async () => {
+      const spy = vi
+        .spyOn(globalThis, 'fetch')
+        .mockResolvedValue(new Response(null, { status: 200 }))
+      client.setAccessToken('token-1')
+      const response = await client.requestExternal('PUT', SIGNED_URL, 'a;b', {
+        'Content-Type': 'text/csv',
+      })
+      expect(spy).toHaveBeenCalledWith(SIGNED_URL, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'text/csv' },
+        body: 'a;b',
+      })
+      expect(response.status).toBe(200)
+    })
+
+    it('throws the ApiError subclass of a non-2xx answer, with the body as text', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+        new Response('<Error><Code>AccessDenied</Code></Error>', {
+          status: 403,
+          statusText: 'Forbidden',
+        }),
+      )
+      const captured = await client.requestExternal('PUT', SIGNED_URL).catch((e) => e)
+      expect(captured).toBeInstanceOf(PermissionDeniedError)
+      expect((captured as ApiError).body).toBe('<Error><Code>AccessDenied</Code></Error>')
+    })
+
+    it('throws ApiConnectionError without the query string (the signature) in the message', async () => {
+      vi.spyOn(globalThis, 'fetch').mockRejectedValue(new TypeError('fetch failed'))
+      const captured = await client.requestExternal('PUT', SIGNED_URL).catch((e) => e)
+      expect(captured).toBeInstanceOf(ApiConnectionError)
+      expect((captured as ApiConnectionError).message).toBe(
+        'Request to PUT https://storage.example.com/acc-1/file-1.csv failed: fetch failed',
+      )
+    })
+  })
 })