@sanity/client 8.0.0 → 8.2.0

package/src/collaboration/types.ts

@@ -0,0 +1,252 @@
+import type {
+  Any,
+  ListenOptions,
+  RequestOptions,
+  ResumableListenOptions,
+  SanityDocument,
+} from '../types'
+
+/** @internal */
+export const possibleRequestOptions = ['headers', 'signal', 'tag', 'timeout', 'token'] as const
+
+/**
+ * Request options honored by the collaboration comments methods.
+ *
+ * @alpha
+ */
+export type CollaborationCommentsRequestOptions = Pick<
+  RequestOptions,
+  (typeof possibleRequestOptions)[number]
+>
+
+/**
+ * Options for collaboration comments write methods.
+ *
+ * @alpha
+ */
+export type CollaborationCommentsWriteOptions = CollaborationCommentsRequestOptions & {
+  /** Transaction ID to associate the write with */
+  transactionId?: string
+}
+
+/**
+ * Listener options for `collaboration.comments.listen`.
+ *
+ * `includeAllVersions` is left out: comments are stored as `sanity.comment`
+ * documents with no drafts or versions, so it would never make a difference.
+ *
+ * @alpha
+ */
+export type CollaborationCommentsListenOptions =
+  | Omit<ListenOptions, 'includeAllVersions'>
+  | Omit<ResumableListenOptions, 'includeAllVersions'>
+
+/**
+ * Status of a comment thread. Replies always share the status of their parent comment.
+ *
+ * @alpha
+ */
+export type CollaborationCommentStatus = 'open' | 'resolved'
+
+/**
+ * Emoji short names that can be used as comment reactions.
+ *
+ * @alpha
+ */
+export type CollaborationCommentReactionShortName =
+  | ':-1:'
+  | ':+1:'
+  | ':eyes:'
+  | ':heart:'
+  | ':heavy_plus_sign:'
+  | ':rocket:'
+
+/**
+ * A single Portable Text block, as used in comment messages and content snapshots.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentPortableTextBlock {
+  _type: string
+  children: Array<{_type: string; [key: string]: Any}>
+  [key: string]: Any
+}
+
+/**
+ * Comment message, as an array of Portable Text blocks.
+ *
+ * @alpha
+ */
+export type CollaborationCommentMessage = CollaborationCommentPortableTextBlock[]
+
+/**
+ * The text an inline comment was anchored to, resolved by the API when the
+ * comment was created.
+ *
+ * Holds one entry per Portable Text block the selection spans, keyed by the
+ * block it came from. `text` is the plain text of that block with the selected
+ * part wrapped in the marker characters `\uF000` (start) and `\uF001` (end).
+ *
+ * @alpha
+ */
+export interface CollaborationCommentSelection {
+  type: 'text'
+  value: {_key: string; text: string}[]
+}
+
+/**
+ * A comment document, as stored by the Comments API.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentDocument extends SanityDocument {
+  _type: 'sanity.comment'
+  _system?: {
+    /** ID of the user that created the comment */
+    createdBy?: string
+  }
+  /** ID shared by a top-level comment and all of its replies */
+  threadId?: string
+  /** Set on replies, pointing to the comment being replied to */
+  parentCommentId?: string
+  message: CollaborationCommentMessage
+  reactions: {
+    _key: string
+    shortName: CollaborationCommentReactionShortName
+    userId: string
+    addedAt: string
+  }[]
+  /** Arbitrary metadata stored with the comment by the creating application */
+  context?: Record<string, unknown>
+  target: {
+    /** Global document reference (`resourceType:resourceId:documentId`, using the published document ID) */
+    document: {
+      _ref: `${string}:${string}:${string}`
+      _type: 'globalDocumentReference'
+      _weak: true
+    }
+    documentType: string
+    /** The exact document ID the comment was created against, e.g. a draft or version ID */
+    sourceDocumentId: string
+    documentRevisionId?: string
+    /**
+     * Set for field and inline comments. `field` is the `path` the comment was
+     * created with; `selection` is set for inline comments only.
+     */
+    path?: {
+      field: string
+      selection?: CollaborationCommentSelection
+    }
+  }
+  /**
+   * Copy of the commented content, as it looked when the comment was created.
+   * Set for inline comments only, and holds just the selected fragment of each
+   * Portable Text block the selection spans.
+   */
+  contentSnapshot?: CollaborationCommentPortableTextBlock[]
+  status: CollaborationCommentStatus
+  /** Set when the message has been updated after creation */
+  lastEditedAt?: string
+}
+
+/**
+ * Inline text selection within a Portable Text field.
+ * Each endpoint pairs the `_key` of a Portable Text block with a character
+ * offset into that block's plain text.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentRange {
+  start: {_key: string; offset: number}
+  end: {_key: string; offset: number}
+}
+
+/**
+ * Target for a top-level comment. Inline selections require both `path` and
+ * `range`; field-level comments may set `path` alone.
+ *
+ * The created comment stores this in a different shape: `path` becomes
+ * `target.path.field`, and `range` is resolved against the document into
+ * `target.path.selection` and `contentSnapshot` rather than being stored.
+ *
+ * @alpha
+ */
+export type CollaborationCommentTarget = {
+  documentId: string
+  documentType: string
+  documentRevisionId?: string
+} & (
+  | {
+      /** Path to the field containing the inline comment selection */
+      path: string
+      range: CollaborationCommentRange
+    }
+  | {
+      /** Path to the commented field */
+      path?: string
+      range?: never
+    }
+)
+
+/**
+ * Comment to create with `collaboration.comments.create`.
+ *
+ * A top-level comment requires `target`; a reply requires `parentCommentId` (never both).
+ * Replies inherit `target`, `status`, and `threadId` from the parent comment.
+ *
+ * ### Examples
+ *
+ * #### Top-level comment
+ * ```ts
+ * // `message` is an array of Portable Text blocks
+ * await client.collaboration.comments.create({
+ *   message,
+ *   target: {documentId: 'doc-1', documentType: 'article'},
+ * })
+ * ```
+ *
+ * #### Reply
+ * ```ts
+ * await client.collaboration.comments.create({
+ *   message,
+ *   parentCommentId: 'comment-1',
+ * })
+ * ```
+ *
+ * @alpha
+ */
+export type CollaborationCommentCreate = {
+  /** Provide to control the ID of the created comment document */
+  _id?: string
+  message: CollaborationCommentMessage
+  context?: Record<string, unknown>
+} & (
+  | {
+      target: CollaborationCommentTarget
+      threadId?: string
+      parentCommentId?: never
+    }
+  | {
+      parentCommentId: string
+      target?: never
+      threadId?: never
+    }
+)
+
+/**
+ * Fields that can be updated on an existing comment.
+ *
+ * @alpha
+ */
+export interface CollaborationCommentUpdate {
+  /** Replaces the current message */
+  message?: CollaborationCommentMessage
+  /** Cascades to the comment's replies */
+  status?: CollaborationCommentStatus
+  /**
+   * Re-anchors the comment within the field and source document it already
+   * targets. Pass `null` to remove the selection and leave a field-level
+   * comment.
+   */
+  range?: CollaborationCommentRange | null
+}

