@sanity/client 7.26.2 → 8.0.0

package/src/http/request.ts

@@ -1,110 +1,333 @@
-import {getIt, type HttpContext, type Middlewares, type Requester} from 'get-it'
-import {jsonRequest, jsonResponse, observable, progress, retry} from 'get-it/middleware'
-import {Observable} from 'rxjs'
+import {
+  createRequester,
+  type FetchFunction,
+  HttpError as GetItHttpError,
+  type RequestOptions as FetchRequestOptions,
+  type TransformMiddleware,
+  type WrappingMiddleware,
+} from 'get-it'
+import {isRetryableRequest, retry} from 'get-it/middleware'
+import {from, Observable} from 'rxjs'
 
 import type {Any} from '../types'
-import {ClientError, ServerError} from './errors'
-
-const httpError = {
-  onResponse: (res: Any, context: HttpContext) => {
-    if (res.statusCode >= 500) {
-      throw new ServerError(res)
-    } else if (res.statusCode >= 400) {
-      throw new ClientError(res, context)
-    }
+import {ClientError, httpResponseFromFetch, ServerError} from './errors'
+
+/**
+ * Middleware accepted by the internal HTTP layer. Two flavors per get-it v9:
+ * a flat-pipeline transform (`beforeRequest`/`afterResponse`) or a wrapping
+ * middleware that surrounds the fetch chain.
+ *
+ * @internal
+ */
+export type LegacyMiddleware = TransformMiddleware | WrappingMiddleware
 
-    return res
-  },
+/**
+ * The shape this client's internal pipeline produces. Mirrors the historical
+ * `ResponseEvent` from the get-it v8 multi-event observable, so all the existing
+ * downstream code (`_requestObservable`, `_uploadObservable`,
+ * `defineCreateClient`) keeps working without churn.
+ *
+ * @internal
+ */
+export interface ResponseEvent {
+  type: 'response'
+  body: unknown
+  statusCode: number
+  statusMessage: string | null
+  headers: Record<string, string>
+  url: string
+  method: string
 }
 
-function printWarnings(config: {ignoreWarnings?: string | RegExp | Array<string | RegExp>} = {}) {
-  const seen: Record<string, boolean> = {}
+/**
+ * Legacy "requester" type — the result of `defineHttpRequest`. Returns a
+ * single-event Observable for compatibility with the rest of the codebase.
+ *
+ * @internal
+ */
+export type LegacyRequester = (options: Any) => Observable<ResponseEvent>
 
-  // Helper function to check if a warning should be ignored
-  const shouldIgnoreWarning = (message: string): boolean => {
-    if (config.ignoreWarnings === undefined) return false
+/**
+ * Promise-based sibling of {@link LegacyRequester}. Resolves directly to the
+ * single `ResponseEvent` the transport produces, skipping the RxJS wrapper.
+ * Used by the promise-based client surface so it never constructs an
+ * Observable.
+ *
+ * @internal
+ */
+export type PromiseRequester = (options: Any) => Promise<ResponseEvent>
 
-    const patterns = Array.isArray(config.ignoreWarnings)
-      ? config.ignoreWarnings
-      : [config.ignoreWarnings]
+/**
+ * Both forms of the transport, sharing a single underlying get-it requester
+ * (so retry state and the one-shot warning de-duplication are shared between
+ * the observable and promise paths).
+ *
+ * @internal
+ */
+export interface DualRequester {
+  observable: LegacyRequester
+  promise: PromiseRequester
+}
+
+/**
+ * Options for tuning the HTTP request pipeline per-client.
+ *
+ * @internal
+ */
+export interface HttpRequestConfig {
+  ignoreWarnings?: string | RegExp | Array<string | RegExp>
+  maxRetries?: number
+  retryDelay?: (attemptNumber: number) => number
+}
+
+/**
+ * Build both the observable and promise transport forms from a single get-it
+ * requester. The promise form is the primitive (`executeRequest` is already
+ * promise-based); the observable form wraps it lazily so each subscription
+ * starts its own request (cold), and unsubscribing aborts the in-flight
+ * fetch — the same contract as the get-it v8 observable adapter.
+ *
+ * @internal
+ */
+export function defineRequester(
+  envOptions: EnvironmentOptions,
+  config: HttpRequestConfig = {},
+): DualRequester {
+  // Framework-patched fetch implementations read extra `RequestInit` fields
+  // for caching semantics — Next.js App Router's `cache` and `next` options in
+  // particular. Legacy callers pass those via an object-valued `fetch` request
+  // option (see `adaptToFetchOptions`, which stashes it in `meta.fetchInit`
+  // since get-it v9's own `fetch` option only accepts a function). Merge them
+  // into the init of whichever fetch implementation is effective for the
+  // request: per-request/test-override fetch, the environment default, or the
+  // global fetch.
+  const applyFetchInit: WrappingMiddleware = (opts, next) => {
+    const fetchInit = opts.meta?.fetchInit
+    if (typeof fetchInit !== 'object' || fetchInit === null) return next(opts)
+    const baseFetch: NonNullable<FetchRequestOptions['fetch']> =
+      opts.fetch ?? envOptions.fetch ?? globalThis.fetch
+    const fetchWithInit: typeof baseFetch = (input, init) =>
+      baseFetch(input, {...fetchInit, ...init})
+    return next({...opts, fetch: fetchWithInit})
+  }
+
+  const requester = createRequester({
+    ...(envOptions.fetch ? {fetch: envOptions.fetch} : {}),
+    headers: envOptions.headers,
+    // Keep get-it's built-in 4xx/5xx → HttpError so the retry middleware can
+    // see them; we translate to ClientError/ServerError after the retry loop
+    // has exhausted in `executeRequest`.
+    httpErrors: true,
+    middleware: [
+      retry({
+        shouldRetry: shouldRetryRequest,
+        maxRetries: config.maxRetries ?? 5,
+        ...(config.retryDelay ? {retryDelay: config.retryDelay} : {}),
+      }),
+      ...envOptions.middleware,
+      applyFetchInit,
+      printWarnings(config),
+    ],
+  })
 
-    return patterns.some((pattern) => {
-      if (typeof pattern === 'string') {
-        return message.includes(pattern)
-      } else if (pattern instanceof RegExp) {
-        return pattern.test(message)
+  const promise: PromiseRequester = (options: Any) => {
+    // Options arrive fetch-shaped from `requestOptions` — the single
+    // translation boundary between public option names and the transport.
+    if (typeof options.url !== 'string') {
+      throw new TypeError('Request options must include a `url`')
+    }
+    return executeRequest(requester, options)
+  }
+
+  // Same per-subscription AbortController pattern as `_observe` in
+  // dataMethods: a caller-supplied signal is combined in via
+  // `AbortSignal.any`, so the request aborts both on the caller's signal and
+  // on unsubscribe. `AbortSignal.any` (rather than `addEventListener`)
+  // because the caller's signal can be long-lived and reused — a manually
+  // added listener would accumulate there once per subscription, since
+  // `{once: true}` only cleans up if the signal actually fires.
+  const observable: LegacyRequester = (options: Any) =>
+    new Observable<ResponseEvent>((subscriber) => {
+      const controller = new AbortController()
+      const userSignal: AbortSignal | undefined = options.signal
+      const signal = userSignal
+        ? AbortSignal.any([userSignal, controller.signal])
+        : controller.signal
+      const subscription = from(promise({...options, signal})).subscribe(subscriber)
+      return () => {
+        subscription.unsubscribe()
+        controller.abort()
       }
-      return false
     })
+
+  return {promise, observable}
+}
+
+/** @internal */
+export function defineHttpRequest(
+  envOptions: EnvironmentOptions,
+  config: HttpRequestConfig = {},
+): LegacyRequester {
+  return defineRequester(envOptions, config).observable
+}
+
+/**
+ * Options describing the environment-specific defaults (Node vs. browser).
+ *
+ * @internal
+ */
+export interface EnvironmentOptions {
+  fetch?: FetchRequestOptions['fetch']
+  headers?: Record<string, string>
+  middleware: LegacyMiddleware[]
+  /**
+   * Resolves the environment's fetch implementation — the same transport
+   * regular requests use (custom fetch variants, undici configuration,
+   * env-proxy support and all), optionally configured for an explicit proxy
+   * URL. Lets consumers of the resolved config (the EventSource fetch
+   * resolver) avoid falling back to whatever `globalThis.fetch` happens to
+   * be. The Node environment supplies get-it's undici-backed fetch; the
+   * browser environment leaves it unset (the global fetch IS the
+   * environment's fetch there).
+   *
+   * Looked up via the env rather than imported directly so that the Node-only
+   * `get-it/node` (which transitively pulls in `undici`) never ends up in the
+   * browser bundle, even via rollup's inlined dynamic imports.
+   */
+  resolveFetch?: (proxyUrl?: string) => FetchFunction
+}
+
+async function executeRequest(
+  requester: ReturnType<typeof createRequester>,
+  fetchOptions: FetchRequestOptions,
+): Promise<ResponseEvent> {
+  const url = fetchOptions.url
+  const method = (fetchOptions.method ?? 'GET').toUpperCase()
+
+  let response
+  try {
+    response = await requester(fetchOptions)
+  } catch (err) {
+    if (err instanceof GetItHttpError) {
+      // `err.body` is the response body as a string (get-it v9 stores the
+      // already-decoded text), regardless of which response variant
+      // `err.response` is.
+      const errBodyText = typeof err.body === 'string' ? err.body : ''
+      const errBody = parseJsonText(errBodyText, err.headers)
+      const canonical = httpResponseFromFetch(
+        {
+          status: err.status,
+          statusText: err.statusText,
+          headers: err.headers,
+          body: errBody,
+        },
+        url,
+        method,
+      )
+      const tag = extractRequestTag(fetchOptions.query)
+      if (canonical.statusCode >= 500) {
+        throw new ServerError(canonical)
+      }
+      throw new ClientError(canonical, tag)
+    }
+    throw err
   }
 
+  const body = parseJsonBody(response)
   return {
-    onResponse: (res: Any) => {
-      const warn = res.headers['x-sanity-warning']
-      const warnings = Array.isArray(warn) ? warn : [warn]
-      for (const msg of warnings) {
-        if (!msg || seen[msg]) continue
+    type: 'response',
+    body,
+    statusCode: response.status,
+    statusMessage: response.statusText || null,
+    headers: headersToRecord(response.headers),
+    url,
+    method,
+  }
+}
 
-        // Skip warnings that match ignore patterns
-        if (shouldIgnoreWarning(msg)) {
-          continue
-        }
+/**
+ * Extract the GROQ request tag (used for error messages) from the query.
+ */
+function extractRequestTag(query: FetchRequestOptions['query']): string | undefined {
+  if (!query) return undefined
+  if (query instanceof URLSearchParams) return query.get('tag') ?? undefined
+  const tag = query.tag
+  return typeof tag === 'string' ? tag : undefined
+}
 
-        seen[msg] = true
-        console.warn(msg) // eslint-disable-line no-console
-      }
-      return res
-    },
+function parseJsonBody(response: {headers: Headers; text(): string}): unknown {
+  return parseJsonText(response.text(), response.headers)
+}
+
+/**
+ * Parse a response body according to its `content-type`: JSON when the header
+ * says so (falling back to the raw text on malformed JSON), text otherwise.
+ * Shared with the browser XHR upload path so error bodies parse identically
+ * on both transports.
+ *
+ * @internal
+ */
+export function parseJsonText(text: string, headers: Headers): unknown {
+  const contentType = (headers.get('content-type') ?? '').toLowerCase()
+  if (!text) return undefined
+  if (contentType.includes('application/json')) {
+    try {
+      return JSON.parse(text)
+    } catch {
+      return text
+    }
   }
+  return text
 }
 
-type HttpRequestConfig = {
-  ignoreWarnings?: string | RegExp | Array<string | RegExp>
+function headersToRecord(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    out[key] = value
+  })
+  return out
 }
 
-/** @internal */
-export function defineHttpRequest(
-  envMiddleware: Middlewares,
-  config: HttpRequestConfig = {},
-): Requester {
-  return getIt([
-    retry({shouldRetry}),
-    ...envMiddleware,
-    printWarnings(config),
-    jsonRequest(),
-    jsonResponse(),
-    progress(),
-    httpError,
-    observable({implementation: Observable}),
-  ])
+function shouldRetryRequest(err: unknown, attempt: number, options: FetchRequestOptions): boolean {
+  // HTTP errors aren't usually retryable, but Content Lake gives us a few
+  // status codes where retrying *is* the right move.
+  if (err instanceof GetItHttpError) {
+    const isSafe = (options.method ?? 'GET') === 'GET' || options.method === 'HEAD'
+    const isQuery = (options.url ?? '').includes('/data/query')
+    const status = err.status
+    const retryableStatus = status === 429 || status === 502 || status === 503
+    if ((isSafe || isQuery) && retryableStatus) return true
+    return false
+  }
+
+  return isRetryableRequest(err, attempt, options)
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function shouldRetry(err: any, attempt: number, options: any) {
-  // Allow opting out of retries
-  if (options.maxRetries === 0) return false
-
-  // By default `retry.shouldRetry` doesn't retry on server errors so we add our own logic.
-
-  const isSafe = options.method === 'GET' || options.method === 'HEAD'
-  const uri = options.uri || options.url
-  const isQuery = uri.startsWith('/data/query')
-  const isRetriableResponse =
-    err.response &&
-    (err.response.statusCode === 429 ||
-      err.response.statusCode === 502 ||
-      err.response.statusCode === 503)
-
-  // We retry the following errors:
-  // - 429 means that the request was rate limited. It's a bit difficult
-  //   to know exactly how long it makes sense to wait and/or how many
-  //   attempts we should retry, but the backoff should alleviate the
-  //   additional load.
-  // - 502/503 can occur when certain components struggle to talk to their
-  //   upstream dependencies. This is most likely a temporary problem
-  //   and retrying makes sense.
-
-  if ((isSafe || isQuery) && isRetriableResponse) return true
-
-  return retry.shouldRetry(err, attempt, options)
+function printWarnings(config: HttpRequestConfig): TransformMiddleware {
+  const seen: Record<string, boolean> = {}
+
+  const shouldIgnore = (message: string): boolean => {
+    if (config.ignoreWarnings === undefined) return false
+    const patterns = Array.isArray(config.ignoreWarnings)
+      ? config.ignoreWarnings
+      : [config.ignoreWarnings]
+    return patterns.some((pattern) =>
+      typeof pattern === 'string' ? message.includes(pattern) : pattern.test(message),
+    )
+  }
+
+  return {
+    afterResponse(response) {
+      const header = response.headers.get('x-sanity-warning')
+      if (!header) return response
+      // Multiple warnings can be comma-separated per HTTP header semantics.
+      for (const msg of header.split(',').map((m) => m.trim())) {
+        if (!msg || seen[msg] || shouldIgnore(msg)) continue
+        seen[msg] = true
+        // oxlint-disable-next-line no-console
+        console.warn(msg)
+      }
+      return response
+    },
+  }
 }

package/src/http/requestOptions.ts

@@ -1,11 +1,34 @@
-import type {RequestOptions} from 'get-it'
+import type {RequestOptions as GetItRequestOptions} from 'get-it'
 
 import type {Any} from '../types'
 
 const projectHeader = 'X-Sanity-Project-ID'
 
-export function requestOptions(config: Any, overrides: Any = {}): Omit<RequestOptions, 'url'> {
-  const headers: Any = {}
+/**
+ * The request shape the transport (`defineRequester`) consumes: get-it v9's
+ * own options, with `headers` pinned to the plain-record form this builder
+ * always produces.
+ *
+ * @internal
+ */
+export type FetchRequest = Omit<GetItRequestOptions, 'headers'> & {
+  headers: Record<string, string>
+}
+
+/**
+ * Project the public request options (`timeout: 0` to disable,
+ * `withCredentials`, `maxRedirects`, the function/object-form `fetch`, ...)
+ * plus the client config into a get-it v9 fetch-shaped request. This is the
+ * single translation boundary between the client's public option names and
+ * the transport — everything below it speaks get-it v9.
+ *
+ * Reads the live client config, so reconfiguration via `client.config()` /
+ * `withConfig()` (token, headers, proxy, ...) applies to subsequent requests.
+ *
+ * @internal
+ */
+export function requestOptions(config: Any, overrides: Any = {}): FetchRequest {
+  const headers: Record<string, string> = {}
 
   if (config.headers) {
     Object.assign(headers, config.headers)
@@ -13,29 +36,122 @@ export function requestOptions(config: Any, overrides: Any = {}): Omit<RequestOp
 
   const token = overrides.token || config.token
   if (token) {
-    headers.Authorization = `Bearer ${token}`
+    headers['Authorization'] = `Bearer ${token}`
   }
 
   if (!overrides.useGlobalApi && !config.useProjectHostname && config.projectId) {
     headers[projectHeader] = config.projectId
   }
 
+  const request: FetchRequest = {
+    url: overrides.url,
+    headers: Object.assign(headers, overrides.headers || {}),
+  }
+
+  if (overrides.method) request.method = overrides.method
+  if (overrides.body !== undefined) request.body = overrides.body
+  if (overrides.query) request.query = expandQueryArrays(overrides.query)
+  if (overrides.signal) request.signal = overrides.signal
+
   const withCredentials = Boolean(
     typeof overrides.withCredentials === 'undefined'
       ? config.withCredentials
       : overrides.withCredentials,
   )
+  if (withCredentials) request.credentials = 'include'
 
+  // The public option is the legacy `maxRedirects` count, but only "follow"
+  // vs "don't" ever worked — fetch has no redirect budget.
+  if (typeof overrides.maxRedirects === 'number') {
+    request.redirect = overrides.maxRedirects === 0 ? 'manual' : 'follow'
+  }
+
+  // Public semantics: `0` disables the timeout (get-it uses `false`), default
+  // is five minutes.
   const timeout = typeof overrides.timeout === 'undefined' ? config.timeout : overrides.timeout
-  return Object.assign({}, overrides, {
-    headers: Object.assign({}, headers, overrides.headers || {}),
-    timeout: typeof timeout === 'undefined' ? 5 * 60 * 1000 : timeout,
-    proxy: overrides.proxy || config.proxy,
-    json: true,
-    withCredentials,
-    fetch:
-      typeof overrides.fetch === 'object' && typeof config.fetch === 'object'
-        ? {...config.fetch, ...overrides.fetch}
-        : overrides.fetch || config.fetch,
-  })
+  request.timeout = typeof timeout === 'undefined' ? 5 * 60 * 1000 : timeout === 0 ? false : timeout
+
+  // `useAbortSignal: false` is set by the query path when the caller provided
+  // no signal of their own, and means no AbortSignal may reach the fetch
+  // init: Next.js' patched fetch opts a request out of React Request
+  // Memoization whenever `init.signal` is present, and get-it v9 implements
+  // timeouts via `AbortSignal.timeout()`. Switch to get-it's rejection-only
+  // timeout mode (`{signal: false}`): the deadline still rejects, but no
+  // signal reaches the fetch init and the underlying request is left running,
+  // so a memoizing fetch can still settle the shared promise for other
+  // consumers.
+  if (overrides.useAbortSignal === false && !request.signal) {
+    request.timeout =
+      typeof request.timeout === 'number' && request.timeout > 0
+        ? {total: request.timeout, signal: false}
+        : false
+  }
+
+  // The public `fetch` option is either a custom fetch implementation
+  // (function) or a bag of extra `RequestInit` fields (object) — Next.js App
+  // Router's `cache`/`next` caching options arrive as the latter. get-it's
+  // `fetch` option only accepts a function, so the init extras travel in
+  // `meta` and are merged into the effective fetch by the `applyFetchInit`
+  // middleware. (A boolean `fetch` was v8's "force the fetch transport"
+  // switch — a no-op now that fetch is the only transport.)
+  const fetchOption =
+    typeof overrides.fetch === 'object' && typeof config.fetch === 'object'
+      ? {...config.fetch, ...overrides.fetch}
+      : overrides.fetch || config.fetch
+  if (typeof fetchOption === 'function') {
+    request.fetch = fetchOption
+  } else if (typeof fetchOption === 'object' && fetchOption !== null) {
+    request.meta = {...request.meta, fetchInit: fetchOption}
+  }
+
+  // The config's fetch resolver supplies the transport for every request —
+  // the environment's own fetch by default, a proxy-configured one when an
+  // explicit `proxy` is set, or a caller-supplied resolver (the test suite
+  // injects its mock this way). A per-request `fetch` function wins over it.
+  // There is deliberately no per-request proxy.
+  if (!request.fetch && config.resolveFetch) {
+    request.fetch = config.resolveFetch(typeof config.proxy === 'string' ? config.proxy : undefined)
+  }
+
+  // Per-request retry cap/opt-out (`maxRetries: 0` disables retries) —
+  // honored natively by get-it's retry middleware, overriding the
+  // client-level maximum in both directions.
+  if (typeof overrides.maxRetries === 'number') {
+    request.maxRetries = overrides.maxRetries
+  }
+
+  // Lineage travels in `meta`; the Node middleware projects it onto the
+  // `x-sanity-lineage` header (merged with the `X_SANITY_LINEAGE` env var).
+  if (typeof config.lineage === 'string' && config.lineage) {
+    request.meta = {...request.meta, lineage: config.lineage}
+  }
+
+  return request
+}
+
+/**
+ * Expand array-valued query params into repeated keys.
+ *
+ * get-it v9 stringifies a plain object's values directly, so passing
+ * `{meta: ['palette', 'location']}` would produce `?meta=palette,location`
+ * — which Content Lake doesn't recognise. Repeated keys
+ * (`?meta=palette&meta=location`) are produced via `URLSearchParams`.
+ */
+function expandQueryArrays(query: Any): FetchRequest['query'] {
+  if (query instanceof URLSearchParams) return query
+  if (!query || typeof query !== 'object') return query
+  if (!Object.values(query).some(Array.isArray)) return query
+
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item !== undefined && item !== null) params.append(key, `${item}`)
+      }
+    } else {
+      params.append(key, `${value}`)
+    }
+  }
+  return params
 }

package/src/{index.browser.ts → index.node.ts}

@@ -1,15 +1,20 @@
 import defineCreateClientExports, {type ClientConfig, SanityClient} from './defineCreateClient'
 import {defineDeprecatedCreateClient} from './defineDeprecatedCreateClient'
-import envMiddleware from './http/browserMiddleware'
+import environment from './http/nodeMiddleware'
+import type {Requester} from './types'
 
 export * from './defineCreateClient'
 
-const exp = defineCreateClientExports<SanityClient, ClientConfig>(envMiddleware, SanityClient)
+const exp = defineCreateClientExports<SanityClient, ClientConfig>(environment, SanityClient)
 
 /** @public */
-export const requester = exp.requester
+export const requester: Requester = exp.requester
 
-/** @public */
+/**
+ * @remarks
+ * As of API version `v2025-02-19`, the default perspective used by the client has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog}
+ * @public
+ */
 export const createClient = exp.createClient
 
 /**

package/src/index.ts

@@ -1,13 +1,14 @@
 import defineCreateClientExports, {type ClientConfig, SanityClient} from './defineCreateClient'
 import {defineDeprecatedCreateClient} from './defineDeprecatedCreateClient'
-import envMiddleware from './http/nodeMiddleware'
+import environment from './http/browserMiddleware'
+import type {Requester} from './types'
 
 export * from './defineCreateClient'
 
-const exp = defineCreateClientExports<SanityClient, ClientConfig>(envMiddleware, SanityClient)
+const exp = defineCreateClientExports<SanityClient, ClientConfig>(environment, SanityClient)
 
 /** @public */
-export const requester = exp.requester
+export const requester: Requester = exp.requester
 
 /**
  * @remarks