@ikatec/digisac-api-sdk 4.8.0 → 4.10.0

package/src/apis/services/ServicesApi.ts

@@ -1,6 +1,12 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
-import type { Service, CreateServicePayload, ServiceLimits, UpdateServicePayload } from './types'
+import type {
+  Service,
+  CreateServicePayload,
+  ServiceLimits,
+  UpdateServicePayload,
+  ArchiveServicePayload,
+} from './types'
 
 export class ServicesApi extends ArchivableCrudApi<
   Service,
@@ -19,4 +25,88 @@ export class ServicesApi extends ArchivableCrudApi<
   getLimits(headers?: Record<string, string>): Promise<ServiceLimits> {
     return this.client.get<ServiceLimits>(`${this.basePath}/limits`, headers)
   }
+
+  /**
+   * @deprecated The backend does not archive a connection by `PUT { archivedAt }`: the PUT
+   * requires `type` (400 without it) and ignores `archivedAt`. Use {@link archiveWithValidation}.
+   */
+  override archive(id: string, headers?: Record<string, string>): Promise<Service> {
+    return super.archive(id, headers)
+  }
+
+  /**
+   * @deprecated The backend does not restore a connection by `PUT { archivedAt: null }`: the PUT
+   * requires `type` (400 without it) and ignores `archivedAt`. Use {@link archiveWithValidation}.
+   */
+  override unarchive(id: string, headers?: Record<string, string>): Promise<Service> {
+    return super.unarchive(id, headers)
+  }
+
+  /**
+   * Archives (`archive: true`) or restores (`archive: false`) a connection through the route used
+   * by the UI. Archiving shuts the connection down, closes its open tickets, marks its schedules
+   * as done and cancels its campaigns; restoring checks the plan limit of the `type` (400 when it
+   * is full).
+   *
+   * Resolves `{}` before the work is done (the route does not await it): poll `getById` until
+   * `archivedAt` changes. Send the `type` of the connection: without it the request is never
+   * answered.
+   * @permissions services.disabled
+   */
+  archiveWithValidation(
+    id: string,
+    body: ArchiveServicePayload,
+    headers?: Record<string, string>,
+  ): Promise<Record<string, never>> {
+    return this.client.post<Record<string, never>, ArchiveServicePayload>(
+      `${this.basePath}/${id}/archive`,
+      body,
+      headers,
+    )
+  }
+
+  /**
+   * Takes the session of the connection over to this server. Resolves the text `'OK'`; an
+   * unknown id answers 404 `Service not found.`.
+   * @permissions services.operate
+   */
+  takeover(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/takeover`, undefined, headers)
+  }
+
+  /**
+   * Logs the connection out of the messaging service. Resolves the text `'OK'`; an unknown id
+   * answers 404 `Service not found.`.
+   * @permissions services.operate
+   */
+  logout(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/logout`, undefined, headers)
+  }
+
+  /**
+   * Shuts the connection down. Resolves the text `'OK'`; an unknown id answers 404
+   * `Service not found.`.
+   * @permissions services.operate
+   */
+  shutdown(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/shutdown`, undefined, headers)
+  }
+
+  /**
+   * Starts the connection. Resolves the text `'OK'`; an unknown id answers 404
+   * `Service not found.`.
+   * @permissions services.operate
+   */
+  start(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/start`, undefined, headers)
+  }
+
+  /**
+   * Restarts the connection. Resolves the text `'OK'`; an unknown id answers 404
+   * `Service not found.`.
+   * @permissions services.operate
+   */
+  restart(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return this.client.post<'OK'>(`${this.basePath}/${id}/restart`, undefined, headers)
+  }
 }

package/src/apis/services/types.ts

@@ -47,6 +47,52 @@ export type ServiceConnectionStatus = {
   timestamp?: string
 }
 
