@sanity/client 7.20.0 → 7.22.0

package/src/http/errors.ts

@@ -64,6 +64,7 @@ export class ClientError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode'] = 400
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
 
   constructor(res: Any, context?: HttpContext) {
@@ -78,6 +79,7 @@ export class ServerError extends Error {
   response: ErrorProps['response']
   statusCode: ErrorProps['statusCode'] = 500
   responseBody: ErrorProps['responseBody']
+  traceId: ErrorProps['traceId']
   details: ErrorProps['details']
 
   constructor(res: Any) {
@@ -93,13 +95,14 @@ function extractErrorProps(res: Any, context?: HttpContext): ErrorProps {
     response: res,
     statusCode: res.statusCode,
     responseBody: stringifyBody(body, res),
+    traceId: extractTraceId(res),
     message: '',
     details: undefined as Any,
   }
 
   // Fall back early if we didn't get a JSON object returned as expected
   if (!isRecord(body)) {
-    props.message = httpErrorMessage(res, body)
+    props.message = `${httpErrorMessage(res, body)}${formatTraceId(props.traceId)}`
     return props
   }
 
@@ -107,18 +110,18 @@ function extractErrorProps(res: Any, context?: HttpContext): ErrorProps {
 
   // API/Boom style errors ({statusCode, error, message})
   if (typeof error === 'string' && typeof body.message === 'string') {
-    props.message = `${error} - ${body.message}`
+    props.message = `${error} - ${body.message}${formatTraceId(props.traceId)}`
     return props
   }
 
   // Content Lake errors with a `error` prop being an object
   if (typeof error !== 'object' || error === null) {
     if (typeof error === 'string') {
-      props.message = error
+      props.message = `${error}${formatTraceId(props.traceId)}`
     } else if (typeof body.message === 'string') {
-      props.message = body.message
+      props.message = `${body.message}${formatTraceId(props.traceId)}`
     } else {
-      props.message = httpErrorMessage(res, body)
+      props.message = `${httpErrorMessage(res, body)}${formatTraceId(props.traceId)}`
     }
     return props
   }
@@ -134,7 +137,7 @@ function extractErrorProps(res: Any, context?: HttpContext): ErrorProps {
     if (allItems.length > MAX_ITEMS_IN_ERROR_MESSAGE) {
       itemsStr += `\n...and ${allItems.length - MAX_ITEMS_IN_ERROR_MESSAGE} more`
     }
-    props.message = `${error.description}${itemsStr}`
+    props.message = `${error.description}${formatTraceId(props.traceId)}${itemsStr}`
     props.details = body.error
     return props
   }
@@ -142,20 +145,20 @@ function extractErrorProps(res: Any, context?: HttpContext): ErrorProps {
   // Query parse errors
   if (isQueryParseError(error)) {
     const tag = context?.options?.query?.tag
-    props.message = formatQueryParseError(error, tag)
+    props.message = formatQueryParseError(error, tag, props.traceId)
     props.details = body.error
     return props
   }
 
   if ('description' in error && typeof error.description === 'string') {
     // Query/database errors ({error: {description, other, arb, props}})
-    props.message = error.description
+    props.message = `${error.description}${formatTraceId(props.traceId)}`
     props.details = error
     return props
   }
 
   // Other, more arbitrary errors
-  props.message = httpErrorMessage(res, body)
+  props.message = `${httpErrorMessage(res, body)}${formatTraceId(props.traceId)}`
   return props
 }
 
@@ -196,17 +199,22 @@ export function isQueryParseError(error: object): error is QueryParseError {
  * @returns A formatted error message string.
  * @public
  */
-export function formatQueryParseError(error: QueryParseError, tag?: string | null) {
+export function formatQueryParseError(
+  error: QueryParseError,
+  tag?: string | null,
+  traceId?: string,
+) {
   const {query, start, end, description} = error
+  const withTraceId = traceId ? `\n(traceId: ${traceId})` : ''
 
   if (!query || typeof start === 'undefined') {
-    return `GROQ query parse error: ${description}`
+    return `GROQ query parse error: ${description}${withTraceId}`
   }
 
   const withTag = tag ? `\n\nTag: ${tag}` : ''
   const framed = codeFrame(query, {start, end}, description)
 
-  return `GROQ query parse error:\n${framed}${withTag}`
+  return `GROQ query parse error:\n${framed}${withTag}${withTraceId}`
 }
 
 function httpErrorMessage(res: Any, body: unknown) {
@@ -215,12 +223,33 @@ function httpErrorMessage(res: Any, body: unknown) {
   return `${res.method}-request to ${res.url} resulted in HTTP ${res.statusCode}${statusMessage}${details}`
 }
 
+/**
+ * Extract the traceId from the traceparent header on the response.
+ *
+ * The traceparent is on the format [version]-[traceId]-[parentId]-[traceFlags], but
+ * when debugging end-user issues it's the traceId we need to be able to get hold of
+ * the relevant traces.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ * @returns The traceId for HTTP response
+ */
+function extractTraceId(res: Any): string | undefined {
+  const traceparent = res?.headers?.['traceparent']
+  if (!traceparent) return
+
+  return traceparent.split('-')[1]
+}
+
 function stringifyBody(body: Any, res: Any) {
   const contentType = (res.headers['content-type'] || '').toLowerCase()
   const isJson = contentType.indexOf('application/json') !== -1
   return isJson ? JSON.stringify(body, null, 2) : body
 }
 
+function formatTraceId(traceId: string | undefined): string {
+  return traceId ? ` (traceId: ${traceId})` : ''
+}
+
 function sliceWithEllipsis(str: string, max: number) {
   return str.length > max ? `${str.slice(0, max)}…` : str
 }

package/src/types.ts

@@ -2,7 +2,9 @@
 /* eslint-disable @typescript-eslint/no-empty-object-type */
 
 import type {Requester} from 'get-it'
+import type {Observable} from 'rxjs'
 
+import type {SanityClient} from './SanityClient'
 import type {InitializedStegaConfig, StegaConfig} from './stega/types'
 
 /**
@@ -203,6 +205,33 @@ 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 */
@@ -404,6 +433,7 @@ export interface ErrorProps {
   response: Any
   statusCode: number
   responseBody: Any
+  traceId?: string
   details: Any
 }
 
@@ -412,6 +442,38 @@ export type HttpRequest = {
   (options: RequestOptions, requester: Requester): ReturnType<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 type RequestHandler = (
+  request: RequestOptions & {url: string},
+  defaultRequester: (options: RequestOptions & {url: string}) => Observable<HttpRequestEvent>,
+  client: SanityClient,
+) => Observable<HttpRequestEvent>
+
 /** @internal */
 export interface RequestObservableOptions extends Omit<RequestOptions, 'url'> {
   url?: string

package/umd/sanityClient.js

@@ -2059,6 +2059,7 @@
     response;
     statusCode = 400;
     responseBody;
+    traceId;
     details;
     constructor(res, context) {
       const props = extractErrorProps(res, context);
@@ -2069,6 +2070,7 @@
     response;
     statusCode = 500;
     responseBody;
+    traceId;
     details;
     constructor(res) {
       const props = extractErrorProps(res);
@@ -2080,29 +2082,30 @@
       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";
@@ -2113,23 +2116,32 @@
   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;
   }
@@ -3425,7 +3437,8 @@ ${selectionOpts}`);
      */
     events({
       includeDrafts = false,
-      tag: _tag
+      tag: _tag,
+      waitFor
     } = {}) {
       const {
         projectId: projectId2,
@@ -3444,7 +3457,7 @@ ${selectionOpts}`);
           "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, false)), 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 = true), (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);
@@ -4342,13 +4355,22 @@ ${selectionOpts}`);
      * 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)
@@ -4358,7 +4380,7 @@ ${selectionOpts}`);
      * 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)
@@ -4376,7 +4398,7 @@ ${selectionOpts}`);
      */
     withConfig(newConfig) {
       const thisConfig = this.config();
-      return new ObservableSanityClient(this.#httpRequest, {
+      return new ObservableSanityClient(this.#originalHttpRequest, {
         ...thisConfig,
         ...newConfig,
         stega: {
@@ -4606,13 +4628,22 @@ ${selectionOpts}`);
      * 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)
@@ -4622,7 +4653,7 @@ ${selectionOpts}`);
      * 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)
@@ -4640,7 +4671,7 @@ ${selectionOpts}`);
      */
     withConfig(newConfig) {
       const thisConfig = this.config();
-      return new SanityClient(this.#httpRequest, {
+      return new SanityClient(this.#originalHttpRequest, {
         ...thisConfig,
         ...newConfig,
         stega: {