@sanity/client 8.0.0 → 8.1.0

package/src/SanityClient.ts

@@ -10,6 +10,7 @@ import {LiveClient} from './data/live'
 import {ObservablePatch, Patch} from './data/patch'
 import {ObservableTransaction, Transaction} from './data/transaction'
 import {DatasetsClient, ObservableDatasetsClient} from './datasets/DatasetsClient'
+import {FunctionsClient, ObservableFunctionsClient} from './functions/FunctionsClient'
 import {
   MediaLibraryVideoClient,
   ObservableMediaLibraryVideoClient,
@@ -81,6 +82,7 @@ export class ObservableSanityClient {
   agent: {
     action: ObservableAgentsActionClient
   }
+  functions: ObservableFunctionsClient
   releases: ObservableReleasesClient
 
   /**
@@ -110,6 +112,7 @@ export class ObservableSanityClient {
     this.agent = {
       action: new ObservableAgentsActionClient(this, this.#httpRequest),
     }
+    this.functions = new ObservableFunctionsClient(this, this.#httpRequest)
     this.releases = new ObservableReleasesClient(this, this.#httpRequest)
   }
 
@@ -707,15 +710,12 @@ export class ObservableSanityClient {
   delete(id: string, options: AllDocumentIdsMutationOptions): Observable<MultipleMutationResult>
   /**
    * Deletes a document with the given document ID.
-   * Returns an observable that resolves to the deleted document.
+   * Returns an observable that resolves to a mutation result object containing the deleted document ID.
    *
    * @param id - Document ID to delete
    * @param options - Options for the mutation
    */
-  delete<R extends Record<string, Any> = Record<string, Any>>(
-    id: string,
-    options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  delete(id: string, options?: BaseMutationOptions): Observable<MultipleMutationResult>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns an observable that resolves to first deleted document.
@@ -762,15 +762,15 @@ export class ObservableSanityClient {
   ): Observable<MultipleMutationResult>
   /**
    * Deletes one or more documents matching the given query or document ID.
-   * Returns an observable that resolves to first deleted document.
+   * Returns an observable that resolves to a mutation result object containing the document IDs that were deleted.
    *
    * @param selection - An object with either an `id` or `query` key defining what to delete
    * @param options - Options for the mutation
    */
-  delete<R extends Record<string, Any> = Record<string, Any>>(
+  delete(
     selection: MutationSelection,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<MultipleMutationResult>
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: string | MutationSelection,
     options?:
@@ -1020,7 +1020,7 @@ export class ObservableSanityClient {
   ): Observable<MultipleMutationResult>
   /**
    * Perform mutation operations against the configured dataset
-   * Returns an observable that resolves to the first mutated document.
+   * Returns an observable that resolves to a mutation result object containing the mutated document IDs.
    *
    * @param operations - Mutation operations to execute
    * @param options - Mutation options
@@ -1028,7 +1028,7 @@ export class ObservableSanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | ObservablePatch | ObservableTransaction,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<MultipleMutationResult>
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | ObservablePatch | ObservableTransaction,
     options?:
@@ -1148,6 +1148,7 @@ export class SanityClient {
   agent: {
     action: AgentActionsClient
   }
+  functions: FunctionsClient
   releases: ReleasesClient
 
   /**
@@ -1182,6 +1183,7 @@ export class SanityClient {
     this.agent = {
       action: new AgentActionsClient(this, this.#httpRequest),
     }
+    this.functions = new FunctionsClient(this, this.#httpRequest)
     this.releases = new ReleasesClient(this, this.#httpRequest)
 
     this.observable = new ObservableSanityClient(httpRequest, config)
@@ -1773,15 +1775,12 @@ export class SanityClient {
   delete(id: string, options: AllDocumentIdsMutationOptions): Promise<MultipleMutationResult>
   /**
    * Deletes a document with the given document ID.
-   * Returns a promise that resolves to the deleted document.
+   * Returns a promise that resolves to a mutation result object containing the deleted document ID.
    *
    * @param id - Document ID to delete
    * @param options - Options for the mutation
    */
-  delete<R extends Record<string, Any> = Record<string, Any>>(
-    id: string,
-    options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  delete(id: string, options?: BaseMutationOptions): Promise<MultipleMutationResult>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns a promise that resolves to first deleted document.
@@ -1828,15 +1827,15 @@ export class SanityClient {
   ): Promise<MultipleMutationResult>
   /**
    * Deletes one or more documents matching the given query or document ID.
-   * Returns a promise that resolves to first deleted document.
+   * Returns a promise that resolves to a mutation result object containing the document IDs that were deleted.
    *
    * @param selection - An object with either an `id` or `query` key defining what to delete
    * @param options - Options for the mutation
    */
-  delete<R extends Record<string, Any> = Record<string, Any>>(
+  delete(
     selection: MutationSelection,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<MultipleMutationResult>
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: string | MutationSelection,
     options?:
@@ -2070,7 +2069,7 @@ export class SanityClient {
   ): Promise<MultipleMutationResult>
   /**
    * Perform mutation operations against the configured dataset
-   * Returns a promise that resolves to the first mutated document.
+   * Returns a promise that resolves to a mutation result object containing the mutated document IDs.
    *
    * @param operations - Mutation operations to execute
    * @param options - Mutation options
@@ -2078,7 +2077,7 @@ export class SanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | Patch | Transaction,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<MultipleMutationResult>
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | Patch | Transaction,
     options?:

package/src/assets/AssetsClient.ts

@@ -8,6 +8,7 @@ import type {
   Any,
   HttpRequest,
   InitializedClientConfig,
+  MediaLibraryAssetDocument,
   SanityAssetDocument,
   SanityImageAssetDocument,
   UploadBody,
@@ -67,7 +68,12 @@ export class ObservableAssetsClient {
     assetType: 'file' | 'image',
     body: UploadBody,
     options?: UploadClientConfig,
-  ): Observable<UploadEvent<{document: SanityAssetDocument | SanityImageAssetDocument}>> {
+  ): Observable<
+    UploadEvent<
+      | {document: SanityAssetDocument | SanityImageAssetDocument}
+      | {asset: MediaLibraryAssetDocument}
+    >
+  > {
     return _upload(this.#client, this.#httpRequest, assetType, body, options)
   }
 }
@@ -84,6 +90,16 @@ export class AssetsClient {
   /**
    * Uploads a file asset to the configured dataset
    *
+   * Note: when the client is configured against a Media Library
+   * (`resource: {type: 'media-library', id}`), this resolves to a
+   * {@link MediaLibraryAssetDocument} at runtime, not to a
+   * {@link SanityAssetDocument}. The declared type cannot express that: the
+   * shape depends on the client's configuration rather than on the arguments,
+   * so an overload cannot discriminate it, and widening the return type into a
+   * union would be a breaking change for every existing caller. Narrow the
+   * result yourself (for example, check for `currentVersion`) if you upload to
+   * a Media Library. Typing this honestly is deferred to the next major.
+   *
    * @param assetType - Asset type (file)
    * @param body - Asset content - can be a browser File instance, a Blob, a Node.js Buffer instance or a Node.js ReadableStream.
    * @param options - Options to use for the upload
@@ -96,6 +112,10 @@ export class AssetsClient {
   /**
    * Uploads an image asset to the configured dataset
    *
+   * Note: against a Media Library this resolves to a
+   * {@link MediaLibraryAssetDocument} at runtime. See the `'file'` overload
+   * above for why the declared type cannot say so.
+   *
    * @param assetType - Asset type (image)
    * @param body - Asset content - can be a browser File instance, a Blob, a Node.js Buffer instance or a Node.js ReadableStream.
    * @param options - Options to use for the upload
@@ -121,19 +141,48 @@ export class AssetsClient {
     assetType: 'file' | 'image',
     body: UploadBody,
     options?: UploadClientConfig,
-  ): Promise<SanityAssetDocument | SanityImageAssetDocument> {
-    type Doc = {document: SanityAssetDocument | SanityImageAssetDocument}
+  ): Promise<SanityAssetDocument | SanityImageAssetDocument | MediaLibraryAssetDocument> {
+    type Doc =
+      | {document: SanityAssetDocument | SanityImageAssetDocument}
+      | {asset: MediaLibraryAssetDocument}
     const observable = _upload<Doc>(this.#client, this.#httpRequest, assetType, body, options)
     return lastValueFrom(
       observable.pipe(
         filter((event): event is UploadResponseEvent<Doc> => event.type === 'response'),
-        map((event) => event.body.document),
+        map((event) => pluckUploadedAsset(event.body)),
       ),
     )
   }
 }
 
-function _upload<T = {document: SanityAssetDocument | SanityImageAssetDocument}>(
+/**
+ * Content Lake's upload endpoint responds with `{document: ...}`; the Media
+ * Library upload endpoint responds with `{asset: ...}` instead (a
+ * `sanity.asset` document, not a Content Lake asset document). Narrowing on
+ * the response body itself - rather than on the client's `resource` config -
+ * keeps this correct regardless of how the two are ever wired together.
+ */
+function isMediaLibraryUploadBody(
+  body:
+    | {document: SanityAssetDocument | SanityImageAssetDocument}
+    | {asset: MediaLibraryAssetDocument},
+): body is {asset: MediaLibraryAssetDocument} {
+  return 'asset' in body
+}
+
+function pluckUploadedAsset(
+  body:
+    | {document: SanityAssetDocument | SanityImageAssetDocument}
+    | {asset: MediaLibraryAssetDocument},
+): SanityAssetDocument | SanityImageAssetDocument | MediaLibraryAssetDocument {
+  return isMediaLibraryUploadBody(body) ? body.asset : body.document
+}
+
+function _upload<
+  T =
+    | {document: SanityAssetDocument | SanityImageAssetDocument}
+    | {asset: MediaLibraryAssetDocument},
+>(
   client: SanityClient | ObservableSanityClient,
   _httpRequest: HttpRequest,
   assetType: 'image' | 'file',

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

@@ -667,23 +667,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 +1122,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 +1154,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)