@sanity/client 7.20.0 → 7.22.0

package/dist/stega.browser.d.cts

@@ -804,6 +804,32 @@ export declare 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
 }
 
 declare type ClientConfigResource =
@@ -829,6 +855,7 @@ export declare class ClientError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any, context?: HttpContext)
 }
@@ -1489,6 +1516,7 @@ export declare interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -1688,7 +1716,11 @@ export declare type FitMode = 'preserve' | 'stretch' | 'crop' | 'smartcrop' | 'p
  * @returns A formatted error message string.
  * @public
  */
-export declare function formatQueryParseError(error: QueryParseError, tag?: string | null): string
+export declare function formatQueryParseError(
+  error: QueryParseError,
+  tag?: string | null,
+  traceId?: string,
+): string
 
 /** @beta */
 declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
@@ -2318,6 +2350,7 @@ export declare class LiveClient {
   events({
     includeDrafts,
     tag: _tag,
+    waitFor,
   }?: {
     includeDrafts?: boolean
     /**
@@ -2326,6 +2359,11 @@ export declare class LiveClient {
      * @defaultValue `undefined`
      */
     tag?: string
+    /**
+     * Delays events until after a Sanity Function has processed them and called the callback endpoint.
+     * When omitted, events are delivered immediately.
+     */
+    waitFor?: 'function'
   }): Observable<LiveEvent>
 }
 
@@ -4951,6 +4989,44 @@ export declare interface ReplaceVersionAction {
  */
 export declare const requester: Requester
 
+/**
+ * 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
+ *
+ * @internal
+ * @deprecated Don't use outside of Sanity internals
+ */
+export declare type RequestHandler = (
+  request: RequestOptions & {
+    url: string
+  },
+  defaultRequester: (
+    options: RequestOptions & {
+      url: string
+    },
+  ) => Observable<HttpRequestEvent>,
+  client: SanityClient,
+) => Observable<HttpRequestEvent>
+
 /** @internal */
 export declare interface RequestObservableOptions extends Omit<RequestOptions, 'url'> {
   url?: string
@@ -5991,6 +6067,7 @@ export declare class ServerError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any)
 }

package/dist/stega.browser.d.ts

@@ -804,6 +804,32 @@ export declare 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
 }
 
 declare type ClientConfigResource =
@@ -829,6 +855,7 @@ export declare class ClientError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any, context?: HttpContext)
 }
@@ -1489,6 +1516,7 @@ export declare interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -1688,7 +1716,11 @@ export declare type FitMode = 'preserve' | 'stretch' | 'crop' | 'smartcrop' | 'p
  * @returns A formatted error message string.
  * @public
  */
-export declare function formatQueryParseError(error: QueryParseError, tag?: string | null): string
+export declare function formatQueryParseError(
+  error: QueryParseError,
+  tag?: string | null,
+  traceId?: string,
+): string
 
 /** @beta */
 declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
@@ -2318,6 +2350,7 @@ export declare class LiveClient {
   events({
     includeDrafts,
     tag: _tag,
+    waitFor,
   }?: {
     includeDrafts?: boolean
     /**
@@ -2326,6 +2359,11 @@ export declare class LiveClient {
      * @defaultValue `undefined`
      */
     tag?: string
+    /**
+     * Delays events until after a Sanity Function has processed them and called the callback endpoint.
+     * When omitted, events are delivered immediately.
+     */
+    waitFor?: 'function'
   }): Observable<LiveEvent>
 }
 
@@ -4951,6 +4989,44 @@ export declare interface ReplaceVersionAction {
  */
 export declare const requester: Requester
 
+/**
+ * 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
+ *
+ * @internal
+ * @deprecated Don't use outside of Sanity internals
+ */
+export declare type RequestHandler = (
+  request: RequestOptions & {
+    url: string
+  },
+  defaultRequester: (
+    options: RequestOptions & {
+      url: string
+    },
+  ) => Observable<HttpRequestEvent>,
+  client: SanityClient,
+) => Observable<HttpRequestEvent>
+
 /** @internal */
 export declare interface RequestObservableOptions extends Omit<RequestOptions, 'url'> {
   url?: string
@@ -5991,6 +6067,7 @@ export declare class ServerError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any)
 }

package/dist/stega.d.cts

@@ -804,6 +804,32 @@ export declare 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
 }
 
 declare type ClientConfigResource =
@@ -829,6 +855,7 @@ export declare class ClientError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any, context?: HttpContext)
 }
@@ -1489,6 +1516,7 @@ export declare interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -1688,7 +1716,11 @@ export declare type FitMode = 'preserve' | 'stretch' | 'crop' | 'smartcrop' | 'p
  * @returns A formatted error message string.
  * @public
  */
