@sanity/client 7.26.2 → 8.0.0

package/src/types.ts

@@ -1,17 +1,29 @@
 // deno-lint-ignore-file no-empty-interface
-/* eslint-disable @typescript-eslint/no-empty-object-type */
 
-import type {Requester} from 'get-it'
+import type {FetchFunction} from 'get-it'
 import type {Observable} from 'rxjs'
 
-import type {SanityClient} from './SanityClient'
 import type {InitializedStegaConfig, StegaConfig} from './stega/types'
 
+/**
+ * Low-level requester returned by `defineHttpRequest`. Surfaces as
+ * `client.config().requester` and as the named `requester` export.
+ *
+ * Defined locally rather than imported from `http/request` so api-extractor
+ * inlines it into the bundled `.d.ts` instead of emitting a relative import
+ * that doesn't survive into `dist/` ([#1290][]).
+ *
+ * [#1290]: https://github.com/sanity-io/client/issues/1290
+ *
+ * @public
+ */
+export type Requester = (options: Any) => Observable<unknown>
+
 /**
  * Used to tag types that is set to `any` as a temporary measure, but should be replaced with proper typings in the future
  * @internal
  */
-export type Any = any // eslint-disable-line @typescript-eslint/no-explicit-any
+export type Any = any // oxlint-disable-line typescript/no-explicit-any
 
 declare global {
   // Declare empty stub interfaces for environments where "dom" lib is not included
@@ -45,11 +57,15 @@ export type ReleaseId = `r${string}`
 type DeprecatedPreviewDrafts = 'previewDrafts'
 
 /** @public */
-export type StackablePerspective = ('published' | 'drafts' | string) & {}
+export type StackablePerspective = 'published' | 'drafts' | (string & {})
 
 /** @public */
 export type ClientPerspective =
-  DeprecatedPreviewDrafts | 'published' | 'drafts' | 'raw' | StackablePerspective[]
+  | DeprecatedPreviewDrafts
+  | 'published'
+  | 'drafts'
+  | 'raw'
+  | StackablePerspective[]
 
 /**
  * @public
@@ -130,6 +146,12 @@ export interface ClientConfig {
    * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog}
    */
   apiVersion?: string
+  /**
+   * Route requests through an HTTP(S) proxy. Node.js only. Can be replaced
+   * on an existing client via `client.config({proxy})` or
+   * `client.withConfig({proxy})`. For environment-driven proxying, set
+   * `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` before the process starts.
+   */
   proxy?: string
 
   /**
@@ -192,16 +214,33 @@ export interface ClientConfig {
   useProjectHostname?: boolean
 
   /**
-   * @deprecated Don't use
+   * Resolves the fetch implementation every request (including EventSource
+   * connections) goes through. Defaults to the environment entry point's
+   * fetch — the Node entry supplies get-it's undici-backed fetch (resolved
+   * via the entry point instead of a direct import so `get-it/node`/`undici`
+   * stays out of the browser bundle), the browser entry leaves it unset (the
+   * global fetch IS the environment's fetch there). Receives the explicit
+   * `proxy` config, when set, as its argument.
+   *
+   * Supplying it in the client config replaces the transport wholesale —
+   * custom fetch variants, alternative undici configurations, or a mock
+   * (the test suite injects `get-it/mock` this way).
+   *
+   * Returns get-it's minimal `FetchFunction` contract rather than the full
+   * `typeof fetch` — that is what the environments actually provide, and
+   * every consumer (the transport, the EventSource fetch resolver) only
+   * needs that subset.
+   *
+   * @internal
    */
-  requester?: Requester
+  resolveFetch?: (proxyUrl?: string) => FetchFunction
 
   /**
    * Adds a `resultSourceMap` key to the API response, with the type `ContentSourceMap`
    */
   resultSourceMap?: boolean | 'withKeyArraySelector'
   /**
-   *@deprecated set `cache` and `next` options on `client.fetch` instead
+   * @deprecated set `cache` and `next` options on `client.fetch` instead
    */
   fetch?:
     | {
@@ -217,33 +256,6 @@ export interface ClientConfig {
    * Lineage token for recursion control
    */
   lineage?: string
-
-  /**
-   * A custom request handler that intercepts all HTTP requests made by the client.
-   *
-   * Useful for logging, adding custom headers, refreshing auth tokens, rate limiting, etc.
-   *
-   * When using `withConfig()`, the new handler **replaces** the previous one (it does not
-   * wrap it). To compose handlers, you can chain them manually:
-   *
-   * ```ts
-   * const parent = createClient({...config, _requestHandler: handlerA})
-   * const child = parent.withConfig({
-   *   _requestHandler: (req, defaultRequester) =>
-   *     handlerB(req, (opts) => handlerA(opts, defaultRequester)),
-   * })
-   * ```
-   *
-   * Setting `_requestHandler` to `undefined` via `withConfig()` removes the handler.
-   *
-   * Note: This only applies to HTTP requests. Real-time listener connections
-   * (`client.listen()`) use EventSource and are not intercepted by this handler.
-   *
-   * @internal
-   * @deprecated Don't use outside of Sanity internals
-   * @see {@link RequestHandler}
-   */
-  _requestHandler?: RequestHandler
 }
 
 /** @public */
@@ -270,6 +282,14 @@ export interface InitializedClientConfig extends ClientConfig {
    * The fully initialized stega config, can be used to check if stega is enabled
    */
   stega: InitializedStegaConfig
+  /**
+   * The resolved low-level requester for this client. Always populated by
+   * `createClient` so internal paths (e.g. the asset upload event stream) can
+   * reach the underlying transport.
+   *
+   * @internal
+   */
+  requester: Requester
   /**
    * Default headers to include with all requests
    *
@@ -280,7 +300,14 @@ export interface InitializedClientConfig extends ClientConfig {
 
 /** @public */
 export type AssetMetadataType =
-  'location' | 'exif' | 'image' | 'palette' | 'lqip' | 'blurhash' | 'thumbhash' | 'none'
+  | 'location'
+  | 'exif'
+  | 'image'
+  | 'palette'
+  | 'lqip'
+  | 'blurhash'
+  | 'thumbhash'
+  | 'none'
 
 /** @public */
 export interface UploadClientConfig {
@@ -300,7 +327,10 @@ export interface UploadClientConfig {
   filename?: string
 
   /**
-   * Milliseconds to wait before timing the request out
+   * Milliseconds to wait before timing the request out.
+   *
+   * Unlike other requests, uploads have NO timeout unless one is explicitly
+   * set here — uploads can legitimately be slow, so timing out is opt-in.
    */
   timeout?: number
 
@@ -442,63 +472,56 @@ export interface ErrorProps {
   details: Any
 }
 
-/** @public */
+/**
+ * The internal HTTP request abstraction used by the client. Resolves directly
+ * to the parsed response body as a Promise — middleware-level transport
+ * details (status codes, headers, progress events) are not exposed. The
+ * observable client surface wraps this in an Observable; the promise surface
+ * uses it directly.
+ *
+ * The body is typed as `unknown`; consumers narrow at their own boundary.
+ *
+ * @internal
+ */
 export type HttpRequest = {
-  (options: RequestOptions, requester: Requester): ReturnType<Requester>
+  (options: Any): Promise<unknown>
 }
 
 /**
- * A function that intercepts HTTP requests made by the client.
- *
- * Receives the resolved request options, a `defaultRequester` function that
- * executes the request through the normal pipeline, and a `client` instance
- * without a `_requestHandler` (to avoid recursive interception).
- *
- * The consumer can:
- * - Modify request options before calling `defaultRequester`
- * - Transform the response stream (e.g. via `pipe`)
- * - Skip `defaultRequester` entirely and return a custom Observable
- * - Use `client` to make additional requests (e.g. refresh an auth token on 401)
- *
- * When set via `withConfig()`, the new handler **replaces** (not wraps) the previous one.
- *
- * Note: This only applies to HTTP requests. Real-time listener connections
- * (`client.listen()`) use EventSource and are not intercepted by this handler.
- *
- * @param request - The resolved request options including `url`
- * @param defaultRequester - Executes the request through the normal pipeline
- * @param client - A client instance with the same configuration but without a `_requestHandler`,
- *   useful for making side requests (e.g. token refresh) without triggering the handler recursively
+ * Target URL for a request. Exactly one of `url` or the deprecated `uri` alias
+ * must be given.
  *
  * @internal
- * @deprecated Don't use outside of Sanity internals
  */
-export type RequestHandler = (
-  request: RequestOptions & {url: string},
-  defaultRequester: (options: RequestOptions & {url: string}) => Observable<HttpRequestEvent>,
-  client: SanityClient,
-) => Observable<HttpRequestEvent>
+export type RequestUrlOptions =
+  | {url: string; uri?: never}
+  | {
+      /**
+       * @deprecated Use `url` instead. Support for `uri` will be removed in a future version.
+       */
+      uri: string
+      url?: never
+    }
 
 /** @internal */
-export interface RequestObservableOptions extends Omit<RequestOptions, 'url'> {
-  url?: string
-  uri?: string
-  canUseCdn?: boolean
-  useCdn?: boolean
-  tag?: string
-  returnQuery?: boolean
-  resultSourceMap?: boolean | 'withKeyArraySelector'
-  perspective?: ClientPerspective
-  /**
-   * @beta
-   */
-  variant?: ClientVariant
-  lastLiveEventId?: string
-  cacheMode?: 'noStale'
-}
+export type RequestObservableOptions = RequestUrlOptions &
+  Omit<RequestOptions, 'url'> & {
+    canUseCdn?: boolean
+    useCdn?: boolean
+    tag?: string
+    returnQuery?: boolean
+    resultSourceMap?: boolean | 'withKeyArraySelector'
+    perspective?: ClientPerspective
+    /**
+     * @beta
+     */
+    variant?: ClientVariant
+    lastLiveEventId?: string
+    cacheMode?: 'noStale'
+  }
 
 /** @public */
-export interface ProgressEvent {
+export interface UploadProgressEvent {
   type: 'progress'
   stage: 'upload' | 'download'
   percent: number
@@ -508,18 +531,20 @@ export interface ProgressEvent {
 }
 
 /** @public */
-export interface ResponseEvent<T = unknown> {
+export interface UploadResponseEvent<T = unknown> {
   type: 'response'
   body: T
-  url: string
-  method: string
-  statusCode: number
-  statusMessage?: string
-  headers: Record<string, string>
 }
 
-/** @public */
-export type HttpRequestEvent<T = unknown> = ResponseEvent<T> | ProgressEvent
+/**
+ * Events emitted by `client.assets.upload()` when called via the observable
+ * API. Progress events are best-effort — they're only emitted when the
+ * environment supports tracking upload/download bytes (e.g. browsers via
+ * `XMLHttpRequest`). Other runtimes only emit the terminal `response` event.
+ *
+ * @public
+ */
+export type UploadEvent<T = unknown> = UploadResponseEvent<T> | UploadProgressEvent
 
 /** @internal */
 export interface AuthProvider {
@@ -652,7 +677,9 @@ export type IdentifiedSanityDocumentStub<T extends Record<string, Any> = Record<
 
 /** @internal */
 export type InsertPatch =
-  {before: string; items: Any[]} | {after: string; items: Any[]} | {replace: string; items: Any[]}
+  | {before: string; items: Any[]}
+  | {after: string; items: Any[]}
+  | {replace: string; items: Any[]}
 
 // Note: this is actually incorrect/invalid, but implemented as-is for backwards compatibility
 /** @internal */
@@ -669,7 +696,7 @@ export interface PatchOperations {
 
 /** @public */
 export interface QueryParams {
-  /* eslint-disable @typescript-eslint/no-explicit-any */
+  /* oxlint-disable typescript/no-explicit-any */
   [key: string]: any
   /** @deprecated you're using a fetch option as a GROQ parameter, this is likely a mistake */
   body?: never
@@ -709,7 +736,7 @@ export interface QueryParams {
   lastLiveEventId?: never
   /** @deprecated you're using a fetch option as a GROQ parameter, this is likely a mistake */
   cacheMode?: never
-  /* eslint-enable @typescript-eslint/no-explicit-any */
+  /* oxlint-enable typescript/no-explicit-any */
 }
 
 /**
@@ -722,7 +749,8 @@ export type QueryWithoutParams = Record<string, never> | undefined
 export type MutationSelectionQueryParams = {[key: string]: Any}
 /** @internal */
 export type MutationSelection =
-  {query: string; params?: MutationSelectionQueryParams} | {id: string | string[]}
+  | {query: string; params?: MutationSelectionQueryParams}
+  | {id: string | string[]}
 /** @internal */
 export type PatchSelection = string | string[] | MutationSelection
 /** @internal */
@@ -750,7 +778,10 @@ export type ReleaseAction =
 
 /** @public */
 export type VersionAction =
-  CreateVersionAction | DiscardVersionAction | ReplaceVersionAction | UnpublishVersionAction
+  | CreateVersionAction
+  | DiscardVersionAction
+  | ReplaceVersionAction
+  | UnpublishVersionAction
 
 /** @public */
 export type Action =
@@ -1296,7 +1327,12 @@ export type ResetEvent = {
 
 /** @public */
 export type ListenEvent<R extends Record<string, Any> = Record<string, Any>> =
-  MutationEvent<R> | ReconnectEvent | WelcomeBackEvent | ResetEvent | WelcomeEvent | OpenEvent
+  | MutationEvent<R>
+  | ReconnectEvent
+  | WelcomeBackEvent
+  | ResetEvent
+  | WelcomeEvent
+  | OpenEvent
 
 /** @public */
 export type ListenEventName =
@@ -1476,7 +1512,9 @@ export interface UnfilteredResponseWithoutQuery extends ResponseQueryOptions {
 
 /** @public */
 export type QueryOptions =
-  FilteredResponseQueryOptions | UnfilteredResponseQueryOptions | UnfilteredResponseWithoutQuery
+  | FilteredResponseQueryOptions
+  | UnfilteredResponseQueryOptions
+  | UnfilteredResponseWithoutQuery
 
 /** @public */
 export interface RawQueryResponse<R> {
@@ -1595,11 +1633,10 @@ export interface MultipleActionResult {
 }
 
 /** @internal */
-export interface RawRequestOptions {
-  url?: string
-  uri?: string
+export type RawRequestOptions = RequestUrlOptions & {
   method?: string
   token?: string
+  /** @deprecated has no effect — response parsing is driven by the response `content-type` */
   json?: boolean
   tag?: string
   useGlobalApi?: boolean
@@ -1607,9 +1644,10 @@ export interface RawRequestOptions {
   query?: {[key: string]: string | string[]}
   headers?: {[key: string]: string}
   timeout?: number
-  proxy?: string
   body?: Any
   maxRedirects?: number
+  /** Max retries for this request; `0` disables retries. Overrides the client-level maximum in both directions. */
+  maxRetries?: number
   signal?: AbortSignal
 }
 
@@ -1805,7 +1843,8 @@ export interface ContentSourceMapRemoteDocument extends ContentSourceMapDocument
 
 /** @public */
 export type ContentSourceMapDocuments = (
-  ContentSourceMapDocument | ContentSourceMapRemoteDocument
+  | ContentSourceMapDocument
+  | ContentSourceMapRemoteDocument
 )[]
 
 /** @public */
@@ -1851,7 +1890,11 @@ export interface LiveEventGoAway {
 }
 /** @public */
 export type LiveEvent =
-  LiveEventRestart | LiveEventReconnect | LiveEventMessage | LiveEventWelcome | LiveEventGoAway
+  | LiveEventRestart
+  | LiveEventReconnect
+  | LiveEventMessage
+  | LiveEventWelcome
+  | LiveEventGoAway
 
 /** @public */
 export interface SanityQueries {}

package/src/users/UsersClient.ts

@@ -1,6 +1,6 @@
-import {lastValueFrom, type Observable} from 'rxjs'
+import {type Observable} from 'rxjs'
 
-import {_request} from '../data/dataMethods'
+import {_request, _requestObservable} from '../data/dataMethods'
 import type {ObservableSanityClient, SanityClient} from '../SanityClient'
 import type {CurrentSanityUser, HttpRequest, SanityUser} from '../types'
 
@@ -18,13 +18,11 @@ export class ObservableUsersClient {
    *
    * @param id - User ID of the user to fetch. If `me` is provided, a minimal response including the users role is returned.
    */
-  getById<T extends 'me' | string>(
-    id: T,
-  ): Observable<T extends 'me' ? CurrentSanityUser : SanityUser> {
-    return _request<T extends 'me' ? CurrentSanityUser : SanityUser>(
+  getById<T extends string>(id: T): Observable<T extends 'me' ? CurrentSanityUser : SanityUser> {
+    return _requestObservable<T extends 'me' ? CurrentSanityUser : SanityUser>(
       this.#client,
       this.#httpRequest,
-      {uri: `/users/${id}`},
+      {url: `/users/${id}`},
     )
   }
 }
@@ -43,13 +41,11 @@ export class UsersClient {
    *
    * @param id - User ID of the user to fetch. If `me` is provided, a minimal response including the users role is returned.
    */
-  getById<T extends 'me' | string>(
-    id: T,
-  ): Promise<T extends 'me' ? CurrentSanityUser : SanityUser> {
-    return lastValueFrom(
-      _request<T extends 'me' ? CurrentSanityUser : SanityUser>(this.#client, this.#httpRequest, {
-        uri: `/users/${id}`,
-      }),
+  getById<T extends string>(id: T): Promise<T extends 'me' ? CurrentSanityUser : SanityUser> {
+    return _request<T extends 'me' ? CurrentSanityUser : SanityUser>(
+      this.#client,
+      this.#httpRequest,
+      {url: `/users/${id}`},
     )
   }
 }

package/src/util/shareReplayLatest.ts

@@ -44,7 +44,7 @@ function _shareReplayLatest<T>(config: ShareReplayLatestConfig<T>): MonoTypeOper
     let latest: T | undefined
     let emitted = false
 
-    // eslint-disable-next-line unused-imports/no-unused-vars
+    // oxlint-disable-next-line no-unused-vars
     const {predicate, ...shareConfig} = config
 
     const wrapped = source.pipe(

package/src/warnings.ts

@@ -3,7 +3,7 @@ import {type Any} from './types'
 import {once} from './util/once'
 
 const createWarningPrinter = (message: string[]) =>
-  // eslint-disable-next-line no-console
+  // oxlint-disable-next-line no-console
   once((...args: Any[]) => console.warn(message.join(' '), ...args))
 
 export const printCdnAndWithCredentialsWarning = createWarningPrinter([
@@ -51,6 +51,11 @@ export const printCreateVersionWithBaseIdWarning = createWarningPrinter([
   'You have called `createVersion()` with a defined `document`. The recommended approach is to provide a `baseId` and `releaseId` instead.',
 ])
 
+export const printDeprecatedUriOptionWarning = createWarningPrinter([
+  'The `uri` request option has been renamed to `url`.',
+  'Please update your code to use `url` instead. Support for `uri` will be removed in a future version.',
+])
+
 export const printDeprecatedResourceConfigWarning = createWarningPrinter([
   'The `~experimental_resource` configuration property has been renamed to `resource`.',
   'Please update your client configuration to use `resource` instead. Support for `~experimental_resource` will be removed in a future version.',