@ikatec/digisac-api-sdk 2.1.1 → 2.2.0

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

@@ -341,6 +341,30 @@ describe('ContactsApi', () => {
     })
   })
 
+  describe('transferTicket', () => {
+    it('calls client.post with /contacts/:id/ticket/transfer and payload', async () => {
+      vi.mocked(client.post).mockResolvedValue({ ok: true })
+      const result = await api.transferTicket('c1', { departmentId: 'd1' })
+      expect(client.post).toHaveBeenCalledWith(
+        '/contacts/c1/ticket/transfer',
+        { departmentId: 'd1' },
+        undefined,
+      )
+      expect(result).toEqual({ ok: true })
+    })
+
+    it('includes optional userId and forwards custom headers', async () => {
+      vi.mocked(client.post).mockResolvedValue({ ok: true })
+      const headers = { 'X-Custom': 'h' }
+      await api.transferTicket('c1', { departmentId: 'd1', userId: 'u1' }, headers)
+      expect(client.post).toHaveBeenCalledWith(
+        '/contacts/c1/ticket/transfer',
+        { departmentId: 'd1', userId: 'u1' },
+        headers,
+      )
+    })
+  })
+
   // ── Error propagation ────────────────────────────────────────────
 
   describe('error propagation', () => {

package/src/apis/contacts/ContactsApi.ts

@@ -9,6 +9,7 @@ import type {
   CreateContactPayload,
   ExistsContactsParams,
   ExportTemplatePayload,
+  TransferTicketPayload,
   UpdateContactPayload,
 } from './types'
 
@@ -102,4 +103,21 @@ export class ContactsApi extends BaseCrudApi<Contact, CreateContactPayload, Upda
       headers,
     )
   }
+
+  /**
+   * Opens (or transfers) the contact's ticket to a department, and optionally a user.
+   * This is the real ticket-open flow used by the UI — there is no `POST /tickets`.
+   * @permissions tickets.transfer.all OR tickets.transfer.me
+   */
+  transferTicket(
+    contactId: string,
+    payload: TransferTicketPayload,
+    headers?: Record<string, string>,
+  ): Promise<unknown> {
+    return this.client.post<unknown, TransferTicketPayload>(
+      `${this.basePath}/${contactId}/ticket/transfer`,
+      payload,
+      headers,
+    )
+  }
 }

package/src/apis/contacts/types.ts

