@ikatec/digisac-api-sdk 4.1.0 → 4.3.0

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'