fms-odata-js 0.3.0

package/src/entity.ts

@@ -0,0 +1,334 @@
+/**
+ * Single-entity handle returned by `Query#byKey(key)`. Supports `.get()`,
+ * `.patch()`, `.delete()`, `.script()` (record-scope FileMaker script
+ * invocation, v0.1.4+), and `.container(field)` (container-field binary
+ * I/O, v0.1.5+).
+ */
+
+import type { FMSOData } from './client.js'
+import {
+  buildContainerJsonBody,
+  ContainerRef,
+  type ContainerJsonValue,
+} from './containers.js'
+import { executeJson, executeRequest } from './http.js'
+import { runScriptAtEntity, type ScriptOptions, type ScriptResult } from './scripts.js'
+import type { RequestOptions } from './types.js'
+import {
+  encodePathSegment,
+  escapeStringLiteral,
+  type ODataLiteral,
+} from './url.js'
+
+/** Options accepted by mutating entity operations. */
+export interface EntityWriteOptions extends RequestOptions {
+  /**
+   * Optional `If-Match` precondition. Pass an ETag returned from a prior read
+   * to enable optimistic concurrency.
+   */
+  ifMatch?: string
+  /**
+   * Whether the server should return the updated representation. Defaults to
+   * `false` (`Prefer: return=minimal`) to match FMS behaviour; set to `true`
+   * to request `Prefer: return=representation`.
+   */
+  returnRepresentation?: boolean
+}
+
+/**
+ * Format an OData primary-key literal for embedding in a URL path
+ * (`EntitySet(<key>)`).
+ */
+function formatKey(key: ODataLiteral): string {
+  if (typeof key === 'number') {
+    if (!Number.isFinite(key)) {
+      throw new TypeError('EntityRef: key must be a finite number')
+    }
+    return String(key)
+  }
+  if (typeof key === 'string') return `'${escapeStringLiteral(key)}'`
+  if (typeof key === 'boolean') return key ? 'true' : 'false'
+  throw new TypeError('EntityRef: unsupported key type')
+}
+
+/**
+ * Handle to a single OData entity. Holds the client, entity-set name, and the
+ * primary key; every method builds a URL of the form
+ * `<baseUrl>/<EntitySet>(<key>)` and delegates to the shared HTTP executor.
+ */
+export class EntityRef<T = Record<string, unknown>> {
+  readonly entitySet: string
+  readonly key: ODataLiteral
+
+  /** @internal */ readonly _client: FMSOData
+
+  constructor(client: FMSOData, entitySet: string, key: ODataLiteral) {
+    this._client = client
+    this.entitySet = entitySet
+    this.key = key
+  }
+
+  /** Absolute URL for this entity. */
+  toURL(): string {
+    return `${this._client.baseUrl}/${encodePathSegment(this.entitySet)}(${formatKey(this.key)})`
+  }
+
+  /** `GET` the entity. Returns the parsed JSON row. */
+  async get(opts: RequestOptions = {}): Promise<T> {
+    const json = await executeJson<T>(this._client._ctx, this.toURL(), {
+      method: 'GET',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+    return json
+  }
+
+  /**
+   * `GET` a single field's scalar value via the OData property URL
+   * (`…/<EntitySet>(<key>)/<fieldName>`). FMS responds with the JSON envelope
+   * `{ value: … }`; this method unwraps it and returns just the value.
+   *
+   * Useful when you only need one column without composing a `$select` query.
+   * For container fields use `container(name).get()` instead.
+   */
+  async fieldValue<V = unknown>(fieldName: string, opts: RequestOptions = {}): Promise<V> {
+    const url = `${this.toURL()}/${encodePathSegment(fieldName)}`
+    const json = await executeJson<{ value: V }>(this._client._ctx, url, {
+      method: 'GET',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+    return json.value
+  }
+
+  /**
+   * `PATCH` the entity with partial values. Returns the updated row when the
+   * server echoes one (OData `Prefer: return=representation`), otherwise
+   * `undefined` on `204 No Content`.
+   */
+  async patch(
+    body: Partial<T> | Record<string, unknown>,
+    opts: EntityWriteOptions = {},
+  ): Promise<T | undefined> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Prefer: opts.returnRepresentation ? 'return=representation' : 'return=minimal',
+    }
+    if (opts.ifMatch) headers['If-Match'] = opts.ifMatch
+
+    const json = await executeJson<T | undefined>(this._client._ctx, this.toURL(), {
+      method: 'PATCH',
+      headers,
+      body: JSON.stringify(body),
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+    return json
+  }
+
+  /** `DELETE` the entity. Resolves on success; throws `FMSODataError` otherwise. */
+  async delete(opts: EntityWriteOptions = {}): Promise<void> {
+    const headers: Record<string, string> = {}
+    if (opts.ifMatch) headers['If-Match'] = opts.ifMatch
+
+    await executeRequest(this._client._ctx, this.toURL(), {
+      method: 'DELETE',
+      headers,
+      accept: 'none',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Invoke a FileMaker script in the context of this single record. FMS sets
+   * the script's current record to this entity before running it.
+   */
+  async script(name: string, opts: ScriptOptions = {}): Promise<ScriptResult> {
+    return runScriptAtEntity(this._client, this.entitySet, this.key, name, opts)
+  }
+
+  /**
+   * Get a typed handle to one of this record's container fields, exposing
+   * `.get()`, `.getStream()`, `.upload(...)`, and `.delete()`.
+   */
+  container(fieldName: string): ContainerRef {
+    return new ContainerRef(this as EntityRef<unknown>, fieldName)
+  }
+
+  /**
+   * Update one or more container fields (and optionally regular fields) on
+   * this record in a single base64 PATCH request. This maps to the Claris
+   * "Operation 3" (`PATCH /<EntitySet>(<key>)` with JSON body containing
+   * `<field>`, `<field>@com.filemaker.odata.ContentType`, and
+   * `<field>@com.filemaker.odata.Filename`).
+   *
+   * Each container value's `data` must already be base64-encoded (use the
+   * library's exported `toBase64()` helper or `Buffer.from(bytes).toString('base64')`).
+   *
+   * @example
+   * await db.from('contact').byKey(7).patchContainers(
+   *   {
+   *     photo:    { data: photoB64,    contentType: 'image/png',       filename: 'p.png' },
+   *     contract: { data: contractB64, contentType: 'application/pdf', filename: 'c.pdf' },
+   *   },
+   *   { website: 'https://example.com' },
+   * )
+   */
+  async patchContainers(
+    containers: Record<string, ContainerJsonValue>,
+    regularFields: Record<string, unknown> = {},
+    opts: EntityWriteOptions = {},
+  ): Promise<void> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Prefer: opts.returnRepresentation ? 'return=representation' : 'return=minimal',
+    }
+    if (opts.ifMatch) headers['If-Match'] = opts.ifMatch
+
+    const body = buildContainerJsonBody(containers, regularFields)
+    await executeRequest(this._client._ctx, this.toURL(), {
+      method: 'PATCH',
+      headers,
+      body: JSON.stringify(body),
+      accept: 'none',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  // -------------------------------------------------------------------------
+  // Record references ($ref) — OData standard, supported since FMS 19
+  // -------------------------------------------------------------------------
+
+  /**
+   * Get the references for a navigation property on this record.
+   *
+   * `GET /<EntitySet>(<key>)/<navProperty>/$ref`
+   *
+   * Returns an array of entity references. For a single-valued navigation
+   * property, the array has at most one element.
+   *
+   * @example
+   * ```ts
+   * const refs = await db.from('contact').byKey(7).getRefs('addresses')
+   * // [{ '@odata.id': 'https://fms.example.com/fmi/odata/v4/DB/address(1)' }, ...]
+   * ```
+   */
+  async getRefs(navProperty: string, opts: RequestOptions = {}): Promise<EntityRefInfo[]> {
+    const url = `${this.toURL()}/${encodePathSegment(navProperty)}/$ref`
+    const json = await executeJson<{ value?: EntityRefInfo[]; '@odata.id'?: string }>(
+      this._client._ctx,
+      url,
+      {
+        method: 'GET',
+        accept: 'json',
+        ...(opts.signal ? { signal: opts.signal } : {}),
+      },
+    )
+    // Single-valued nav properties return { "@odata.id": "..." } directly;
+    // collection nav properties return { value: [{ "@odata.id": "..." }, ...] }
+    if (json?.value) return json.value
+    if (json?.['@odata.id']) return [json as EntityRefInfo]
+    return []
+  }
+
+  /**
+   * Add a reference to a related record via a navigation property.
+   *
+   * `POST /<EntitySet>(<key>)/<navProperty>/$ref`
+   *
+   * For single-valued navigation properties, use `setRef()` instead (PATCH).
+   *
+   * @example
+   * ```ts
+   * await db.from('contact').byKey(7).addRef('addresses', 42)
+   * ```
+   */
+  async addRef(navProperty: string, relatedKey: string | number, opts: EntityWriteOptions = {}): Promise<void> {
+    const url = `${this.toURL()}/${encodePathSegment(navProperty)}/$ref`
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (opts.ifMatch) headers['If-Match'] = opts.ifMatch
+
+    const body = JSON.stringify({ '@odata.id': this._refId(navProperty, relatedKey) })
+    await executeRequest(this._client._ctx, url, {
+      method: 'POST',
+      headers,
+      body,
+      accept: 'none',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Set (replace) the reference for a single-valued navigation property.
+   *
+   * `PATCH /<EntitySet>(<key>)/<navProperty>/$ref`
+   *
+   * @example
+   * ```ts
+   * await db.from('order').byKey(100).setRef('customer', 7)
+   * ```
+   */
+  async setRef(navProperty: string, relatedKey: string | number, opts: EntityWriteOptions = {}): Promise<void> {
+    const url = `${this.toURL()}/${encodePathSegment(navProperty)}/$ref`
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (opts.ifMatch) headers['If-Match'] = opts.ifMatch
+
+    const body = JSON.stringify({ '@odata.id': this._refId(navProperty, relatedKey) })
+    await executeRequest(this._client._ctx, url, {
+      method: 'PATCH',
+      headers,
+      body,
+      accept: 'none',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Remove a reference from a navigation property.
+   *
+   * `DELETE /<EntitySet>(<key>)/<navProperty>/$ref`
+   *
+   * For collection-valued navigation properties, pass the `relatedKey` to
+   * remove a specific reference. For single-valued, omit `relatedKey` to
+   * clear the reference.
+   *
+   * @example
+   * ```ts
+   * await db.from('contact').byKey(7).removeRef('addresses', 42)
+   * await db.from('order').byKey(100).removeRef('customer')
+   * ```
+   */
+  async removeRef(navProperty: string, relatedKey?: string | number, opts: EntityWriteOptions = {}): Promise<void> {
+    let url = `${this.toURL()}/${encodePathSegment(navProperty)}/$ref`
+    const headers: Record<string, string> = {}
+    if (opts.ifMatch) headers['If-Match'] = opts.ifMatch
+
+    if (relatedKey !== undefined) {
+      // For collection nav properties, target the specific reference by ID
+      url += `('${escapeStringLiteral(this._refId(navProperty, relatedKey))}')`
+    }
+
+    await executeRequest(this._client._ctx, url, {
+      method: 'DELETE',
+      headers,
+      accept: 'none',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /** @internal — build a relative @odata.id for a related entity. */
+  private _refId(navProperty: string, relatedKey: string | number): string {
+    // The @odata.id can be a relative URL or a full URL. We use a relative
+    // form that's portable across deployments: just the entity set name and key.
+    // FMS resolves this relative to the service root.
+    const navSet = navProperty // The navigation property name typically matches the target entity set
+    if (typeof relatedKey === 'number') return `${navSet}(${relatedKey})`
+    return `${navSet}('${escapeStringLiteral(relatedKey)}')`
+  }
+}
+
+/** Entity reference info returned by `getRefs()`. */
+export interface EntityRefInfo {
+  '@odata.id': string
+}
+

package/src/errors.ts

@@ -0,0 +1,134 @@
+/**
+ * Normalized error thrown by all fms-odata-js operations.
+ *
+ * The error class shape is aligned with `@fms-odata/spec-ts` (the canonical
+ * spec package). fms-odata-js keeps its own class identity for backward
+ * compatibility with existing `instanceof` checks in user code.
+ *
+ * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/13-quirks.md
+ */
+export class FMSODataError extends Error {
+  readonly status: number
+  readonly code: string | undefined
+  readonly odataError: unknown
+  readonly request: { url: string; method: string } | undefined
+
+  constructor(
+    message: string,
+    init: {
+      status: number
+      code?: string
+      odataError?: unknown
+      request?: { url: string; method: string }
+    },
+  ) {
+    super(message)
+    this.name = 'FMSODataError'
+    this.status = init.status
+    if (init.code !== undefined) this.code = init.code
+    if (init.odataError !== undefined) this.odataError = init.odataError
+    if (init.request !== undefined) this.request = init.request
+  }
+}
+
+/**
+ * Parse an error Response body into a `FMSODataError`. Handles both stock OData
+ * JSON envelopes (`{ error: { code, message } }`) and FileMaker's XML envelope
+ * (`<m:error><m:code>212</m:code><m:message>...</m:message></m:error>`).
+ *
+ * @internal
+ */
+export async function parseErrorResponse(
+  res: Response,
+  request: { url: string; method: string },
+): Promise<FMSODataError> {
+  const status = res.status
+  let body = ''
+  try {
+    body = await res.text()
+  } catch {
+    // body unreadable; fall through with empty string
+  }
+
+  let code: string | undefined
+  let message = res.statusText || `HTTP ${status}`
+  let odataError: unknown = body
+
+  const ctype = (res.headers.get('content-type') ?? '').toLowerCase()
+  const looksJson = ctype.includes('json') || (body.startsWith('{') && body.endsWith('}'))
+  const looksXml = ctype.includes('xml') || body.trimStart().startsWith('<?xml') || body.includes('<m:error')
+
+  if (looksJson) {
+    try {
+      const json = JSON.parse(body) as { error?: { code?: string; message?: string | { value?: string } } }
+      odataError = json
+      const errCode = json?.error?.code
+      const rawMsg = json?.error?.message
+      const msg = typeof rawMsg === 'string' ? rawMsg : rawMsg?.value
+      if (errCode) code = String(errCode)
+      if (msg) message = msg
+    } catch {
+      // leave defaults
+    }
+  } else if (looksXml) {
+    const codeMatch = body.match(/<m:code>([^<]+)<\/m:code>/)
+    const msgMatch = body.match(/<m:message(?:\s[^>]*)?>([^<]+)<\/m:message>/)
+    if (codeMatch?.[1]) code = codeMatch[1]
+    if (msgMatch?.[1]) message = msgMatch[1]
+  }
+
+  return new FMSODataError(message, { status, ...(code !== undefined ? { code } : {}), odataError, request })
+}
+
+/**
+ * Thrown when a FileMaker script invocation completes with a non-zero
+ * `scriptError`. The HTTP request itself succeeded (the server returned 2xx),
+ * but the script reported an error via the FMS result envelope.
+ *
+ * Subclass of `FMSODataError` so existing `instanceof FMSODataError` checks and
+ * error-handling code keep working.
+ */
+export class FMScriptError extends FMSODataError {
+  /** FileMaker script error code as a string (e.g. `"101"`). */
+  readonly scriptError: string
+  /** Raw `scriptResult` value returned by the script, if any. */
+  readonly scriptResult: string | undefined
+
+  constructor(
+    message: string,
+    init: {
+      status: number
+      scriptError: string
+      scriptResult?: string
+      odataError?: unknown
+      request?: { url: string; method: string }
+    },
+  ) {
+    super(message, {
+      status: init.status,
+      code: init.scriptError,
+      ...(init.odataError !== undefined ? { odataError: init.odataError } : {}),
+      ...(init.request !== undefined ? { request: init.request } : {}),
+    })
+    this.name = 'FMScriptError'
+    this.scriptError = init.scriptError
+    if (init.scriptResult !== undefined) this.scriptResult = init.scriptResult
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Spec alignment: re-export type-level helpers from @fms-odata/spec-ts
+// ---------------------------------------------------------------------------
+
+/** OData standard error response body shape (from spec). */
+export type { ODataErrorBody } from '@fms-odata/spec-ts'
+
+/** Check if an error is a FileMaker OData error. */
+export function isFMSODataError(err: unknown): err is FMSODataError {
+  return err instanceof FMSODataError
+}
+
+/** Check if an error is a FileMaker script error. */
+export function isFMScriptError(err: unknown): err is FMScriptError {
+  return err instanceof FMScriptError
+}

package/src/http.ts

@@ -0,0 +1,190 @@
+/**
+ * HTTP plumbing shared by the query builder, entity handles, and (later)
+ * containers, scripts, metadata, and batch.
+ *
+ * Aligned with `@fms-odata/spec-ts` for auth type definitions. fms-odata-js
+ * keeps its own `resolveAuthHeader`, `basicAuth`, `combineSignals`, and
+ * `executeRequest` implementations which are more feature-rich (401 retry,
+ * timeout composition, browser/Web Viewer compatibility).
+ *
+ * Responsibilities:
+ * - Authorization header resolution (Basic, Bearer, or FMID, auto-detected).
+ * - Timeout + AbortSignal composition.
+ * - 401 retry via `onUnauthorized` (once).
+ * - Error envelope normalization into `FMSODataError`.
+ *
+ * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/04-authentication.md
+ */
+
+import { parseErrorResponse, FMSODataError } from './errors.js'
+import type { TokenProvider, RequestOptions } from './types.js'
+
+/** A scheme-prefixed Authorization value (e.g. `Basic …`, `Bearer …`, or `FMID …`). */
+const AUTH_SCHEME_RE = /^(basic|bearer|fmid|negotiate|digest)\s+\S/i
+
+/** Resolve a `TokenProvider` to a complete Authorization header value. */
+export async function resolveAuthHeader(provider: TokenProvider): Promise<string> {
+  const raw =
+    typeof provider === 'function'
+      ? await provider()
+      : provider
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw new TypeError('fms-odata-js: token resolver produced an empty value')
+  }
+  return AUTH_SCHEME_RE.test(raw) ? raw : `Bearer ${raw}`
+}
+
+/** Encode an FMS account username + password into a `Basic …` header value. */
+export function basicAuth(user: string, password: string): string {
+  const raw = `${user}:${password}`
+  // Prefer Buffer (Node); fall back to btoa (browser / Web Viewer).
+  const b64 =
+    typeof Buffer !== 'undefined'
+      ? Buffer.from(raw, 'utf8').toString('base64')
+      : btoa(unescape(encodeURIComponent(raw)))
+  return `Basic ${b64}`
+}
+
+/** Build an FMID auth header value for FileMaker Cloud (Claris ID token). */
+export function fmidAuth(token: string): string {
+  return `FMID ${token}`
+}
+
+/** Auth scheme type (aligned with spec). */
+export type { FMAuthScheme, FMAuthToken, FMAuthTokenProvider } from '@fms-odata/spec-ts'
+
+/** Combine multiple `AbortSignal`s into one that aborts when any input aborts. */
+export function combineSignals(
+  signals: ReadonlyArray<AbortSignal | undefined>,
+): AbortSignal | undefined {
+  const filtered = signals.filter((s): s is AbortSignal => s !== undefined)
+  if (filtered.length === 0) return undefined
+  if (filtered.length === 1) return filtered[0]
+  const ctrl = new AbortController()
+  for (const s of filtered) {
+    if (s.aborted) {
+      ctrl.abort((s as AbortSignal & { reason?: unknown }).reason)
+      return ctrl.signal
+    }
+    s.addEventListener(
+      'abort',
+      () => ctrl.abort((s as AbortSignal & { reason?: unknown }).reason),
+      { once: true },
+    )
+  }
+  return ctrl.signal
+}
+
+/** Options accepted by the shared request executor. */
+export interface HttpRequestOptions extends RequestOptions {
+  method?: string
+  headers?: HeadersInit
+  body?: BodyInit | null
+  /** Expected response shape; controls default Accept header. */
+  accept?: 'json' | 'xml' | 'text' | 'binary' | 'none'
+}
+
+/** Context supplied by `FMSOData` to execute a request. */
+export interface HttpClientContext {
+  token: TokenProvider
+  onUnauthorized?: () => void | Promise<void>
+  fetch: typeof globalThis.fetch
+  timeoutMs: number | undefined
+}
+
+const ACCEPT_DEFAULTS: Record<NonNullable<HttpRequestOptions['accept']>, string> = {
+  json: 'application/json',
+  xml: 'application/xml',
+  text: 'text/plain',
+  binary: 'application/octet-stream',
+  none: '*/*',
+}
+
+/**
+ * Execute an HTTP request against the FMS OData endpoint. Centralizes auth,
+ * timeout, retry, and error handling. Returns the raw `Response` on success.
+ */
+export async function executeRequest(
+  ctx: HttpClientContext,
+  url: string,
+  opts: HttpRequestOptions = {},
+): Promise<Response> {
+  return executeRequestImpl(ctx, url, opts, /* retried */ false)
+}
+
+async function executeRequestImpl(
+  ctx: HttpClientContext,
+  url: string,
+  opts: HttpRequestOptions,
+  retried: boolean,
+): Promise<Response> {
+  const method = opts.method ?? 'GET'
+  const headers = new Headers(opts.headers)
+  headers.set('Authorization', await resolveAuthHeader(ctx.token))
+  // Required by the Claris FMS OData API for all requests.
+  if (!headers.has('OData-Version')) headers.set('OData-Version', '4.0')
+  if (!headers.has('OData-MaxVersion')) headers.set('OData-MaxVersion', '4.0')
+  if (!headers.has('Accept')) {
+    headers.set('Accept', ACCEPT_DEFAULTS[opts.accept ?? 'json'])
+  }
+
+  const timeoutCtrl = new AbortController()
+  const timeoutId =
+    ctx.timeoutMs && ctx.timeoutMs > 0
+      ? setTimeout(() => timeoutCtrl.abort(new Error(`Timeout after ${ctx.timeoutMs}ms`)), ctx.timeoutMs)
+      : undefined
+
+  const signal = combineSignals([opts.signal, ctx.timeoutMs ? timeoutCtrl.signal : undefined])
+
+  let res: Response
+  try {
+    res = await ctx.fetch(url, {
+      method,
+      headers,
+      keepalive: true,
+      ...(opts.body !== undefined ? { body: opts.body } : {}),
+      ...(signal ? { signal } : {}),
+    })
+  } catch (err) {
+    if (timeoutId) clearTimeout(timeoutId)
+    // AbortError (timeout or caller cancellation) propagates as-is.
+    throw err
+  }
+  if (timeoutId) clearTimeout(timeoutId)
+
+  if (res.status === 401 && ctx.onUnauthorized && !retried) {
+    await ctx.onUnauthorized()
+    return executeRequestImpl(ctx, url, opts, true)
+  }
+
+  if (!res.ok) {
+    throw await parseErrorResponse(res, { url, method })
+  }
+  return res
+}
+
+/** Convenience: execute and parse the response as JSON. */
+export async function executeJson<T = unknown>(
+  ctx: HttpClientContext,
+  url: string,
+  opts: HttpRequestOptions = {},
+): Promise<T> {
+  const res = await executeRequest(ctx, url, opts)
+  if (res.status === 204) return undefined as T
+  const ctype = (res.headers.get('content-type') ?? '').toLowerCase()
+  if (!ctype.includes('json')) {
+    // Some FMS responses omit the header on success; try to parse anyway.
+    const text = await res.text()
+    if (!text) return undefined as T
+    try {
+      return JSON.parse(text) as T
+    } catch {
+      throw new FMSODataError(`Expected JSON response, got "${ctype || 'no content-type'}"`, {
+        status: res.status,
+        odataError: text,
+        request: { url, method: opts.method ?? 'GET' },
+      })
+    }
+  }
+  return (await res.json()) as T
+}