@@ -153,6 +153,8 @@ export type CreateContactPayload = {
   name?: string
   serviceId: string
   idFromService?: string
+  /** Top-level convenience input; the backend copies it into `data.number`. */
+  number?: string
   defaultDepartmentId?: string
   defaultUserId?: string
   data?: ContactData
@@ -170,6 +172,8 @@ export type UpdateContactPayload = {
   note?: string | null
   isSilenced?: boolean
   block?: boolean
+  /** Tag IDs to associate with the contact. */
+  tagIds?: string[]
 }
 
 export type ExportTemplatePayload = {
@@ -187,3 +191,16 @@ export type ExistsContactsParams = {
 }
 
 export type CountMediaResult = Record<string, number>
+
+/**
+ * Body for `POST /contacts/:id/ticket/transfer`. Opens or transfers the contact's
+ * ticket. The backend only reads these fields; it does not enforce a 24h window or template.
+ */
+export type TransferTicketPayload = {
+  departmentId: string
+  userId?: string
+  comments?: string
+  kanbanCardColumnId?: string
+  kanbanCardSubject?: string
+  initialMessage?: string
+}

package/src/apis/departments/DepartmentsApi.ts

@@ -1,8 +1,8 @@
 import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
+import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
 import type { Department, CreateDepartmentPayload, UpdateDepartmentPayload } from './types'
 
-export class DepartmentsApi extends BaseCrudApi<
+export class DepartmentsApi extends ArchivableCrudApi<
   Department,
   CreateDepartmentPayload,
   UpdateDepartmentPayload

package/src/apis/departments/types.ts

@@ -24,4 +24,5 @@ export type CreateDepartmentPayload = {
 export type UpdateDepartmentPayload = {
   name?: string
   distributionId?: string | null
+  archivedAt?: string | null
 }

package/src/apis/kanbanBoards/types.ts

@@ -19,6 +19,8 @@ export type KanbanBoardRelationships = 'departments' | 'columns'
 export type CreateKanbanBoardPayload = {
   name: string
   timeoutAlertEnabled?: boolean
+  /** Department IDs to link to the board. Required by the backend on creation. */
+  departmentIds: string[]
 }
 
 export type UpdateKanbanBoardPayload = {

package/src/apis/services/ServicesApi.ts

@@ -1,8 +1,12 @@
 import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
+import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
 import type { Service, CreateServicePayload, UpdateServicePayload } from './types'
 
-export class ServicesApi extends BaseCrudApi<Service, CreateServicePayload, UpdateServicePayload> {
+export class ServicesApi extends ArchivableCrudApi<
+  Service,
+  CreateServicePayload,
+  UpdateServicePayload
+> {
   constructor(client: ApiClient) {
     super(client, '/services')
   }

package/src/apis/services/types.ts

@@ -219,4 +219,5 @@ export type UpdateServicePayload = {
   settings?: ServiceSettings
   defaultDepartmentId?: string | null
   botId?: string | null
+  archivedAt?: string | null
 }

package/src/apis/tags/types.ts

@@ -19,6 +19,8 @@ export type TagRelationships = 'contacts' | 'departments'
 export type CreateTagPayload = {
   label: string
   backgroundColor?: string
+  /** Department IDs to link to the tag on creation. */
+  departments?: string[]
 }
 
 export type UpdateTagPayload = {

package/src/apis/ticketTopics/TicketTopicsApi.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { TicketTopicsApi } from './TicketTopicsApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type { TicketTopic } from './types'
+
+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(),
+  }
+}
+
+describe('TicketTopicsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: TicketTopicsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new TicketTopicsApi(client)
+  })
+
+  it('archives via POST /ticket-topics/:id/archive with { archive: true }', async () => {
+    const topic = { id: 't1' } as TicketTopic
+    vi.mocked(client.post).mockResolvedValue(topic)
+
+    const result = await api.archive('t1')
+    expect(client.post).toHaveBeenCalledWith(
+      '/ticket-topics/t1/archive',
+      { archive: true },
+      undefined,
+    )
+    expect(result).toEqual(topic)
+  })
+
+  it('unarchives via POST /ticket-topics/:id/archive with { archive: false }', async () => {
+    vi.mocked(client.post).mockResolvedValue({ id: 't1' } as TicketTopic)
+
+    await api.unarchive('t1')
+    expect(client.post).toHaveBeenCalledWith(
+      '/ticket-topics/t1/archive',
+      { archive: false },
+      undefined,
+    )
+  })
+
+  it('archive/unarchive stay bound when destructured', async () => {
+    vi.mocked(client.post).mockResolvedValue({ id: 't1' } as TicketTopic)
+    const { archive, unarchive } = api
+    await archive('t1')
+    await unarchive('t1')
+    expect(client.post).toHaveBeenCalledTimes(2)
+  })
+})

package/src/apis/ticketTopics/TicketTopicsApi.ts

@@ -9,5 +9,32 @@ export class TicketTopicsApi extends BaseCrudApi<
 > {
   constructor(client: ApiClient) {
     super(client, '/ticket-topics')
+    this.archive = this.archive.bind(this)
+    this.unarchive = this.unarchive.bind(this)
+  }
+
+  /**
+   * Archives a ticket topic. Unlike most resources, ticket-topics archive through a
+   * dedicated endpoint (POST `${basePath}/${id}/archive`) rather than `updateById`.
+   * @permissions ticketTopic.update
+   */
+  archive(id: string, headers?: Record<string, string>): Promise<TicketTopic> {
+    return this.client.post<TicketTopic>(
+      `${this.basePath}/${id}/archive`,
+      { archive: true },
+      headers,
+    )
+  }
+
+  /**
+   * Restores a previously archived ticket topic via the same dedicated endpoint.
+   * @permissions ticketTopic.update
+   */
+  unarchive(id: string, headers?: Record<string, string>): Promise<TicketTopic> {
+    return this.client.post<TicketTopic>(
+      `${this.basePath}/${id}/archive`,
+      { archive: false },
+      headers,
+    )
   }
 }

package/src/apis/tickets/TicketsApi.test.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { TicketsApi } from './TicketsApi'
+import type { ApiClient } from '../../core/ApiClient'
+
+// ── 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(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('TicketsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: TicketsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new TicketsApi(client)
+  })
+
+  describe('closeMany', () => {
+    it('PUTs /tickets/close-many with explicit ids', async () => {
+      vi.mocked(client.put).mockResolvedValue({ ok: true })
+      const result = await api.closeMany({ ids: ['t1', 't2'] })
+      expect(client.put).toHaveBeenCalledWith(
+        '/tickets/close-many',
+        { ids: ['t1', 't2'] },
+        undefined,
+      )
+      expect(result).toEqual({ ok: true })
+    })
+
+    it('PUTs /tickets/close-many with a JSON-stringified query for the select-all variant', async () => {
+      vi.mocked(client.put).mockResolvedValue({ ok: true })
+      await api.closeMany({ allContactsSelected: true, query: { query: '{"where":{}}' } })
+      expect(client.put).toHaveBeenCalledWith(
+        '/tickets/close-many',
+        { allContactsSelected: true, query: { query: '{"where":{}}' } },
+        undefined,
+      )
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.put).mockResolvedValue({ ok: true })
+      const headers = { 'X-Custom': 'value' }
+      await api.closeMany({ ids: ['t1'] }, headers)
+      expect(client.put).toHaveBeenCalledWith('/tickets/close-many', { ids: ['t1'] }, headers)
+    })
+
+    it('propagates errors', async () => {
+      vi.mocked(client.put).mockRejectedValue(new Error('Forbidden'))
+      await expect(api.closeMany({ ids: ['t1'] })).rejects.toThrow('Forbidden')
+    })
+  })
+})

