@ikatec/digisac-api-sdk 4.9.0 → 4.10.0

package/src/core/BaseApiClient.test.ts

@@ -498,4 +498,102 @@ describe('BaseApiClient', () => {
       errorClass: 'AccessDenied',
     })
   })
+
+  // ── requestRaw ───────────────────────────────────────────────────
+
+  describe('requestRaw', () => {
+    it('resolves the raw Response of a 2xx answer, with the headers and body untouched', async () => {
+      const spy = mockFetch({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/pdf', 'Content-Disposition': 'attachment' },
+        body: '%PDF-1.4',
+      })
+      client.setAccessToken('token-1')
+      const response = await client.requestRaw('GET', '/terms/t-1/export-pdf')
+      expect(spy).toHaveBeenCalledWith(
+        'https://api.example.com/terms/t-1/export-pdf',
+        expect.objectContaining({
+          method: 'GET',
+          headers: expect.objectContaining({ Authorization: 'Bearer token-1' }),
+        }),
+      )
+      expect(response.status).toBe(200)
+      expect(response.headers.get('Content-Type')).toBe('application/pdf')
+      expect(await response.text()).toBe('%PDF-1.4')
+    })
+
+    it('sends the JSON body and the custom headers', async () => {
+      const spy = mockFetch({ ok: true, status: 200, statusText: 'OK', body: 'a;b' })
+      await client.requestRaw('POST', '/export', { where: { id: '1' } }, { 'X-Custom': 'v' })
+      expect(spy).toHaveBeenCalledWith(
+        'https://api.example.com/export',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({ where: { id: '1' } }),
+          headers: expect.objectContaining({ 'X-Custom': 'v' }),
+        }),
+      )
+    })
+
+    it('throws the ApiError subclass of a non-2xx answer', async () => {
+      mockFetch({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ error: 'NotFoundHttpError', message: 'Route not found.' }),
+      })
+      await expect(client.requestRaw('GET', '/missing')).rejects.toBeInstanceOf(NotFoundError)
+    })
+
+    it('throws ApiConnectionError when the request fails', async () => {
+      vi.spyOn(globalThis, 'fetch').mockRejectedValue(new TypeError('fetch failed'))
+      await expect(client.requestRaw('GET', '/down')).rejects.toBeInstanceOf(ApiConnectionError)
+    })
+  })
+
+  // ── requestExternal ──────────────────────────────────────────────
+
+  describe('requestExternal', () => {
+    const SIGNED_URL = 'https://storage.example.com/acc-1/file-1.csv?X-Amz-Signature=secret'
+
+    it('sends the body as is to the absolute URL, without the token nor the JSON Content-Type', async () => {
+      const spy = vi
+        .spyOn(globalThis, 'fetch')
+        .mockResolvedValue(new Response(null, { status: 200 }))
+      client.setAccessToken('token-1')
+      const response = await client.requestExternal('PUT', SIGNED_URL, 'a;b', {
+        'Content-Type': 'text/csv',
+      })
+      expect(spy).toHaveBeenCalledWith(SIGNED_URL, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'text/csv' },
+        body: 'a;b',
+      })
+      expect(response.status).toBe(200)
+    })
+
+    it('throws the ApiError subclass of a non-2xx answer, with the body as text', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+        new Response('<Error><Code>AccessDenied</Code></Error>', {
+          status: 403,
+          statusText: 'Forbidden',
+        }),
+      )
+      const captured = await client.requestExternal('PUT', SIGNED_URL).catch((e) => e)
+      expect(captured).toBeInstanceOf(PermissionDeniedError)
+      expect((captured as ApiError).body).toBe('<Error><Code>AccessDenied</Code></Error>')
+    })
+
+    it('throws ApiConnectionError without the query string (the signature) in the message', async () => {
+      vi.spyOn(globalThis, 'fetch').mockRejectedValue(new TypeError('fetch failed'))
+      const captured = await client.requestExternal('PUT', SIGNED_URL).catch((e) => e)
+      expect(captured).toBeInstanceOf(ApiConnectionError)
+      expect((captured as ApiConnectionError).message).toBe(
+        'Request to PUT https://storage.example.com/acc-1/file-1.csv failed: fetch failed',
+      )
+    })
+  })
 })

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/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
+}