@sanity/client 7.2.2 → 7.4.0

package/src/data/eventsource.ts

@@ -1,5 +1,6 @@
 import {defer, isObservable, mergeMap, Observable, of} from 'rxjs'
 
+import {formatQueryParseError, isQueryParseError} from '../http/errors'
 import {type Any} from '../types'
 
 /**
@@ -169,8 +170,10 @@ function connectWithESInstance<EventTypeName extends string>(
       }
       if (message.type === 'channelError') {
         // An error occurred. This is different from a network-level error (which will be emitted as 'error').
-        // Possible causes are things such as malformed filters, non-existant datasets or similar.
-        observer.error(new ChannelError(extractErrorMessage(event?.data), event.data))
+        // Possible causes are things such as malformed filters, non-existant datasets
+        // or similar.
+        const tag = new URL(es.url).searchParams.get('tag')
+        observer.error(new ChannelError(extractErrorMessage(event?.data, tag), event.data))
         return
       }
       if (message.type === 'disconnect') {
@@ -235,16 +238,22 @@ function parseEvent(
   }
 }
 
-function extractErrorMessage(err: Any) {
-  if (!err.error) {
+function extractErrorMessage(err: Any, tag?: string | null) {
+  const error = err.error
+
+  if (!error) {
     return err.message || 'Unknown listener error'
   }
 
-  if (err.error.description) {
-    return err.error.description
+  if (isQueryParseError(error)) {
+    return formatQueryParseError(error, tag)
+  }
+
+  if (error.description) {
+    return error.description
   }
 
-  return typeof err.error === 'string' ? err.error : JSON.stringify(err.error, null, 2)
+  return typeof error === 'string' ? error : JSON.stringify(error, null, 2)
 }
 
 function isEmptyObject(data: object) {

package/src/data/listen.ts

@@ -70,7 +70,7 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
   params?: ListenParams,
   opts: ListenOptions = {},
 ): Observable<MutationEvent<R> | ListenEvent<R>> {
-  const {url, token, withCredentials, requestTagPrefix} = this.config()
+  const {url, token, withCredentials, requestTagPrefix, headers: configHeaders} = this.config()
   const tag = opts.tag && requestTagPrefix ? [requestTagPrefix, opts.tag].join('.') : opts.tag
   const options = {...defaults(opts, defaultOptions), tag}
   const listenOpts = pick(options, possibleOptions)
@@ -88,9 +88,15 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
     esOptions.withCredentials = true
   }
 
-  if (token) {
-    esOptions.headers = {
-      Authorization: `Bearer ${token}`,
+  if (token || configHeaders) {
+    esOptions.headers = {}
+
+    if (token) {
+      esOptions.headers.Authorization = `Bearer ${token}`
+    }
+
+    if (configHeaders) {
+      Object.assign(esOptions.headers, configHeaders)
     }
   }
 

package/src/data/live.ts

@@ -52,6 +52,7 @@ export class LiveClient {
       token,
       withCredentials,
       requestTagPrefix,
+      headers: configHeaders,
     } = this.#client.config()
     const apiVersion = _apiVersion.replace(/^v/, '')
     if (apiVersion !== 'X' && apiVersion < requiredApiVersion) {
@@ -76,15 +77,22 @@ export class LiveClient {
       url.searchParams.set('includeDrafts', 'true')
     }
     const esOptions: EventSourceInit & {headers?: Record<string, string>} = {}
-    if (includeDrafts && token) {
-      esOptions.headers = {
-        Authorization: `Bearer ${token}`,
-      }
-    }
     if (includeDrafts && withCredentials) {
       esOptions.withCredentials = true
     }
 
+    if ((includeDrafts && token) || configHeaders) {
+      esOptions.headers = {}
+
+      if (includeDrafts && token) {
+        esOptions.headers.Authorization = `Bearer ${token}`
+      }
+
+      if (configHeaders) {
+        Object.assign(esOptions.headers, configHeaders)
+      }
+    }
+
     const key = `${url.href}::${JSON.stringify(esOptions)}`
     const existing = eventsCache.get(key)
 

package/src/defineCreateClient.ts

@@ -17,7 +17,13 @@ export {
 } from './data/eventsource'
 export * from './data/patch'
 export * from './data/transaction'
-export {ClientError, CorsOriginError, ServerError} from './http/errors'
+export {
+  ClientError,
+  CorsOriginError,
+  formatQueryParseError,
+  isQueryParseError,
+  ServerError,
+} from './http/errors'
 export * from './SanityClient'
 export * from './types'
 

package/src/http/errors.ts

@@ -1,4 +1,8 @@
-import type {ActionError, Any, ErrorProps, MutationError} from '../types'
+import type {HttpContext} from 'get-it'
+
+import type {ActionError, Any, ErrorProps, MutationError, QueryParseError} from '../types'
+import {codeFrame} from '../util/codeFrame'
+import {isRecord} from '../util/isRecord'
 
 const MAX_ITEMS_IN_ERROR_MESSAGE = 5
 
@@ -9,8 +13,8 @@ export class ClientError extends Error {
   responseBody: ErrorProps['responseBody']
   details: ErrorProps['details']
 
-  constructor(res: Any) {
-    const props = extractErrorProps(res)
+  constructor(res: Any, context?: HttpContext) {
+    const props = extractErrorProps(res, context)
     super(props.message)
     Object.assign(this, props)
   }
@@ -30,7 +34,7 @@ export class ServerError extends Error {
   }
 }
 
-function extractErrorProps(res: Any): ErrorProps {
+function extractErrorProps(res: Any, context?: HttpContext): ErrorProps {
   const body = res.body
   const props = {
     response: res,
@@ -40,15 +44,35 @@ function extractErrorProps(res: Any): ErrorProps {
     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)
+    return props
+  }
+
+  const error = body.error
+
   // API/Boom style errors ({statusCode, error, message})
-  if (body.error && body.message) {
-    props.message = `${body.error} - ${body.message}`
+  if (typeof error === 'string' && typeof body.message === 'string') {
+    props.message = `${error} - ${body.message}`
+    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
+    } else if (typeof body.message === 'string') {
+      props.message = body.message
+    } else {
+      props.message = httpErrorMessage(res, body)
+    }
     return props
   }
 
   // Mutation errors (specifically)
-  if (isMutationError(body) || isActionError(body)) {
-    const allItems = body.error.items || []
+  if (isMutationError(error) || isActionError(error)) {
+    const allItems = error.items || []
     const items = allItems
       .slice(0, MAX_ITEMS_IN_ERROR_MESSAGE)
       .map((item) => item.error?.description)
@@ -57,48 +81,85 @@ function extractErrorProps(res: Any): ErrorProps {
     if (allItems.length > MAX_ITEMS_IN_ERROR_MESSAGE) {
       itemsStr += `\n...and ${allItems.length - MAX_ITEMS_IN_ERROR_MESSAGE} more`
     }
-    props.message = `${body.error.description}${itemsStr}`
+    props.message = `${error.description}${itemsStr}`
     props.details = body.error
     return props
   }
 
-  // Query/database errors ({error: {description, other, arb, props}})
-  if (body.error && body.error.description) {
-    props.message = body.error.description
+  // Query parse errors
+  if (isQueryParseError(error)) {
+    const tag = context?.options?.query?.tag
+    props.message = formatQueryParseError(error, tag)
     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.details = error
+    return props
+  }
+
   // Other, more arbitrary errors
-  props.message = body.error || body.message || httpErrorMessage(res)
+  props.message = httpErrorMessage(res, body)
   return props
 }
 
-function isMutationError(body: Any): body is MutationError {
+function isMutationError(error: object): error is MutationError {
+  return (
+    'type' in error &&
+    error.type === 'mutationError' &&
+    'description' in error &&
+    typeof error.description === 'string'
+  )
+}
+
+function isActionError(error: object): error is ActionError {
   return (
-    isPlainObject(body) &&
-    isPlainObject(body.error) &&
-    body.error.type === 'mutationError' &&
-    typeof body.error.description === 'string'
+    'type' in error &&
+    error.type === 'actionError' &&
+    'description' in error &&
+    typeof error.description === 'string'
   )
 }
 
-function isActionError(body: Any): body is ActionError {
+/** @internal */
+export function isQueryParseError(error: object): error is QueryParseError {
   return (
-    isPlainObject(body) &&
-    isPlainObject(body.error) &&
-    body.error.type === 'actionError' &&
-    typeof body.error.description === 'string'
+    isRecord(error) &&
+    error.type === 'queryParseError' &&
+    typeof error.query === 'string' &&
+    typeof error.start === 'number' &&
+    typeof error.end === 'number'
   )
 }
 
