@ikatec/digisac-api-sdk 2.1.3 → 2.2.0

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/BaseCrudApi.test.ts

@@ -131,6 +131,37 @@ describe('BaseCrudApi', () => {
     })
   })
 
+  // ── getOne ───────────────────────────────────────────────────────
+
+  describe('getOne', () => {
+    it('requests limit 1 (non-paginated) and returns the first item', async () => {
+      const item: Item = { id: '1', name: 'Test' }
+      vi.mocked(client.get).mockResolvedValue([item])
+
+      const result = await api.getOne()
+      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
+      expect(calledUrl).toContain('/items?')
+      expect(calledUrl).toContain('limit=1')
+      expect(calledUrl).toContain('paginate=false')
+      expect(result).toEqual(item)
+    })
+
+    it('returns null when no records match', async () => {
+      vi.mocked(client.get).mockResolvedValue([])
+
+      const result = await api.getOne({ where: { name: 'missing' } })
+      expect(result).toBeNull()
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue([])
+      const headers = { 'X-Custom': 'value' }
+
+      await api.getOne(undefined, headers)
+      expect(vi.mocked(client.get).mock.calls.at(0)?.at(1)).toEqual(headers)
+    })
+  })
+
   // ── getById ──────────────────────────────────────────────────────
 
   describe('getById', () => {

package/src/core/BaseCrudApi.ts

@@ -28,6 +28,7 @@ export class BaseCrudApi<
     this.client = client
     this.basePath = basePath.replace(/\/$/, '')
     this.getMany = this.getMany.bind(this)
+    this.getOne = this.getOne.bind(this)
     this.getById = this.getById.bind(this)
     this.create = this.create.bind(this)
     this.updateById = this.updateById.bind(this)
@@ -53,6 +54,19 @@ export class BaseCrudApi<
     )
   }
 
+  /**
+   * Returns the first resource matching the query, or `null` when none match.
+   * Convenience over `getMany` with `limit: 1`.
+   * @permissions $resourceName.view
+   */
+  async getOne(query?: TQuery, headers?: Record<string, string>): Promise<TResponse | null> {
+    const results = await this.getMany(
+      { ...query, limit: 1, paginate: false } as TQuery & { paginate: false },
+      headers,
+    )
+    return results[0] ?? null
+  }
+
   /**
    * Returns a single resource by ID.
    * @permissions $resourceName.view

package/src/core/index.ts

@@ -2,4 +2,5 @@ export type { ApiClient, HttpMethod } from './ApiClient'
 export { BaseApiClient, ApiError } from './BaseApiClient'
 export type { ValidationError } from './BaseApiClient'
 export { BaseCrudApi } from './BaseCrudApi'
+export { ArchivableCrudApi } from './ArchivableCrudApi'
 export type { WhereClause, IncludeItem, ListQuery, GetByIdQuery, Paginated } from './types'