@sanity/client 7.26.2 → 8.1.0

package/src/types.ts

@@ -1,17 +1,30 @@
 // deno-lint-ignore-file no-empty-interface
-/* eslint-disable @typescript-eslint/no-empty-object-type */
 
-import type {Requester} from 'get-it'
+import type {FetchFunction, RequestOptions as GetItRequestOptions} 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 `defineRequester(...).observable`.
+ * 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
@@ -33,6 +46,30 @@ export interface RequestOptions {
   signal?: AbortSignal
 }
 
+/**
+ * The fully resolved request passed to a {@link RequestHandler}.
+ *
+ * @public
+ */
+export type RequestHandlerOptions = GetItRequestOptions
+
+/**
+ * Intercepts a client request around the normal HTTP pipeline.
+ *
+ * Call `next(request)` to execute the request. It resolves to the parsed
+ * response body and rejects with the same errors the client normally exposes,
+ * including {@link ClientError} and {@link ServerError}. A handler can modify
+ * the request, retry it by calling `next` again, or return a synthetic body.
+ *
+ * Browser asset uploads and server-sent event connections do not use this handler.
+ *
+ * @public
+ */
+export type RequestHandler = (
+  request: RequestHandlerOptions,
+  next: (request: RequestHandlerOptions) => Promise<unknown>,
+) => Promise<unknown>
+
 /**
  * @public
  * @deprecated – The `r`-prefix is not required, use `string` instead
@@ -45,11 +82,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 +171,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
 
   /**
@@ -137,6 +184,20 @@ export interface ClientConfig {
    */
   requestTagPrefix?: string
 
+  /**
+   * Intercepts requests after the client has resolved their URL, headers, and
+   * transport options. The handler wraps the normal client pipeline, so errors
+   * from `next` are already converted to {@link ClientError} or
+   * {@link ServerError}.
+   *
+   * A handler supplied through `withConfig()` replaces the current handler.
+   * To compose handlers, read the current handler from `client.config()` and
+   * call it from the replacement.
+   *
+   * Browser asset uploads and server-sent event connections are not intercepted.
+   */
+  requestHandler?: RequestHandler
+
   /**
    * Optional default headers to include with all requests
    *
@@ -192,16 +253,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 +295,15 @@ 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}
+   * ID of the blueprints stack that `functions.invoke()` resolves function
+   * names against. Function names are unique within a stack
+   */
+  stackId?: string
+  /**
+   * ID of the organization owning the blueprints stack
    */
-  _requestHandler?: RequestHandler
+  organizationId?: string
 }
 
 /** @public */
@@ -270,6 +330,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 +348,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 +375,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 +520,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, requestHandler?: RequestHandler): 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 +579,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 +725,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 +744,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 +784,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 +797,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 */
@@ -748,9 +824,21 @@ export type ReleaseAction =
   | DeleteReleaseAction
   | ImportReleaseAction
 
+/**
+ * @public
+ * @beta
+ */
+export type VariantDefinitionAction =
+  | CreateVariantDefinitionAction
+  | EditVariantDefinitionAction
+  | DeleteVariantDefinitionAction
+
 /** @public */
 export type VersionAction =
-  CreateVersionAction | DiscardVersionAction | ReplaceVersionAction | UnpublishVersionAction
+  | CreateVersionAction
+  | DiscardVersionAction
+  | ReplaceVersionAction
+  | UnpublishVersionAction
 
 /** @public */
 export type Action =
@@ -763,6 +851,7 @@ export type Action =
   | UnpublishAction
   | VersionAction
   | ReleaseAction
+  | VariantDefinitionAction
 
 /** @public */
 export type ImportReleaseAction =
@@ -920,6 +1009,88 @@ export interface UnpublishVersionAction {
   publishedId: string
 }
 
