@sanity/sdk 2.8.0 → 2.9.0

package/src/document/documentStore.ts

@@ -1,5 +1,5 @@
-import {type Action} from '@sanity/client'
-import {getPublishedId} from '@sanity/client/csm'
+import {type Action, type Mutation} from '@sanity/client'
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 import {jsonMatch} from '@sanity/json-match'
 import {type SanityDocument} from 'groq'
 import {type ExprNode} from 'groq-js'
@@ -26,30 +26,45 @@ import {
   withLatestFrom,
 } from 'rxjs'
 
-import {getClientState} from '../client/clientStore'
-import {type DocumentHandle} from '../config/sanityConfig'
+import {type ClientOptions, getClientState} from '../client/clientStore'
 import {
-  bindActionByDataset,
-  type BoundDatasetKey,
+  type DocumentHandle,
+  type DocumentSource,
+  isCanvasSource,
+  isDatasetSource,
+  isMediaLibrarySource,
+} from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
+import {
+  bindActionBySource,
+  type BoundSourceKey,
   type StoreAction,
 } from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {createStateSourceAction, type StateSource} from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
-import {getDraftId} from '../utils/ids'
 import {type DocumentAction} from './actions'
 import {API_VERSION, INITIAL_OUTGOING_THROTTLE_TIME} from './documentConstants'
-import {type DocumentEvent, getDocumentEvents} from './events'
+import {
+  type DocumentEvent,
+  type DocumentTransactionSubmissionResult,
+  getDocumentEvents,
+} from './events'
 import {listen, OutOfSyncError} from './listen'
 import {type JsonMatch} from './patchOperations'
-import {calculatePermissions, createGrantsLookup, type DatasetAcl, type Grant} from './permissions'
+import {
+  calculatePermissions,
+  createGrantsLookup,
+  type DatasetAcl,
+  type DocumentPermissionsResult,
+  type Grant,
+} from './permissions'
 import {ActionError} from './processActions'
 import {
   type AppliedTransaction,
   applyFirstQueuedTransaction,
   applyRemoteDocument,
   cleanupOutgoingTransaction,
-  getDocumentIdsFromActions,
   manageSubscriberIds,
   type OutgoingTransaction,
   type QueuedTransaction,
@@ -107,15 +122,15 @@ export interface DocumentState {
   unverifiedRevisions?: {[TTransactionId in string]?: UnverifiedDocumentRevision}
 }
 
-export const documentStore = defineStore<DocumentStoreState, BoundDatasetKey>({
+export const documentStore = defineStore<DocumentStoreState, BoundSourceKey>({
   name: 'Document',
-  getInitialState: (instance) => ({
+  getInitialState: (instance, {source}) => ({
     documentStates: {},
     // these can be emptied on refetch
     queued: [],
     applied: [],
-    sharedListener: createSharedListener(instance),
-    fetchDocument: createFetchDocument(instance),
+    sharedListener: createSharedListener(instance, source),
+    fetchDocument: createFetchDocument(instance, source),
     events: new Subject(),
   }),
   initialize(context) {
@@ -183,33 +198,32 @@ export function getDocumentState(
   return _getDocumentState(...args)
 }
 
-const _getDocumentState = bindActionByDataset(
+const _getDocumentState = bindActionBySource(
   documentStore,
   createStateSourceAction({
     selector: ({state: {error, documentStates}}, options: DocumentOptions<string | undefined>) => {
-      const {documentId, path, liveEdit} = options
+      const {documentId: docId, path, liveEdit, perspective} = options
+      const documentId = DocumentId(docId)
       if (error) throw error
+      let document: SanityDocument | null | undefined
 
       if (liveEdit) {
-        // For liveEdit documents, only look at the single document
-        const document = documentStates[documentId]?.local
-        if (document === undefined) return undefined
-        if (!path) return document
-        const result = jsonMatch(document, path).next()
-        if (result.done) return undefined
-        const {value} = result.value
-        return value
+        document = documentStates[documentId]?.local
+      } else {
+        let version: SanityDocument | null | undefined
+        if (isReleasePerspective(perspective)) {
+          const versionId = getVersionId(documentId, perspective.releaseName)
+          version = documentStates[versionId]?.local
+          // early exit if we don't have the version document and we're in a release perspective
+          if (version === undefined) return undefined
+        }
+        const draft = documentStates[getDraftId(documentId)]?.local
+        const published = documentStates[getPublishedId(documentId)]?.local
+        // early exit if we don't have all the documents for draft/published logic
+        if (draft === undefined || published === undefined) return undefined
+        document = version ?? draft ?? published
       }
 
-      // Standard draft/published logic
-      const draftId = getDraftId(documentId)
-      const publishedId = getPublishedId(documentId)
-      const draft = documentStates[draftId]?.local
-      const published = documentStates[publishedId]?.local
-
-      // wait for draft and published to be loaded before returning a value
-      if (draft === undefined || published === undefined) return undefined
-      const document = draft ?? published
       if (!path) return document
       const result = jsonMatch(document, path).next()
       if (result.done) return undefined
@@ -217,7 +231,7 @@ const _getDocumentState = bindActionByDataset(
       return value
     },
     onSubscribe: (context, options: DocumentOptions<string | undefined>) =>
-      manageSubscriberIds(context, options.documentId, {expandDraftPublished: !options.liveEdit}),
+      manageSubscriberIds(context, [options]),
   }),
 )
 
@@ -241,7 +255,7 @@ export function resolveDocument(
 ): Promise<SanityDocument | null> {
   return _resolveDocument(...args)
 }
-const _resolveDocument = bindActionByDataset(
+const _resolveDocument = bindActionBySource(
   documentStore,
   ({instance}, docHandle: DocumentHandle<string, string, string>) => {
     return firstValueFrom(
@@ -254,57 +268,59 @@ const _resolveDocument = bindActionByDataset(
 )
 
 /** @beta */
-export const getDocumentSyncStatus = bindActionByDataset(
+export const getDocumentSyncStatus = bindActionBySource(
   documentStore,
   createStateSourceAction({
     selector: (
       {state: {error, documentStates: documents, outgoing, applied, queued}},
       doc: DocumentHandle,
     ) => {
-      const documentId = typeof doc === 'string' ? doc : doc.documentId
+      const documentId = DocumentId(typeof doc === 'string' ? doc : doc.documentId)
       if (error) throw error
 
       if (doc.liveEdit) {
         // For liveEdit documents, only check the single document
-        const document = documents[documentId]
-        if (document === undefined) return undefined
-        return !queued.length && !applied.length && !outgoing
+        if (documents[documentId] === undefined) return undefined
+      } else {
+        const version = isReleasePerspective(doc.perspective)
+          ? documents[getVersionId(documentId, doc.perspective.releaseName)]
+          : undefined
+        if (isReleasePerspective(doc.perspective) && version === undefined) return undefined
+        // Standard draft/published logic
+        const draft = documents[getDraftId(documentId)]
+        const published = documents[getPublishedId(documentId)]
+        if (draft === undefined || published === undefined) return undefined
       }
-
-      // Standard draft/published logic
-      const draftId = getDraftId(documentId)
-      const publishedId = getPublishedId(documentId)
-
-      const draft = documents[draftId]
-      const published = documents[publishedId]
-
-      if (draft === undefined || published === undefined) return undefined
       return !queued.length && !applied.length && !outgoing
     },
-    onSubscribe: (context, doc: DocumentHandle) => manageSubscriberIds(context, doc.documentId),
+    onSubscribe: (context, doc: DocumentHandle) => {
+      return manageSubscriberIds(context, [doc])
+    },
   }),
 )
 
 type PermissionsStateOptions = {
+  source?: DocumentSource
   actions: DocumentAction[]
 }
 
 /** @beta */
-export const getPermissionsState = bindActionByDataset(
+export const getPermissionsState = bindActionBySource(
   documentStore,
   createStateSourceAction({
     selector: calculatePermissions,
-    onSubscribe: (context, {actions}: PermissionsStateOptions) =>
-      manageSubscriberIds(context, getDocumentIdsFromActions(actions)),
+    onSubscribe: (context, {actions}: PermissionsStateOptions) => {
+      manageSubscriberIds(context, actions)
+    },
   }) as StoreAction<
     DocumentStoreState,
     [PermissionsStateOptions],
-    StateSource<ReturnType<typeof calculatePermissions>>
+    StateSource<DocumentPermissionsResult>
   >,
 )
 
 /** @beta */
-export const resolvePermissions = bindActionByDataset(
+export const resolvePermissions = bindActionBySource(
   documentStore,
   ({instance}, options: PermissionsStateOptions) => {
     return firstValueFrom(
@@ -314,16 +330,18 @@ export const resolvePermissions = bindActionByDataset(
 )
 
 /** @beta */
-export const subscribeDocumentEvents = bindActionByDataset(
+export const subscribeDocumentEvents = bindActionBySource(
   documentStore,
-  ({state}, eventHandler: (e: DocumentEvent) => void) => {
+  ({state}, options: {source?: DocumentSource; eventHandler: (e: DocumentEvent) => void}) => {
     const {events} = state.get()
-    const subscription = events.subscribe(eventHandler)
+    const subscription = events.subscribe(options.eventHandler)
     return () => subscription.unsubscribe()
   },
 )
 
-const subscribeToQueuedAndApplyNextTransaction = ({state}: StoreContext<DocumentStoreState>) => {
+const subscribeToQueuedAndApplyNextTransaction = ({
+  state,
+}: StoreContext<DocumentStoreState, BoundSourceKey>) => {
   const {events} = state.get()
   return state.observable
     .pipe(
@@ -354,7 +372,8 @@ const subscribeToQueuedAndApplyNextTransaction = ({state}: StoreContext<Document
 const subscribeToAppliedAndSubmitNextTransaction = ({
   state,
   instance,
-}: StoreContext<DocumentStoreState>) => {
+  key: {source},
+}: StoreContext<DocumentStoreState, BoundSourceKey>) => {
   const {events} = state.get()
 
   return state.observable
@@ -374,22 +393,52 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
       tap((next) => state.set('transitionAppliedTransactionsToOutgoing', next)),
       map((s) => s.outgoing),
       distinctUntilChanged(),
-      withLatestFrom(getClientState(instance, {apiVersion: API_VERSION}).observable),
+      withLatestFrom(
+        getClientState(instance, {
+          apiVersion: API_VERSION,
+          // TODO: remove in v3 when we're ready for everything to be queried via source
+          source: source && !isDatasetSource(source) ? source : undefined,
+        }).observable,
+      ),
       concatMap(([outgoing, client]) => {
         if (!outgoing) return EMPTY
+
+        const revertOnError = catchError((error: unknown) => {
+          state.set('revertOutgoingTransaction', revertOutgoingTransaction)
+          const message = error instanceof Error ? error.message : 'Request failed'
+          events.next({type: 'reverted', message, outgoing, error})
+          return EMPTY
+        })
+
+        const toResult = map((result: unknown) => ({
+          result: result as DocumentTransactionSubmissionResult,
+          outgoing,
+        }))
+
+        // Any liveEdit action in the batch routes to the mutations API. For mixed batches
+        // non-liveEdit operations (e.g. publish) lose atomicity, but that is acceptable
+        // given how rare mixed batches are.
+        if (outgoing.actions.some((action) => action.liveEdit)) {
+          return client.observable
+            .mutate(outgoing.outgoingMutations as Mutation[], {
+              transactionId: outgoing.transactionId,
+              visibility: 'async',
+              returnDocuments: false,
+              returnFirst: false,
+              tag: 'document.mutate',
+              skipCrossDatasetReferenceValidation: true,
+            })
+            .pipe(revertOnError, toResult)
+        }
+
+        // Pure non-liveEdit transactions use the actions API.
         return client.observable
           .action(outgoing.outgoingActions as Action[], {
             transactionId: outgoing.transactionId,
             skipCrossDatasetReferenceValidation: true,
+            tag: 'document.action',
           })
-          .pipe(
-            catchError((error) => {
-              state.set('revertOutgoingTransaction', revertOutgoingTransaction)
-              events.next({type: 'reverted', message: error.message, outgoing, error})
-              return EMPTY
-            }),
-            map((result) => ({result, outgoing})),
-          )
+          .pipe(revertOnError, toResult)
       }),
       tap(({outgoing, result}) => {
         state.set('cleanupOutgoingTransaction', cleanupOutgoingTransaction)
@@ -401,7 +450,7 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
 }
 
 const subscribeToSubscriptionsAndListenToDocuments = (
-  context: StoreContext<DocumentStoreState>,
+  context: StoreContext<DocumentStoreState, BoundSourceKey>,
 ) => {
   const {state} = context
   const {events} = state.get()
@@ -431,8 +480,8 @@ const subscribeToSubscriptionsAndListenToDocuments = (
           ...added.map((id) => ({id, add: true})),
           ...removed.map((id) => ({id, add: false})),
         ].sort((a, b) => {
-          const aIsDraft = a.id === getDraftId(a.id)
-          const bIsDraft = b.id === getDraftId(b.id)
+          const aIsDraft = a.id === getDraftId(DocumentId(a.id))
+          const bIsDraft = b.id === getDraftId(DocumentId(b.id))
 
           if (aIsDraft && bIsDraft) return a.id.localeCompare(b.id, 'en-US')
           if (aIsDraft) return -1
@@ -469,13 +518,30 @@ const subscribeToSubscriptionsAndListenToDocuments = (
 const subscribeToClientAndFetchDatasetAcl = ({
   instance,
   state,
-  key: {projectId, dataset},
-}: StoreContext<DocumentStoreState, BoundDatasetKey>) => {
-  return getClientState(instance, {apiVersion: API_VERSION})
+  key: {source},
+}: StoreContext<DocumentStoreState, BoundSourceKey>) => {
+  const clientOptions: ClientOptions = {apiVersion: API_VERSION}
+  // TODO: remove in v3 when we're ready for everything to be queried via source
+  if (source && !isDatasetSource(source)) {
+    clientOptions.source = source
+  }
+
+  let uri: string
+  if (source && isDatasetSource(source)) {
+    uri = `/projects/${source.projectId}/datasets/${source.dataset}/acl`
+  } else if (source && isMediaLibrarySource(source)) {
+    uri = `/media-libraries/${source.mediaLibraryId}/acl`
+  } else if (source && isCanvasSource(source)) {
+    uri = `/canvases/${source.canvasId}/acl`
+  } else {
+    throw new Error(`Received invalid source: ${JSON.stringify(source)}`)
+  }
+
+  return getClientState(instance, clientOptions)
     .observable.pipe(
       switchMap((client) =>
         client.observable.request<DatasetAcl>({
-          uri: `/projects/${projectId}/datasets/${dataset}/acl`,
+          uri,
           tag: 'acl.get',
           withCredentials: true,
         }),

package/src/document/events.ts

@@ -1,8 +1,13 @@
-import {type SanityClient} from '@sanity/client'
+import {type MultipleMutationResult, type SanityClient} from '@sanity/client'
 
 import {type DocumentAction} from './actions'
 import {type OutgoingTransaction} from './reducers'
 
+/** @beta Response body from submitting an outgoing transaction (actions or mutations API). */
+export type DocumentTransactionSubmissionResult =
+  | Awaited<ReturnType<SanityClient['action']>>
+  | MultipleMutationResult
+
 /** @beta */
 export type DocumentEvent =
   | ActionErrorEvent
@@ -35,7 +40,7 @@ export interface ActionErrorEvent {
 export interface TransactionAcceptedEvent {
   type: 'accepted'
   outgoing: OutgoingTransaction
-  result: Awaited<ReturnType<SanityClient['action']>>
+  result: DocumentTransactionSubmissionResult
 }
 /**
  * @beta

package/src/document/permissions.test.ts

@@ -1,9 +1,9 @@
+import {DocumentId, getDraftId, getPublishedId} from '@sanity/id-utils'
 import {type SanityDocument} from '@sanity/types'
 import {evaluateSync, type ExprNode, parse} from 'groq-js'
 import {describe, expect, it} from 'vitest'
 
 import {createSanityInstance} from '../store/createSanityInstance'
-import {getDraftId, getPublishedId} from '../utils/ids'
 import {type DocumentAction} from './actions'
 import {calculatePermissions, createGrantsLookup, type DatasetAcl, type Grant} from './permissions'
 import {type SyncTransactionState} from './reducers'
@@ -66,8 +66,10 @@ describe('calculatePermissions', () => {
     // For a document.create action, the selector expects both published and draft keys.
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: createDoc('doc1', 'Original Title')},
-        [getDraftId('doc1')]: {local: null},
+        [getPublishedId(DocumentId('doc1'))]: {
+          local: createDoc(DocumentId('doc1'), 'Original Title'),
+        },
+        [getDraftId(DocumentId('doc1'))]: {local: null},
       },
       defaultGrants,
     )
@@ -83,7 +85,7 @@ describe('calculatePermissions', () => {
     // Missing the draft key will cause documentsSelector to return undefined.
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: createDoc('doc1', 'Title')},
+        [getPublishedId(DocumentId('doc1'))]: {local: createDoc(DocumentId('doc1'), 'Title')},
         // Missing getDraftId('doc1')
       },
       defaultGrants,
@@ -99,8 +101,8 @@ describe('calculatePermissions', () => {
     const deniedGrants = {...defaultGrants, create: alwaysDeny}
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: createDoc('doc1', 'Title')},
-        [getDraftId('doc1')]: {local: null},
+        [getPublishedId(DocumentId('doc1'))]: {local: createDoc(DocumentId('doc1'), 'Title')},
+        [getDraftId(DocumentId('doc1'))]: {local: null},
       },
       deniedGrants,
     )
@@ -127,8 +129,8 @@ describe('calculatePermissions', () => {
     // Both published and draft documents are present as null.
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: null},
-        [getDraftId('doc1')]: {local: null},
+        [getPublishedId(DocumentId('doc1'))]: {local: null},
+        [getDraftId(DocumentId('doc1'))]: {local: null},
       },
       defaultGrants,
     )
@@ -153,8 +155,8 @@ describe('calculatePermissions', () => {
     const deniedGrants = {...defaultGrants, update: alwaysDeny}
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: createDoc('doc1', 'Title')},
-        [getDraftId('doc1')]: {local: createDoc(getDraftId('doc1'), 'Draft Title')},
+        [getPublishedId(DocumentId('doc1'))]: {local: createDoc(DocumentId('doc1'), 'Title')},
+        [getDraftId(DocumentId('doc1'))]: {local: createDoc(DocumentId('doc1'), 'Draft Title')},
       },
       deniedGrants,
     )
@@ -179,8 +181,8 @@ describe('calculatePermissions', () => {
 
   it('should return undefined if grants are not provided', () => {
     const state = createState({
-      [getPublishedId('doc1')]: {local: createDoc('doc1', 'Title')},
-      [getDraftId('doc1')]: {local: null},
+      [getPublishedId(DocumentId('doc1'))]: {local: createDoc(DocumentId('doc1'), 'Title')},
+      [getDraftId(DocumentId('doc1'))]: {local: null},
     })
     const actions: DocumentAction[] = [
       {documentId: 'doc1', type: 'document.create', documentType: 'article'},
@@ -192,8 +194,8 @@ describe('calculatePermissions', () => {
     // For document.delete, if the published document is missing, processActions throws an ActionError.
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: null},
-        [getDraftId('doc1')]: {local: null},
+        [getPublishedId(DocumentId('doc1'))]: {local: null},
+        [getDraftId(DocumentId('doc1'))]: {local: null},
       },
       defaultGrants,
     )
@@ -217,8 +219,8 @@ describe('calculatePermissions', () => {
   it('should memoize the result for identical state and actions inputs', () => {
     const state = createState(
       {
-        [getPublishedId('doc1')]: {local: createDoc('doc1', 'Title')},
-        [getDraftId('doc1')]: {local: null},
+        [getPublishedId(DocumentId('doc1'))]: {local: createDoc(DocumentId('doc1'), 'Title')},
+        [getDraftId(DocumentId('doc1'))]: {local: null},
       },
       defaultGrants,
     )

package/src/document/permissions.ts

@@ -1,9 +1,10 @@
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 import {type SanityDocument} from '@sanity/types'
 import {evaluateSync, type ExprNode, parse} from 'groq-js'
 import {createSelector} from 'reselect'
 
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {type SelectorContext} from '../store/createStateSourceAction'
-import {getDraftId, getPublishedId} from '../utils/ids'
 import {MultiKeyWeakMap} from '../utils/MultiKeyWeakMap'
 import {type DocumentAction} from './actions'
 import {ActionError, PermissionActionError, processActions} from './processActions'
@@ -71,7 +72,14 @@ const documentsSelector = createSelector(
           // For liveEdit documents, only fetch the single document
           if (action.liveEdit) return [action.documentId]
           // For standard documents, fetch both draft and published
-          return [getPublishedId(action.documentId), getDraftId(action.documentId)]
+          const ids: string[] = [
+            getPublishedId(DocumentId(action.documentId)),
+            getDraftId(DocumentId(action.documentId)),
+          ]
+          if (isReleasePerspective(action.perspective)) {
+            ids.push(getVersionId(DocumentId(action.documentId), action.perspective.releaseName))
+          }
+          return ids
         })
         .flat(),
     )
@@ -210,16 +218,32 @@ const _calculatePermissions = createSelector(
       // Check edit actions with no patches
       if (action.type === 'document.edit' && !action.patches?.length) {
         const docId = action.documentId
-        // For liveEdit documents, only check the single document
-        const doc = action.liveEdit
-          ? documents[docId]
-          : (documents[getDraftId(docId)] ?? documents[getPublishedId(docId)])
+        let doc: SanityDocument | null | undefined
+        if (action.liveEdit) {
+          doc = documents[docId]
+        }
+        // don't allow users to edit version documents that don't exist
+        // they should be explicitly created first, as in studio
+        else if (isReleasePerspective(action.perspective)) {
+          doc = documents[getVersionId(DocumentId(docId), action.perspective.releaseName)]
+        } else {
+          doc =
+            documents[getDraftId(DocumentId(docId))] ?? documents[getPublishedId(DocumentId(docId))]
+        }
         if (!doc) {
-          reasons.push({
-            type: 'precondition',
-            message: `The document with ID "${docId}" could not be found. Please check that it exists before editing.`,
-            documentId: docId,
-          })
+          if (isReleasePerspective(action.perspective)) {
+            reasons.push({
+              type: 'precondition',
+              message: `The version document with ID "${docId}" could not be found. Please create it or add it to the release first.`,
+              documentId: docId,
+            })
+          } else {
+            reasons.push({
+              type: 'precondition',
+              message: `The document with ID "${docId}" could not be found. Please check that it exists before editing.`,
+              documentId: docId,
+            })
+          }
         } else if (!checkGrant(grants.update, doc)) {
           reasons.push({
             type: 'access',