+/**
+ * `data.webchat` of a Webchat service. Every key is optional: the object only fills up once the
+ * service is set up, and older services lack the keys added later (e.g. `instagram`). The backend
+ * stores what the forms send without normalizing it, so `null` and `{}` show up where the web
+ * forms write them.
+ */
+export type WebchatServiceData = {
+  /** Widget id in the webchat API; the page link is `${webchatUrl}/${id}`. Absent before setup. */
+  id?: string
+  name?: string | null
+  /** WhatsApp channel of the widget: DDI + number, without mask. `null` once cleared. */
+  phone?: string | null
+  /** Telegram channel of the widget, without `@`. `null` once cleared. */
+  telegram?: string | null
+  /** Instagram channel of the widget, without `@`. `null` once cleared. */
+  instagram?: string | null
+  isOpenForm?: boolean
+  isOpenChat?: boolean
+  /** `{}` when no picture was picked in the legacy form. */
+  file?: { base64Url?: string; mimetype?: string; fileName?: string }
+  googleId?: string | null
+  desktopChatOpen?: boolean
+  mobileChatOpen?: boolean
+  getClientData?: boolean
+  closeTicketByClient?: boolean
+  phoneClient?: boolean
+  phoneClientRequired?: boolean
+  clientName?: boolean
+  clientNameRequired?: boolean
+  /** `null` or `{}` when no custom field is asked for. */
+  customField?: { id?: string; name?: string } | null
+  customFieldRequired?: boolean
+  custom?: {
+    webchatBalloon?: boolean
+    webchatBalloonText?: string | null
+    webchatColor?: string
+    /** File id. */
+    logo?: string
+    /** File id. */
+    profilePhoto?: string
+    /** File id. */
+    webchatIcon?: string
+    typeIcon?: string
+  }
+}
+
 export type ServiceData = {
   // ─── Common ───────────────────────────────────────────────────────────────
   token?: string
@@ -106,7 +152,7 @@ export type ServiceData = {
     mimetype: string
     fileName: string
   }
-  webchat?: Record<string, unknown>
+  webchat?: WebchatServiceData
 
   // ─── Other ────────────────────────────────────────────────────────────────
   driverId?: string
@@ -207,6 +253,8 @@ export type ServiceRelationships = 'bot' | 'defaultDepartment'
 export type CreateServicePayload = {
   name: string
   type: ServiceType
+  /** Send `null`: without it the duplicate-name check never answers (SUS-3784). */
+  archivedAt?: null
   data?: ServiceData
   settings?: ServiceSettings
   defaultDepartmentId?: string
@@ -214,14 +262,28 @@ export type CreateServicePayload = {
 }
 
 export type UpdateServicePayload = {
+  /** Required by the backend (400 without it), although optional here for compatibility. */
+  type?: ServiceType
   name?: string
   data?: ServiceData
   settings?: ServiceSettings
   defaultDepartmentId?: string | null
   botId?: string | null
+  /**
+   * Ignored by the backend (archive through `ServicesApi.archiveWithValidation`). Send `null`
+   * with a `name`: without `archivedAt` the duplicate-name check never answers (SUS-3784).
+   */
   archivedAt?: string | null
 }
 
+/** Body of `ServicesApi.archiveWithValidation`. */
+export type ArchiveServicePayload = {
+  /** `true` archives, `false` restores. */
+  archive: boolean
+  /** The type of the connection, used by the plan limit check (the request hangs without it). */
+  type: ServiceType
+}
+
 export type ServiceLimit = {
   used: number
   total: number

package/src/apis/stickers/StickersApi.ts

@@ -1,9 +1,41 @@
 import type { ApiClient } from '../../core/ApiClient'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
+import type { GetByIdQuery } from '../../core/types'
 import type { Sticker, CreateStickerPayload, UpdateStickerPayload } from './types'
 
+/**
+ * Stickers of the account. The backend serves `GET /stickers` and `POST /stickers` (plus
+ * `GET /stickers/exist`, `POST /stickers/add` and `DELETE /stickers/remove/:stickerId`); there is
+ * no read by id, update nor `DELETE /stickers/:id`.
+ */
 export class StickersApi extends BaseCrudApi<Sticker, CreateStickerPayload, UpdateStickerPayload> {
   constructor(client: ApiClient) {
     super(client, '/stickers')
   }
+
+  /** @deprecated Not served: the backend has no GET /stickers/:id, so this route answers 404. */
+  override getById(
+    id: string,
+    query?: GetByIdQuery<Sticker>,
+    headers?: Record<string, string>,
+  ): Promise<Sticker> {
+    return super.getById(id, query, headers)
+  }
+
+  /** @deprecated Not served: the backend has no PUT /stickers/:id, so this route answers 404. */
+  override updateById(
+    id: string,
+    body: UpdateStickerPayload,
+    headers?: Record<string, string>,
+  ): Promise<Sticker> {
+    return super.updateById(id, body, headers)
+  }
+
+  /**
+   * @deprecated Not served: the backend has no DELETE /stickers/:id (it removes a sticker by
+   * `DELETE /stickers/remove/:stickerId`), so this route answers 404.
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<Sticker> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/tags/TagsApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { ContactsSelection } from '../contacts/types'
 import type {
@@ -9,11 +10,25 @@ import type {
   UpdateTagPayload,
 } from './types'
 
-export class TagsApi extends BaseCrudApi<Tag, CreateTagPayload, UpdateTagPayload> {
+export class TagsApi extends BaseCrudApi<
+  Tag,
+  CreateTagPayload,
+  UpdateTagPayload,
+  ListQuery<Tag>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/tags')
   }
 
+  /**
+   * Deletes a tag. Resolves the text `'OK'`; an unknown id answers 500.
+   * @permissions tags.view OR tags.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
+
   /**
    * Adds the tag to every contact of the account that matches the selection. Resolves to `'OK'`,
    * or `false` when every contact already had the tag.

package/src/apis/timetable/TimetableApi.ts

@@ -1,13 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Timetable, CreateTimetablePayload, UpdateTimetablePayload } from './types'
 
 export class TimetableApi extends BaseCrudApi<
   Timetable,
   CreateTimetablePayload,
-  UpdateTimetablePayload
+  UpdateTimetablePayload,
+  ListQuery<Timetable>,
+  'OK'
 > {
   constructor(client: ApiClient) {
     super(client, '/timetable')
   }
+
+  /**
+   * Deletes a timetable. Resolves the text `'OK'`.
+   * @permissions timetables.view OR timetables.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/apis/users/UsersApi.ts

@@ -1,4 +1,5 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { ArchivableCrudApi } from '../../core/ArchivableCrudApi'
 import type { Contact } from '../contacts/types'
 import type {
@@ -19,11 +20,26 @@ import type {
   ValidateUserImportResult,
 } from './types'
 
-export class UsersApi extends ArchivableCrudApi<User, CreateUserPayload, UpdateUserPayload> {
+export class UsersApi extends ArchivableCrudApi<
+  User,
+  CreateUserPayload,
+  UpdateUserPayload,
+  ListQuery<User>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/users')
   }
 
+  /**
+   * Deletes a user (removes it as the default user of the contacts and deletes its webhooks first).
+   * Resolves the text `'OK'`.
+   * @permissions users.destroy
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
+
   /**
    * Archives or restores a user through the dedicated route used by the UI, which also
    * sets the user offline and ends its sessions. The route enforces the business rules that

package/src/apis/users/types.ts

@@ -71,7 +71,10 @@ export type CreateUserPayload = {
   isClientUser?: boolean
   roles?: string[]
   departments?: string[]
+  /** @deprecated Not read by the backend: restrict the connections with `restrictedServices`. */
   services?: string[]
+  /** Connections the user cannot access, as `{ value: serviceId }`. */
+  restrictedServices?: { value: string }[]
   scheduleId?: string
 }
 
@@ -83,7 +86,15 @@ export type UpdateUserPayload = {
   isClientUser?: boolean
   roles?: string[]
   departments?: string[]
+  /** @deprecated Not read by the backend: restrict the connections with `restrictedServices`. */
   services?: string[]
+  /**
+   * Connections the user cannot access, as `{ value: serviceId }`. Every update without it (and
+   * every update of an admin) clears the restrictions of the user.
+   */
+  restrictedServices?: { value: string }[]
+  /** New password of the user. */
+  password?: string
   timetableId?: string | null
   preferences?: UserPreferences
   language?: string

package/src/apis/webhooks/WebhooksApi.ts

@@ -1,9 +1,24 @@
 import type { ApiClient } from '../../core/ApiClient'
+import type { ListQuery } from '../../core/types'
 import { BaseCrudApi } from '../../core/BaseCrudApi'
 import type { Webhook, CreateWebhookPayload, UpdateWebhookPayload } from './types'
 
-export class WebhooksApi extends BaseCrudApi<Webhook, CreateWebhookPayload, UpdateWebhookPayload> {
+export class WebhooksApi extends BaseCrudApi<
+  Webhook,
+  CreateWebhookPayload,
+  UpdateWebhookPayload,
+  ListQuery<Webhook>,
+  'OK'
+> {
   constructor(client: ApiClient) {
     super(client, '/me/webhooks')
   }
+
+  /**
+   * Deletes a webhook. Resolves the text `'OK'`; an unknown id answers 500.
+   * @permissions settingsApi.update
+   */
+  override deleteById(id: string, headers?: Record<string, string>): Promise<'OK'> {
+    return super.deleteById(id, headers)
+  }
 }

package/src/core/ApiClient.ts

@@ -32,4 +32,28 @@ export interface ApiClient {
     endpoint: string,
     headers?: Record<string, string>,
   ): Promise<TResponse>
+  /**
+   * Like {@link request}, but resolves the raw `Response` of a successful (2xx) call instead of
+   * the parsed body, for the routes whose headers matter (`Content-Type`, `Content-Disposition`)
+   * or whose body is binary (xlsx, pdf, files). Non-2xx still throws the `ApiError` subclass.
+   * Optional: a custom client without it cannot call the API methods that need the raw response.
+   */
+  requestRaw?<TBody = unknown>(
+    method: HttpMethod,
+    endpoint: string,
+    body?: TBody,
+    headers?: Record<string, string>,
+  ): Promise<Response>
+  /**
+   * Sends a request to an absolute URL outside the API (e.g. the signed storage URL of
+   * `FilesApi.upload`): 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. Optional: without it, the API methods that need it send through the global `fetch`.
+   */
+  requestExternal?(
+    method: HttpMethod,
+    url: string,
+    body?: BodyInit,
+    headers?: Record<string, string>,
+  ): Promise<Response>
 }

package/src/core/ArchivableCrudApi.ts

@@ -17,7 +17,8 @@ export class ArchivableCrudApi<
   TCreate,
   TUpdate extends { archivedAt?: string | null } = TCreate & { archivedAt?: string | null },
   TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
-> extends BaseCrudApi<TResponse, TCreate, TUpdate, TQuery> {
+  TDeleteResponse = TResponse,
+> extends BaseCrudApi<TResponse, TCreate, TUpdate, TQuery, TDeleteResponse> {
   constructor(client: ApiClient, basePath: string) {
     super(client, basePath)
   }

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