package/src/csm/applySourceDocuments.ts

@@ -3,12 +3,10 @@ import {parseJsonPath} from './jsonPath'
 import {resolveMapping} from './resolveMapping'
 import * as paths from './studioPath'
 import type {
-  Any,
   ApplySourceDocumentsUpdateFunction,
   ClientPerspective,
   ContentSourceMap,
   ContentSourceMapDocuments,
-  Path,
   SanityDocument,
 } from './types'
 import {walkMap} from './walkMap'
@@ -55,7 +53,7 @@ export function applySourceDocuments<Result = unknown>(
 
     if (sourceDocument) {
       const parsedPath = parseJsonPath(sourcePath + pathSuffix)
-      const stringifiedPath = paths.toString(parsedPath as Path)
+      const stringifiedPath = paths.toString(parsedPath)
       const cachedDocument = cachedDocuments[mapping.source.document]
 
       if (!cachedDocument) {
@@ -67,7 +65,7 @@ export function applySourceDocuments<Result = unknown>(
         : value
       return value === changedValue
         ? value
-        : updateFn<Result[keyof Result]>(changedValue as Any, {
+        : updateFn<Result[keyof Result]>(changedValue as Result[keyof Result], {
             cachedDocument,
             previousValue: value as Result[keyof Result],
             sourceDocument,

package/src/csm/draftUtils.ts

@@ -32,11 +32,24 @@ export function isPublishedId(id: string): id is PublishedId {
   return !isDraftId(id) && !isVersionId(id)
 }
 
+/**
+ * A phantom brand like `DraftId` has no runtime representation, so it can never be produced
+ * by narrowing a string - there's nothing to check. These two functions are the only places
+ * allowed to assert a plain string into a branded id.
+ */
+function asDraftId(value: string): DraftId {
+  return value as DraftId
+}
+
+function asPublishedId(value: string): PublishedId {
+  return value as PublishedId
+}
+
 /** @internal */
 export function getDraftId(id: string): DraftId {
   if (isVersionId(id)) {
     const publishedId = getPublishedId(id)
-    return (DRAFTS_PREFIX + publishedId) as DraftId
+    return asDraftId(DRAFTS_PREFIX + publishedId)
   }
 
   return isDraftId(id) ? id : ((DRAFTS_PREFIX + id) as DraftId)
@@ -69,12 +82,18 @@ export function getVersionFromId(id: string): string | undefined {
 export function getPublishedId(id: string): PublishedId {
   if (isVersionId(id)) {
     // make sure to only remove the versions prefix and the bundle name
-    return id.split(PATH_SEPARATOR).slice(2).join(PATH_SEPARATOR) as PublishedId as PublishedId
+    return asPublishedId(id.split(PATH_SEPARATOR).slice(2).join(PATH_SEPARATOR))
   }
 
   if (isDraftId(id)) {
-    return id.slice(DRAFTS_PREFIX.length) as PublishedId
+    return asPublishedId(id.slice(DRAFTS_PREFIX.length))
+  }
+
+  if (isPublishedId(id)) {
+    return id
   }
 
-  return id as PublishedId
+  // Unreachable: `isPublishedId` is defined as `!isDraftId(id) && !isVersionId(id)`, both of
+  // which were already checked (and found false) above, so this can never execute.
+  throw new Error(`Unable to resolve a published id from "${id}"`)
 }

package/src/data/dataMethods.ts

@@ -73,7 +73,13 @@ const indexBy = (docs: Any[], attr: Any) =>
     return indexed
   }, Object.create(null))
 
-const getQuerySizeLimit = 11264
+/**
+ * Encoded query strings longer than this are sent as a `POST` body rather than
+ * in the request URL.
+ *
+ * @internal
+ */
+export const getQuerySizeLimit = 11264
 
 /**
  * Resolve the effective stega config, cleaned params, response mapper and
@@ -667,23 +673,6 @@ function _mapDataResponse(
 /**
  * @internal
  */
-export function _dataRequestObservable(
-  client: Client,
-  httpRequest: HttpRequest,
-  endpoint: string,
-  body: Any,
-  options: Any = {},
-): Observable<Any> {
-  return _observe(options.signal, (signal) =>
-    _dataRequest(client, httpRequest, endpoint, body, {...options, signal}),
-  )
-}
-
-/**
- * Promise-based sibling of {@link _dataRequestObservable}.
- *
- * @internal
- */
 export function _dataRequest(
   client: Client,
   httpRequest: HttpRequest,
@@ -1139,7 +1128,7 @@ export function _prepareRequest(client: Client, options: RequestObservableOption
  *
  * @internal
  */
-export function _observe<R>(
+function _observe<R>(
   userSignal: AbortSignal | undefined,
   run: (signal: AbortSignal) => Promise<R>,
 ): Observable<R> {
@@ -1171,7 +1160,7 @@ export function _observe<R>(
  */
 export function _request<R>(client: Client, httpRequest: HttpRequest, options: Any): Promise<R> {
   const reqOptions = _prepareRequest(client, options)
-  return httpRequest(reqOptions).then((body) => body as R)
+  return httpRequest(reqOptions, client.config().requestHandler).then((body) => body as R)
 }
 
 /**

package/src/data/eventsource.ts

@@ -1,14 +1,16 @@
+import type {ErrorEvent, EventSourceConstructor} from 'eventsource'
 import {defer, isObservable, mergeMap, Observable, of} from 'rxjs'
 
 import {formatQueryParseError, isQueryParseError} from '../http/errors'
-import {type Any} from '../types'
+import {isRecord} from '../util/isRecord'
 
 /**
- * @public
  * Thrown when the EventSource connection could not be established, or was rejected by the server.
  * Transient failures (network drops, 5xx, 408, 429) are reconnected internally and emitted as
  * `reconnect` events; a permanent rejection (any other 4xx, eg an expired token) errors the
  * stream with this class so consumers can react — check `status` for the rejection code.
+ *
+ * @public
  */
 export class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
@@ -28,8 +30,9 @@ export class ConnectionFailedError extends Error {
 
 /**
  * The listener has been told to explicitly disconnect.
- *  This is a rare situation, but may occur if the API knows reconnect attempts will fail,
- *  eg in the case of a deleted dataset, a blocked project or similar events.
+ * This is a rare situation, but may occur if the API knows reconnect attempts will fail,
+ * eg in the case of a deleted dataset, a blocked project or similar events.
+ *
  * @public
  */
 export class DisconnectError extends Error {
@@ -42,8 +45,9 @@ export class DisconnectError extends Error {
 }
 
 /**
- * @public
  * The server sent a `channelError` message. Usually indicative of a bad or malformed request
+ *
+ * @public
  */
 export class ChannelError extends Error {
   readonly name = 'ChannelError'
@@ -55,8 +59,9 @@ export class ChannelError extends Error {
 }
 
 /**
- * @public
  * The server sent an `error`-event to tell the client that an unexpected error has happened.
+ *
+ * @public
  */
 export class MessageError extends Error {
   readonly name = 'MessageError'
@@ -68,8 +73,9 @@ export class MessageError extends Error {
 }
 
 /**
- * @public
  * An error occurred while parsing the message sent by the server as JSON. Should normally not happen.
+ *
+ * @public
  */
 export class MessageParseError extends Error {
   readonly name = 'MessageParseError'
@@ -95,7 +101,7 @@ export type EventSourceEvent<Name extends string> = ServerSentEvent<Name>
 /**
  * @internal
  */
-export type EventSourceInstance = InstanceType<typeof globalThis.EventSource>
+export type EventSourceInstance = InstanceType<EventSourceConstructor>
 
 /**
  * Sanity API specific EventSource handler shared between the listen and live APIs
@@ -123,9 +129,7 @@ export function connectEventSource<EventName extends string>(
   return defer(() => {
     const es = initEventSource()
     return isObservable(es) ? es : of(es)
-  }).pipe(mergeMap((es) => connectWithESInstance(es, events))) as Observable<
-    ServerSentEvent<EventName>
-  >
+  }).pipe(mergeMap((es) => connectWithESInstance(es, events)))
 }
 
 /**
@@ -140,21 +144,30 @@ function connectWithESInstance<EventTypeName extends string>(
   events: EventTypeName[],
 ) {
   return new Observable<EventSourceEvent<EventTypeName>>((observer) => {
-    const emitOpen = (events as string[]).includes('open')
-    const emitReconnect = (events as string[]).includes('reconnect')
+    // Events actually requested by the caller. Backs `isRequestedEvent`, the type
+    // guard used below to narrow plain strings (eg `message.type`) to `EventTypeName`
+    // without a cast.
+    const requestedEvents = new Set<string>(events)
+    const isRequestedEvent = (type: string): type is EventTypeName => requestedEvents.has(type)
+    const emitOpen = isRequestedEvent('open')
 
     // EventSource will emit a regular Event if it fails to connect, however the API may also emit an `error` MessageEvent
     // So we need to handle both cases
-    function onError(evt: MessageEvent | Event) {
+    function onError(evt: ErrorEvent | MessageEvent) {
       // If the event has a `data` property, then it`s a MessageEvent emitted by the API and we should forward the error
       if ('data' in evt) {
-        const [parseError, event] = parseEvent(evt as MessageEvent)
+        const [parseError, event] = parseEvent(evt)
         observer.error(
-          parseError
+          parseError || !event
             ? new MessageParseError('Unable to parse EventSource error message', {
                 cause: parseError,
               })
-            : new MessageError((event.data as {message: string}).message, event),
+            : new MessageError(
+                isRecord(event.data) && typeof event.data.message === 'string'
+                  ? event.data.message
+                  : '',
+                event,
+              ),
         )
         return
       }
@@ -169,29 +182,35 @@ function connectWithESInstance<EventTypeName extends string>(
       // regardless of readyState — implementations disagree on whether the connection
       // closes before or after the error event is dispatched — and let
       // `reconnectOnConnectionFailure` classify it (4xx fatal, otherwise retried).
-      const rawStatus = (evt as {code?: unknown}).code
-      const status = typeof rawStatus === 'number' ? rawStatus : undefined
-      if (status !== undefined) {
-        observer.error(new ConnectionFailedError('EventSource connection failed', {status}))
+      if (evt.code !== undefined) {
+        observer.error(
+          new ConnectionFailedError('EventSource connection failed', {status: evt.code}),
+        )
         return
       }
 
       if (es.readyState === es.CLOSED) {
         // In these cases we'll signal to consumers (via the error path) that a retry/reconnect is needed.
         observer.error(new ConnectionFailedError('EventSource connection failed'))
-      } else if (emitReconnect) {
-        observer.next({type: 'reconnect' as EventTypeName})
+      } else {
+        const type = 'reconnect'
+        if (isRequestedEvent(type)) {
+          observer.next({type})
+        }
       }
     }
 
     function onOpen() {
       // The open event of the EventSource API is fired when a connection with an event source is opened.
-      observer.next({type: 'open' as EventTypeName})
+      const type = 'open'
+      if (isRequestedEvent(type)) {
+        observer.next({type})
+      }
     }
 
     function onMessage(message: MessageEvent) {
       const [parseError, event] = parseEvent(message)
-      if (parseError) {
+      if (parseError || !event) {
         observer.error(
           new MessageParseError('Unable to parse EventSource message', {cause: parseError}),
         )
@@ -212,17 +231,25 @@ function connectWithESInstance<EventTypeName extends string>(
         observer.error(
           new DisconnectError(
             `Server disconnected client: ${
-              (event.data as {reason?: string})?.reason || 'unknown error'
+              (isRecord(event.data) &&
+                typeof event.data.reason === 'string' &&
+                event.data.reason) ||
+              'unknown error'
             }`,
           ),
         )
         return
       }
-      observer.next({
-        type: message.type as EventTypeName,
-        id: message.lastEventId,
-        ...(event.data ? {data: event.data} : {}),
-      })
+      // `onMessage` is only ever registered for `REQUIRED_EVENTS` (handled above, and always
+      // returned from before reaching here) and the caller-requested `events` (see
+      // `cleanedEvents` below), so `message.type` is guaranteed to be a requested event here.
+      if (isRequestedEvent(message.type)) {
+        observer.next({
+          type: message.type,
+          id: message.lastEventId,
+          ...(event.data ? {data: event.data} : {}),
+        })
+      }
     }
 
     es.addEventListener('error', onError)
@@ -251,7 +278,7 @@ function connectWithESInstance<EventTypeName extends string>(
 
 function parseEvent(
   message: MessageEvent,
-): [null, {type: string; id: string; data?: unknown}] | [Error, null] {
+): [null, {type: string; id: string; data?: unknown}] | [unknown, null] {
   try {
     const data = typeof message.data === 'string' && JSON.parse(message.data)
     return [
@@ -263,23 +290,26 @@ function parseEvent(
       },
     ]
   } catch (err) {
-    return [err as Error, null]
+    return [err, null]
   }
 }
 
-function extractErrorMessage(err: Any, tag?: string | null) {
-  const error = err.error
+function extractErrorMessage(err: unknown, tag?: string | null): string {
+  const error = isRecord(err) ? err.error : undefined
 
   if (!error) {
-    return err.message || 'Unknown listener error'
+    const message = isRecord(err) ? err.message : undefined
+    return (typeof message === 'string' && message) || 'Unknown listener error'
   }
 
-  if (isQueryParseError(error)) {
-    return formatQueryParseError(error, tag)
-  }
+  if (isRecord(error)) {
+    if (isQueryParseError(error)) {
+      return formatQueryParseError(error, tag)
+    }
 
-  if (error.description) {
-    return error.description
+    if (typeof error.description === 'string') {
+      return error.description
+    }
   }
 
   return typeof error === 'string' ? error : JSON.stringify(error, null, 2)

package/src/data/listen.ts

@@ -29,9 +29,11 @@ import {resolveEventSourceFetch} from './resolveEventSourceFetch'
 // Limit is 16K for a _request_, eg including headers. Have to account for an
 // unknown range of headers, but an average EventSource request from Chrome seems
 // to have around 700 bytes of cruft, so let us account for 1.2K to be "safe"
-const MAX_URL_LENGTH = 16000 - 1200
+/** @internal */
+export const MAX_URL_LENGTH = 16000 - 1200
 
-const possibleOptions = [
+/** @internal */
+export const possibleOptions = [
   'includePreviousRevision',
   'includeResult',
   'includeMutations',
@@ -42,7 +44,8 @@ const possibleOptions = [
   'tag',
 ]
 
-const defaultOptions = {
+/** @internal */
+export const defaultOptions = {
   includeResult: true,
 }
 
@@ -137,7 +140,7 @@ export function _listen<
   opts: Opts = {} as Opts,
 ): Observable<ListenEventFromOptions<R, Opts>> {
   const config = this.config()
-  const {url, token, withCredentials, requestTagPrefix, headers: configHeaders} = config
+  const {url, requestTagPrefix} = config
   const tag = opts.tag && requestTagPrefix ? [requestTagPrefix, opts.tag].join('.') : opts.tag
   const options = {...defaults(opts, defaultOptions), tag}
   const listenOpts = pick(options, possibleOptions)
@@ -150,6 +153,18 @@ export function _listen<
 
   const listenFor = (options.events ? options.events : ['mutation']) satisfies Opts['events']
 
+  return _connectListenEventSource<ListenEventFromOptions<R, Opts>>(this, uri, listenFor)
+}
+
+/** @internal */
+export function _connectListenEventSource<TEvent extends {type: string}>(
+  client: SanityClient | ObservableSanityClient,
+  uri: string,
+  listenFor: string[],
+): Observable<TEvent> {
+  const config = client.config()
+  const {token, withCredentials, headers: configHeaders} = config
+
   const headers: Record<string, string> = {}
   if (token) {
     headers.Authorization = `Bearer ${token}`
@@ -173,5 +188,5 @@ export function _listen<
       type: event.type,
       ...('data' in event ? (event.data as object) : {}),
     })),
-  ) as Observable<ListenEventFromOptions<R, Opts>>
+  ) as Observable<TEvent>
 }