@sanity/sdk 2.12.0 → 2.13.0

package/src/document/processActions/releaseArchive.ts

@@ -12,7 +12,7 @@ export function handleReleaseArchive(
   action: ArchiveReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {base, working, grants, outgoingActions, transactionId} = ctx
+  const {base, working, grants, outgoingActions, transactionId, identity} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
   const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
@@ -24,7 +24,7 @@ export function handleReleaseArchive(
     })
   }
 
-  if (!checkGrant(grants.update, existing)) {
+  if (!checkGrant(grants.update, existing, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,
@@ -48,7 +48,7 @@ export function handleReleaseUnarchive(
   action: UnarchiveReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {base, working, grants, outgoingActions, transactionId} = ctx
+  const {base, working, grants, outgoingActions, transactionId, identity} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
   const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
@@ -60,7 +60,7 @@ export function handleReleaseUnarchive(
     })
   }
 
-  if (!checkGrant(grants.update, existing)) {
+  if (!checkGrant(grants.update, existing, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,

package/src/document/processActions/releaseCreate.ts

@@ -15,7 +15,7 @@ export function handleReleaseCreate(
   action: CreateReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations, identity} = ctx
   let {base, working} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
@@ -40,7 +40,7 @@ export function handleReleaseCreate(
   base = processMutations({documents: base, transactionId, mutations, timestamp})
   working = processMutations({documents: working, transactionId, mutations, timestamp})
 
-  if (!checkGrant(grants.create, working[releaseDocumentId] as SanityDocument)) {
+  if (!checkGrant(grants.create, working[releaseDocumentId] as SanityDocument, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,

package/src/document/processActions/releaseDelete.ts

@@ -19,7 +19,7 @@ export function handleReleaseDelete(
   action: DeleteReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations, identity} = ctx
   let {base, working} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
@@ -42,7 +42,7 @@ export function handleReleaseDelete(
     })
   }
 
-  if (!checkGrant(grants.update, existing)) {
+  if (!checkGrant(grants.update, existing, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,

package/src/document/processActions/releaseEdit.ts

@@ -6,7 +6,7 @@ export function handleReleaseEdit(
   action: EditReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations, identity} = ctx
   const {base, working} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
@@ -19,6 +19,7 @@ export function handleReleaseEdit(
     transactionId,
     timestamp,
     grants,
+    identity,
     notFoundMessage: `Cannot edit release "${action.releaseId}" because it does not exist.`,
     permissionMessage: `You do not have permission to edit release "${action.releaseId}".`,
   })

package/src/document/processActions/releasePublish.ts

@@ -12,7 +12,7 @@ export function handleReleasePublish(
   action: PublishReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {base, working, grants, outgoingActions, transactionId} = ctx
+  const {base, working, grants, outgoingActions, transactionId, identity} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
   const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
@@ -24,7 +24,7 @@ export function handleReleasePublish(
     })
   }
 
-  if (!checkGrant(grants.update, existing)) {
+  if (!checkGrant(grants.update, existing, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,

package/src/document/processActions/releaseSchedule.ts

@@ -12,7 +12,7 @@ export function handleReleaseSchedule(
   action: ScheduleReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {base, working, grants, outgoingActions, transactionId} = ctx
+  const {base, working, grants, outgoingActions, transactionId, identity} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
 
@@ -33,7 +33,7 @@ export function handleReleaseSchedule(
     })
   }
 
-  if (!checkGrant(grants.update, existing)) {
+  if (!checkGrant(grants.update, existing, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,
@@ -58,7 +58,7 @@ export function handleReleaseUnschedule(
   action: UnscheduleReleaseAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {base, working, grants, outgoingActions, transactionId} = ctx
+  const {base, working, grants, outgoingActions, transactionId, identity} = ctx
 
   const releaseDocumentId = getReleaseDocumentId(action.releaseId)
   const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
@@ -70,7 +70,7 @@ export function handleReleaseUnschedule(
     })
   }
 
-  if (!checkGrant(grants.update, existing)) {
+  if (!checkGrant(grants.update, existing, identity)) {
     throw new PermissionActionError({
       documentId: releaseDocumentId,
       transactionId,

package/src/document/processActions/shared.ts

@@ -12,6 +12,12 @@ export interface ActionHandlerContext {
   transactionId: string
   timestamp: string
   grants: Record<Grant, ExprNode>
+  /**
+   * The current user's ID, used by GROQ's `identity()` when evaluating ACL
+   * filters. May be `undefined` before the user has loaded; in that case
+   * `identity()` evaluates to null.
+   */
+  identity: string | undefined
   outgoingActions: HttpAction[]
   outgoingMutations: Mutation[]
 }
@@ -21,8 +27,12 @@ export interface ActionHandlerResult {
   working: DocumentSet
 }
 
-export function checkGrant(grantExpr: ExprNode, document: SanityDocument): boolean {
-  const value = evaluateSync(grantExpr, {params: {document}})
+export function checkGrant(
+  grantExpr: ExprNode,
+  document: SanityDocument,
+  identity: string | undefined,
+): boolean {
+  const value = evaluateSync(grantExpr, {params: {document}, identity})
   return value.type === 'boolean' && value.data
 }
 
@@ -55,6 +65,7 @@ interface ApplySingleDocPatchOptions {
   transactionId: string
   timestamp: string
   grants: Record<Grant, ExprNode>
+  identity: string | undefined
   /**
    * Error message thrown when the target document does not exist in either
    * the base or working set.
@@ -98,6 +109,7 @@ export function applySingleDocPatch({
   transactionId,
   timestamp,
   grants,
+  identity,
   notFoundMessage = 'Cannot edit document because it does not exist.',
   permissionMessage = `You do not have permission to edit document "${documentId}".`,
 }: ApplySingleDocPatchOptions): ApplySingleDocPatchResult {
@@ -120,7 +132,7 @@ export function applySingleDocPatch({
   const diffedPatches = diffValue(baseBefore, baseAfter) as PatchOperations[]
 
   const workingBefore = working[documentId] as SanityDocument
-  if (!checkGrant(grants.update, workingBefore)) {
+  if (!checkGrant(grants.update, workingBefore, identity)) {
     throw new PermissionActionError({documentId, transactionId, message: permissionMessage})
   }
 

package/src/document/processActions/unpublish.ts

@@ -16,7 +16,7 @@ export function handleUnpublish(
   action: UnpublishDocumentAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  const {transactionId, timestamp, grants, identity, outgoingActions, outgoingMutations} = ctx
   let {base, working} = ctx
 
   const documentId = getId(action.documentId)
@@ -48,7 +48,7 @@ export function handleUnpublish(
     {createIfNotExists: newDraftFromPublished},
   ]
 
-  if (!checkGrant(grants.update, sourceDoc)) {
+  if (!checkGrant(grants.update, sourceDoc, identity)) {
     throw new PermissionActionError({
       documentId,
       transactionId,
@@ -56,7 +56,7 @@ export function handleUnpublish(
     })
   }
 
-  if (!working[draftId] && !checkGrant(grants.create, newDraftFromPublished)) {
+  if (!working[draftId] && !checkGrant(grants.create, newDraftFromPublished, identity)) {
     throw new PermissionActionError({
       documentId,
       transactionId,

package/src/document/reducers.ts

@@ -19,7 +19,7 @@ const EMPTY_REVISIONS: NonNullable<Required<DocumentState['unverifiedRevisions']
 
 export type SyncTransactionState = Pick<
   DocumentStoreState,
-  'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants'
+  'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants' | 'identity'
 >
 
 type DocumentHandleLike = Pick<DocumentHandle, 'perspective'> & {
@@ -232,6 +232,7 @@ export function applyFirstQueuedTransaction(prev: SyncTransactionState): SyncTra
     base: working,
     timestamp,
     grants: prev.grants,
+    identity: prev.identity,
   })
   const applied: AppliedTransaction = {
     ...queued,
@@ -399,7 +400,7 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
 
   for (const t of prev.applied) {
     try {
-      const next = processActions({...t, working, grants: prev.grants})
+      const next = processActions({...t, working, grants: prev.grants, identity: prev.identity})
       working = next.working
       nextApplied.push({...t, ...next})
     } catch (error) {
@@ -506,7 +507,7 @@ export function applyRemoteDocument(
   // transaction again through the listener and this same flow will run then
   for (const curr of prev.applied) {
     try {
-      const next = processActions({...curr, working, grants: prev.grants})
+      const next = processActions({...curr, working, grants: prev.grants, identity: prev.identity})
       working = next.working
       // next includes an updated `previous` set and `working` set and updates
       // the `outgoingAction` and `outgoingMutations`. the `base` set from the

package/src/document/resourceRules.test.ts

@@ -0,0 +1,178 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {type EditDocumentAction} from './actions'
+import {getEffectiveDocumentModel, normalizeActionsForResource} from './resourceRules'
+
+const datasetResource = {projectId: 'p', dataset: 'd'}
+const canvasResource = {canvasId: 'canvas-1'}
+const mediaLibraryResource = {mediaLibraryId: 'ml-1'}
+
+function editAction(
+  overrides: Partial<EditDocumentAction> & Pick<EditDocumentAction, 'documentId' | 'documentType'>,
+): EditDocumentAction {
+  return {
+    type: 'document.edit',
+    patches: [{set: {foo: 'bar'}}],
+    ...overrides,
+  }
+}
+
+describe('getEffectiveDocumentModel', () => {
+  it('returns passthrough for no resource', () => {
+    expect(getEffectiveDocumentModel(undefined, 'anything')).toEqual({
+      liveEdit: undefined,
+      supportsReleases: true,
+    })
+  })
+
+  it('returns passthrough for dataset resources', () => {
+    expect(getEffectiveDocumentModel(datasetResource, 'author')).toEqual({
+      liveEdit: undefined,
+      supportsReleases: true,
+    })
+  })
+
+  it('forces liveEdit and disallows releases for canvas resources', () => {
+    expect(getEffectiveDocumentModel(canvasResource, 'page')).toEqual({
+      liveEdit: true,
+      supportsReleases: false,
+    })
+  })
+
+  it('forces liveEdit for non-asset media library types', () => {
+    expect(getEffectiveDocumentModel(mediaLibraryResource, 'sanity.imageAsset')).toEqual({
+      liveEdit: true,
+      supportsReleases: false,
+    })
+  })
+
+  it('keeps draft/published model for sanity.asset in media library', () => {
+    expect(getEffectiveDocumentModel(mediaLibraryResource, 'sanity.asset')).toEqual({
+      liveEdit: false,
+      supportsReleases: false,
+    })
+  })
+})
+
+describe('normalizeActionsForResource', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+  })
+
+  afterEach(() => {
+    warnSpy.mockRestore()
+  })
+
+  it('leaves dataset edits with a release perspective alone', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'author',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const result = normalizeActionsForResource([action], datasetResource)
+
+    expect(result[0]).toBe(action)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('strips release perspective and forces liveEdit for canvas, warning once', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'page',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const [result] = normalizeActionsForResource([action], canvasResource) as [EditDocumentAction]
+
+    expect(result.liveEdit).toBe(true)
+    expect(result.perspective).toBeUndefined()
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toContain('Canvas')
+    expect(warnSpy.mock.calls[0][0]).toContain('page (doc1)')
+  })
+
+  it('strips release perspective and forces liveEdit for non-asset media library types', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'sanity.imageAsset',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const [result] = normalizeActionsForResource([action], mediaLibraryResource) as [
+      EditDocumentAction,
+    ]
+
+    expect(result.liveEdit).toBe(true)
+    expect(result.perspective).toBeUndefined()
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toContain('Media Library')
+  })
+
+  it('strips release perspective but keeps draft/publish model for sanity.asset', () => {
+    const action = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'sanity.asset',
+      perspective: {releaseName: 'relA'},
+    })
+
+    const [result] = normalizeActionsForResource([action], mediaLibraryResource) as [
+      EditDocumentAction,
+    ]
+
+    expect(result.liveEdit).toBeUndefined()
+    expect(result.perspective).toBeUndefined()
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('silently forces liveEdit for canvas with no release perspective', () => {
+    const action = editAction({
+      documentId: 'drafts.doc1',
+      documentType: 'page',
+      perspective: 'drafts',
+    })
+
+    const [result] = normalizeActionsForResource([action], canvasResource) as [EditDocumentAction]
+
+    expect(result.liveEdit).toBe(true)
+    expect(result.documentId).toBe('doc1')
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  it('emits a single warning for multiple stripped actions in one call', () => {
+    const a = editAction({
+      documentId: 'versions.relA.doc1',
+      documentType: 'page',
+      perspective: {releaseName: 'relA'},
+    })
+    const b = editAction({
+      documentId: 'versions.relA.doc2',
+      documentType: 'page',
+      perspective: {releaseName: 'relA'},
+    })
+
+    normalizeActionsForResource([a, b], canvasResource)
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toContain('doc1')
+    expect(warnSpy.mock.calls[0][0]).toContain('doc2')
+  })
+
+  it('passes non-edit actions through unchanged', () => {
+    const action = {
+      type: 'document.publish' as const,
+      documentId: 'doc1',
+      documentType: 'page',
+    }
+
+    const result = normalizeActionsForResource([action], canvasResource)
+
+    expect(result[0]).toBe(action)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+})

package/src/document/resourceRules.ts

@@ -0,0 +1,117 @@
+import {DocumentId, getPublishedId} from '@sanity/id-utils'
+
+import {
+  type DocumentResource,
+  isCanvasResource,
+  isMediaLibraryResource,
+} from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
+import {type Action, type DocumentAction} from './actions'
+import {getEffectiveDocumentId} from './util'
+
+export interface EffectiveDocModel {
+  /**
+   * If this is `undefined`, the resource has no opinion and the handle's `liveEdit`
+   * flag should be respected.
+   */
+  liveEdit: boolean | undefined
+  /**
+   * When `false`, the resource does not support release perspectives. Callers
+   * should drop any release perspective and fall back to the standard path.
+   */
+  supportsReleases: boolean
+}
+
+const MEDIA_LIBRARY_DRAFTED_TYPES = new Set(['sanity.asset'])
+
+/**
+ * Different resources have different "default" editing models.
+ *
+ * Canvas uses a liveEdit model.
+ * Medial Library is mostly liveEdit except for `sanity.asset`, which retains the
+ * draft/published model. Neither resource supports release perspectives.
+ */
+export function getEffectiveDocumentModel(
+  resource: DocumentResource | undefined,
+  documentType: string | undefined,
+): EffectiveDocModel {
+  if (!resource) {
+    return {liveEdit: undefined, supportsReleases: true}
+  }
+  if (isCanvasResource(resource)) {
+    return {liveEdit: true, supportsReleases: false}
+  }
+  if (isMediaLibraryResource(resource)) {
+    const isDrafted = documentType ? MEDIA_LIBRARY_DRAFTED_TYPES.has(documentType) : false
+    return {liveEdit: !isDrafted, supportsReleases: false}
+  }
+  return {liveEdit: undefined, supportsReleases: true}
+}
+
+function describeResource(resource: DocumentResource | undefined): string {
+  if (resource && isCanvasResource(resource)) return 'Canvas'
+  if (resource && isMediaLibraryResource(resource)) return 'Media Library'
+  return 'this resource'
+}
+
+/**
+ * Rewrites edit actions to match the editing model of the bound resource.
+ *
+ * Canvas and Media Library resources do not support release perspectives, and
+ * Canvas (plus most Media Library types) does not have a draft/published
+ * model. When an edit action arrives with a release perspective for a resource
+ * that doesn't support it, the perspective is stripped and a single warning
+ * is logged. When the resource forces liveEdit, the action's `liveEdit` flag
+ * is set so the dispatcher takes the liveEdit branch.
+ *
+ * Only `document.edit` actions are normalized today — other action types
+ * (publish, unpublish, release actions, etc.) pass through unchanged.
+ *
+ * @internal
+ */
+export function normalizeActionsForResource(
+  actions: Action[],
+  resource: DocumentResource | undefined,
+): Action[] {
+  // collect actions that may have changed in unexpected ways
+  const stripped: Array<{documentType: string; documentId: string}> = []
+
+  const normalized = actions.map((action) => {
+    if (action.type !== 'document.edit') return action
+
+    const {liveEdit: forcedLiveEdit, supportsReleases} = getEffectiveDocumentModel(
+      resource,
+      action.documentType,
+    )
+    const shouldRemovePerspective = isReleasePerspective(action.perspective) && !supportsReleases
+    const shouldForceLiveEdit = forcedLiveEdit === true && !action.liveEdit
+
+    if (!shouldRemovePerspective && !shouldForceLiveEdit) return action
+
+    const corrected: DocumentAction = {...action}
+    if (shouldForceLiveEdit) corrected.liveEdit = true
+    if (shouldRemovePerspective) corrected.perspective = undefined
+
+    // ensure we're using the right document ID for the corrected model
+    corrected.documentId = getEffectiveDocumentId({
+      ...corrected,
+      documentId: getPublishedId(DocumentId(corrected.documentId)),
+    })
+
+    if (shouldRemovePerspective) {
+      stripped.push({documentType: action.documentType, documentId: corrected.documentId})
+    }
+
+    return corrected
+  })
+
+  if (stripped.length > 0) {
+    const docs = stripped.map((e) => `${e.documentType} (${e.documentId})`).join(', ')
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[sanity-sdk] ${describeResource(resource)} does not support release perspectives — falling back to the standard editing path for: ${docs}`,
+    )
+  }
+
+  return normalized
+}