package/src/apis/tickets/TicketsApi.ts

@@ -1,9 +1,30 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Ticket, CreateTicketPayload, UpdateTicketPayload } from './types'
+import type {
+  Ticket,
+  CreateTicketPayload,
+  UpdateTicketPayload,
+  CloseManyTicketsPayload,
+} from './types'
 
 export class TicketsApi extends BaseCrudApi<Ticket, CreateTicketPayload, UpdateTicketPayload> {
   constructor(client: ApiClient) {
     super(client, '/tickets')
   }
+
+  /**
+   * Closes multiple tickets in a single request. This is the only ticket-close
+   * endpoint exposed by the API — there is no per-ticket close/update route.
+   *
+   * Pass `{ ids }` to close specific tickets, or `{ allContactsSelected: true, query }`
+   * to close every OPEN ticket matching `query` (the backend forces `isOpen: true`).
+   * @permissions tickets.close.all OR tickets.close.me
+   */
+  closeMany(payload: CloseManyTicketsPayload, headers?: Record<string, string>): Promise<unknown> {
+    return this.client.put<unknown, CloseManyTicketsPayload>(
+      `${this.basePath}/close-many`,
+      payload,
+      headers,
+    )
+  }
 }

package/src/apis/tickets/types.ts

@@ -67,3 +67,15 @@ export type UpdateTicketPayload = {
   comments?: string | null
   isOpen?: boolean
 }
+
+/**
+ * Body for `PUT /tickets/close-many`.
+ *
+ * Either close an explicit list of tickets by id, or close every open ticket
+ * matching a query. For the query variant the outer `query` is an object whose
+ * `query` field is a JSON-stringified list query (e.g. `JSON.stringify({ where: {} })`);
+ * the backend always forces `where.isOpen = true`.
+ */
+export type CloseManyTicketsPayload =
+  | { ids: string[]; ticketTopicIds?: string[] | string; comments?: string }
+  | { allContactsSelected: true; query: { query: string } }

package/src/apis/users/UsersApi.ts

@@ -1,8 +1,8 @@
 import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
+import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
 import type { User, CreateUserPayload, UpdateUserPayload } from './types'
 
