@sanity/client 8.1.0 → 8.3.0

package/src/functions/FunctionsClient.ts

@@ -2,7 +2,7 @@ import {lastValueFrom, type Observable} from 'rxjs'
 
 import type {ObservableSanityClient, SanityClient} from '../SanityClient'
 import type {HttpRequest} from '../types'
-import {_invoke, type InvokeFunctionRequest} from './invoke'
+import {_invoke, type InvokeFunctionOptions, type InvokeFunctionRequest} from './invoke'
 
 /** @public */
 export class ObservableFunctionsClient {
@@ -17,16 +17,36 @@ export class ObservableFunctionsClient {
    * Invoke a deployed function by its blueprint name.
    *
    * The name is resolved within the stack given by `stackId` on the request or
-   * the client config. Passes the function's return value once it finishes.
+   * the client config. Starts the invocation and emits `undefined` as soon as
+   * it is accepted; pass `{sync: true}` to wait for the function's return value
+   * instead.
    *
    * @param functionName - name of the function, as declared in the blueprint
    * @param request - payload and request options
+   * @param options - invocation options
    */
+  invoke(
+    functionName: string,
+    request?: InvokeFunctionRequest,
+    options?: InvokeFunctionOptions & {sync?: false},
+  ): Observable<undefined>
+  invoke<R = unknown>(
+    functionName: string,
+    request: InvokeFunctionRequest | undefined,
+    options: InvokeFunctionOptions & {sync: true},
+  ): Observable<R>
+  invoke<R = unknown>(
+    functionName: string,
+    request?: InvokeFunctionRequest,
+    options?: InvokeFunctionOptions,
+  ): Observable<R | undefined>
+  // Implementation signature — not part of the public API.
   invoke<R = unknown>(
     functionName: string,
     request?: InvokeFunctionRequest,
+    options?: InvokeFunctionOptions,
   ): Observable<R | undefined> {
-    return _invoke<R>(this.#client, this.#httpRequest, functionName, request)
+    return _invoke<R>(this.#client, this.#httpRequest, functionName, request, options)
   }
 }
 
@@ -44,23 +64,46 @@ export class FunctionsClient {
    *
    * The name is resolved within the stack given by `stackId` on the request or
    * the client config, which costs one extra request per call. Rejects if the
-   * stack has no function by that name, or if the name resolves to anything
-   * other than a `sanity.function.pubsub` function.
+   * stack has no function by that name, or if the name resolves to a function
+   * type that cannot be invoked the way it was asked for.
    *
    * The lookup is scoped to `projectId`, or to `organizationId` when one is set
    * for a stack deployed at organization scope.
    *
-   * The request stays open until the function finishes, and resolves with its
-   * return value, or `undefined` if it returns nothing. Long-running functions
-   * may need an explicit `timeout`.
+   * The invocation is started by default: the promise resolves with `undefined`
+   * as soon as the call is accepted, without waiting for the function to run.
+   * Pass `{sync: true}` to keep the request open until the function finishes
+   * and resolve with its return value — long-running functions may then need an
+   * explicit `timeout`. Only `sanity.function.pubsub` functions can be invoked
+   * synchronously.
    *
    * @param functionName - name of the function, as declared in the blueprint
    * @param request - payload and request options
+   * @param options - invocation options
    */
+  invoke(
+    functionName: string,
+    request?: InvokeFunctionRequest,
+    options?: InvokeFunctionOptions & {sync?: false},
+  ): Promise<undefined>
+  invoke<R = unknown>(
+    functionName: string,
+    request: InvokeFunctionRequest | undefined,
+    options: InvokeFunctionOptions & {sync: true},
+  ): Promise<R>
+  invoke<R = unknown>(
+    functionName: string,
+    request?: InvokeFunctionRequest,
+    options?: InvokeFunctionOptions,
+  ): Promise<R | undefined>
+  // Implementation signature — not part of the public API.
   invoke<R = unknown>(
     functionName: string,
     request?: InvokeFunctionRequest,
+    options?: InvokeFunctionOptions,
   ): Promise<R | undefined> {
-    return lastValueFrom(_invoke<R>(this.#client, this.#httpRequest, functionName, request))
+    return lastValueFrom(
+      _invoke<R>(this.#client, this.#httpRequest, functionName, request, options),
+    )
   }
 }

package/src/functions/invoke.ts

@@ -6,7 +6,15 @@ import type {HttpRequest, InitializedClientConfig} from '../types'
 
 /** Function resource types in a blueprint are namespaced under this prefix. */
 const FUNCTION_RESOURCE_PREFIX = 'sanity.function.'
-const INVOKABLE_FUNCTION_TYPE = 'sanity.function.pubsub'
+const SYNC_INVOCABLE_FUNCTION_TYPES = ['sanity.function.pubsub']
+const ASYNC_INVOCABLE_FUNCTION_TYPES = [
+  'sanity.function.durable',
+  'sanity.function.pubsub',
+  'sanity.function.queue',
+]
+const INVOCABLE_FUNCTION_TYPES = [
+  ...new Set([...SYNC_INVOCABLE_FUNCTION_TYPES, ...ASYNC_INVOCABLE_FUNCTION_TYPES]),
+]
 
 /** @public */
 export interface InvokeFunctionEvent {
@@ -37,6 +45,18 @@ export interface InvokeFunctionRequest {
   signal?: AbortSignal
 }
 
+/** @public */
+export interface InvokeFunctionOptions {
+  /**
+   * Wait for the function to finish and resolve with its return value.
+   *
+   * Defaults to `false`: the invocation is started, the request resolves as soon
+   * as it is accepted, and the value is always `undefined`. Only function types
+   * that support running inline can be invoked synchronously.
+   */
+  sync?: boolean
+}
+
 /**
  * Subset of a stack resource the client needs in order to resolve a name.
  *
@@ -109,6 +129,7 @@ function _resolveFunctionId(
   stackId: string,
   headers: Record<string, string>,
   request: InvokeFunctionRequest | undefined,
+  sync: boolean,
 ): Observable<string> {
   return _requestObservable<{resources?: StackResource[]}>(client, httpRequest, {
     method: 'GET',
@@ -132,9 +153,15 @@ function _resolveFunctionId(
         )
       }
 
-      if (match.type !== INVOKABLE_FUNCTION_TYPE) {
+      if (!INVOCABLE_FUNCTION_TYPES.includes(match.type)) {
         throw new Error(`Function invocation is not supported for ${match.type}`)
       }
+      if (sync && !SYNC_INVOCABLE_FUNCTION_TYPES.includes(match.type)) {
+        throw new Error(`Synchronous function invocation is not supported for ${match.type}`)
+      }
+      if (!sync && !ASYNC_INVOCABLE_FUNCTION_TYPES.includes(match.type)) {
+        throw new Error(`Asynchronous function invocation is not supported for ${match.type}`)
+      }
 
       return match.externalId
     }),
@@ -147,6 +174,7 @@ export function _invoke<R = unknown>(
   httpRequest: HttpRequest,
   functionName: string,
   request?: InvokeFunctionRequest,
+  options?: InvokeFunctionOptions,
 ): Observable<R | undefined> {
   // Deferred so a bad config surfaces as an error on the returned observable
   // (and so a rejected promise) rather than throwing at the call site.
@@ -154,17 +182,30 @@ export function _invoke<R = unknown>(
     const config = client.config()
     const headers = scopeHeaders(config, request)
     const stackId = resolveStackId(config, request)
-
-    return _resolveFunctionId(client, httpRequest, functionName, stackId, headers, request).pipe(
-      // A function that returns nothing answers 204, which the transport parses
+    const sync = options?.sync ?? false
+
+    return _resolveFunctionId(
+      client,
+      httpRequest,
+      functionName,
+      stackId,
+      headers,
+      request,
+      sync,
+    ).pipe(
+      // An async invocation is only acknowledged (202, no body), and a sync
+      // function that returns nothing answers 204, which the transport parses
       // to an `undefined` body. The status code is not observable from here —
       // the `HttpRequest` boundary resolves to the body alone — so an empty
       // response and a function that returned nothing both surface as
       // `undefined`.
+      //
+      // The route is async by default, so `sync=false` is left off the wire
+      // rather than spelled out.
       mergeMap((functionId) =>
         _requestObservable<R | undefined>(client, httpRequest, {
           method: 'POST',
-          url: `/functions/${functionId}/invoke`,
+          url: `/functions/${functionId}/invoke${sync ? '?sync=true' : ''}`,
           headers,
           body: {event: {data: request?.event?.data ?? {}}},
           timeout: request?.timeout,

package/src/types.ts

@@ -304,6 +304,16 @@ export interface ClientConfig {
    * ID of the organization owning the blueprints stack
    */
   organizationId?: string
+  /**
+   * Organization-scoped configuration for collaboration APIs.
+   *
+   * Currently this is used by `collaboration.comments` methods.
+   *
+   * @alpha
+   */
+  collaboration?: {
+    organizationId?: string
+  }
 }
 
 /** @public */
@@ -840,6 +850,17 @@ export type VersionAction =
   | ReplaceVersionAction
   | UnpublishVersionAction
 
+/**
+ * @public
+ * @beta
+ */
+export type VariantAction =
+  | CreateVariantAction
+  | EditVariantAction
+  | DeleteVariantAction
+  | PublishVariantAction
+  | UnpublishVariantAction
+
 /** @public */
 export type Action =
   | CreateAction
@@ -850,6 +871,7 @@ export type Action =
   | PublishAction
   | UnpublishAction
   | VersionAction
+  | VariantAction
   | ReleaseAction
   | VariantDefinitionAction
 
@@ -1009,6 +1031,203 @@ export interface UnpublishVersionAction {
   publishedId: string
 }
 
+/**
+ * Creates a variant of a document, either by supplying the full document
+ * content, or the base ID of a document to copy.
+ *
+ * @public
+ * @beta
+ */
+export type CreateVariantAction = {
+  actionType: 'sanity.action.document.variant.create'
+
+  /**
+   * ID of the document group to create a variant in. Must be a published
+   * document ID, without a `drafts.` or `versions.` prefix.
+   */
+  publishedId: string
+
+  /**
+   * Name of the variant definition this document belongs to, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * Source bundle: `'drafts'`, or a release id.
+   *
+   * Defaults to the published bundle.
+   */
+  bundleId?: 'drafts' | (string & {})
+} & (
+  | {
+      /**
+       * The full document content. Requires a `_type` property.
+       */
+      document: SanityDocumentStub
+      baseId?: never
+      ifBaseRevisionId?: never
+    }
+  | {
+      /**
+       * ID of an existing document to copy the content from.
+       */
+      baseId: string
+
+      /**
+       * When set, the action fails unless the current revision of the base
+       * document matches this value.
+       */
+      ifBaseRevisionId?: string
+      document?: never
+    }
+)
+
+/**
+ * Modifies a variant version of a document by applying a patch.
+ *
+ * If no such variant document exists it is first created, by copying the
+ * variant's published sibling, or the published document if the variant was
+ * never published.
+ *
+ * @public
+ * @beta
+ */
+export interface EditVariantAction {
+  actionType: 'sanity.action.document.variant.edit'
+
+  /**
+   * ID of the document group the variant belongs to. Must be a published
+   * document ID, without a `drafts.` or `versions.` prefix.
+   */
+  publishedId: string
+
+  /**
+   * Name of the variant definition this document belongs to, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * Source bundle: `'drafts'`, or a release id.
+   *
+   * Defaults to the published bundle.
+   */
+  bundleId?: 'drafts' | (string & {})
+
+  /**
+   * Patch operations to apply.
+   */
+  patch: PatchOperations
+}
+
+/**
+ * Deletes a variant of a document.
+ *
+ * @public
+ * @beta
+ */
+export interface DeleteVariantAction {
+  actionType: 'sanity.action.document.variant.delete'
+
+  /**
+   * ID of the document group the variant belongs to. Must be a published
+   * document ID, without a `drafts.` or `versions.` prefix.
+   */
+  publishedId: string
+
+  /**
+   * Name of the variant definition this document belongs to, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * Source bundle: `'drafts'`, or a release id.
+   *
+   * Defaults to the published bundle.
+   */
+  bundleId?: 'drafts' | (string & {})
+
+  /**
+   * Delete document history.
+   */
+  purge?: boolean
+}
+
+/**
+ * Publishes a variant version of a document, replacing the published variant
+ * and removing the source variant document.
+ *
+ * @public
+ * @beta
+ */
+export interface PublishVariantAction {
+  actionType: 'sanity.action.document.variant.publish'
+
+  /**
+   * ID of the document group the variant belongs to. Must be a published
+   * document ID, without a `drafts.` or `versions.` prefix.
+   */
+  publishedId: string
+
+  /**
+   * Name of the variant definition this document belongs to, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * Bundle to publish from: `'drafts'`, or a release id.
+   */
+  bundleId: 'drafts' | (string & {})
+
+  /**
+   * When set, publishing fails unless the current revision of the source
+   * variant document matches this value.
+   */
+  ifVersionRevisionId?: string
+
+  /**
+   * When set, publishing fails unless the current revision of the published
+   * variant document matches this value.
+   */
+  ifPublishedVariantRevisionId?: string
+}
+
+/**
+ * Unpublishes a variant version of a document.
+ *
+ * By default the published variant is removed and preserved as a draft
+ * variant. When a release id is given as the `bundleId`, the deletion is
+ * instead staged in that release, and takes effect when it is published.
+ *
+ * @public
+ * @beta
+ */
+export interface UnpublishVariantAction {
+  actionType: 'sanity.action.document.variant.unpublish'
+
+  /**
+   * ID of the document group the variant belongs to. Must be a published
+   * document ID, without a `drafts.` or `versions.` prefix.
+   */
+  publishedId: string
+
+  /**
+   * Name of the variant definition this document belongs to, as in
+   * `_.variants.{variantName}`. Must be a bare name, not a full document ID.
+   */
+  variantId: string
+
+  /**
+   * The content release in which to stage the unpublish.
+   *
+   * By default, the currently published document is unpublished immediately.
+   */
+  bundleId?: string
+}
+
 /**
  * Creates a new `system.variant` definition document.
  *
@@ -2078,7 +2297,27 @@ export type {
   TranslateTarget,
   TranslateTargetInclude,
 } from './agent/actions/translate'
-export type {InvokeFunctionEvent, InvokeFunctionRequest} from './functions/invoke'
+export type {
+  InvokeFunctionEvent,
+  InvokeFunctionOptions,
+  InvokeFunctionRequest,
+} from './functions/invoke'
+export type {
+  CollaborationCommentCreate,
+  CollaborationCommentDocument,
+  CollaborationCommentMessage,
+  CollaborationCommentPortableTextBlock,
+  CollaborationCommentReactionShortName,
+  CollaborationCommentSelection,
+  CollaborationCommentsListenOptions,
+  CollaborationCommentsRequestOptions,
+  CollaborationCommentStatus,
+  CollaborationCommentsWriteOptions,
+  CollaborationCommentTarget,
+  CollaborationCommentUpdate,
+  CollaborationCommentRange,
+  CollaborationCommentFieldValue,
+} from './collaboration/types'
 export type {
   ContentSourceMapParsedPath,
   ContentSourceMapParsedPathKeyedSegment,

package/src/util/createVersionId.ts

@@ -5,20 +5,30 @@ import {
   isDraftId,
   isVersionId,
 } from '@sanity/client/csm'
-import {customAlphabet} from 'nanoid'
 
 import type {IdentifiedSanityDocumentStub, SanityDocumentStub} from '../types'
 import {validateVersionIdMatch} from '../validators'
 
+const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+
 /**
  * @internal
  *
  * ~24 years (or 7.54e+8 seconds) needed, in order to have a 1% probability of at least one collision if 10 ID's are generated every hour.
  */
-export const generateReleaseId = customAlphabet(
-  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
-  8,
-)
+export function generateReleaseId() {
+  let id = ''
+
+  while (id.length < 8) {
+    const bytes = crypto.getRandomValues(new Uint8Array(8 - id.length))
+    for (const byte of bytes) {
+      const index = byte & 63
+      if (index < alphabet.length) id += alphabet[index]
+    }
+  }
+
+  return id
+}
 
 /** @internal */
 export const getDocumentVersionId = (publishedId: string, releaseId?: string) =>