@sanity/client 7.20.0 → 7.22.0

package/dist/index.browser.d.cts

@@ -810,6 +810,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 =
@@ -835,6 +861,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)
 }
@@ -1391,6 +1418,7 @@ export declare interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -1541,7 +1569,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>> = (
@@ -2161,6 +2193,7 @@ export declare class LiveClient {
   events({
     includeDrafts,
     tag: _tag,
+    waitFor,
   }?: {
     includeDrafts?: boolean
     /**
@@ -2169,6 +2202,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>
 }
 
@@ -4778,6 +4816,44 @@ export declare interface ReplaceVersionAction {
 /** @public */
 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
@@ -5809,6 +5885,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/index.browser.d.ts

@@ -810,6 +810,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 =
@@ -835,6 +861,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)
 }
@@ -1391,6 +1418,7 @@ export declare interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -1541,7 +1569,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>> = (
@@ -2161,6 +2193,7 @@ export declare class LiveClient {
   events({
     includeDrafts,
     tag: _tag,
+    waitFor,
   }?: {
     includeDrafts?: boolean
     /**
@@ -2169,6 +2202,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>
 }
 
@@ -4778,6 +4816,44 @@ export declare interface ReplaceVersionAction {
 /** @public */
 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
@@ -5809,6 +5885,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/index.browser.js

@@ -85,6 +85,7 @@ class ClientError extends Error {
   response;
   statusCode = 400;
   responseBody;
+  traceId;
   details;
   constructor(res, context) {
     const props = extractErrorProps(res, context);
@@ -95,6 +96,7 @@ class ServerError extends Error {
   response;
   statusCode = 500;
   responseBody;
+  traceId;
   details;
   constructor(res) {
     const props = extractErrorProps(res);
@@ -106,29 +108,30 @@ function extractErrorProps(res, context) {
     response: res,
     statusCode: res.statusCode,
     responseBody: stringifyBody(body, res),
+    traceId: extractTraceId(res),
     message: "",
     details: void 0
   };
   if (!isRecord(body))
-    return props.message = httpErrorMessage(res, body), props;
+    return props.message = `${httpErrorMessage(res, body)}${formatTraceId(props.traceId)}`, props;
   const error = body.error;
   if (typeof error == "string" && typeof body.message == "string")
-    return props.message = `${error} - ${body.message}`, props;
+    return props.message = `${error} - ${body.message}${formatTraceId(props.traceId)}`, props;
   if (typeof error != "object" || error === null)
-    return typeof error == "string" ? props.message = error : typeof body.message == "string" ? props.message = body.message : props.message = httpErrorMessage(res, body), props;
+    return typeof error == "string" ? props.message = `${error}${formatTraceId(props.traceId)}` : typeof body.message == "string" ? props.message = `${body.message}${formatTraceId(props.traceId)}` : props.message = `${httpErrorMessage(res, body)}${formatTraceId(props.traceId)}`, props;
   if (isMutationError(error) || isActionError(error)) {
     const allItems = error.items || [], items = allItems.slice(0, MAX_ITEMS_IN_ERROR_MESSAGE).map((item) => item.error?.description).filter(Boolean);
     let itemsStr = items.length ? `:
 - ${items.join(`
 - `)}` : "";
     return allItems.length > MAX_ITEMS_IN_ERROR_MESSAGE && (itemsStr += `
-...and ${allItems.length - MAX_ITEMS_IN_ERROR_MESSAGE} more`), props.message = `${error.description}${itemsStr}`, props.details = body.error, props;
+...and ${allItems.length - MAX_ITEMS_IN_ERROR_MESSAGE} more`), props.message = `${error.description}${formatTraceId(props.traceId)}${itemsStr}`, props.details = body.error, props;
   }
   if (isQueryParseError(error)) {
     const tag = context?.options?.query?.tag;
-    return props.message = formatQueryParseError(error, tag), props.details = body.error, props;
+    return props.message = formatQueryParseError(error, tag, props.traceId), props.details = body.error, props;
   }
-  return "description" in error && typeof error.description == "string" ? (props.message = error.description, props.details = error, props) : (props.message = httpErrorMessage(res, body), props);
+  return "description" in error && typeof error.description == "string" ? (props.message = `${error.description}${formatTraceId(props.traceId)}`, props.details = error, props) : (props.message = `${httpErrorMessage(res, body)}${formatTraceId(props.traceId)}`, props);
 }
 function isMutationError(error) {
   return "type" in error && error.type === "mutationError" && "description" in error && typeof error.description == "string";
@@ -139,23 +142,32 @@ function isActionError(error) {
 function isQueryParseError(error) {
   return isRecord(error) && error.type === "queryParseError" && typeof error.query == "string" && typeof error.start == "number" && typeof error.end == "number";
 }
-function formatQueryParseError(error, tag) {
-  const { query, start, end, description } = error;
+function formatQueryParseError(error, tag, traceId) {
+  const { query, start, end, description } = error, withTraceId = traceId ? `
+(traceId: ${traceId})` : "";
   if (!query || typeof start > "u")
-    return `GROQ query parse error: ${description}`;
+    return `GROQ query parse error: ${description}${withTraceId}`;
   const withTag = tag ? `
 
 Tag: ${tag}` : "";
   return `GROQ query parse error:
-${codeFrame(query, { start, end }, description)}${withTag}`;
+${codeFrame(query, { start, end }, description)}${withTag}${withTraceId}`;
 }
 function httpErrorMessage(res, body) {
   const details = typeof body == "string" ? ` (${sliceWithEllipsis(body, 100)})` : "", statusMessage = res.statusMessage ? ` ${res.statusMessage}` : "";
   return `${res.method}-request to ${res.url} resulted in HTTP ${res.statusCode}${statusMessage}${details}`;
 }
+function extractTraceId(res) {
+  const traceparent = res?.headers?.traceparent;
+  if (traceparent)
+    return traceparent.split("-")[1];
+}
 function stringifyBody(body, res) {
   return (res.headers["content-type"] || "").toLowerCase().indexOf("application/json") !== -1 ? JSON.stringify(body, null, 2) : body;
 }
+function formatTraceId(traceId) {
+  return traceId ? ` (traceId: ${traceId})` : "";
+}
 function sliceWithEllipsis(str, max) {
   return str.length > max ? `${str.slice(0, max)}\u2026` : str;
 }
@@ -1451,7 +1463,8 @@ class LiveClient {
    */
   events({
     includeDrafts = !1,
-    tag: _tag
+    tag: _tag,
+    waitFor
   } = {}) {
     const {
       projectId: projectId2,
@@ -1470,7 +1483,7 @@ class LiveClient {
         "The live events API requires a token or withCredentials when 'includeDrafts: true'. Please update your client configuration. The token should have the lowest possible access role."
       );
     const path = _getDataUrl(this.#client, "live/events"), url = new URL(this.#client.getUrl(path, !1)), tag = _tag && requestTagPrefix ? [requestTagPrefix, _tag].join(".") : _tag;
-    tag && url.searchParams.set("tag", tag), includeDrafts && url.searchParams.set("includeDrafts", "true");
+    tag && url.searchParams.set("tag", tag), includeDrafts && url.searchParams.set("includeDrafts", "true"), waitFor && url.searchParams.set("waitFor", waitFor);
     const esOptions = {};
     includeDrafts && withCredentials && (esOptions.withCredentials = !0), (includeDrafts && token || configHeaders) && (esOptions.headers = {}, includeDrafts && token && (esOptions.headers.Authorization = `Bearer ${token}`), configHeaders && Object.assign(esOptions.headers, configHeaders));
     const key = `${url.href}::${JSON.stringify(esOptions)}`, existing = eventsCache.get(key);
@@ -2368,13 +2381,22 @@ class ObservableSanityClient {
    * Private properties
    */
   #clientConfig;
+  #originalHttpRequest;
   #httpRequest;
   /**
    * Instance properties
    */
   listen = _listen;
   constructor(httpRequest, config = defaultConfig) {
-    this.config(config), this.#httpRequest = httpRequest, this.assets = new ObservableAssetsClient(this, this.#httpRequest), this.datasets = new ObservableDatasetsClient(this, this.#httpRequest), this.live = new LiveClient(this), this.mediaLibrary = {
+    this.config(config), this.#originalHttpRequest = httpRequest;
+    const requestHandler = config._requestHandler;
+    this.#httpRequest = requestHandler ? /* @__PURE__ */ (() => {
+      let bareClient;
+      return (options, requester2) => {
+        const opts = options;
+        return bareClient || (bareClient = new SanityClient(httpRequest, { ...config, _requestHandler: void 0 })), requestHandler(opts, (o) => httpRequest(o, requester2), bareClient);
+      };
+    })() : httpRequest, this.assets = new ObservableAssetsClient(this, this.#httpRequest), this.datasets = new ObservableDatasetsClient(this, this.#httpRequest), this.live = new LiveClient(this), this.mediaLibrary = {
       video: new ObservableMediaLibraryVideoClient(this, this.#httpRequest)
     }, this.projects = new ObservableProjectsClient(this, this.#httpRequest), this.users = new ObservableUsersClient(this, this.#httpRequest), this.agent = {
       action: new ObservableAgentsActionClient(this, this.#httpRequest)
@@ -2384,7 +2406,7 @@ class ObservableSanityClient {
    * Clone the client - returns a new instance
    */
   clone() {
-    return new ObservableSanityClient(this.#httpRequest, this.config());
+    return new ObservableSanityClient(this.#originalHttpRequest, this.config());
   }
   config(newConfig) {
     if (newConfig === void 0)
@@ -2402,7 +2424,7 @@ class ObservableSanityClient {
    */
   withConfig(newConfig) {
     const thisConfig = this.config();
-    return new ObservableSanityClient(this.#httpRequest, {
+    return new ObservableSanityClient(this.#originalHttpRequest, {
       ...thisConfig,
       ...newConfig,
       stega: {
@@ -2632,13 +2654,22 @@ class SanityClient {
    * Private properties
    */
   #clientConfig;
+  #originalHttpRequest;
   #httpRequest;
   /**
    * Instance properties
    */
   listen = _listen;
   constructor(httpRequest, config = defaultConfig) {
-    this.config(config), this.#httpRequest = httpRequest, this.assets = new AssetsClient(this, this.#httpRequest), this.datasets = new DatasetsClient(this, this.#httpRequest), this.live = new LiveClient(this), this.mediaLibrary = {
+    this.config(config), this.#originalHttpRequest = httpRequest;
+    const requestHandler = config._requestHandler;
+    this.#httpRequest = requestHandler ? /* @__PURE__ */ (() => {
+      let bareClient;
+      return (options, requester2) => {
+        const opts = options;
+        return bareClient || (bareClient = new SanityClient(httpRequest, { ...config, _requestHandler: void 0 })), requestHandler(opts, (o) => httpRequest(o, requester2), bareClient);
+      };
+    })() : httpRequest, this.assets = new AssetsClient(this, this.#httpRequest), this.datasets = new DatasetsClient(this, this.#httpRequest), this.live = new LiveClient(this), this.mediaLibrary = {
       video: new MediaLibraryVideoClient(this, this.#httpRequest)
     }, this.projects = new ProjectsClient(this, this.#httpRequest), this.users = new UsersClient(this, this.#httpRequest), this.agent = {
       action: new AgentActionsClient(this, this.#httpRequest)
@@ -2648,7 +2679,7 @@ class SanityClient {
    * Clone the client - returns a new instance
    */
   clone() {
-    return new SanityClient(this.#httpRequest, this.config());
+    return new SanityClient(this.#originalHttpRequest, this.config());
   }
   config(newConfig) {
     if (newConfig === void 0)
@@ -2666,7 +2697,7 @@ class SanityClient {
    */
   withConfig(newConfig) {
     const thisConfig = this.config();
-    return new SanityClient(this.#httpRequest, {
+    return new SanityClient(this.#originalHttpRequest, {
       ...thisConfig,
       ...newConfig,
       stega: {