-export class UsersApi extends BaseCrudApi<User, CreateUserPayload, UpdateUserPayload> {
+export class UsersApi extends ArchivableCrudApi<User, CreateUserPayload, UpdateUserPayload> {
   constructor(client: ApiClient) {
     super(client, '/users')
   }

package/src/apis/users/types.ts

@@ -67,4 +67,5 @@ export type UpdateUserPayload = {
   timetableId?: string | null
   preferences?: UserPreferences
   language?: string
+  archivedAt?: string | null
 }

package/src/core/ArchivableCrudApi.test.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ArchivableCrudApi } from './ArchivableCrudApi'
+import type { ApiClient } from './ApiClient'
+
+// ── Test types ───────────────────────────────────────────────────────
+
+type Item = { id: string; name: string; archivedAt: string | null }
+type CreateItem = { name: string }
+type UpdateItem = { name?: string; archivedAt?: string | null }
+
+// ── 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(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('ArchivableCrudApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: ArchivableCrudApi<Item, CreateItem, UpdateItem>
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new ArchivableCrudApi<Item, CreateItem, UpdateItem>(client, '/items')
+  })
+
+  it('inherits BaseCrudApi behavior (deleteById)', async () => {
+    vi.mocked(client.delete).mockResolvedValue({ id: '1', name: 'x', archivedAt: null })
+    await api.deleteById('1')
+    expect(client.delete).toHaveBeenCalledWith('/items/1', undefined)
+  })
+
+  describe('archive', () => {
+    it('PUTs basePath/id with an archivedAt timestamp', async () => {
+      const archived: Item = { id: 'abc', name: 'x', archivedAt: '2026-01-01T00:00:00.000Z' }
+      vi.mocked(client.put).mockResolvedValue(archived)
+
+      const result = await api.archive('abc')
+
+      const [path, body, headers] = vi.mocked(client.put).mock.calls.at(0) ?? []
+      expect(path).toBe('/items/abc')
+      expect(typeof (body as { archivedAt?: unknown }).archivedAt).toBe('string')
+      expect(headers).toBeUndefined()
+      expect(result).toEqual(archived)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.put).mockResolvedValue({ id: '1', name: 'x', archivedAt: null })
+      const headers = { 'X-Reason': 'cleanup' }
+
+      await api.archive('1', headers)
+      expect(vi.mocked(client.put).mock.calls.at(0)?.at(2)).toEqual(headers)
+    })
+  })
+
+  describe('unarchive', () => {
+    it('PUTs basePath/id with archivedAt null', async () => {
+      const restored: Item = { id: 'abc', name: 'x', archivedAt: null }
+      vi.mocked(client.put).mockResolvedValue(restored)
+
+      const result = await api.unarchive('abc')
+
+      expect(client.put).toHaveBeenCalledWith('/items/abc', { archivedAt: null }, undefined)
+      expect(result).toEqual(restored)
+    })
+  })
+
+  it('archive/unarchive stay bound when destructured', async () => {
+    vi.mocked(client.put).mockResolvedValue({ id: '1', name: 'x', archivedAt: null })
+    const { archive, unarchive } = api
+    await archive('1')
+    await unarchive('1')
+    expect(client.put).toHaveBeenCalledTimes(2)
+  })
+})

package/src/core/ArchivableCrudApi.ts

@@ -0,0 +1,42 @@
+import type { ApiClient } from './ApiClient'
+import { BaseCrudApi } from './BaseCrudApi'
+import type { ListQuery } from './types'
+
+/**
+ * CRUD base for resources that support soft-delete via an `archivedAt` timestamp
+ * (PUT `${basePath}/${id}` with `{ archivedAt }`). Adds `archive`/`unarchive` on
+ * top of {@link BaseCrudApi}.
+ *
+ * Only extend this for resources whose archive write mechanism is `archivedAt`.
+ * Resources that archive through a different field (e.g. cards use `isArchived`)
+ * or a dedicated endpoint (e.g. ticket-topics POST `/archive`) must NOT use this
+ * base and should implement `archive`/`unarchive` themselves.
+ */
+export class ArchivableCrudApi<
+  TResponse,
+  TCreate,
+  TUpdate extends { archivedAt?: string | null } = TCreate & { archivedAt?: string | null },
+  TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
+> extends BaseCrudApi<TResponse, TCreate, TUpdate, TQuery> {
+  constructor(client: ApiClient, basePath: string) {
+    super(client, basePath)
+    this.archive = this.archive.bind(this)
+    this.unarchive = this.unarchive.bind(this)
+  }
+
+  /**
+   * Archives a resource (soft-delete) by setting `archivedAt` to the current time.
+   * @permissions $resourceName.update
+   */
+  archive(id: string, headers?: Record<string, string>): Promise<TResponse> {
+    return this.updateById(id, { archivedAt: new Date().toISOString() } as TUpdate, headers)
+  }
+
+  /**
+   * Restores a previously archived resource by clearing `archivedAt`.
+   * @permissions $resourceName.update
+   */
+  unarchive(id: string, headers?: Record<string, string>): Promise<TResponse> {
+    return this.updateById(id, { archivedAt: null } as TUpdate, headers)
+  }
+}

package/src/core/BaseApiClient.test.ts