-export declare function formatQueryParseError(error: QueryParseError, tag?: string | null): string
+export declare function formatQueryParseError(
+  error: QueryParseError,
+  tag?: string | null,
+  traceId?: string,
+): string
 
 /** @beta */
 declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
@@ -2318,6 +2350,7 @@ export declare class LiveClient {
   events({
     includeDrafts,
     tag: _tag,
+    waitFor,
   }?: {
     includeDrafts?: boolean
     /**
@@ -2326,6 +2359,11 @@ export declare class LiveClient {
      * @defaultValue `undefined`
      */
     tag?: string
+    /**
+     * Delays events until after a Sanity Function has processed them and called the callback endpoint.
+     * When omitted, events are delivered immediately.
+     */
+    waitFor?: 'function'
   }): Observable<LiveEvent>
 }
 
@@ -4951,6 +4989,44 @@ export declare interface ReplaceVersionAction {
  */
 export declare const requester: Requester
 
+/**
+ * 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
+ *
+ * @internal
+ * @deprecated Don't use outside of Sanity internals
+ */
+export declare type RequestHandler = (
+  request: RequestOptions & {
+    url: string
+  },
+  defaultRequester: (
+    options: RequestOptions & {
+      url: string
+    },
+  ) => Observable<HttpRequestEvent>,
+  client: SanityClient,
+) => Observable<HttpRequestEvent>
+
 /** @internal */
 export declare interface RequestObservableOptions extends Omit<RequestOptions, 'url'> {
   url?: string
@@ -5991,6 +6067,7 @@ export declare class ServerError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any)
 }

package/dist/stega.d.ts

@@ -804,6 +804,32 @@ export declare 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
 }
 
 declare type ClientConfigResource =
@@ -829,6 +855,7 @@ export declare class ClientError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any, context?: HttpContext)
 }
@@ -1489,6 +1516,7 @@ export declare interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -1688,7 +1716,11 @@ export declare type FitMode = 'preserve' | 'stretch' | 'crop' | 'smartcrop' | 'p
  * @returns A formatted error message string.
  * @public
  */
-export declare function formatQueryParseError(error: QueryParseError, tag?: string | null): string
+export declare function formatQueryParseError(
+  error: QueryParseError,
+  tag?: string | null,
+  traceId?: string,
+): string
 
 /** @beta */
 declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
@@ -2318,6 +2350,7 @@ export declare class LiveClient {
   events({
     includeDrafts,
     tag: _tag,
+    waitFor,
   }?: {
     includeDrafts?: boolean
     /**
@@ -2326,6 +2359,11 @@ export declare class LiveClient {
      * @defaultValue `undefined`
      */
     tag?: string
+    /**
+     * Delays events until after a Sanity Function has processed them and called the callback endpoint.
+     * When omitted, events are delivered immediately.
+     */
+    waitFor?: 'function'
   }): Observable<LiveEvent>
 }
 
