@ikatec/digisac-api-sdk 4.9.0 → 4.11.0

package/src/core/BaseApiClient.ts

@@ -1,6 +1,7 @@
 import type { ApiClient, HttpMethod } from './ApiClient'
 import { ApiConnectionError, ApiError } from './errors'
 import { DEFAULT_QUERY_FORMAT, type QueryFormat } from './queryString'
+import { requestExternal } from './requestExternal'
 
 export interface BaseApiClientOptions {
   /** How list/get queries are serialized in the URL. Defaults to `'json'`. */
@@ -29,6 +30,53 @@ export class BaseApiClient implements ApiClient {
     body?: TBody,
     headers?: Record<string, string>,
   ): Promise<TResponse> {
+    return this.handleResponse<TResponse>(await this.send(method, endpoint, body, headers))
+  }
+
+  /**
+   * Sends the request and resolves the raw `Response` of a 2xx answer (headers and body
+   * untouched, so a binary body can be read with `arrayBuffer()`). Non-2xx throws the
+   * `ApiError` subclass, as {@link request} does.
+   */
+  async requestRaw<TBody = unknown>(
+    method: HttpMethod,
+    endpoint: string,
+    body?: TBody,
+    headers?: Record<string, string>,
+  ): Promise<Response> {
+    const response = await this.send(method, endpoint, body, headers)
+    if (!response.ok) {
+      throw ApiError.fromResponse(
+        response.status,
+        response.statusText,
+        response.headers,
+        await this.readErrorBody(response),
+      )
+    }
+    return response
+  }
+
+  /**
+   * Sends a request to an absolute URL outside the API, without the base URL, the access token
+   * and the JSON serialization. Resolves the raw `Response` of a 2xx answer; non-2xx throws the
+   * `ApiError` subclass. Override it to intercept those requests as well.
+   */
+  requestExternal(
+    method: HttpMethod,
+    url: string,
+    body?: BodyInit,
+    headers?: Record<string, string>,
+  ): Promise<Response> {
+    return requestExternal(method, url, body, headers)
+  }
+
+  /** Builds and sends the request; a network failure is thrown as `ApiConnectionError`. */
+  protected async send<TBody = unknown>(
+    method: HttpMethod,
+    endpoint: string,
+    body?: TBody,
+    headers?: Record<string, string>,
+  ): Promise<Response> {
     const url = `${this.baseUrl}/${endpoint.replace(/^\//, '')}`
     const init: RequestInit = {
       method,
@@ -40,17 +88,14 @@ export class BaseApiClient implements ApiClient {
       ...(body !== undefined && { body: JSON.stringify(body) }),
     }
 
-    let response: Response
     try {
-      response = await fetch(url, init)
+      return await fetch(url, init)
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error)
       throw new ApiConnectionError(`Request to ${method} ${url} failed: ${reason}`, {
         cause: error,
       })
     }
-
-    return this.handleResponse<TResponse>(response)
   }
 
   protected async handleResponse<TResponse>(response: Response): Promise<TResponse> {

package/src/core/BaseCrudApi.test-d.ts

@@ -1,7 +1,7 @@
 import { expectError, expectType } from 'tsd'
 import type { ApiClient } from './ApiClient'
 import { BaseCrudApi } from './BaseCrudApi'
-import type { Paginated } from './types'
+import type { ListQuery, Paginated } from './types'
 
 // ── Test model ──────────────────────────────────────────────────────
 
@@ -40,6 +40,16 @@ expectType<Promise<Item>>(api.create({ name: 'x' }))
 expectType<Promise<Item>>(api.updateById('1', {}))
 expectType<Promise<Item>>(api.deleteById('1'))
 
+// Routes that do not answer the resource on create/update (TCreateResponse, TUpdateResponse)
+const writes = new BaseCrudApi<Item, CreateItem, UpdateItem, ListQuery<Item>, 'OK', void, Item[]>(
+  client,
+  '/items',
+)
+expectType<Promise<void>>(writes.create({ name: 'x' }))
+expectType<Promise<Item[]>>(writes.updateById('1', {}))
+expectType<Promise<'OK'>>(writes.deleteById('1'))
+expectType<Promise<Item>>(writes.getById('1'))
+
 expectError(api.create({}))
 expectError(api.create({ name: 1 }))
 expectError(api.updateById('1', { name: 1 }))

package/src/core/BaseCrudApi.ts

@@ -16,7 +16,9 @@ export type {
 
 /**
  * Generic CRUD resource: the reads of `BaseReadApi` plus `create`, `updateById` and `deleteById`.
- * `TDeleteResponse` is what `deleteById` resolves to (most routes answer the text `'OK'`).
+ * `TDeleteResponse` is what `deleteById` resolves to (most routes answer the text `'OK'`);
+ * `TCreateResponse` and `TUpdateResponse` are what `create` and `updateById` resolve to, for the routes
+ * that do not answer the resource (an empty body, `{}`, another model).
  */
 export class BaseCrudApi<
   TResponse,
@@ -24,24 +26,31 @@ export class BaseCrudApi<
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
   TDeleteResponse = TResponse,
+  TCreateResponse = TResponse,
+  TUpdateResponse = TResponse,
 >
   extends BaseReadApi<TResponse, TQuery>
-  implements CrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse>
+  implements
+    CrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse, TCreateResponse, TUpdateResponse>
 {
   /**
    * Creates a new resource.
    * @permissions $resourceName.create
    */
-  create(body: TCreate, headers?: Record<string, string>): Promise<TResponse> {
-    return this.client.post<TResponse, TCreate>(this.basePath, body, headers)
+  create(body: TCreate, headers?: Record<string, string>): Promise<TCreateResponse> {
+    return this.client.post<TCreateResponse, TCreate>(this.basePath, body, headers)
   }
 
   /**
    * Updates an existing resource by ID.
    * @permissions $resourceName.update
    */
-  updateById(id: string, body: TUpdate, headers?: Record<string, string>): Promise<TResponse> {
-    return this.client.put<TResponse, TUpdate>(`${this.basePath}/${id}`, body, headers)
+  updateById(
+    id: string,
+    body: TUpdate,
+    headers?: Record<string, string>,
+  ): Promise<TUpdateResponse> {
+    return this.client.put<TUpdateResponse, TUpdate>(`${this.basePath}/${id}`, body, headers)
   }
 
   /**

package/src/core/requestExternal.ts

@@ -0,0 +1,43 @@
+import type { HttpMethod } from './ApiClient'
+import { ApiConnectionError, ApiError } from './errors'
+
+/** The URL without its query string, which may carry a signature that must not reach the logs. */
+function withoutQuery(url: string): string {
+  return url.replace(/[?#].*$/s, '')
+}
+
+/**
+ * Sends a request to an absolute URL outside the API (e.g. a signed storage URL): no base URL, no
+ * `Authorization` header and no JSON serialization, `body` goes as is. Resolves the raw `Response`
+ * of a 2xx answer; non-2xx throws the `ApiError` subclass with the body as text, and a network
+ * failure throws `ApiConnectionError`.
+ */
+export async function requestExternal(
+  method: HttpMethod,
+  url: string,
+  body?: BodyInit,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  let response: Response
+  try {
+    response = await fetch(url, {
+      method,
+      ...(headers && { headers }),
+      ...(body !== undefined && { body }),
+    })
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new ApiConnectionError(`Request to ${method} ${withoutQuery(url)} failed: ${reason}`, {
+      cause: error,
+    })
+  }
+  if (!response.ok) {
+    throw ApiError.fromResponse(
+      response.status,
+      response.statusText,
+      response.headers,
+      (await response.text().catch(() => undefined)) || undefined,
+    )
+  }
+  return response
+}

package/src/core/types.ts

@@ -160,8 +160,10 @@ export type CrudApi<
   TUpdate = TCreate,
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
   TDeleteResponse = TResponse,
+  TCreateResponse = TResponse,
+  TUpdateResponse = TResponse,
 > = HasGetMany<TResponse, TQuery> &
   HasGetById<TResponse> &
-  HasCreate<TResponse, TCreate> &
-  HasUpdateById<TResponse, TUpdate> &
+  HasCreate<TCreateResponse, TCreate> &
+  HasUpdateById<TUpdateResponse, TUpdate> &
   HasDeleteById<TDeleteResponse>