@@ -127,6 +127,33 @@ describe('BaseApiClient', () => {
     expect(result).toBeUndefined()
   })
 
+  it('returns undefined for empty body even when Content-Type is application/json', async () => {
+    // Regression: some endpoints (e.g. POST /me/takeover) reply 200 with the default
+    // application/json Content-Type and an empty body. `response.json()` would throw
+    // "SyntaxError: Unexpected end of input".
+    mockFetch({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      headers: { 'Content-Type': 'application/json' },
+      body: '',
+    })
+    const result = await client.post('/me/takeover')
+    expect(result).toBeUndefined()
+  })
+
+  it('returns undefined for 204 No Content regardless of Content-Type', async () => {
+    mockFetch({
+      ok: true,
+      status: 204,
+      statusText: 'No Content',
+      headers: { 'Content-Type': 'application/json' },
+      body: '',
+    })
+    const result = await client.post('/me/takeover')
+    expect(result).toBeUndefined()
+  })
+
   it('returns plain text when response is not JSON', async () => {
     mockFetch({ ok: true, status: 200, statusText: 'OK', body: 'OK' })
     const result = await client.post<string>('/action')
@@ -220,6 +247,20 @@ describe('BaseApiClient', () => {
     })
   })
 
+  it('does not throw when error response has Content-Type application/json but empty body', async () => {
+    mockFetch({
+      ok: false,
+      status: 502,
+      statusText: 'Bad Gateway',
+      headers: { 'Content-Type': 'application/json' },
+      body: '',
+    })
+    await expect(client.get('/fail')).rejects.toMatchObject({
+      message: 'HTTP Error 502: Bad Gateway',
+      status: 502,
+    })
+  })
+
   it('uses error field as message when message is absent', async () => {
     mockFetch({
       ok: false,

package/src/core/BaseApiClient.ts

@@ -63,7 +63,7 @@ export class BaseApiClient implements ApiClient {
   protected async handleResponse<TResponse>(response: Response): Promise<TResponse> {
     if (!response.ok) {
       const contentType = response.headers.get('Content-Type')
-      const isJson = contentType && contentType.includes('application/json')
+      const isJson = contentType?.includes('application/json') ?? false
 
       let errorMessage = `HTTP Error ${response.status}: ${response.statusText}`
       let errorClass: string | undefined
@@ -71,10 +71,13 @@ export class BaseApiClient implements ApiClient {
 
       if (isJson) {
         try {
-          const errorData = await response.json()
-          errorMessage = errorData.message || errorData.error || errorMessage
-          errorClass = errorData.error
-          validationErrors = errorData.validationErrors ?? null
+          const errorText = await response.text()
+          if (errorText) {
+            const errorData = JSON.parse(errorText)
+            errorMessage = errorData.message || errorData.error || errorMessage
+            errorClass = errorData.error
+            validationErrors = errorData.validationErrors ?? null
+          }
         } catch {
           // If JSON parsing fails, use the default error message
         }
@@ -83,23 +86,33 @@ export class BaseApiClient implements ApiClient {
       throw new ApiError(errorMessage, errorClass, response.status, validationErrors)
     }
 
+    // 204 No Content never has a body; short-circuit before reading the stream.
+    if (response.status === 204) {
+      return undefined as unknown as TResponse
+    }
+
+    // Read body as text once and treat an empty body as "no content" regardless of
+    // Content-Type. Servers sometimes return 200 with Content-Type: application/json
+    // and an empty body (e.g. POST endpoints whose framework keeps the default JSON
+    // content-type even when nothing is written). `response.json()` would throw
+    // "Unexpected end of input" in that case.
+    const text = await response.text()
+    if (!text) {
+      return undefined as unknown as TResponse
+    }
+
     const contentType = response.headers.get('Content-Type')
-    const isJson = contentType && contentType.includes('application/json')
+    const isJson = contentType?.includes('application/json') ?? false
 
     if (isJson) {
-      return (await response.json()) as TResponse
+      return JSON.parse(text) as TResponse
     }
 
-    const text = await response.text()
-    if (text) {
-      try {
-        return JSON.parse(text) as TResponse
-      } catch {
-        return text as unknown as TResponse
-      }
+    try {
+      return JSON.parse(text) as TResponse
+    } catch {
+      return text as unknown as TResponse
     }
-
-    return undefined as unknown as TResponse
   }
 
   get<TResponse = unknown>(endpoint: string, headers?: Record<string, string>): Promise<TResponse> {