-function isPlainObject(obj: Any): obj is Record<string, unknown> {
-  return typeof obj === 'object' && obj !== null && !Array.isArray(obj)
+/**
+ * Formats a GROQ query parse error into a human-readable string.
+ *
+ * @param error - The error object containing details about the parse error.
+ * @param tag - An optional tag to include in the error message.
+ * @returns A formatted error message string.
+ * @public
+ */
+export function formatQueryParseError(error: QueryParseError, tag?: string | null) {
+  const {query, start, end, description} = error
+
+  if (!query || typeof start === 'undefined') {
+    return `GROQ query parse error: ${description}`
+  }
+
+  const withTag = tag ? `\n\nTag: ${tag}` : ''
+  const framed = codeFrame(query, {start, end}, description)
+
+  return `GROQ query parse error:\n${framed}${withTag}`
 }
 
-function httpErrorMessage(res: Any) {
+function httpErrorMessage(res: Any, body: unknown) {
+  const details = typeof body === 'string' ? ` (${sliceWithEllipsis(body, 100)})` : ''
   const statusMessage = res.statusMessage ? ` ${res.statusMessage}` : ''
-  return `${res.method}-request to ${res.url} resulted in HTTP ${res.statusCode}${statusMessage}`
+  return `${res.method}-request to ${res.url} resulted in HTTP ${res.statusCode}${statusMessage}${details}`
 }
 
 function stringifyBody(body: Any, res: Any) {
@@ -107,6 +168,10 @@ function stringifyBody(body: Any, res: Any) {
   return isJson ? JSON.stringify(body, null, 2) : body
 }
 
+function sliceWithEllipsis(str: string, max: number) {
+  return str.length > max ? `${str.slice(0, max)}…` : str
+}
+
 /** @public */
 export class CorsOriginError extends Error {
   projectId: string

package/src/http/request.ts

@@ -1,4 +1,4 @@
-import {getIt, type Middlewares, type Requester} from 'get-it'
+import {getIt, type HttpContext, type Middlewares, type Requester} from 'get-it'
 import {jsonRequest, jsonResponse, observable, progress, retry} from 'get-it/middleware'
 import {Observable} from 'rxjs'
 
@@ -6,11 +6,11 @@ import type {Any} from '../types'
 import {ClientError, ServerError} from './errors'
 
 const httpError = {
-  onResponse: (res: Any) => {
+  onResponse: (res: Any, context: HttpContext) => {
     if (res.statusCode >= 500) {
       throw new ServerError(res)
     } else if (res.statusCode >= 400) {
-      throw new ClientError(res)
+      throw new ClientError(res, context)
     }
 
     return res

package/src/http/requestOptions.ts

@@ -7,6 +7,10 @@ const projectHeader = 'X-Sanity-Project-ID'
 export function requestOptions(config: Any, overrides: Any = {}): Omit<RequestOptions, 'url'> {
   const headers: Any = {}
 
+  if (config.headers) {
+    Object.assign(headers, config.headers)
+  }
+
   const token = overrides.token || config.token
   if (token) {
     headers.Authorization = `Bearer ${token}`

package/src/types.ts

@@ -102,6 +102,14 @@ export interface ClientConfig {
    * Optional request tag prefix for all request tags
    */
   requestTagPrefix?: string
+
+  /**
+   * Optional default headers to include with all requests
+   *
+   * @remarks request-specific headers will override any default headers with the same name.
+   */
+  headers?: Record<string, string>
+
   ignoreBrowserTokenWarning?: boolean
   withCredentials?: boolean
   allowReconfigure?: boolean
@@ -173,6 +181,12 @@ export interface InitializedClientConfig extends ClientConfig {
    * The fully initialized stega config, can be used to check if stega is enabled
    */
   stega: InitializedStegaConfig
+  /**
+   * Default headers to include with all requests
+   *
+   * @remarks request-specific headers will override any default headers with the same name.
+   */
+  headers?: Record<string, string>
 }
 
 /** @public */
@@ -1359,11 +1373,26 @@ export interface ApiError {
 
 /** @internal */
 export interface MutationError {
-  error: {
-    type: 'mutationError'
-    description: string
-    items?: MutationErrorItem[]
-  }
+  type: 'mutationError'
+  description: string
+  items?: MutationErrorItem[]
+}
+
+/**
+ * Returned from the Content Lake API when a query is malformed, usually with a start
+ * and end column to indicate where the error occurred, but not always. Can we used to
+ * provide a more structured error message to the user.
+ *
+ * This will be located under the response `error` property.
+ *
+ * @public
+ */
+export interface QueryParseError {
+  type: 'queryParseError'
+  description: string
+  start?: number
+  end?: number
+  query?: string
 }
 
 /** @internal */
@@ -1377,11 +1406,9 @@ export interface MutationErrorItem {
 
 /** @internal */
 export interface ActionError {
-  error: {
-    type: 'actionError'
-    description: string
-    items?: ActionErrorItem[]
-  }
+  type: 'actionError'
+  description: string
+  items?: ActionErrorItem[]
 }
 
 /** @internal */
@@ -1605,6 +1632,8 @@ export type {
   GenerateTargetDocument,
   GenerateTargetInclude,
 } from './agent/actions/generate'
+export type {PatchDocument, PatchOperation, PatchTarget} from './agent/actions/patch'
+export type {PromptRequest} from './agent/actions/prompt'
 export type {
   TransformDocument,
   TransformTarget,

package/src/util/codeFrame.ts

@@ -0,0 +1,174 @@
+/**
+ * Inlined, modified version of the `codeFrameColumns` function from `@babel/code-frame`.
+ * MIT-licensed - https://github.com/babel/babel/blob/main/LICENSE
+ * Copyright (c) 2014-present Sebastian McKenzie and other contributors.
+ */
+type Location = {
+  column: number
+  line: number
+}
+
+type NodeLocation = {
+  start: Location
+  end?: Location
+}
+
+type GroqLocation = {
+  start: number
+  end?: number
+}
+
+/**
+ * RegExp to test for newlines.
+ */
+
+const NEWLINE = /\r\n|[\n\r\u2028\u2029]/
+
+/**
+ * Extract what lines should be marked and highlighted.
+ */
+
+type MarkerLines = Record<number, true | [number, number]>
+
+/**
+ * Highlight a code frame with the given location and message.
+ *
+ * @param query - The query to be highlighted.
+ * @param location - The location of the error in the code/query.
+ * @param message - Message to be displayed inline (if possible) next to the highlighted
+ * location in the code. If it can't be positioned inline, it will be placed above the
+ * code frame.
+ * @returns The highlighted code frame.
+ */
+export function codeFrame(query: string, location: GroqLocation, message?: string): string {
+  const lines = query.split(NEWLINE)
+  const loc = {
+    start: columnToLine(location.start, lines),
+    end: location.end ? columnToLine(location.end, lines) : undefined,
+  }
+
+  const {start, end, markerLines} = getMarkerLines(loc, lines)
+
+  const numberMaxWidth = `${end}`.length
+
+  return query
+    .split(NEWLINE, end)
+    .slice(start, end)
+    .map((line, index) => {
+      const number = start + 1 + index
+      const paddedNumber = ` ${number}`.slice(-numberMaxWidth)
+      const gutter = ` ${paddedNumber} |`
+      const hasMarker = markerLines[number]
+      const lastMarkerLine = !markerLines[number + 1]
+      if (!hasMarker) {
+        return ` ${gutter}${line.length > 0 ? ` ${line}` : ''}`
+      }
+
+      let markerLine = ''
+      if (Array.isArray(hasMarker)) {
+        const markerSpacing = line.slice(0, Math.max(hasMarker[0] - 1, 0)).replace(/[^\t]/g, ' ')
+        const numberOfMarkers = hasMarker[1] || 1
+
+        markerLine = [
+          '\n ',
+          gutter.replace(/\d/g, ' '),
+          ' ',
+          markerSpacing,
+          '^'.repeat(numberOfMarkers),
+        ].join('')
+
+        if (lastMarkerLine && message) {
+          markerLine += ' ' + message
+        }
+      }
+      return ['>', gutter, line.length > 0 ? ` ${line}` : '', markerLine].join('')
+    })
+    .join('\n')
+}
+
+function getMarkerLines(
+  loc: NodeLocation,
+  source: Array<string>,
+): {
+  start: number
+  end: number
+  markerLines: MarkerLines
+} {
+  const startLoc: Location = {...loc.start}
+  const endLoc: Location = {...startLoc, ...loc.end}
+  const linesAbove = 2
+  const linesBelow = 3
+  const startLine = startLoc.line ?? -1
+  const startColumn = startLoc.column ?? 0
+  const endLine = endLoc.line
+  const endColumn = endLoc.column
+
+  let start = Math.max(startLine - (linesAbove + 1), 0)
+  let end = Math.min(source.length, endLine + linesBelow)
+
+  if (startLine === -1) {
+    start = 0
+  }
+
+  if (endLine === -1) {
+    end = source.length
+  }
+
+  const lineDiff = endLine - startLine
+  const markerLines: MarkerLines = {}
+
+  if (lineDiff) {
+    for (let i = 0; i <= lineDiff; i++) {
+      const lineNumber = i + startLine
+
+      if (!startColumn) {
+        markerLines[lineNumber] = true
+      } else if (i === 0) {
+        const sourceLength = source[lineNumber - 1].length
+
+        markerLines[lineNumber] = [startColumn, sourceLength - startColumn + 1]
+      } else if (i === lineDiff) {
+        markerLines[lineNumber] = [0, endColumn]
+      } else {
+        const sourceLength = source[lineNumber - i].length
+
+        markerLines[lineNumber] = [0, sourceLength]
+      }
+    }
+  } else {
+    if (startColumn === endColumn) {
+      if (startColumn) {
+        markerLines[startLine] = [startColumn, 0]
+      } else {
+        markerLines[startLine] = true
+      }
+    } else {
+      markerLines[startLine] = [startColumn, endColumn - startColumn]
+    }
+  }
+
+  return {start, end, markerLines}
+}
+
+function columnToLine(column: number, lines: string[]): Location {
+  let offset = 0
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineLength = lines[i].length + 1 // assume '\n' after each line
+
+    if (offset + lineLength > column) {
+      return {
+        line: i + 1, // 1-based line
+        column: column - offset, // 0-based column
+      }
+    }
+
+    offset += lineLength
+  }
+
+  // Fallback: beyond last line
+  return {
+    line: lines.length,
+    column: lines[lines.length - 1]?.length ?? 0,
+  }
+}

package/src/{csm → util}/isRecord.ts

@@ -1,4 +1,4 @@
 /** @internal */
 export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }