@ikatec/digisac-api-sdk 4.1.0 → 4.3.0

package/dist/core/BaseReadApi.mjs

@@ -0,0 +1,43 @@
+import { BaseApi } from "./BaseApi.mjs";
+
+//#region src/core/BaseReadApi.ts
+/**
+* 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).
+*/
+var BaseReadApi = class extends BaseApi {
+	basePath;
+	constructor(client, basePath) {
+		super(client);
+		this.basePath = basePath.replace(/\/$/, "");
+	}
+	getMany(query, headers) {
+		const queryString = this.toQueryString(query);
+		return this.client.get(`${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, headers) {
+		return (await this.getMany({
+			...query,
+			limit: 1,
+			paginate: false
+		}, headers))?.[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, query, headers) {
+		return this.client.get(`${this.basePath}/${id}${this.toQueryString(query)}`, headers);
+	}
+};
+
+//#endregion
+export { BaseReadApi };
+//# sourceMappingURL=BaseReadApi.mjs.map

package/dist/core/BaseReadApi.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseReadApi.mjs","names":[],"sources":["../../src/core/BaseReadApi.ts"],"sourcesContent":["import type { ApiClient } from './ApiClient'\nimport { BaseApi } from './BaseApi'\nimport type { GetByIdQuery, HasGetById, HasGetMany, ListQuery, Paginated } from './types'\n\n/**\n * Generic read-only resource: `getMany`, `getOne` and `getById` under `basePath`. Base of\n * `BaseCrudApi`, and of the resources the backend only serves for reading (e.g. permissions,\n * auth history).\n */\nexport class BaseReadApi<TResponse, TQuery extends ListQuery<TResponse> = ListQuery<TResponse>>\n  extends BaseApi\n  implements HasGetMany<TResponse, TQuery>, HasGetById<TResponse>\n{\n  public readonly basePath: string\n\n  constructor(client: ApiClient, basePath: string) {\n    super(client)\n    this.basePath = basePath.replace(/\\/$/, '')\n  }\n\n  getMany(\n    query: TQuery & { paginate: false },\n    headers?: Record<string, string>,\n  ): Promise<TResponse[]>\n  getMany(\n    query?: TQuery & { paginate?: true },\n    headers?: Record<string, string>,\n  ): Promise<Paginated<TResponse>>\n  getMany(\n    query?: TQuery,\n    headers?: Record<string, string>,\n  ): Promise<Paginated<TResponse> | TResponse[]>\n  getMany(\n    query?: TQuery,\n    headers?: Record<string, string>,\n  ): Promise<Paginated<TResponse> | TResponse[]> {\n    const queryString = this.toQueryString(query)\n    return this.client.get<Paginated<TResponse> | TResponse[]>(\n      `${this.basePath}${queryString}`,\n      headers,\n    )\n  }\n\n  /**\n   * Returns the first resource matching the query, or `null` when none match.\n   * Convenience over `getMany` with `limit: 1`.\n   * @permissions $resourceName.view\n   */\n  async getOne(query?: TQuery, headers?: Record<string, string>): Promise<TResponse | null> {\n    const results = await this.getMany(\n      { ...query, limit: 1, paginate: false } as TQuery & { paginate: false },\n      headers,\n    )\n    // An empty response body resolves to `undefined`.\n    return results?.[0] ?? null\n  }\n\n  /**\n   * Returns a single resource by ID. When it does not exist most routes answer 200 with an empty\n   * body, which resolves to `undefined`.\n   * @permissions $resourceName.view\n   */\n  getById(\n    id: string,\n    query?: GetByIdQuery<TResponse>,\n    headers?: Record<string, string>,\n  ): Promise<TResponse> {\n    return this.client.get<TResponse>(`${this.basePath}/${id}${this.toQueryString(query)}`, headers)\n  }\n}\n"],"mappings":";;;;;;;;AASA,IAAa,cAAb,cACU,QAEV;CACE,AAAgB;CAEhB,YAAY,QAAmB,UAAkB;AAC/C,QAAM,OAAO;AACb,OAAK,WAAW,SAAS,QAAQ,OAAO,GAAG;;CAe7C,QACE,OACA,SAC6C;EAC7C,MAAM,cAAc,KAAK,cAAc,MAAM;AAC7C,SAAO,KAAK,OAAO,IACjB,GAAG,KAAK,WAAW,eACnB,QACD;;;;;;;CAQH,MAAM,OAAO,OAAgB,SAA6D;AAMxF,UALgB,MAAM,KAAK,QACzB;GAAE,GAAG;GAAO,OAAO;GAAG,UAAU;GAAO,EACvC,QACD,IAEgB,MAAM;;;;;;;CAQzB,QACE,IACA,OACA,SACoB;AACpB,SAAO,KAAK,OAAO,IAAe,GAAG,KAAK,SAAS,GAAG,KAAK,KAAK,cAAc,MAAM,IAAI,QAAQ"}

package/dist/core/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_core_errors = require('./errors.cjs');
 const require_core_BaseApiClient = require('./BaseApiClient.cjs');
 const require_core_BaseApi = require('./BaseApi.cjs');
+const require_core_BaseReadApi = require('./BaseReadApi.cjs');
 const require_core_BaseCrudApi = require('./BaseCrudApi.cjs');
 const require_core_ArchivableCrudApi = require('./ArchivableCrudApi.cjs');
 
@@ -13,6 +14,7 @@ exports.BadRequestError = require_core_errors.BadRequestError;
 exports.BaseApi = require_core_BaseApi.BaseApi;
 exports.BaseApiClient = require_core_BaseApiClient.BaseApiClient;
 exports.BaseCrudApi = require_core_BaseCrudApi.BaseCrudApi;
+exports.BaseReadApi = require_core_BaseReadApi.BaseReadApi;
 exports.ConflictError = require_core_errors.ConflictError;
 exports.DigisacError = require_core_errors.DigisacError;
 exports.InternalServerError = require_core_errors.InternalServerError;

package/dist/core/index.d.ts

@@ -5,6 +5,7 @@ export type { QueryFormat } from './queryString';
 export { DigisacError, ApiConnectionError, ApiError, BadRequestError, ValidationError, AuthenticationError, PaymentRequiredError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, parseFieldErrors, } 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';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA"}

package/dist/core/index.mjs

@@ -1,7 +1,8 @@
 import { ApiConnectionError, ApiError, AuthenticationError, BadRequestError, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors } from "./errors.mjs";
 import { BaseApiClient } from "./BaseApiClient.mjs";
 import { BaseApi } from "./BaseApi.mjs";
+import { BaseReadApi } from "./BaseReadApi.mjs";
 import { BaseCrudApi } from "./BaseCrudApi.mjs";
 import { ArchivableCrudApi } from "./ArchivableCrudApi.mjs";
 
-export { ApiConnectionError, ApiError, ArchivableCrudApi, AuthenticationError, BadRequestError, BaseApi, BaseApiClient, BaseCrudApi, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors };
+export { ApiConnectionError, ApiError, ArchivableCrudApi, AuthenticationError, BadRequestError, BaseApi, BaseApiClient, BaseCrudApi, BaseReadApi, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors };

package/dist/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_core_errors = require('./core/errors.cjs');
 const require_core_BaseApiClient = require('./core/BaseApiClient.cjs');
 const require_core_BaseApi = require('./core/BaseApi.cjs');
+const require_core_BaseReadApi = require('./core/BaseReadApi.cjs');
 const require_core_BaseCrudApi = require('./core/BaseCrudApi.cjs');
 const require_core_ArchivableCrudApi = require('./core/ArchivableCrudApi.cjs');
 require('./core/index.cjs');
@@ -14,6 +15,7 @@ exports.BadRequestError = require_core_errors.BadRequestError;
 exports.BaseApi = require_core_BaseApi.BaseApi;
 exports.BaseApiClient = require_core_BaseApiClient.BaseApiClient;
 exports.BaseCrudApi = require_core_BaseCrudApi.BaseCrudApi;
+exports.BaseReadApi = require_core_BaseReadApi.BaseReadApi;
 exports.ConflictError = require_core_errors.ConflictError;
 exports.DigisacError = require_core_errors.DigisacError;
 exports.InternalServerError = require_core_errors.InternalServerError;

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { ApiConnectionError, ApiError, AuthenticationError, BadRequestError, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors } from "./core/errors.mjs";
 import { BaseApiClient } from "./core/BaseApiClient.mjs";
 import { BaseApi } from "./core/BaseApi.mjs";
+import { BaseReadApi } from "./core/BaseReadApi.mjs";
 import { BaseCrudApi } from "./core/BaseCrudApi.mjs";
 import { ArchivableCrudApi } from "./core/ArchivableCrudApi.mjs";
 import "./core/index.mjs";
 
-export { ApiConnectionError, ApiError, ArchivableCrudApi, AuthenticationError, BadRequestError, BaseApi, BaseApiClient, BaseCrudApi, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors };
+export { ApiConnectionError, ApiError, ArchivableCrudApi, AuthenticationError, BadRequestError, BaseApi, BaseApiClient, BaseCrudApi, BaseReadApi, ConflictError, DigisacError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, ValidationError, parseFieldErrors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikatec/digisac-api-sdk",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/src/apis/authHistory/AuthHistoryApi.test.ts

@@ -25,7 +25,6 @@ const entry: AuthHistory = {
   event: 'auth',
   userId: 'user-1',
   accountId: 'acc-1',
-  branch: 'main',
   originIP: '127.0.0.1',
   originUA: 'Mozilla/5.0',
   createdAt: '2024-01-01T00:00:00Z',
@@ -95,10 +94,19 @@ describe('AuthHistoryApi', () => {
       expect(result).toEqual(entry)
     })
 
+    it('sends the query (e.g. include) in the query string, not as headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(entry)
+      await api.getById('ah-1', { include: ['user'] })
+      expect(client.get).toHaveBeenCalledWith(
+        `/auth-history/ah-1?query=${encodeURIComponent(JSON.stringify({ include: ['user'] }))}`,
+        undefined,
+      )
+    })
+
     it('forwards custom headers', async () => {
       vi.mocked(client.get).mockResolvedValue(entry)
       const headers = { 'X-Custom': 'h' }
-      await api.getById('ah-1', headers)
+      await api.getById('ah-1', undefined, headers)
       expect(client.get).toHaveBeenCalledWith('/auth-history/ah-1', headers)
     })
 

package/src/apis/authHistory/AuthHistoryApi.ts

@@ -1,43 +1,17 @@
-import { BaseApi } from '../../core/BaseApi'
-import type { ListQuery, Paginated, HasGetMany, HasGetById } from '../../core/types'
+import type { ApiClient } from '../../core/ApiClient'
+import { BaseReadApi } from '../../core/BaseReadApi'
 import type { AuthHistory } from './types'
 
-export class AuthHistoryApi
-  extends BaseApi
-  implements HasGetMany<AuthHistory>, HasGetById<AuthHistory>
-{
-  /**
-   * Returns a paginated list of authentication events (auth, password_change, logout). Non-admin users can only see their own records.
-   * @permissions authHistory.view
-   */
-  getMany(
-    query: ListQuery<AuthHistory> & { paginate: false },
-    headers?: Record<string, string>,
-  ): Promise<AuthHistory[]>
-  getMany(
-    query?: ListQuery<AuthHistory> & { paginate?: true },
-    headers?: Record<string, string>,
-  ): Promise<Paginated<AuthHistory>>
-  getMany(
-    query?: ListQuery<AuthHistory>,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<AuthHistory> | AuthHistory[]>
-  getMany(
-    query?: ListQuery<AuthHistory>,
-    headers?: Record<string, string>,
-  ): Promise<Paginated<AuthHistory> | AuthHistory[]> {
-    const queryString = this.toQueryString(query)
-    return this.client.get<Paginated<AuthHistory> | AuthHistory[]>(
-      `/auth-history${queryString}`,
-      headers,
-    )
-  }
-
-  /**
-   * Returns a single authentication event by its ID. Non-admin users can only access their own records.
-   * @permissions authHistory.view
-   */
-  getById(id: string, headers?: Record<string, string>): Promise<AuthHistory> {
-    return this.client.get<AuthHistory>(`/auth-history/${id}`, headers)
+/**
+ * Authentication events (auth, password_change, logout), read-only (guarded by
+ * `authHistory.view`). Non-admin users can only see and access their own records.
+ *
+ * Since 4.2 `getById` has the base signature `(id, query?, headers?)`: a call written as
+ * `getById(id, headers)` with the headers in a variable still compiles, but the headers are sent
+ * as the query string — move them to the third argument.
+ */
+export class AuthHistoryApi extends BaseReadApi<AuthHistory> {
+  constructor(client: ApiClient) {
+    super(client, '/auth-history')
   }
 }

package/src/apis/authHistory/types.ts

@@ -8,9 +8,10 @@ export type AuthHistory = {
   event: AuthHistoryEvent
   userId: string
   accountId: string
-  branch: string
-  originIP: string
-  originUA: string
+  /** Nullable in the database. */
+  originIP: string | null
+  /** Nullable in the database. */
+  originUA: string | null
   createdAt: string
   updatedAt: string
   // relationships

package/src/apis/customFields/types.ts

@@ -17,33 +17,29 @@ export type CustomFieldType =
   | 'list'
 
 export type CustomFieldOption = {
-  id?: string
-  label?: string
+  id?: string | null
+  label?: string | null
 }
 
-/** Settings for `list` and `checkbox` types: a list of selectable options. */
-export type CustomFieldListSettings = {
-  options: CustomFieldOption[]
+/**
+ * Settings of a custom field — a free JSONB the backend does not validate, echoed back as sent.
+ * The fields below are the ones the web app form sends (`front/src/pages/custom-fields/components/
+ * form.tsx`): `options` for the `list` and `checkbox` types, `min`/`max` for `numeric` and `monetary`,
+ * `currency` for `monetary`, `maxLength` for `text` and `long-text`, and `placeholder` for the inputs.
+ */
+export type CustomFieldSettings = {
+  options?: CustomFieldOption[]
+  placeholder?: string | null
+  currency?: string | null
+  maxLength?: number | null
+  min?: string | null
+  max?: string | null
 }
 
-/** Settings for `monetary` type: optional min/max value constraints. */
-export type CustomFieldMonetarySettings = {
-  options: CustomFieldOption[]
-  min?: string
-  max?: string
-}
-
-/** Settings for `text` and `long-text` types: optional max length constraint. */
-export type CustomFieldTextSettings = {
-  options: CustomFieldOption[]
-  maxLength?: number
-}
-
-export type CustomFieldSettings =
-  | CustomFieldListSettings
-  | CustomFieldMonetarySettings
-  | CustomFieldTextSettings
-
+/**
+ * A custom field of the account. Custom fields are soft-deleted, but `deletedAt` is never returned
+ * (customFieldsTransformer).
+ */
 export type CustomField = {
   id: string
   name: string
@@ -55,7 +51,6 @@ export type CustomField = {
   accountId: string
   createdAt: string
   updatedAt: string
-  deletedAt: string | null
 }
 
 export type CreateCustomFieldPayload = {
@@ -64,12 +59,13 @@ export type CreateCustomFieldPayload = {
   allowed: 'contacts'
   showOnRegister?: boolean
   required?: boolean
-  settings?: CustomFieldSettings
+  settings?: CustomFieldSettings | null
 }
 
 export type UpdateCustomFieldPayload = {
   name?: string
   type?: CustomFieldType
+  allowed?: 'contacts'
   showOnRegister?: boolean
   required?: boolean
   settings?: CustomFieldSettings | null

package/src/apis/dashboard/DashboardApi.test-d.ts

@@ -0,0 +1,49 @@
+import { expectError, expectType } from 'tsd'
+import type { ApiClient } from '../../core/ApiClient'
+import { DashboardApi } from './DashboardApi'
+import type {
+  DashboardDepartmentItem,
+  DashboardGrouped,
+  DashboardPeriodItem,
+  DashboardQuery,
+  DashboardUserItem,
+} from './types'
+
+declare const client: ApiClient
+declare const filters: DashboardQuery
+declare const flag: boolean
+const dashboard = new DashboardApi(client)
+
+// ── without `withTotals` (or `false`): the plain array ──────────────
+
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod())
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod({ grouping: 'weekly' }))
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod({ withTotals: false }))
+expectType<Promise<DashboardPeriodItem[]>>(dashboard.getByPeriod(filters))
+expectType<Promise<DashboardUserItem[]>>(dashboard.getByUser(filters))
+expectType<Promise<DashboardDepartmentItem[]>>(dashboard.getByDepartment(filters))
+
+// ── `withTotals: true`: `{ totals, items }` ─────────────────────────
+
+expectType<Promise<DashboardGrouped<DashboardPeriodItem>>>(
+  dashboard.getByPeriod({ withTotals: true }),
+)
+expectType<Promise<DashboardGrouped<DashboardPeriodItem>>>(
+  dashboard.getByPeriod({ ...filters, withTotals: true }),
+)
+expectType<Promise<DashboardGrouped<DashboardUserItem>>>(dashboard.getByUser({ withTotals: true }))
+expectType<Promise<DashboardGrouped<DashboardDepartmentItem>>>(
+  dashboard.getByDepartment({ withTotals: true }),
+)
+
+// ── `withTotals` only known at runtime: the union ───────────────────
+
+expectType<Promise<DashboardPeriodItem[] | DashboardGrouped<DashboardPeriodItem>>>(
+  dashboard.getByPeriod({ ...filters, withTotals: flag }),
+)
+
+// ── what the backend does not take ──────────────────────────────────
+
+expectError(dashboard.getByPeriod({ grouping: 'quarterly' }))
+expectError(dashboard.getByTopic({ withTotals: true }))
+expectError(dashboard.getByService({ withTotals: true }))

package/src/apis/dashboard/DashboardApi.test.ts

@@ -0,0 +1,270 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DashboardApi } from './DashboardApi'
+import type { ApiClient } from '../../core/ApiClient'
+import type {
+  DashboardDepartmentItem,
+  DashboardGeneral,
+  DashboardPeriodItem,
+  DashboardQuery,
+  DashboardServiceItem,
+  DashboardTopicItem,
+  DashboardUserItem,
+  DashboardWithTotals,
+} 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 general: DashboardGeneral = {
+  sentMessagesCount: 10,
+  receivedMessagesCount: 5,
+  totalMessagesCount: 15,
+  openedTicketsCount: 2,
+  closedTicketsCount: 3,
+  totalTicketsCount: 5,
+  waitingTime: 60,
+  waitingTimeAfterBot: 30,
+  waitingTimeAvg: 45,
+  ticketTime: 600,
+  contactsCount: 4,
+}
+
+const periodItems: DashboardPeriodItem[] = [
+  { name: '01/09/2026', sentMessagesCount: 4, receivedMessagesCount: 2, totalMessagesCount: 6 },
+  { name: '02/09/2026', openedTicketsCount: 1, closedTicketsCount: 1, totalTicketsCount: 2 },
+]
+
+const userItems: DashboardUserItem[] = [
+  { name: 'Alice', sentMessagesCount: 7, closedTicketsCount: 3, ticketTopicsCount: 1 },
+]
+
+const departmentItems: DashboardDepartmentItem[] = [
+  { name: 'Suporte', openedTicketsCount: 2, waitingTime: 60, ticketTime: 600 },
+]
+
+const topicItems: DashboardTopicItem[] = [
+  { name: 'Financeiro', openedTicketsCount: 1, waitingTimeAfterBot: 30, waitingTimeAvg: 45 },
+]
+
+const serviceItems: DashboardServiceItem[] = [
+  { name: 'WhatsApp', receivedMessagesCount: 5, contactsCount: 4, ticketTopicsCount: 2 },
+]
+
+const filters: DashboardQuery = {
+  startPeriod: '2026-09-01T00:00:00.000Z',
+  endPeriod: '2026-09-07T23:59:59.999Z',
+  status: 'closed',
+  departmentId: ['d1'],
+}
+
+const queryString = (query: DashboardQuery & DashboardWithTotals) =>
+  `?query=${encodeURIComponent(JSON.stringify(query))}`
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('DashboardApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: DashboardApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new DashboardApi(client)
+  })
+
+  it('has no CRUD routes', () => {
+    expect(api.basePath).toBe('/dashboard')
+    expect(api).not.toHaveProperty('getMany')
+  })
+
+  describe('getGeneral', () => {
+    it('calls client.get with /dashboard/general and no query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(general)
+      const result = await api.getGeneral()
+      expect(client.get).toHaveBeenCalledWith('/dashboard/general', undefined)
+      expect(result).toEqual(general)
+    })
+
+    it('sends the filters in the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(general)
+      await api.getGeneral(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/general${queryString(filters)}`,
+        undefined,
+      )
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(general)
+      const headers = { 'X-Custom': 'h' }
+      await api.getGeneral(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/general', headers)
+    })
+  })
+
+  describe('getByPeriod', () => {
+    it('calls client.get with /dashboard/by-period and no query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      const result = await api.getByPeriod()
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-period', undefined)
+      expect(result).toEqual(periodItems)
+    })
+
+    it('sends the filters and the grouping in the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      const query: DashboardQuery = { ...filters, grouping: 'weekly' }
+      await api.getByPeriod(query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-period${queryString(query)}`,
+        undefined,
+      )
+    })
+
+    it('answers { totals, items } with withTotals: true', async () => {
+      const grouped = { totals: general, items: periodItems }
+      vi.mocked(client.get).mockResolvedValue(grouped)
+      const query = { ...filters, withTotals: true as const }
+      const result = await api.getByPeriod(query)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-period${queryString(query)}`,
+        undefined,
+      )
+      expect(result).toEqual(grouped)
+      expect(result.totals.totalTicketsCount).toBe(5)
+      expect(result.items).toHaveLength(2)
+    })
+
+    it('does not send withTotals: false (the backend reads it as truthy in the qs format)', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      await api.getByPeriod({ ...filters, withTotals: false })
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-period${queryString(filters)}`,
+        undefined,
+      )
+      await api.withQueryFormat('qs').getByPeriod({ withTotals: false, grouping: 'weekly' })
+      expect(client.get).toHaveBeenLastCalledWith('/dashboard/by-period?grouping=weekly', undefined)
+      await api.getByPeriod({ withTotals: false })
+      expect(client.get).toHaveBeenLastCalledWith('/dashboard/by-period', undefined)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(periodItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByPeriod(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-period', headers)
+    })
+  })
+
+  describe('getByUser', () => {
+    it('calls client.get with /dashboard/by-user and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(userItems)
+      const result = await api.getByUser(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-user${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(userItems)
+    })
+
+    it('answers { totals, items } with withTotals: true', async () => {
+      const grouped = { totals: general, items: userItems }
+      vi.mocked(client.get).mockResolvedValue(grouped)
+      const result = await api.getByUser({ withTotals: true })
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-user${queryString({ withTotals: true })}`,
+        undefined,
+      )
+      expect(result.items[0]?.name).toBe('Alice')
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(userItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByUser(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-user', headers)
+    })
+  })
+
+  describe('getByDepartment', () => {
+    it('calls client.get with /dashboard/by-department and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(departmentItems)
+      const result = await api.getByDepartment(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-department${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(departmentItems)
+    })
+
+    it('answers { totals, items } with withTotals: true', async () => {
+      const grouped = { totals: general, items: departmentItems }
+      vi.mocked(client.get).mockResolvedValue(grouped)
+      const result = await api.getByDepartment({ withTotals: true })
+      expect(result).toEqual(grouped)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(departmentItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByDepartment(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-department', headers)
+    })
+  })
+
+  describe('getByTopic', () => {
+    it('calls client.get with /dashboard/by-topic and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(topicItems)
+      const result = await api.getByTopic(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-topic${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(topicItems)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(topicItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByTopic(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-topic', headers)
+    })
+  })
+
+  describe('getByService', () => {
+    it('calls client.get with /dashboard/by-service and the filters', async () => {
+      vi.mocked(client.get).mockResolvedValue(serviceItems)
+      const result = await api.getByService(filters)
+      expect(client.get).toHaveBeenCalledWith(
+        `/dashboard/by-service${queryString(filters)}`,
+        undefined,
+      )
+      expect(result).toEqual(serviceItems)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue(serviceItems)
+      const headers = { 'X-Custom': 'h' }
+      await api.getByService(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/dashboard/by-service', headers)
+    })
+  })
+
+  describe('error propagation', () => {
+    it('propagates errors from the grouped routes', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Unauthorized'))
+      await expect(api.getByPeriod()).rejects.toThrow('Unauthorized')
+    })
+  })
+})