+/**
+ * Creates a new `system.variant` definition document.
+ *
+ * @public
+ * @beta
+ */
+export interface CreateVariantDefinitionAction {
+  actionType: 'sanity.action.variant.definition.create'
+
+  /**
+   * Name of the variant definition to create, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * Conditions used to select this variant.
+   */
+  conditions?: ClientVariantConditions
+
+  /**
+   * Selection priority. Higher values are preferred when multiple variants
+   * match.
+   *
+   * Defaults to `0`.
+   */
+  priority?: number
+
+  metadata?: Record<string, Any>
+}
+
+/**
+ * Edits an existing variant definition.
+ *
+ * @public
+ * @beta
+ */
+export interface EditVariantDefinitionAction {
+  actionType: 'sanity.action.variant.definition.edit'
+
+  /**
+   * Name of the variant definition to edit, as in `_.variants.{variantName}`.
+   * Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * Patch operations to apply.
+   */
+  patch: PatchOperations
+
+  /**
+   * When set, the action fails unless the current revision of the variant
+   * definition matches this value.
+   */
+  ifRevisionId?: string
+}
+
+/**
+ * Deletes a variant definition.
+ *
+ * Deletion fails if any document holds a strong reference to this variant.
+ *
+ * @public
+ * @beta
+ */
+export interface DeleteVariantDefinitionAction {
+  actionType: 'sanity.action.variant.definition.delete'
+
+  /**
+   * Name of the variant definition to delete, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * When set, the action fails unless the current revision of the variant
+   * definition matches this value.
+   */
+  ifRevisionId?: string
+}
+
 /**
  * Creates a new draft document. The published version of the document must not already exist.
  * If the draft version of the document already exists the action will fail by default, but
@@ -1296,7 +1467,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 +1652,9 @@ export interface UnfilteredResponseWithoutQuery extends ResponseQueryOptions {
 
 /** @public */
 export type QueryOptions =
-  FilteredResponseQueryOptions | UnfilteredResponseQueryOptions | UnfilteredResponseWithoutQuery
+  | FilteredResponseQueryOptions
+  | UnfilteredResponseQueryOptions
+  | UnfilteredResponseWithoutQuery
 
 /** @public */
 export interface RawQueryResponse<R> {
@@ -1595,11 +1773,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 +1784,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 +1983,8 @@ export interface ContentSourceMapRemoteDocument extends ContentSourceMapDocument
 
 /** @public */
 export type ContentSourceMapDocuments = (
-  ContentSourceMapDocument | ContentSourceMapRemoteDocument
+  | ContentSourceMapDocument
+  | ContentSourceMapRemoteDocument
 )[]
 
 /** @public */
@@ -1851,7 +2030,11 @@ export interface LiveEventGoAway {
 }
 /** @public */
 export type LiveEvent =
-  LiveEventRestart | LiveEventReconnect | LiveEventMessage | LiveEventWelcome | LiveEventGoAway
+  | LiveEventRestart
+  | LiveEventReconnect
+  | LiveEventMessage
+  | LiveEventWelcome
+  | LiveEventGoAway
 
 /** @public */
 export interface SanityQueries {}
@@ -1895,6 +2078,7 @@ export type {
   TranslateTarget,
   TranslateTargetInclude,
 } from './agent/actions/translate'
+export type {InvokeFunctionEvent, InvokeFunctionRequest} from './functions/invoke'
 export type {
   ContentSourceMapParsedPath,
   ContentSourceMapParsedPathKeyedSegment,
@@ -2116,3 +2300,44 @@ export interface VideoPlaybackTokens {
 
 /** @public */
 export type MediaLibraryAssetInstanceIdentifier = string | SanityReference
+
+/**
+ * A single tracked version of a Media Library asset - one uploaded instance,
+ * referencing the underlying (Content Lake shaped) asset document it wraps.
+ *
+ * @public
+ */
+export interface MediaLibraryAssetVersion {
+  _key: string
+  _type: 'sanity.asset.version'
+  title?: string
+  instance: SanityReference
+}
+
+/**
+ * The document returned by the Media Library upload endpoint
+ * (`POST /media-libraries/:id/upload`).
+ *
+ * This is _not_ the same shape as {@link SanityAssetDocument} /
+ * {@link SanityImageAssetDocument}: a Media Library asset is a `sanity.asset`
+ * document that tracks one or more uploaded versions, each pointing at its
+ * own underlying Content Lake asset document via `currentVersion`/`versions`.
+ *
+ * Modelled directly on an observed API response. Fields whose full shape has
+ * not been confirmed (`parent`, `rootDirectory`, `aspects`) are typed loosely
+ * on purpose - widen them once their shape is confirmed.
+ *
+ * @public
+ */
+export interface MediaLibraryAssetDocument {
+  _id: string
+  _type: 'sanity.asset'
+  assetType: string
+  title?: string
+  cdnAccessPolicy?: string
+  currentVersion: SanityReference
+  versions: MediaLibraryAssetVersion[]
+  aspects?: Record<string, Any>
+  parent?: SanityReference | null
+  rootDirectory?: Any
+}

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}`},
     )
   }
 }