@@ -4951,6 +4989,44 @@ export declare interface ReplaceVersionAction {
  */
 export declare const requester: Requester
 
+/**
+ * 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
+ *
+ * @internal
+ * @deprecated Don't use outside of Sanity internals
+ */
+export declare type RequestHandler = (
+  request: RequestOptions & {
+    url: string
+  },
+  defaultRequester: (
+    options: RequestOptions & {
+      url: string
+    },
+  ) => Observable<HttpRequestEvent>,
+  client: SanityClient,
+) => Observable<HttpRequestEvent>
+
 /** @internal */
 export declare interface RequestObservableOptions extends Omit<RequestOptions, 'url'> {
   url?: string
@@ -5991,6 +6067,7 @@ export declare class ServerError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
   constructor(res: Any)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "7.20.0",
+  "version": "7.22.0",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -130,7 +130,7 @@
   },
   "dependencies": {
     "@sanity/eventsource": "^5.0.2",
-    "get-it": "^8.7.0",
+    "get-it": "^8.7.2",
     "nanoid": "^3.3.11",
     "rxjs": "^7.0.0"
   },

package/src/SanityClient.ts

@@ -43,6 +43,7 @@ import type {
   RawQuerylessQueryResponse,
   RawQueryResponse,
   RawRequestOptions,
+  RequestOptions,
   SanityDocument,
   SanityDocumentStub,
   SingleActionResult,
@@ -87,6 +88,7 @@ export class ObservableSanityClient {
    * Private properties
    */
   #clientConfig: InitializedClientConfig
+  #originalHttpRequest: HttpRequest
   #httpRequest: HttpRequest
 
   /**
@@ -97,7 +99,22 @@ export class ObservableSanityClient {
   constructor(httpRequest: HttpRequest, config: ClientConfig = defaultConfig) {
     this.config(config)
 
-    this.#httpRequest = httpRequest
+    this.#originalHttpRequest = httpRequest
+    const requestHandler = config._requestHandler
+
+    this.#httpRequest = requestHandler
+      ? (() => {
+          let bareClient: SanityClient | undefined
+          const wrapped: HttpRequest = (options, requester) => {
+            const opts = options as RequestOptions & {url: string}
+            if (!bareClient) {
+              bareClient = new SanityClient(httpRequest, {...config, _requestHandler: undefined})
+            }
+            return requestHandler(opts, (o) => httpRequest(o, requester), bareClient)
+          }
+          return wrapped
+        })()
+      : httpRequest
 
     this.assets = new ObservableAssetsClient(this, this.#httpRequest)
     this.datasets = new ObservableDatasetsClient(this, this.#httpRequest)
@@ -117,7 +134,7 @@ export class ObservableSanityClient {
    * Clone the client - returns a new instance
    */
   clone(): ObservableSanityClient {
-    return new ObservableSanityClient(this.#httpRequest, this.config())
+    return new ObservableSanityClient(this.#originalHttpRequest, this.config())
   }
 
   /**
@@ -150,7 +167,7 @@ export class ObservableSanityClient {
    */
   withConfig(newConfig?: Partial<ClientConfig>): ObservableSanityClient {
     const thisConfig = this.config()
-    return new ObservableSanityClient(this.#httpRequest, {
+    return new ObservableSanityClient(this.#originalHttpRequest, {
       ...thisConfig,
       ...newConfig,
       stega: {
@@ -1128,6 +1145,7 @@ export class SanityClient {
    * Private properties
    */
   #clientConfig: InitializedClientConfig
+  #originalHttpRequest: HttpRequest
   #httpRequest: HttpRequest
 
   /**
@@ -1138,7 +1156,21 @@ export class SanityClient {
   constructor(httpRequest: HttpRequest, config: ClientConfig = defaultConfig) {
     this.config(config)
 
-    this.#httpRequest = httpRequest
+    this.#originalHttpRequest = httpRequest
+    const requestHandler = config._requestHandler
+    this.#httpRequest = requestHandler
+      ? (() => {
+          let bareClient: SanityClient | undefined
+          const wrapped: HttpRequest = (options, requester) => {
+            const opts = options as RequestOptions & {url: string}
+            if (!bareClient) {
+              bareClient = new SanityClient(httpRequest, {...config, _requestHandler: undefined})
+            }
+            return requestHandler(opts, (o) => httpRequest(o, requester), bareClient)
+          }
+          return wrapped
+        })()
+      : httpRequest
 
     this.assets = new AssetsClient(this, this.#httpRequest)
     this.datasets = new DatasetsClient(this, this.#httpRequest)
@@ -1160,7 +1192,7 @@ export class SanityClient {
    * Clone the client - returns a new instance
    */
   clone(): SanityClient {
-    return new SanityClient(this.#httpRequest, this.config())
+    return new SanityClient(this.#originalHttpRequest, this.config())
   }
 
   /**
@@ -1197,7 +1229,7 @@ export class SanityClient {
    */
   withConfig(newConfig?: Partial<ClientConfig>): SanityClient {
     const thisConfig = this.config()
-    return new SanityClient(this.#httpRequest, {
+    return new SanityClient(this.#originalHttpRequest, {
       ...thisConfig,
       ...newConfig,
       stega: {

package/src/data/live.ts

@@ -35,6 +35,7 @@ export class LiveClient {
   events({
     includeDrafts = false,
     tag: _tag,
+    waitFor,
   }: {
     includeDrafts?: boolean
     /**
@@ -43,6 +44,11 @@ export class LiveClient {
      * @defaultValue `undefined`
      */
     tag?: string
+    /**
+     * Delays events until after a Sanity Function has processed them and called the callback endpoint.
+     * When omitted, events are delivered immediately.
+     */
+    waitFor?: 'function'
   } = {}): Observable<LiveEvent> {
     const {
       projectId,
@@ -74,6 +80,9 @@ export class LiveClient {
     if (includeDrafts) {
       url.searchParams.set('includeDrafts', 'true')
     }
+    if (waitFor) {
+      url.searchParams.set('waitFor', waitFor)
+    }
     const esOptions: EventSourceInit & {headers?: Record<string, string>} = {}
     if (includeDrafts && withCredentials) {
       esOptions.withCredentials = true