@ikatec/digisac-api-sdk 4.1.0 → 4.2.0

package/src/apis/people/types.ts

@@ -17,10 +17,15 @@ export type PersonRelationships = 'organizations' | 'contacts'
 
 export type CreatePersonPayload = {
   name: string
-  document?: string
+  document?: string | null
+  /** Organizations of the account to link the person to (400 if any belongs to another account). */
+  organizationIds?: string[]
 }
 
 export type UpdatePersonPayload = {
-  name?: string
+  /** Required by the backend on every update (400 `required` otherwise). */
+  name: string
   document?: string | null
+  /** Replaces the linked organizations: `[]` unlinks all, omitting it keeps them. */
+  organizationIds?: string[]
 }

package/src/apis/permissions/PermissionsApi.test.ts

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { PermissionsApi } from './PermissionsApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type { Permission } 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 permission: Permission = { id: 'p-1', name: 'customFields.create', type: 'customFields' }
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('PermissionsApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: PermissionsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new PermissionsApi(client)
+  })
+
+  it('exposes only the read routes served by the backend', () => {
+    expect(api.basePath).toBe('/permissions')
+    expect(api).not.toHaveProperty('create')
+    expect(api).not.toHaveProperty('updateById')
+    expect(api).not.toHaveProperty('deleteById')
+  })
+
+  describe('getMany', () => {
+    it('calls client.get with /permissions and no query string when there is no query', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [permission], total: 1 })
+      await api.getMany()
+      expect(client.get).toHaveBeenCalledWith('/permissions', undefined)
+    })
+
+    it('serializes the query in the client format', async () => {
+      vi.mocked(client.get).mockResolvedValue([permission])
+      const result = await api.getMany({ paginate: false })
+      expect(client.get).toHaveBeenCalledWith(
+        `/permissions?query=${encodeURIComponent(JSON.stringify({ paginate: false }))}`,
+        undefined,
+      )
+      expect(result).toEqual([permission])
+    })
+  })
+
+  describe('getOne', () => {
+    it('asks for a single unpaginated result and returns it', async () => {
+      vi.mocked(client.get).mockResolvedValue([permission])
+      const result = await api.getOne({ where: { name: 'customFields.create' } })
+      const query = { where: { name: 'customFields.create' }, limit: 1, paginate: false }
+      expect(client.get).toHaveBeenCalledWith(
+        `/permissions?query=${encodeURIComponent(JSON.stringify(query))}`,
+        undefined,
+      )
+      expect(result).toEqual(permission)
+    })
+
+    it('returns null when nothing matches', async () => {
+      vi.mocked(client.get).mockResolvedValue([])
+      expect(await api.getOne()).toBeNull()
+    })
+  })
+
+  describe('getById', () => {
+    it('calls client.get with /permissions/:id', async () => {
+      vi.mocked(client.get).mockResolvedValue(permission)
+      const result = await api.getById('p-1')
+      expect(client.get).toHaveBeenCalledWith('/permissions/p-1', undefined)
+      expect(result).toEqual(permission)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(permission)
+      const headers = { 'X-Custom': 'h' }
+      await api.getById('p-1', undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/permissions/p-1', headers)
+    })
+  })
+})

package/src/apis/permissions/PermissionsApi.ts

@@ -1,12 +1,12 @@
 import type { ApiClient } from '../../core/ApiClient'
-import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Permission, CreatePermissionPayload, UpdatePermissionPayload } from './types'
+import { BaseReadApi } from '../../core/BaseReadApi'
+import type { Permission } from './types'
 
-export class PermissionsApi extends BaseCrudApi<
-  Permission,
-  CreatePermissionPayload,
-  UpdatePermissionPayload
-> {
+/**
+ * The permission catalog used by roles. The backend only serves `GET /permissions` and
+ * `GET /permissions/:id` (guarded by `roles.view`), so there is no create/update/delete.
+ */
+export class PermissionsApi extends BaseReadApi<Permission> {
   constructor(client: ApiClient) {
     super(client, '/permissions')
   }

package/src/apis/permissions/types.ts

@@ -210,24 +210,12 @@ export type PermissionName =
   | 'kanban.update'
   | 'kanban.destroy'
 
+/**
+ * A permission, as `GET /permissions` answers it (the transformer only picks these fields).
+ * Permissions are a fixed catalog: the API is read-only.
+ */
 export type Permission = {
   id: string
   name: PermissionName
   type: PermissionType | null
-  description: string | null
-  createdAt: string
-  updatedAt: string
-  deletedAt: string | null
-}
-
-export type CreatePermissionPayload = {
-  name: PermissionName
-  type?: PermissionType
-  description?: string
-}
-
-export type UpdatePermissionPayload = {
-  name?: PermissionName
-  type?: PermissionType | null
-  description?: string | null
 }

package/src/apis/personalAccessTokens/PersonalAccessTokensApi.ts

@@ -6,6 +6,11 @@ import type {
   UpdatePersonalAccessTokenPayload,
 } from './types'
 
+/**
+ * Personal access tokens of the authenticated user (`/me/tokens`, all routes guarded by
+ * `settingsApi.update`). The listing is scoped to the user; `getById` of a missing token answers
+ * 404 (`{ message: 'Not found' }`) instead of `null`.
+ */
 export class PersonalAccessTokensApi extends BaseCrudApi<
   PersonalAccessToken,
   CreatePersonalAccessTokenPayload,

package/src/apis/personalAccessTokens/types.ts

@@ -1,28 +1,49 @@
 import type { User } from '../users/types'
 
+export type PersonalAccessTokenStatus = 'active' | 'revoked' | 'expired'
+
+/** Accepted lifetimes of a token (`No expiration` keeps `accessTokenExpiresAt` null). */
+export type PersonalAccessTokenExpiresIn = '30d' | '90d' | '180d' | '1y' | 'No expiration'
+
+/**
+ * A personal access token of the authenticated user.
+ *
+ * `accessToken` comes in full only in the `create` answer; every other route masks it
+ * (`abcde***vwxyz`). `status` and `user` (only `{ name }`) come on `getMany`/`getById`.
+ * `deleteById` revokes the token (soft delete): it keeps being listed with `status: 'revoked'`.
+ */
 export type PersonalAccessToken = {
   id: string
   name: string
+  /** `*` when created without a scope. */
   scope: string | null
   accessToken: string
   accessTokenExpiresAt: string | null
   userId: string
+  clientId: string | null
+  impersonate?: boolean | null
   createdAt: string
   updatedAt: string
   deletedAt: string | null
+  /** Only on `getMany`/`getById` answers. */
+  status?: PersonalAccessTokenStatus
   // relationships
-  user?: User
+  /** Only on `getMany`/`getById` answers, with just the name. */
+  user?: Pick<User, 'name'>
 }
 
 export type PersonalAccessTokenRelationships = 'user'
 
 export type CreatePersonalAccessTokenPayload = {
+  /** Up to 255 characters. */
   name: string
+  /** Up to 255 characters (`*` by default). */
   scope?: string
-  accessTokenExpiresAt?: string
+  expiresIn?: PersonalAccessTokenExpiresIn
 }
 
 export type UpdatePersonalAccessTokenPayload = {
-  name?: string
-  scope?: string | null
+  /** Required by the backend on every update (400 `required` otherwise). */
+  name: string
+  scope?: string
 }

package/src/apis/queryFormat.test.ts

@@ -5,6 +5,9 @@ import { BaseApiClient } from '../core/BaseApiClient'
 import type { QueryFormat } from '../core/queryString'
 import { AuthHistoryApi } from './authHistory/AuthHistoryApi'
 import { ContactsApi } from './contacts/ContactsApi'
+import { DashboardApi } from './dashboard/DashboardApi'
+import { NowApi } from './now/NowApi'
+import { PermissionsApi } from './permissions/PermissionsApi'
 import { ServiceAccessManagementApi } from './serviceAccessManagement/ServiceAccessManagementApi'
 import { StickerUsersApi } from './stickerUsers/StickerUsersApi'
 import { TermsApi } from './terms/TermsApi'
@@ -84,6 +87,78 @@ const cases: Case[] = [
       return (f ? api.withQueryFormat(f) : api).getMany({ page: 2, perPage: 5 })
     },
   },
+  {
+    name: 'DashboardApi.getGeneral',
+    path: '/dashboard/general',
+    query: { status: 'closed', departmentId: ['d1'] },
+    call: (client, f) => {
+      const api = new DashboardApi(client)
+      return (f ? api.withQueryFormat(f) : api).getGeneral({
+        status: 'closed',
+        departmentId: ['d1'],
+      })
+    },
+  },
+  {
+    name: 'NowApi.getResume',
+    path: '/now/resume',
+    query: { departmentId: ['d1'], userId: 'u1' },
+    call: (client, f) => {
+      const api = new NowApi(client)
+      return (f ? api.withQueryFormat(f) : api).getResume({ departmentId: ['d1'], userId: 'u1' })
+    },
+  },
+  {
+    name: 'NowApi.getAttendanceResume',
+    path: '/now/attendance-resume',
+    query: { departmentId: ['d1'], userId: 'u1' },
+    call: (client, f) => {
+      const api = new NowApi(client)
+      return (f ? api.withQueryFormat(f) : api).getAttendanceResume({
+        departmentId: ['d1'],
+        userId: 'u1',
+      })
+    },
+  },
+  {
+    name: 'NowApi.getDepartmentsResume',
+    path: '/now/departments-resume',
+    query: { departmentId: ['d1'], userId: 'u1' },
+    call: (client, f) => {
+      const api = new NowApi(client)
+      return (f ? api.withQueryFormat(f) : api).getDepartmentsResume({
+        departmentId: ['d1'],
+        userId: 'u1',
+      })
+    },
+  },
+  {
+    name: 'PermissionsApi.getMany',
+    path: '/permissions',
+    query: listQuery,
+    call: (client, f) => {
+      const api = new PermissionsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getMany(listQuery)
+    },
+  },
+  {
+    name: 'PermissionsApi.getById',
+    path: '/permissions/p1',
+    query: getQuery,
+    call: (client, f) => {
+      const api = new PermissionsApi(client)
+      return (f ? api.withQueryFormat(f) : api).getById('p1', { attributes: ['id'] })
+    },
+  },
+  {
+    name: 'AuthHistoryApi.getById',
+    path: '/auth-history/a1',
+    query: getQuery,
+    call: (client, f) => {
+      const api = new AuthHistoryApi(client)
+      return (f ? api.withQueryFormat(f) : api).getById('a1', { attributes: ['id'] })
+    },
+  },
   {
     name: 'ServiceAccessManagementApi.getMany',
     path: '/service-access-management',

package/src/apis/roles/RolesApi.ts

@@ -1,8 +1,13 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
-import type { Role, CreateRolePayload, UpdateRolePayload } from './types'
+import type { Role, CreateRolePayload, UpdateRolePayload, RolesListQuery } from './types'
 
-export class RolesApi extends BaseCrudApi<Role, CreateRolePayload, UpdateRolePayload> {
+export class RolesApi extends BaseCrudApi<
+  Role,
+  CreateRolePayload,
+  UpdateRolePayload,
+  RolesListQuery
+> {
   constructor(client: ApiClient) {
     super(client, '/roles')
   }

package/src/apis/roles/types.ts

@@ -1,5 +1,9 @@
+import type { ListQuery } from '../../core/types'
 import type { Permission } from '../permissions/types'
 
+/**
+ * A role (cargo). Roles are not soft-deleted, so there is no `deletedAt`.
+ */
 export type Role = {
   id: string
   displayName: string
@@ -7,21 +11,40 @@ export type Role = {
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
+  /** Only when listed with `customInclude: ['usersCount']`. */
+  usersCount?: number
   // relationships
   permissions?: Permission[]
 }
 
 export type RoleRelationships = 'permissions'
 
+/**
+ * The permissions of a role, by id or `{ id }`. The backend reads the `permissions` key (also
+ * `permissionsId`/`permissionsIds`) — any other key is silently ignored and the role ends up with
+ * no permissions.
+ */
+export type RolePermissionRef = string | { id: string }
+
 export type CreateRolePayload = {
+  /** Up to 255 characters; must be unique in the account. */
   displayName: string
   isAdmin?: boolean
-  permissionIds?: string[]
+  permissions?: RolePermissionRef[]
 }
 
 export type UpdateRolePayload = {
-  displayName?: string
+  /** Required by the backend on every update (400 `required` otherwise). */
+  displayName: string
   isAdmin?: boolean | null
-  permissionIds?: string[]
+  /** Replaces the role permissions. An empty array leaves them unchanged. */
+  permissions?: RolePermissionRef[]
+}
+
+/** List query of `/roles`, with the backend extras to count the users of each role. */
+export type RolesListQuery = ListQuery<Role> & {
+  /** `['usersCount']` adds `usersCount` to each role. */
+  customInclude?: 'usersCount'[]
+  /** Which users `usersCount` counts (default `all`). */
+  usersCountFilter?: 'all' | 'active' | 'archived'
 }

package/src/apis/terms/TermsApi.ts

@@ -12,7 +12,10 @@ import type { Term } from './types'
 export class TermsApi extends BaseApi implements HasGetById<Term> {
   public readonly basePath = '/terms'
 
-  /** Returns a single term by its ID, scoped to the current account (`null` when not found). */
+  /**
+   * Returns a single term by its ID, scoped to the current account. When it does not exist the
+   * backend answers 200 with an empty body, which resolves to `undefined`.
+   */
   getById(id: string, query?: GetByIdQuery<Term>, headers?: Record<string, string>): Promise<Term> {
     const queryString = this.toQueryString(query)
     return this.client.get<Term>(`${this.basePath}/${id}${queryString}`, headers)

package/src/apis/timetable/types.ts

@@ -1,8 +1,15 @@
+export type TimetableWeekDay = 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
+
+/**
+ * A working period of the timetable. `start`/`end` are `HH:MM` and `end` must be later than
+ * `start`; the period applies to every day in `weekDays`.
+ */
 export type TimetableWorkSlot = {
-  day: number
+  /** `HH:MM` */
   start: string
+  /** `HH:MM`, later than `start`. */
   end: string
-  active: boolean
+  weekDays: TimetableWeekDay[]
 }
 
 export type Timetable = {
@@ -16,13 +23,12 @@ export type Timetable = {
 }
 
 export type CreateTimetablePayload = {
+  /** Must be unique in the account (409 otherwise, unless the account allows duplicate names). */
   name: string
+  /** Minutes before the end of the period to notify. Must be truthy: `0` answers 400 `required`. */
   previousTimeToNotification: number
   workPlan: TimetableWorkSlot[]
 }
 
-export type UpdateTimetablePayload = {
-  name?: string
-  previousTimeToNotification?: number
-  workPlan?: TimetableWorkSlot[]
-}
+/** The backend requires the three fields on every update (400 `required` otherwise). */
+export type UpdateTimetablePayload = CreateTimetablePayload

package/src/core/BaseCrudApi.ts

@@ -1,6 +1,5 @@
-import type { ApiClient } from './ApiClient'
-import { BaseApi } from './BaseApi'
-import type { CrudApi, GetByIdQuery, ListQuery, Paginated } from './types'
+import { BaseReadApi } from './BaseReadApi'
+import type { CrudApi, ListQuery } from './types'
 export type {
   WhereClause,
   IncludeItem,
@@ -15,71 +14,16 @@ export type {
   CrudApi,
 } from './types'
 
+/** Generic CRUD resource: the reads of `BaseReadApi` plus `create`, `updateById` and `deleteById`. */
 export class BaseCrudApi<
   TResponse,
   TCreate,
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
 >
-  extends BaseApi
+  extends BaseReadApi<TResponse, TQuery>
   implements CrudApi<TResponse, TCreate, TUpdate, TQuery>
 {
-  public readonly basePath: string
-
-  constructor(client: ApiClient, basePath: string) {
-    super(client)
-    this.basePath = basePath.replace(/\/$/, '')
-  }
-
-  getMany(
-    query: TQuery & { paginate: false },
-    headers?: Record<string, string>,
-  ): Promise<TResponse[]>
-  getMany(
-    query?: TQuery & { paginate?: true },
-    headers?: Record<string, string>,
-  ): Promise<Paginated<TResponse>>
-  getMany(
-    query?: TQuery,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<TResponse> | TResponse[]>
-  getMany(
-    query?: TQuery,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<TResponse> | TResponse[]> {
-    const queryString = this.toQueryString(query)
-    return this.client.get<Paginated<TResponse> | TResponse[]>(
-      `${this.basePath}${queryString}`,
-      headers,
-    )
-  }
-
-  /**
-   * 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,
-    )
-    // An empty response body resolves to `undefined`.
-    return results?.[0] ?? null
-  }
-
-  /**
-   * Returns a single resource by ID.
-   * @permissions $resourceName.view
-   */
-  getById(
-    id: string,
-    query?: GetByIdQuery<TResponse>,
-    headers?: Record<string, string>,
-  ): Promise<TResponse> {
-    return this.client.get<TResponse>(`${this.basePath}/${id}${this.toQueryString(query)}`, headers)
-  }
-
   /**
    * Creates a new resource.
    * @permissions $resourceName.create

package/src/core/BaseReadApi.ts

@@ -0,0 +1,70 @@
+import type { ApiClient } from './ApiClient'
+import { BaseApi } from './BaseApi'
+import type { GetByIdQuery, HasGetById, HasGetMany, ListQuery, Paginated } from './types'
+
+/**
+ * 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).
+ */
+export class BaseReadApi<TResponse, TQuery extends ListQuery<TResponse> = ListQuery<TResponse>>
+  extends BaseApi
+  implements HasGetMany<TResponse, TQuery>, HasGetById<TResponse>
+{
+  public readonly basePath: string
+
+  constructor(client: ApiClient, basePath: string) {
+    super(client)
+    this.basePath = basePath.replace(/\/$/, '')
+  }
+
+  getMany(
+    query: TQuery & { paginate: false },
+    headers?: Record<string, string>,
+  ): Promise<TResponse[]>
+  getMany(
+    query?: TQuery & { paginate?: true },
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse>>
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]>
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]> {
+    const queryString = this.toQueryString(query)
+    return this.client.get<Paginated<TResponse> | TResponse[]>(
+      `${this.basePath}${queryString}`,
+      headers,
+    )
+  }
+
+  /**
+   * 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,
+    )
+    // An empty response body resolves to `undefined`.
+    return results?.[0] ?? null
+  }
+
+  /**
+   * Returns a single resource by ID. When it does not exist most routes answer 200 with an empty
+   * body, which resolves to `undefined`.
+   * @permissions $resourceName.view
+   */
+  getById(
+    id: string,
+    query?: GetByIdQuery<TResponse>,
+    headers?: Record<string, string>,
+  ): Promise<TResponse> {
+    return this.client.get<TResponse>(`${this.basePath}/${id}${this.toQueryString(query)}`, headers)
+  }
+}

package/src/core/index.ts

@@ -20,6 +20,7 @@ export {
 } from './errors'
 export type { FieldError, ErrorClassName, ApiErrorOptions } from './errors'
 export { BaseApi } from './BaseApi'
+export { BaseReadApi } from './BaseReadApi'
 export { BaseCrudApi } from './BaseCrudApi'
 export { ArchivableCrudApi } from './ArchivableCrudApi'
 export type { WhereClause, IncludeItem, ListQuery, GetByIdQuery, Paginated } from './types'